🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
Python agentai-societiesartificial-intelligencecommunicative-aicooperative-aideep-learninglarge-language-modelsmulti-agent-systemsnatural-language-processing
feat: serpapi toolkit (#3489)
JINO ROHITec3a0919884f
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yamlindex 70b6ea47e..eabd4719a 100644--- a/.pre-commit-config.yaml+++ b/.pre-commit-config.yaml@@ -4,9 +4,9 @@ repos:hooks:- id: ruffargs: [--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: localhooks:@@ -17,7 +17,7 @@ repos:types: [python]pass_filenames: falserequire_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: localhooks:@@ -26,22 +26,25 @@ repos:entry: python licenses/update_license.py . licenses/license_template.txtlanguage: systemtypes: [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.tomlrev: v2.4.1hooks:- id: codespell- exclude: ^(docs/reference/|docs/.*\.rst$) # Ignore auto-generated content only+ exclude: ^docs/ # Ignore all docsadditional_dependencies:- tomli # for python_version < '3.11'- repo: https://github.com/gitleaks/gitleaksrev: v8.16.3hooks:- id: gitleaks+ exclude: ^docs/- repo: https://github.com/pre-commit/pre-commit-hooksrev: v4.4.0hooks:- 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.pyindex 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 thefunctions 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 compatibilitydiff --git a/examples/toolkits/search_toolkit.py b/examples/toolkits/search_toolkit.pyindex 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.tomlindex 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.lockindex 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"