ag2-use-builtin-tools

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Use AG2's built-in tools

使用AG2的内置工具

When to use

适用场景

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

Provider-native tools (
```
ag2.tools
```
—
```
WebSearchTool
```
,
```
CodeExecutionTool
```
, etc.) — executed server-side by Anthropic / OpenAI / Gemini. No Python implementation on your side.

Common toolkits (

ag2.tools

—

FilesystemToolkit

DuckDuckSearchTool

TavilySearchTool

SkillsToolkit

; plus

ExaToolkit

from

ag2.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

当用户希望添加AG2已具备的功能时，可使用此技能。分为两类：

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

如需执行Shell命令，请使用

ag2-shell-tool

（该功能较为重要，独立为一个技能）。如需自定义Python工具，请使用

ag2-add-custom-tool

。

60-second recipes

60秒快速示例

Web search (provider-native)

网页搜索（服务商原生）

python

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

python

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

Web fetch (Anthropic / Gemini only)

网页抓取（仅支持Anthropic/Gemini）

python

from ag2.tools import WebFetchTool

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

python

from ag2.tools import WebFetchTool

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

Code execution

代码执行

python

from ag2.tools import CodeExecutionTool

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

python

from ag2.tools import CodeExecutionTool

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

MCP server integration

MCP服务器集成

python

from ag2.tools import MCPServerTool

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

python

from ag2.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)

图像生成（仅支持OpenAI Responses）

python

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]

python

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]

Filesystem (sandboxed, any provider)

文件系统（沙箱环境，支持所有服务商）

python

from ag2.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

python

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

。

Web search via DuckDuckGo (no API key)

基于DuckDuckGo的网页搜索（无需API密钥）

python

from ag2.tools import DuckDuckSearchTool

python

from ag2.tools import DuckDuckSearchTool

requires: pip install ag2[ddgs]

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

undefined

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

undefined

Exa neural search

Exa神经搜索

python

import os
from ag2.extensions.tools.search import ExaToolkit

python

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


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.

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


每个工具都以工厂方法形式暴露（`exa.search()`、`exa.find_similar()`、`exa.get_contents()`、`exa.answer()`），因此您可以按需传递参数，并配置每次调用的参数。

Tavily search

Tavily搜索

python

import os
from ag2.tools import TavilySearchTool

python

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

undefined

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

undefined

Going deeper

深入了解

Per-tool provider support, every parameter, version pinning —
```
references/builtin_tools_matrix.md
```
.

Source docs —

website/docs/user-guide/tools/builtin_tools.mdx

(provider-native),

website/docs/user-guide/tools/common_toolkits.mdx

(common toolkits — also covers

SkillsToolkit

and

SkillSearchToolkit

Toolkits authoring —

website/docs/user-guide/tools/toolkits.mdx

各工具的服务商支持、所有参数、版本固定——详见
```
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

。

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

工具与服务商不匹配——
```
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
扩展包——需直接安装其官方包（
```
pip install "exa-py>=2.12.1,<3"
```
）。如果缺少依赖，配置回退层会抛出清晰的
```
ImportError
```
，而非模糊的崩溃。请在交付代码前完成安装。如果您无法执行命令，请明确说明具体的
```
pip install
```
命令。