ag2-use-builtin-tools

使用 AG2 内置工具

何时使用

当用户希望添加 AG2 已提供的功能时，请使用此技能。分为两类：

1. 提供商原生工具（ag2.tools — WebSearchTool、CodeExecutionTool 等）——由 Anthropic / OpenAI / Gemini 在服务端执行。你无需自行实现 Python 代码。
2. 常用工具包（ag2.tools — FilesystemToolkit、DuckDuckSearchTool、TavilySearchTool、SkillsToolkit；以及来自 ag2.extensions.tools.search 的 ExaToolkit）——在当前进程中运行的常规 Python 代码，适用于所有提供商。

对于 shell 命令，请使用 ag2-shell-tool（它很重要，因此单独设立了一个技能）。 对于自定义 Python 工具，请使用 ag2-add-custom-tool。

60 秒速查

网页搜索（提供商原生）

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

网页抓取（仅限 Anthropic / Gemini）

from ag2.tools import WebFetchTool

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

代码执行

from ag2.tools import CodeExecutionTool

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

MCP 服务集成

from ag2.tools import MCPServerTool

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

图像生成（仅限 OpenAI Responses）

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")],
)
reply = await agent.ask("Generate a logo for a coffee shop.")
images = reply.files  # list[BinaryResult]

文件系统（沙盒环境，适用于任何提供商）

from ag2.tools import FilesystemToolkit

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

base_path 会强制执行路径限制——../../etc/passwd 会引发 PermissionError。使用 read_only=True 仅开放 read_file 和 find_files。对于临时工作区，请使用 tempfile.TemporaryDirectory()，而不是将 /tmp 写死在代码中。

通过 DuckDuckGo 搜索网页（无需 API 密钥）

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

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

Exa 神经搜索

import os
from ag2.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"])]

每个工具都以工厂方法的形式公开（exa.search()、exa.find_similar()、exa.get_contents()、exa.answer()），因此你可以按需传入所需参数，并使用每次调用的配置。

Tavily 搜索

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

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

深入了解

• 各工具的提供商支持情况、所有参数和版本固定 — references/builtin_tools_matrix.md。
• 源文档 — website/docs/user-guide/tools/builtin_tools.mdx（提供商原生工具）、website/docs/user-guide/tools/common_toolkits.mdx（常用工具包——也介绍了 SkillsToolkit 和 SkillSearchToolkit）。
• 工具包编写 — website/docs/user-guide/tools/toolkits.mdx。

常见问题

• 工具与提供商不匹配 — WebFetchTool 在 OpenAI 中会引发错误；MemoryTool 仅适用于 Anthropic；ImageGenerationTool 仅适用于 OpenAI Responses。请先查看 references/builtin_tools_matrix.md。
• Anthropic 工具默认使用较旧版本 — 如果需要在 Opus 4.6 / Sonnet 4.6 上进行动态过滤，请固定版本，例如 version="web_search_20260209"。
• FilesystemToolkit 的路径受到沙盒限制 — 这是设计如此。不要尝试绕过路径遍历防护；应改用范围更广的 base_path。
• 工具包和单个工具可以自由混用 — tools=[fs, exa, my_custom_tool] 完全没问题。
• 缺少可选依赖 — DuckDuckSearchTool（ag2[ddgs]）和 TavilySearchTool（ag2[tavily]）需要安装对应的 ag2[<extra>]；ExaToolkit 是一个扩展，没有 ag2 extra——请直接安装其软件包（pip install "exa-py>=2.12.1,<3"）。缺少依赖时，配置回退层会给出清晰的 ImportError，而不是令人困惑的崩溃。交付代码前请先安装。如果无法运行命令，请注明准确的 pip install 命令。