Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

feat: serpapi toolkit (#3489)

JINO ROHITec3a0919884f
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 70b6ea47e..eabd4719a 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -4,9 +4,9 @@ repos:
hooks:
- id: ruff
args: [--fix, --exit-non-zero-on-fix, --show-fixes]
- exclude: ^(docs/cookbooks/|examples/usecases/|examples/custom_client_usage\.py) # Ignore files under docs/cookbooks and examples/usecases
+ exclude: ^(docs/|examples/usecases/|examples/custom_client_usage\.py) # Ignore files under docs and examples/usecases
- id: ruff-format
- exclude: ^(docs/cookbooks/|examples/usecases/) # Ignore files under docs/cookbooks and examples/usecases
+ exclude: ^(docs/|examples/usecases/) # Ignore files under docs and examples/usecases
- repo: local
hooks:
@@ -17,7 +17,7 @@ repos:
types: [python]
pass_filenames: false
require_serial: true
- exclude: ^(docs/cookbooks/|examples/usecases/) # Ignore files under docs/cookbooks and examples/usecases
+ exclude: ^(docs/|examples/usecases/) # Ignore files under docs and examples/usecases
- repo: local
hooks:
@@ -26,22 +26,25 @@ repos:
entry: python licenses/update_license.py . licenses/license_template.txt
language: system
types: [python]
- exclude: ^(docs/cookbooks/|examples/usecases/) # Ignore files under docs/cookbooks and examples/usecases
+ exclude: ^(docs/|examples/usecases/) # Ignore files under docs and examples/usecases
- repo: https://github.com/codespell-project/codespell
# Configuration for codespell is in pyproject.toml
rev: v2.4.1
hooks:
- id: codespell
- exclude: ^(docs/reference/|docs/.*\.rst$) # Ignore auto-generated content only
+ exclude: ^docs/ # Ignore all docs
additional_dependencies:
- tomli # for python_version < '3.11'
- repo: https://github.com/gitleaks/gitleaks
rev: v8.16.3
hooks:
- id: gitleaks
+ exclude: ^docs/
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.4.0
hooks:
- id: end-of-file-fixer
+ exclude: ^docs/
- id: trailing-whitespace
+ exclude: ^docs/
diff --git a/camel/toolkits/search_toolkit.py b/camel/toolkits/search_toolkit.py
index 728b5f836..7cb88a502 100644
--- a/camel/toolkits/search_toolkit.py
+++ b/camel/toolkits/search_toolkit.py
@@ -1344,6 +1344,108 @@ class SearchToolkit(BaseToolkit):
except Exception as e:
return {"error": f"Metaso search failed: {e}"}
+ @api_keys_required([(None, 'SERPAPI_KEY')])
+ def search_serpapi(
+ self,
+ query: str,
+ engine: str = "google",
+ location: str = "Austin,Texas",
+ google_domain: str = "google.com",
+ gl: str = "us",
+ search_lang: str = "en",
+ device: str = "desktop",
+ number_of_result_pages: int = 1,
+ safe: str = "off",
+ filter: int = 0,
+ custom_params: Optional[Dict[str, Any]] = None,
+ ) -> Dict[str, Any]:
+ r"""Use SerpApi search engine to search information for the given query.
+
+ SerpApi provides real-time search engine results from multiple search engines
+ including Google, Bing, Yahoo, DuckDuckGo, Baidu, Yandex, and more.
+
+ Args:
+ query (str): The search query string.
+ engine (str): Search engine to use. Supported engines include:
+ 'google', 'bing', 'yahoo', 'duckduckgo', 'baidu', 'yandex',
+ 'youtube', 'ebay', 'amazon', etc. (default: :obj:`"google"`)
+ location (str): Location for localized search results. Can be a city,
+ state, country, or coordinates. (default: :obj:`"Austin,Texas"`)
+ google_domain (str): Google domain to use (e.g., 'google.com', 'google.co.uk').
+ Only applicable for Google engine. (default: :obj:`"google.com"`)
+ gl (str): Country code for localized results (e.g., 'us', 'uk', 'ca').
+ Only applicable for Google engine. (default: :obj:`"us"`)
+ search_lang (str): Language code for results (e.g., 'en', 'es', 'fr').
+ Only applicable for Google engine. (default: :obj:`"en"`)
+ device (str): Device type: 'desktop', 'tablet', or 'mobile'.
+ (default: :obj:`"desktop"`)
+ number_of_result_pages (int): Number of organic results to return.
+ Adjust based on task needs. (default: :obj:`1`)
+ safe (str): Safe search level: 'off', 'medium', 'high', 'active'.
+ (default: :obj:`"off"`)
+ filter (int): Filter results: 0 (no filter), 1 (filter similar results).
+ (default: :obj:`0`)
+ custom_params (Optional[Dict[str, Any]]): Additional custom parameters
+ to pass to SerpApi. (default: :obj:`None`)
+
+ Returns:
+ Dict[str, Any]: A dictionary containing search results:
+ - 'results': List of organic search results, each containing:
+ - 'title': The title of the search result
+ - 'link': The URL of the search result
+ - 'snippet': The description snippet
+ - 'keywords': Highlighted keywords in the snippet
+ - 'source': The source of the result
+ - 'error: Error if any
+ """
+ from serpapi import SerpApiClient
+
+ SerpApiClient.SERP_API_KEY = os.getenv("SERPAPI_KEY")
+ params = {
+ "engine": engine,
+ "q": query,
+ "location": location,
+ "google_domain": google_domain,
+ "gl": gl,
+ "hl": search_lang,
+ "device": device,
+ "num": number_of_result_pages,
+ "safe": safe,
+ "filter": filter,
+ }
+
+ if custom_params:
+ params.update(custom_params)
+ try:
+ search = SerpApiClient(params)
+ results = search.get_dict()
+
+ if (
+ "organic_results" not in results
+ or not results["organic_results"]
+ ):
+ return {"error": "No organic results found"}
+
+ formatted_results = []
+ for result in results['organic_results']:
+ formatted_result = {
+ "title": result.get("title", ""),
+ "link": result.get("link", ""),
+ "snippet": result.get("snippet", ""),
+ "keywords": result.get("snippet_highlighted_words", []),
+ "source": result.get("source", ""),
+ }
+ formatted_results.append(formatted_result)
+
+ return {"results": formatted_results}
+
+ except ImportError:
+ return {
+ "error": "serpapi library not installed. Install with: pip install google-search-results"
+ }
+ except Exception as e:
+ return {"error": f"SerpApi search failed: {e!s}"}
+
def get_tools(self) -> List[FunctionTool]:
r"""Returns a list of FunctionTool objects representing the
functions in the toolkit.
@@ -1365,6 +1467,7 @@ class SearchToolkit(BaseToolkit):
FunctionTool(self.search_exa),
FunctionTool(self.search_alibaba_tongxiao),
FunctionTool(self.search_metaso),
+ FunctionTool(self.search_serpapi),
]
# Deprecated method alias for backward compatibility
diff --git a/examples/toolkits/search_toolkit.py b/examples/toolkits/search_toolkit.py
index a95f436a6..4c390b562 100644
--- a/examples/toolkits/search_toolkit.py
+++ b/examples/toolkits/search_toolkit.py
@@ -417,3 +417,38 @@ print(metaso_response)
Similarity: 0.9584", 'position': 10, 'date': '2025年05月23日'}], 'total': 38}
===============================================================================
""" # noqa: E501
+
+
+serpapi_agent = ChatAgent(
+ system_message="""You are a helpful assistant that helps users with
+ their queries""",
+ tools=[FunctionTool(SearchToolkit().search_serpapi)],
+)
+
+usr_msg = "What are the latest developments in quantum error correction?"
+response = serpapi_agent.step(input_message=usr_msg, response_format=None)
+print(response)
+
+"""
+===============================================================================
+msgs=[BaseMessage(role_name='System', role_type=<RoleType.SYSTEM: 'system'>,
+meta_dict={}, content='Recent reports indicate a rapid acceleration in quantum
+error correction research, with rising investments focused on achieving
+fault-tolerant performance. This suggests that error correction has become a
+defining challenge in the quantum industry.', video_bytes=None, image_list=None
+image_detail='auto', video_detail='auto', parsed=None, reasoning_content=None)]
+terminated=False info={'id': 'f7w3acbaFIyA0-kP9MuZoAk', 'usage':
+{'prompt_tokens': 1290, 'completion_tokens': 65, 'total_tokens': 1513},
+'termination_reasons': ['stop'], 'num_tokens': 191, 'tool_calls':
+[ToolCallingRecord(tool_name='search_serpapi', args={'query': 'latest
+developments in quantum error correction', 'engine': 'google'}, result=
+{'results': [{'title': "Quantum Report Says Error Correction Now The
+Industry's ...", 'link': 'https://thequantuminsider.com/2025/11/19/quantum-
+report-says-error-correction-now-the-industrys-defining-challenge/',
+'snippet': 'The findings show rapid acceleration in error-correction research,
+rising investments linked to fault-tolerant performance and heightened ...',
+'keywords': ['rapid acceleration in error-correction research'], 'source':
+'The Quantum Insider'}]}, tool_call_id='function-call-18262120514510234122',
+images=None)], 'external_tool_call_requests': None}
+===============================================================================
+"""
diff --git a/pyproject.toml b/pyproject.toml
index c487ef1c8..6a2f14cb9 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -33,6 +33,7 @@ dependencies = [
"websockets>=13.0,<15.1",
"astor>=0.8.1",
"pillow>=10.0.0",
+ "google-search-results>=2.4.2",
]
@@ -663,7 +664,9 @@ module = [
"sentence_transformers.*",
"markitdown",
"httplib2",
+ "serpapi.*",
]
+
ignore_missing_imports = true
[tool.codespell]
diff --git a/uv.lock b/uv.lock
index 4bb2d7795..d06479069 100644
--- a/uv.lock
+++ b/uv.lock
@@ -874,6 +874,7 @@ dependencies = [
{ name = "astor" },
{ name = "colorama" },
{ name = "docstring-parser" },
+ { name = "google-search-results" },
{ name = "httpx" },
{ name = "jsonschema" },
{ name = "mcp" },
@@ -1405,6 +1406,7 @@ requires-dist = [
{ name = "google-cloud-storage", marker = "extra == 'storage'", specifier = ">=2.18.0,<3" },
{ name = "google-genai", marker = "extra == 'all'", specifier = ">=1.13.0" },
{ name = "google-genai", marker = "extra == 'rag'", specifier = ">=1.13.0" },
+ { name = "google-search-results", specifier = ">=2.4.2" },
{ name = "googlemaps", marker = "extra == 'all'", specifier = ">=4.10.0,<5" },
{ name = "googlemaps", marker = "extra == 'web-tools'", specifier = ">=4.10.0,<5" },
{ name = "gradio", marker = "extra == 'all'", specifier = ">=3,<4" },
@@ -3648,6 +3650,15 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/1f/0b/93afde9cfe012260e9fe1522f35c9b72d6ee222f316586b1f23ecf44d518/google_resumable_media-2.8.0-py3-none-any.whl", hash = "sha256:dd14a116af303845a8d932ddae161a26e86cc229645bc98b39f026f9b1717582", size = 81340, upload-time = "2025-11-17T15:38:05.594Z" },
]
+[[package]]
+name = "google-search-results"
+version = "2.4.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "requests" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/77/30/b3a6f6a2e00f8153549c2fa345c58ae1ce8e5f3153c2fe0484d444c3abcb/google_search_results-2.4.2.tar.gz", hash = "sha256:603a30ecae2af8e600b22635757a6df275dad4b934f975e67878ccd640b78245", size = 18818, upload-time = "2023-03-10T11:13:09.953Z" }
+
[[package]]
name = "googleapis-common-protos"
version = "1.72.0"