Implementation:Microsoft Autogen Studio Google Search Tool

Sources	python/packages/autogen-studio/autogenstudio/gallery/tools/google_search.py
Domains	Tools, Search, Web Scraping, API Integration, AutoGen Studio
Last Updated	2026-02-11

Overview

Description

The Google Search Tool is a comprehensive search utility within AutoGen Studio that enables agents to perform web searches using Google's Custom Search API. The tool provides search functionality with optional webpage content fetching and automatic conversion to markdown format, making it ideal for information retrieval and content analysis tasks.

This implementation combines search capabilities with intelligent content extraction, supporting language and country-specific searches, safe search filtering, and configurable output formatting. It integrates seamlessly with the autogen-core framework using the FunctionTool wrapper.

Key Features

Google Custom Search integration: Leverages Google's powerful search capabilities
Content fetching: Retrieves and converts full webpage content to markdown
Configurable filtering: Language, country, and safe search options
Snippet extraction: Includes search result descriptions
Error handling: Comprehensive validation and informative error messages
Async operation: Non-blocking HTTP requests for efficient execution
HTML to Markdown conversion: Clean, readable content extraction

Usage

The tool requires two environment variables: GOOGLE_API_KEY (Custom Search API key) and GOOGLE_CSE_ID (Custom Search Engine ID). These must be configured before the tool can be used.

Environment Setup:

export GOOGLE_API_KEY="your_google_api_key"
export GOOGLE_CSE_ID="your_custom_search_engine_id"

Basic Usage:

results = await google_search(
    query="machine learning tutorials",
    num_results=5,
    include_content=True
)

Code Reference

Source Location

File: python/packages/autogen-studio/autogenstudio/gallery/tools/google_search.py
Repository: https://github.com/microsoft/autogen
Lines: 144 total

Function Signature

async def google_search(
    query: str,
    num_results: int = 3,
    include_snippets: bool = True,
    include_content: bool = True,
    content_max_length: Optional[int] = 10000,
    language: str = "en",
    country: Optional[str] = None,
    safe_search: bool = True,
) -> List[Dict[str, str]]

Import Statement

from autogenstudio.gallery.tools.google_search import google_search, google_search_tool

Dependencies

Standard Library: os, typing, urllib.parse
Third-party: httpx, html2text, beautifulsoup4
AutoGen: autogen_core.code_executor, autogen_core.tools

I/O Contract

Inputs

Parameter	Type	Default	Description
query	str	(required)	Search query string
num_results	int	3	Number of results to return (max 10)
include_snippets	bool	True	Include result snippets/descriptions in output
include_content	bool	True	Fetch and include full webpage content in markdown format
content_max_length	Optional[int]	10000	Maximum length of webpage content (None for unlimited, up to 50000)
language	str	"en"	Language code for search results (e.g., "en", "es", "fr")
country	Optional[str]	None	Country code for search results (e.g., "us", "uk")
safe_search	bool	True	Enable safe search filtering (True="active", False="off")

Outputs

Field	Type	Description
return	List[Dict[str, str]]	List of search result dictionaries

Result Dictionary Structure:

Field	Type	Conditional	Description
title	str	Always	Search result title
link	str	Always	URL of the search result
snippet	str	If include_snippets=True	Brief description/snippet from search results
content	str	If include_content=True	Full webpage content in markdown format (or error message if fetch failed)

Exceptions

Exception	Condition
ValueError	Missing GOOGLE_API_KEY or GOOGLE_CSE_ID environment variables
ValueError	Failed to perform search (network error, timeout)
ValueError	Invalid API response format (missing expected fields)
ValueError	General error during search operation

Implementation Details

Core Algorithm

Validation Phase:
1. Retrieve GOOGLE_API_KEY from environment
2. Retrieve GOOGLE_CSE_ID from environment
3. Validate both are present (raise ValueError if missing)
4. Clamp num_results to range [1, 10]
API Request Phase:
1. Build query parameters with API key, CSE ID, and search options
2. Add language (hl) and safe search parameters
3. Add country (gl) parameter if specified
4. Make async HTTP GET request to Google Custom Search API
5. Raise exception on HTTP errors
6. Parse JSON response
Response Processing Phase:
1. Check for "items" key in response
2. For each item in results:
  1. Extract title and link fields
  2. Add snippet if include_snippets=True
  3. Fetch page content if include_content=True
3. Return list of result dictionaries
Content Fetching Phase (helper function):
1. Make async HTTP request to result URL
2. Parse HTML with BeautifulSoup
3. Remove script and style elements
4. Convert relative URLs to absolute
5. Transform HTML to markdown using html2text
6. Apply max_length truncation if specified
7. Return markdown content or error message

Helper Functions

fetch_page_content(url, max_length): Internal async helper that retrieves webpage content and converts it to markdown. Includes comprehensive error handling to return error messages rather than raising exceptions.

Configuration Options

