本技能用于把 AG2 已内置的工具接入 Agent,适用于用户想为 Agent 添加 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。
文档提供了多种示例用法。联网搜索(提供商原生)示例中,使用 AnthropicConfig 配合 WebSearchTool,并可设置 max_uses、user_location、allowed_domains、blocked_domains。网页抓取(仅 Anthropic / Gemini)使用 WebFetchTool,可设置 max_uses、max_content_tokens、citations。代码执行使用 CodeExecutionTool。MCP 服务集成使用 MCPServerTool,可设置 server_url、server_label、allowed_tools。图像生成(仅 OpenAI Responses)使用 OpenAIResponsesConfig 配合 ImageGenerationTool,可设置 quality、size、output_format,生成的图像可从 reply.files 获取(list[BinaryResult])。
文件系统方面使用 FilesystemToolkit,通过 base_path 指定工作目录并强制沙箱约束(如 ../../etc/passwd 会触发 PermissionError);可用 read_only=True 只暴露 read_file 和 find_files;临时工作区建议使用 tempfile.TemporaryDirectory() 而不是硬编码 /tmp。
搜索工具方面:DuckDuckSearchTool 无需 API key,需安装 pip install ag2[ddgs],可设置 max_results、region、safesearch;ExaToolkit 需直接安装 pip install "exa-py>=2.12.1,<3"(没有 ag2[exa] extra),每个工具以工厂方法暴露(exa.search()、exa.find_similar()、exa.get_contents()、exa.answer()),可只传所需并做逐次调用配置;TavilySearchTool 需安装 pip install ag2[tavily],可设置 api_key、search_depth、include_answer。
文档还提示深入资料(如 references/builtin_tools_matrix.md 中的逐工具提供商支持、全部参数、版本固定;以及来源文档路径)和常见陷阱:工具与提供商不匹配(WebFetchTool 在 OpenAI 下会抛错;MemoryTool 仅 Anthropic;ImageGenerationTool 仅 OpenAI Responses);Anthropic 工具版本默认较低,需要时可固定 version="web_search_20260209" 等;FilesystemToolkit 路径沙箱为设计使然,不要绕过路径穿越防护;工具包与单个工具可自由混用;可选依赖缺失时会从配置回退层给出清晰的 ImportError,安装前先执行对应 pip install 命令。