Skip to content

Built-in Provider Tools#

AG2 includes built-in tools that map to server-side capabilities offered by LLM providers. These tools are executed by the provider's API — not locally — and require no function implementation on your side.

Tool Anthropic OpenAI Gemini xAI Z.AI
CodeExecutionTool ✓ ✓ ✓ ✓ ✗
WebSearchTool ✓ ✓ ✓ ✓ ✓
WebFetchTool ✓ ✗ ✓ ✗ ✗
FileSearchTool ✗ ✓ ✓ ✗ ✗
ShellTool ✓ ✓ ✗ ✗ ✗
SkillsTool ✓ ✓ ✗ ✗ ✗
MCPServerTool ✓ ✓ ✗ ✓ ✗
ImageGenerationTool ✗ ✓ ✗ ✗ ✗
MemoryTool ✓ ✗ ✗ ✗ ✗
XSearchTool ✗ ✗ ✗ ✓ ✗
RetrievalTool ✗ ✗ ✗ ✗ ✓
GoogleMapsTool ✗ ✗ ✓ ✗ ✗

Gives the model access to real-time web search results.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
from ag2 import Agent
from ag2.config import AnthropicConfig
from ag2.tools import WebSearchTool, UserLocation

agent = Agent(
    "researcher",
    config=AnthropicConfig(model="claude-sonnet-4-6"),
    tools=[
        WebSearchTool(
            max_uses=5,
            user_location=UserLocation(country="US"),
            allowed_domains=["github.com", "pypi.org"],
            blocked_domains=["pinterest.com"],
        ),
    ],
)

Not all parameters are supported by every provider. Unsupported parameters are silently ignored.

Parameter Anthropic OpenAI Gemini xAI Z.AI
max_uses ✓ ✓ ✗ ✗ ✗
user_location ✓ ✓ ✗ ✓ ✗
search_context_size ✗ ✓ ✗ ✗ ✓
allowed_domains ✓ ✓ ✗ ✓ ✗
blocked_domains ✓ ✗ ✓ ✓ ✗

Note

Z.AI maps WebSearchTool to its search-prime engine and only honors search_context_size (as content_size); the other parameters are silently ignored.

Web Fetch#

Fetches full content from specific URLs. Useful for reading documentation, articles, or PDFs.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
from ag2 import Agent
from ag2.config import AnthropicConfig
from ag2.tools import WebFetchTool

agent = Agent(
    "researcher",
    config=AnthropicConfig(model="claude-sonnet-4-6"),
    tools=[
        WebFetchTool(
            max_uses=3,
            max_content_tokens=50000,
            citations=True,
        ),
    ],
)
Parameter Anthropic Gemini
max_uses ✓ ✗
allowed_domains ✓ ✗
blocked_domains ✓ ✗
citations ✓ ✗
max_content_tokens ✓ ✗

Note

OpenAI does not support web fetch. Using WebFetchTool with an OpenAI config will raise an error.

Google Maps#

GoogleMapsTool enables Grounding with Google Maps on the Gemini 3 family, giving the model access to up-to-date places, business info, and location data.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
from ag2 import Agent
from ag2.config import GeminiConfig
from ag2.tools import GoogleMapsTool

agent = Agent(
    "concierge",
    config=GeminiConfig(model="gemini-3-flash-preview"),
    tools=[
        GoogleMapsTool(
            latitude=40.7128,
            longitude=-74.0060,
            language_code="en",
        ),
    ],
)
Parameter Description
latitude / longitude Bias results toward a location (sent via tool_config.retrieval_config). Both required for geo-biasing.
language_code Localise results (e.g. "en").
enable_widget Request the interactive Maps widget context token.

Note

GoogleMapsTool is only supported by Gemini. All other providers raise UnsupportedToolError.

FileSearchTool lets the model search a provider-hosted document store and ground its answers in the retrieved chunks. On OpenAI this searches vector stores (upload files via the OpenAI SDK or dashboard, then reference the store by id); on Gemini this searches FileSearchStore resources.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
from ag2 import Agent
from ag2.config import OpenAIResponsesConfig
from ag2.tools import FileSearchTool

