为 agent 添加工具

适用场景

• 为提示词智能体或托管智能体添加网页搜索、MCP 服务器、OpenAPI 等工具，并希望多个智能体共用。

• 为智能体添加只在应用内执行的自定义函数，例如查询内部系统或执行计算。

前提

• 有 Foundry 项目，并对开发者身份与智能体身份授予 Foundry User 角色（按场景还可能需要终端用户的 OAuth 身份）。

• 已安装对应语言的 SDK，例如 Python 的 azure-ai-projects。

• 工具所在区域与模型的支持情况：待核实（2026-11-05 获取），以官方“区域与模型兼容性”说明为准。

方式一：使用 Toolbox（推荐）

1. 创建工具集版本，把需要的工具（如 MCP 服务器、网页搜索）放入同一个版本。每个工具都应填写 description，帮助模型选择工具。

2. 首个版本自动成为默认版本；后续版本需要测试后手动提升为默认。

3. 复制工具集的消费端点（consumer endpoint），在托管智能体中以 MCP 客户端方式接入。

4. 验证：用特定版本的端点列出工具，再发送一条会触发目标工具的请求。

方式二：函数调用（function calling）

1. 定义函数的名称、描述与参数（JSON Schema），并把必填字段写入 required。

2. 在创建智能体时把函数工具放入 tools。

3. 发送用户问题，检查输出中是否有 function_call 类型的项。

4. 本地执行函数，用 function_call_output 把结果回传到同一会话。

5. 获取智能体基于函数结果的最终回答。

两种方式的对比

验证

• 方式一：列出的工具与预期一致，一次请求确实调用了目标工具。

• 方式二：首次响应包含 function_call 项；应用回传结果后，智能体给出自然语言回答。

• 如启用了追踪，可在追踪中确认工具调用发生。

排错

安全注意

• 把工具参数与工具输出视为不可信输入，使用前校验与清理。

• 不要在工具输出中放入密钥、令牌或连接字符串，只返回模型需要的数据。

• 为身份分配最小权限。

• 有写入或删除等副作用的操作，应要求用户明确确认。

限制与待核实

• 工具集与函数调用的预览状态、各工具的区域与模型支持：待核实（2026-11-05 获取）。

• 运行 10 分钟时限为官方函数调用页面的说明，待核实是否适用于所有运行形态。

• 官方工具集页面的完整操作步骤较长，本页只摘录主线，具体命令以官方页面为准。

来源与核对

• 来源：Create and manage a toolbox in Microsoft Foundry（https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/toolbox）

• 来源：Use function calling with Microsoft Foundry agents（https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/function-calling）

• 来源：What is Toolbox in Microsoft Foundry?（https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/toolbox-overview）

• 核对范围：正文已读（函数调用页正文已读；工具集操作页已读前置条件、版本与排错相关章节，未逐段核对全部代码）。