将工具添加到 Azure AI 代理
Tip
有关更多详细信息,请参阅 “文本和图像 ”选项卡!
工具允许代理执行操作,即调用 API、执行代码、搜索文件或与外部服务交互。 如果没有工具,代理只能基于它已经知道的内容生成文本。 有了工具,它就能够对世界采取行动。
Microsoft Agent Framework 支持两大类工具:由提供方托管和管理的服务提供工具,以及由你自己编写并向代理注册的自定义函数工具。
服务提供的工具
使用 Foundry 提供程序时,无需任何额外的实现即可使用一系列托管工具。 通过在代理配置中包含它们来启用它们 , 提供程序将处理实际执行。
最常用的服务提供的工具包括:
| 工具 | 它的作用是什么 |
|---|---|
| 代码解释器 | 在沙盒环境中执行Python代码进行计算和数据分析 |
| 文件搜索 | 从上传的文档中搜索和检索信息 |
| Web 搜索 | 从互联网获取最新信息 |
| 托管 MCP 工具 | MCP(模型上下文协议)服务器由提供程序运行时直接调用 |
| Azure AI 搜索 | 通过 Foundry 连接查询Azure AI 搜索索引 |
| Foundry 工具箱 | 在 Foundry 项目中管理的已命名、带版本的托管工具配置包 |
注释
某些工具(包括 Azure AI 搜索、Bing Grounding、SharePoint 等)处于预览或实验阶段。 它们适用于 Foundry 代理,但对于其他提供商,支持可能有限。
自定义函数工具
使用自定义函数工具,可以使用所需的任何逻辑来扩展代理—调用内部 API、查询数据库、执行计算或Python函数可以执行的任何其他操作。
若要将函数注册为工具,可在创建过程中将其直接传递给代理。 该框架检查函数的签名并生成一个架构,该架构告知模型函数的作用、它期望的参数以及它返回的参数。
要使模型能够可靠地调用工具,需要清楚地描述函数。 代理框架支持两种方法:
-
带描述的类型注解——对每个参数使用 Python 的
Annotated类型,并添加字段描述。 函数的 docstring 用作工具说明。 -
@tool修饰器 - 显式指定工具的名称和说明作为修饰器参数,让你完全控制模型看到的内容。 如果需要精确控制输入结构,还可以使用 Pydantic 模型提供显式架构。
在任一情况下,框架都会自动处理架构生成和工具调用。 当模型确定应调用工具时,框架将执行该函数,并在生成最终响应之前将结果返回给模型。
添加多个工具
可以为单个代理注册多个工具。 在创建代理时传递函数列表,模型会自动为聊天的每个部分选择最合适的工具。 无需编写任何路由逻辑 - 框架基于聊天上下文和提供的工具说明处理工具业务流程。
工具审批
对于工具调用应在执行前需要人工评审的方案,代理框架支持 工具审批 模式。 在工具上启用审批模式时,代理会在调用该函数并请求确认之前暂停。 这对于不可逆、昂贵或涉及敏感数据的操作非常有用。 可以使用 approval_mode 装饰器上的 @tool 参数为每个工具配置审批行为。
使用代理作为工具
可以通过将一个代理用作另一个代理的工具来组合代理。 将内部代理转换为函数工具,并将其传递给外部代理,然后可将特定任务委托给外部代理。 这使得可以实现模块化设计,其中专用代理负责处理特定领域的任务,并由协调代理在这些代理之间路由请求——这一模式将在多代理模块中作更深入的探讨。
自定义工具的最佳做法
- 编写明确的说明 - 模型选择正确的工具的能力完全取决于你提供的说明。 具体说明函数的作用以及何时应使用它。
- 为每个参数添加说明——说明每个输入参数,以便模型能够生成有效的调用,尤其是在仅凭参数名称无法理解其含义时。
- 返回有意义的数据 - 工具应返回结构化的可解释输出。 模型在形成其响应时直接使用返回值。
- 使工具保持专注 — 每个工具都应做好一项工作。 将多个职责合并为单个函数会使模型难以正确调用它。
- 正常处理错误 — 如果工具遇到意外输入或外部服务失败,则返回信息性错误消息,而不是引发异常,以便模型可以有所帮助地做出响应。