Built-in Provider Tools#

AG2 includes built-in tools that map to capabilities offered by LLM providers. Almost all of them are executed by the provider's API — not locally — and require no function implementation on your side. The one exception is marked in the table below.

Web Search#

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-5"),
    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.

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-5"),
    tools=[
        WebFetchTool(
            max_uses=3,
            max_content_tokens=50000,
            citations=True,
        ),
    ],
)

Two of those options arrived with later tool versions. Setting one on a version that predates it raises WebFetchOptionUnsupportedError while the request is built, naming the option and the version it arrived in. The API refuses the same pairing with a 400, so this costs you the round trip and tells you which version to ask for:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

from ag2 import Agent
from ag2.config import AnthropicConfig
from ag2.tools import WebFetchTool

agent = Agent(
    "researcher",
    config=AnthropicConfig(model="claude-sonnet-5"),
    tools=[
        # Asking this agent anything raises: `use_cache` needs web_fetch_20260309 or later,
        # and no request is sent.
        WebFetchTool(use_cache=False, version="web_fetch_20250910"),
    ],
)

Which sources may supply a URL#

url_sources says, per source, which URLs the model is allowed to fetch. It is a policy control rather than a tuning knob: an agent that fetches URLs out of user text is reachable by anyone who can type into the conversation, and allowed_domains cannot stand in for it because that filters by host, not by who proposed the URL.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

from ag2 import Agent
from ag2.config import AnthropicConfig
from ag2.tools import tool
from ag2.tools.builtin.web_fetch import OnlyTools, UrlSources, WebFetchTool

@tool
async def search_docs(query: str) -> list[str]:
    """Return the URLs of documents matching the query."""
    return ["https://docs.example.com/guide"]

agent = Agent(
    "researcher",
    config=AnthropicConfig(model="claude-sonnet-5"),
    tools=[
        search_docs,
        WebFetchTool(
            # Fetch only what `search_docs` returned — never a link a user pasted.
            url_sources=UrlSources(
                user_input="none",
                client_tool_results=OnlyTools(["search_docs"]),
            ),
        ),
    ],
)

user_input is "all" or "none". client_tool_results and server_tool_results take those two as well as OnlyTools([...]) and ExceptTools([...]), which name tools. A name must belong to a tool the same request declares; one that does not raises WebFetchUrlSourceToolNotFoundError before the request is sent, because the API resolves those names against tools[] and a policy naming a tool that is not there covers nothing.

A source you leave unset is not sent, and the API's default applies to it. Measured 2026-09-19, that default is permissive: with url_sources omitted, a URL reaching the model only through a user message is fetched, and so is one reaching it only through a client tool's result.

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",
        ),
    ],
)

File Search#

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,
        ),
    ],
)

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"].

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-5"),
    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-5"),
    tools=[MemoryTool()],
)

Shell#

Gives the model the ability to run shell commands inside a provider-hosted environment. Only OpenAI offers one; the environment carries the backend configuration.

 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"]),
            ),
        ),
    ],
)

Anthropic Bash#

AnthropicBashTool declares Anthropic's bash_20250124 tool. Anthropic does not execute it: the model returns an ordinary tool_use block and waits for a tool_result, so AG2 runs the command for you and sends the output back.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

from ag2 import Agent
from ag2.config import AnthropicConfig
from ag2.tools import AnthropicBashTool

agent = Agent(
    "devops",
    config=AnthropicConfig(model="claude-sonnet-5"),
    tools=[AnthropicBashTool()],
)

reply = await agent.ask("How many Python files are in this directory?")
print(await reply.content())

With no arguments, commands run in a local subprocess. Execution is backed by the same machinery as SandboxShellTool, so the first argument picks the backend and the keyword arguments restrict what the model may run:

1
2
3
4
5
6
7
8

from ag2.extensions.docker import DockerEnvironment
from ag2.tools import AnthropicBashTool

bash = AnthropicBashTool(
    DockerEnvironment(image="python:3.12-slim", network_mode="none"),
    allowed=["ls", "cat", "python"],
    ignore=["**/.env", "*.key"],
)

The semantics are identical to SandboxShellTool's — see Command Filtering for the details.

Which Anthropic tool runs shell commands#

Anthropic exposes bash twice, and the two are not interchangeable:

Pick CodeExecutionTool when a throwaway sandbox on Anthropic's side is enough; pick AnthropicBashTool when the commands must act on your own files.

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.

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-5"),
    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-5"),
    tools=[
        MCPServerTool(
            server_url="https://mcp.example.com/sse",
            server_label="my-tools",
            allowed_tools=["search", "summarize"],
        ),
    ],
)

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))

X Search#

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,
        ),
    ],
)

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 }}.",
        ),
    ],
)

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.