agent = Agent(
    "librarian",
    config=OpenAIResponsesConfig(model="gpt-4o"),
    tools=[
        FileSearchTool(
            vector_store_ids=["vs_abc123"],
            max_num_results=4,
            include_results=True,
        ),
    ],
)
Parameter Description
vector_store_ids OpenAI only. Required for OpenAI. Ids of the vector stores to search.
max_num_results Cap the number of retrieved chunks. Maps to Gemini's top_k.
filters OpenAI only. An OpenAI comparison or compound filter object, passed through verbatim.
include_results Return the raw retrieved chunks in the tool result (adds include=["file_search_call.results"]). Off by default — chunks are full text and inflate responses.
store_names Gemini only. Required for Gemini. Gemini FileSearchStore resource names to search.
metadata_filter Gemini only. AIP-160 filter string applied to store metadata.

vector_store_ids and filters are OpenAI-only; store_names and metadata_filter are Gemini-only. max_num_results is shared and maps to Gemini's top_k.

Search activity surfaces on the event stream as BuiltinToolCallEvent / BuiltinToolResultEvent pairs. With include_results=True the result event carries each chunk as a TextInput part, plus per-file relevance scores in metadata["results"].

Note

FileSearchTool is supported by the OpenAI Responses API (OpenAIResponsesConfig) and Gemini (GeminiConfig). Other providers raise an error.

Code Execution#

Lets the model write and run code inline during a conversation.

1
2
3
4
5
6
7
8
9
from ag2 import Agent
from ag2.config import AnthropicConfig
from ag2.tools import CodeExecutionTool

agent = Agent(
    "analyst",
    config=AnthropicConfig(model="claude-sonnet-4-6"),
    tools=[CodeExecutionTool()],
)

The tool accepts a version parameter for provider version pinning:

CodeExecutionTool(version="code_execution_20260521")

Accepted versions: code_execution_20250825 (default), code_execution_20260120, and code_execution_20260521.

Memory#

Enables Claude to store and retrieve information across conversations. Claude can create, read, update, and delete files in a /memories directory.

1
2
3
4
5
6
7
8
9
from ag2 import Agent
from ag2.config import AnthropicConfig
from ag2.tools import MemoryTool

agent = Agent(
    "assistant",
    config=AnthropicConfig(model="claude-sonnet-4-6"),
    tools=[MemoryTool()],
)

Note

MemoryTool is currently only supported by Anthropic.

Shell#

Gives the model the ability to run shell commands. The execution environment depends on the provider.

1
2
3
4
5
6
7
8
9
from ag2 import Agent
from ag2.config import AnthropicConfig
from ag2.tools import ShellTool

agent = Agent(
    "devops",
    config=AnthropicConfig(model="claude-sonnet-4-6"),
    tools=[ShellTool()],
)

OpenAI supports configuring the execution environment:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
from ag2 import Agent
from ag2.config import OpenAIResponsesConfig
from ag2.tools import ShellTool
from ag2.tools.builtin.shell import ContainerAutoEnvironment, NetworkPolicy

agent = Agent(
    "devops",
    config=OpenAIResponsesConfig(model="gpt-4.1"),
    tools=[
        ShellTool(
            environment=ContainerAutoEnvironment(
                network_policy=NetworkPolicy(allowed_domains=["pypi.org"]),
            ),
        ),
    ],
)
Environment Description
ContainerAutoEnvironment Provider-managed container with optional network policy
ContainerReferenceEnvironment Reference an existing container by ID

Warning

ShellTool gives the model direct shell access. Use it only with trusted prompts and consider restricting the environment.

Provider Skills#

SkillsTool activates skills that are hosted and executed by the provider — packaged capabilities such as spreadsheet or document generation. Pass skill ids as strings, or Skill objects to pin a version.

Note

Provider skills are unrelated to AG2's local Skills (SkillPlugin / SkillsToolkit), which run on your machine. SkillsTool only tells the provider which of its own skills to enable server-side.

1
2
3
4
5
6
7
8
9
from ag2 import Agent
from ag2.config import AnthropicConfig
from ag2.tools import Skill, SkillsTool

agent = Agent(
    "analyst",
    config=AnthropicConfig(model="claude-sonnet-4-6"),
    tools=[SkillsTool("pptx", Skill("xlsx", version="latest"))],
)

1
2
3
4
5
6
7
8
9
from ag2 import Agent
from ag2.config import OpenAIResponsesConfig
from ag2.tools import SkillsTool

agent = Agent(
    "analyst",
    config=OpenAIResponsesConfig(model="gpt-5.4"),
    tools=[SkillsTool("openai-spreadsheets")],
)