API Endpoint: https://www.googleapis.com/customsearch/v1
Request Timeout: 10 seconds
Default User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
HTML Parser: html.parser (via BeautifulSoup)
Max Content Length: 50000 characters (internal limit for fetch_page_content)

API Parameters

Parameter	API Key	Description
key	key	Google API key
cx	cx	Custom Search Engine ID
q	q	Search query
num	num	Number of results (1-10)
hl	hl	Interface language
gl	gl	Geolocation (country)
safe	safe	Safe search ("active" or "off")

Usage Examples

Example 1: Basic Search

# Simple search with default parameters
results = await google_search(
    query="Python programming best practices"
)

for result in results:
    print(f"Title: {result['title']}")
    print(f"URL: {result['link']}")
    print(f"Snippet: {result['snippet']}")
    print(f"Content length: {len(result['content'])} chars")
    print("---")

Example 2: Search Without Content

# Fast search without fetching full content
results = await google_search(
    query="latest AI research papers",
    num_results=10,
    include_content=False  # Only get titles, links, and snippets
)

# Useful for quick link gathering or when full content isn't needed
for result in results:
    print(f"{result['title']}: {result['link']}")

Example 3: Localized Search

# Search for Spanish content in Spain
results = await google_search(
    query="recetas tradicionales españolas",
    num_results=5,
    language="es",
    country="es",
    content_max_length=5000
)

for result in results:
    print(f"Título: {result['title']}")
    print(f"Contenido: {result['content'][:200]}...")

Example 4: Search with Unlimited Content

# Fetch complete webpage content without truncation
results = await google_search(
    query="comprehensive guide to docker",
    num_results=1,
    content_max_length=None  # No limit (up to 50000 internal max)
)

# Get full article content for detailed analysis
full_content = results[0]['content']

Example 5: Safe Search Disabled

# Disable safe search for research purposes
results = await google_search(
    query="medical terminology",
    safe_search=False,
    num_results=5
)

Example 6: Using the FunctionTool

from autogenstudio.gallery.tools.google_search import google_search_tool

# Add tool to an agent's toolset
research_agent = ConversableAgent(
    name="researcher",
    tools=[google_search_tool]
)

# Agent can now process instructions like:
# "Search Google for information about quantum computing and summarize the results"

Example 7: Handling Missing Results

# Handle cases where no results are found
results = await google_search(query="xyzabc123nonexistent456")

if not results:
    print("No search results found")
else:
    print(f"Found {len(results)} results")

Example 8: Error Handling

try:
    results = await google_search(
        query="test query",
        num_results=5
    )
except ValueError as e:
    if "Missing required environment variables" in str(e):
        print("Please set GOOGLE_API_KEY and GOOGLE_CSE_ID")
    elif "Failed to perform search" in str(e):
        print("Network error or API issue")
    else:
        print(f"Error: {e}")

Setup Instructions

Obtaining API Credentials

Step 1: Get Google API Key

Visit Google Cloud Console
Create a new project or select existing project
Enable "Custom Search API"
Go to "Credentials" and create an API key
Copy the API key

Step 2: Create Custom Search Engine

Visit Programmable Search Engine
Click "Add" to create a new search engine
Configure search settings:
- Sites to search: "Search the entire web"
- Name: Choose a name for your search engine
Create the search engine
Copy the Search Engine ID (cx parameter)

Step 3: Configure Environment

export GOOGLE_API_KEY="AIzaSy..."
export GOOGLE_CSE_ID="a1b2c3d4e5..."

API Quotas and Limits

Free tier: 100 queries per day
Paid tier: Higher quotas available
Results per query: Maximum 10 results
Rate limiting: Varies by quota tier

Error Handling

Common Error Scenarios

Missing Credentials:

# Raises: ValueError: Missing required environment variables.
#         Please set GOOGLE_API_KEY and GOOGLE_CSE_ID.

Network Errors:

# Raises: ValueError: Failed to perform search: Connection timeout
await google_search(query="test")

Invalid API Response:

# Raises: ValueError: Invalid API response format: 'items'
# (Occurs when search returns no results or unexpected format)

Content Fetch Failures:

# Does NOT raise exception - returns error in content field:
# result['content'] = "Error fetching content: Connection timeout"

Comparison with Bing Search Tool

Feature	Google Search Tool	Bing Search Tool
API Provider	Google Custom Search	Microsoft Bing
Max Results	10	50
Result Types	Web pages only	Web, News, Images, Videos
Safe Search	Boolean (on/off)	Three levels (off/moderate/strict)
Free Tier	100 queries/day	Varies by Azure plan
Setup Complexity	Requires API key + CSE ID	Requires only API key

Related Pages

Implementation: Studio Bing Search Tool - Alternative search implementation using Bing API
Implementation: Studio Fetch Webpage Tool - Standalone webpage fetching utility
Microsoft Autogen Studio Tools - Overview of all AutoGen Studio gallery tools
AutoGen Core Function Tools - Documentation on FunctionTool framework
Web Search Integration Patterns - Best practices for search tool integration

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment