Ag2 Use Builtin Tools

Use AG2 beta's built-in tools

When to use

Reach for this skill when the user wants to add a capability that AG2 already ships. Two families:

1. Provider-native tools (autogen.beta.tools — WebSearchTool, CodeExecutionTool, etc.) — executed server-side by Anthropic / OpenAI / Gemini. No Python implementation on your side. 2. Common toolkits (autogen.beta.tools — FilesystemToolkit, DuckDuckSearchTool, TavilySearchTool, SkillsToolkit; plus ExaToolkit from autogen.beta.extensions.tools.search) — regular Python that runs in your process and works with every provider.

For shell commands, use ag2-shell-tool (it's important enough to live in its own skill). For custom Python tools, use ag2-add-custom-tool.

60-second recipes

Web search (provider-native)

from autogen.beta import Agent
from autogen.beta.config import AnthropicConfig
from autogen.beta.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"],
        ),
    ],
)

Web fetch (Anthropic / Gemini only)

from autogen.beta.tools import WebFetchTool

tools = [WebFetchTool(max_uses=3, max_content_tokens=50000, citations=True)]

Code execution

from autogen.beta.tools import CodeExecutionTool

agent = Agent("analyst", config=config, tools=[CodeExecutionTool()])

MCP server integration

from autogen.beta.tools import MCPServerTool

tools = [
    MCPServerTool(
        server_url="https://mcp.example.com/sse",
        server_label="my-tools",
        allowed_tools=["search", "summarize"],
    ),
]

Image generation (OpenAI Responses only)

from autogen.beta.config import OpenAIResponsesConfig
from autogen.beta.tools import ImageGenerationTool

agent = Agent(
    "designer",
    config=OpenAIResponsesConfig(model="gpt-4.1"),
    tools=[ImageGenerationTool(quality="high", size="1024x1024", output_format="png")],
)
reply = await agent.ask("Generate a logo for a coffee shop.")
images = reply.files  # list[BinaryResult]

Filesystem (sandboxed, any provider)

from autogen.beta.tools import FilesystemToolkit

fs = FilesystemToolkit(base_path="/tmp/workspace")
agent = Agent("worker", config=config, tools=[fs])

base_path is enforced — ../../etc/passwd raises PermissionError. Use read_only=True to expose only read_file and find_files. For ephemeral workspaces use tempfile.TemporaryDirectory() rather than hardcoding /tmp.

Web search via DuckDuckGo (no API key)

from autogen.beta.tools import DuckDuckSearchTool
# requires: pip install ag2[ddgs]

tools = [DuckDuckSearchTool(max_results=10, region="us-en", safesearch="moderate")]

Exa neural search

import os
from autogen.beta.extensions.tools.search import ExaToolkit
# requires: pip install "exa-py>=2.12.1,<3"  (no ag2[exa] extra — install the package directly)

tools = [ExaToolkit(api_key=os.environ["EXA_API_KEY"])]

Each tool is exposed as a factory method (exa.search(), exa.find_similar(), exa.get_contents(), exa.answer()) so you can pass only what you need with per-call config.

Tavily search

import os
from autogen.beta.tools import TavilySearchTool
# requires: pip install ag2[tavily]

tools = [TavilySearchTool(
    api_key=os.environ["TAVILY_API_KEY"],
    search_depth="advanced",
    include_answer=True,
)]

Going deeper

• Per-tool provider support, every parameter, version pinning — references/builtin_tools_matrix.md.
• Source docs — website/docs/beta/tools/builtin_tools.mdx (provider-native), website/docs/beta/tools/common_toolkits.mdx (common toolkits — also covers SkillsToolkit and SkillSearchToolkit).
• Toolkits authoring — website/docs/beta/tools/toolkits.mdx.

Common pitfalls

• Mismatch between tool and provider — WebFetchTool raises with OpenAI; MemoryTool is Anthropic-only; ImageGenerationTool is OpenAI Responses only. Check references/builtin_tools_matrix.md first.
• Anthropic tool versions default to older revisions — pin version="web_search_20260209" etc. when you need dynamic filtering on Opus 4.6 / Sonnet 4.6.
• `FilesystemToolkit` paths are sandboxed — by design. Don't try to bypass the path-traversal guard; choose a wider base_path instead.
• Toolkits and individual tools mix freely — tools=[fs, exa, my_custom_tool] is fine.
• Optional dependency missing — DuckDuckSearchTool (ag2[ddgs]) and TavilySearchTool (ag2[tavily]) need their ag2[<extra>] install; ExaToolkit is a beta extension with no `ag2` extra — install its package directly (pip install "exa-py>=2.12.1,<3"). Without the dependency you get a clear ImportError from the config-fallback layer, not a confusing crash. Install before delivering the code. If you cannot run commands, state the exact pip install command.

Built-in tools — provider matrix and per-tool parameters

Provider-native tools (server-side execution)

Unsupported combinations raise UnsupportedToolError at request time.

WebSearchTool parameters

Unsupported parameters are silently ignored.

WebFetchTool parameters (Anthropic / Gemini only)

MCPServerTool parameters

ImageGenerationTool parameters (OpenAI Responses only)

Generated images surface on reply.files: list[BinaryResult].

Anthropic tool versions

Newer Anthropic tool revisions support dynamic filtering (the model writes code to filter results before they reach context) but require Opus 4.6 / Sonnet 4.6.

from autogen.beta.tools import WebFetchTool, WebSearchTool

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

Default versions are compatible with all Claude models including Haiku.

Common toolkits (local execution, all providers)

FilesystemToolkit

Constructor:

FilesystemToolkit(base_path="/tmp/workspace", read_only=False)

base_path is enforced — escape attempts raise PermissionError. Individual tools available as fs.read_file(), fs.find_files(), etc.

DuckDuckSearchTool

DuckDuckSearchTool(
    max_results=5,         # default
    region="us-en",        # default
    safesearch="moderate", # "on" | "moderate" | "off"
)

All parameters accept Variable(...) for deferred resolution.

ExaToolkit

Import from autogen.beta.extensions.tools.search (beta extension, not autogen.beta.tools).

Constructor:

ExaToolkit(api_key=..., num_results=10, max_characters=2000)

Per-call factory params include search_type, category, include_domains, exclude_domains, start_published_date, end_published_date, use_autoprompt, livecrawl. All accept Variable.

TavilySearchTool

TavilySearchTool(
    api_key=...,
    max_results=5,
    search_depth="advanced",   # "basic" | "advanced" | "fast" | "ultra-fast"
    topic="news",              # "general" | "news" | "finance"
    include_answer=True,
    include_raw_content=True,
    include_images=True,
    time_range="week",         # "day" | "week" | "month" | "year"
    include_domains=[...],
    exclude_domains=[...],
)

SkillsToolkit / SkillSearchToolkit

Discovers and runs skills following the agentskills.io convention. By default reads from .agents/skills/ in the current working directory.

from autogen.beta.tools import SkillsToolkit
from autogen.beta.tools.skills import LocalRuntime

skills = SkillsToolkit()                              # uses .agents/skills/
skills = SkillsToolkit(runtime="./my-skills")         # custom dir
skills = SkillsToolkit(runtime=LocalRuntime("./my-skills", extra_paths=["./shared-skills"]))

Three-step progressive disclosure: list_skills (catalog) → load_skill (full SKILL.md) → run_skill_script (execute a script).

SkillSearchToolkit adds search_skills, install_skill, remove_skill against the skills.sh registry. Set GITHUB_TOKEN (env or SkillsClientConfig) to lift the GitHub API rate limit from 60 → 5000 requests/hour.

Required extras