Skills never appear as standalone entries in the provider's tools[] array — each client wires them into the request differently:

  • Anthropic — skills ride the container API parameter. They execute inside the code-execution container, so a CodeExecutionTool is added automatically when missing, along with the required beta headers. First-party skill ids: pptx, xlsx, docx, pdf.
  • OpenAI (Responses API) — skills attach to the hosted shell tool's container_auto environment as skill_reference entries; a shell tool is added automatically when missing. System skill ids carry the openai- prefix (e.g. openai-spreadsheets). Combining SkillsTool with ContainerReferenceEnvironment raises an error — skills for an existing container are configured when the container is created.

Version pins are strings. For Anthropic, a version date such as "20251013" or "latest" (None is sent as "latest"). For OpenAI, a positive integer such as "2" or "latest" (None omits the field, meaning the skill's default version).

MCP Server#

Integrates external MCP (Model Context Protocol) servers, giving the model access to remote tools.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
from ag2 import Agent
from ag2.config import AnthropicConfig
from ag2.tools import MCPServerTool

agent = Agent(
    "assistant",
    config=AnthropicConfig(model="claude-sonnet-4-6"),
    tools=[
        MCPServerTool(
            server_url="https://mcp.example.com/sse",
            server_label="my-tools",
            allowed_tools=["search", "summarize"],
        ),
    ],
)
Parameter Anthropic OpenAI
server_url ✓ ✓
server_label ✓ ✓
authorization_token ✓ ✗
description ✓ ✗
allowed_tools ✓ ✓
blocked_tools ✓ ✗
headers ✗ ✓

Image Generation#

ImageGenerationTool instructs the model to generate images inline during a conversation. Generated images are returned via reply.files.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
from ag2 import Agent
from ag2.config import OpenAIResponsesConfig
from ag2.tools import ImageGenerationTool

agent = Agent(
    "designer",
    config=OpenAIResponsesConfig(model="gpt-4.1"),
    tools=[
        ImageGenerationTool(
            quality="high",
            size="1024x1024",
            output_format="png",
            background="transparent",
        ),
    ],
)

reply = await agent.ask("Generate a logo for a coffee shop.")
for image in reply.files:
    print(image.metadata.get("media_type"), len(image.data))

Note

ImageGenerationTool is only supported by OpenAI (Responses API). Gemini generates images through a response modality rather than a tool. See Image Generation for the full guide covering both providers.

XSearchTool gives xAI's Grok models real-time search over X (Twitter), optionally scoped to specific handles, a date range, or media understanding. This tool is xAI-specific.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
from datetime import datetime

from ag2 import Agent
from ag2.config import XAIConfig
from ag2.tools import XSearchTool

agent = Agent(
    "researcher",
    config=XAIConfig(model="grok-4"),
    tools=[
        XSearchTool(
            allowed_x_handles=["xai"],
            from_date=datetime(2024, 1, 1),
            enable_image_understanding=True,
        ),
    ],
)
Parameter Description
allowed_x_handles Restrict the search to these X handles.
excluded_x_handles Exclude these X handles from results.
from_date / to_date Bound the search to a datetime range.
enable_image_understanding Let the model interpret images in posts.
enable_video_understanding Let the model interpret videos in posts.

Note

XSearchTool is only supported by xAI.

Retrieval#

RetrievalTool lets the model query a Z.AI knowledge base by id, grounding its answers in the retrieved documents.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
from ag2 import Agent
from ag2.config import ZAIConfig
from ag2.tools.builtin import RetrievalTool

agent = Agent(
    "researcher",
    config=ZAIConfig(model="glm-4.6"),
    tools=[
        RetrievalTool(
            knowledge_id="kb_123",
            prompt_template="Use {{ knowledge }} to answer {{ question }}.",
        ),
    ],
)
Parameter Description
knowledge_id Required. Id of the Z.AI knowledge base to query.
prompt_template Optional template for injecting retrieved content, using {{ knowledge }} and {{ question }} placeholders.

Note

RetrievalTool is only supported by Z.AI.

Anthropic Tool Versions#

Anthropic versions their server-side tools. Newer versions support dynamic filtering (Claude writes code to filter results before loading into context), but require Opus 4.6 or Sonnet 4.6.

Set the version on each built-in tool (defaults match the older Anthropic tool revisions):

1
2
3
4
5
6
from ag2.tools import WebFetchTool, WebSearchTool

tools = [
    WebSearchTool(version="web_search_20260209"),  # default: web_search_20250305
    WebFetchTool(version="web_fetch_20260209"),    # default: web_fetch_20250910
]

The default versions are compatible with all Claude models including Haiku.