你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

将工具箱与托管智能体配合使用

托管代理在 Foundry 代理服务中运行代码。 在本文中，你将该代码连接到 工具箱 ，以便代理通过一个模型上下文协议 （MCP） 终结点发现和调用工具箱工具。

如果你使用像 GitHub Copilot 这样的编码代理，Microsoft Foundry Skill 可以帮助将托管的代理连接到工具箱端点，并使该示例适配你自己的工具。

Prerequisites

  • 具有至少一个工具和默认版本的 工具箱 。
  • 具有已部署模型的 Microsoft Foundry 项目。
  • 托管代理项目。 若要一起创建代理和工具箱，请完成 工具箱快速入门。
  • 可以访问 Foundry 项目的开发标识。 在运行示例前，请使用 az login 或 azd auth login 在本地登录。
  • 工具箱工具背后的服务所需的任何权限。 对于使用 OAuth 或Microsoft Entra标识直通的工具，请在部署代理之前查看工具箱身份验证。

选择工具箱终结点

对于应遵循工具箱的 default_version 的智能体，请使用工具箱使用者终结点：

https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/mcp?api-version=v1

将另一个工具箱版本提升为默认值时，使用此终结点的代理将获取新版本，而无需更改或重新部署终结点。

仅当您需要在提升前测试不可变版本时，才使用特定版本的开发者端点：

https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1

验证代理在工具箱中的身份

代理使用其 Microsoft Entra 身份和 https://ai.azure.com/.default 作用域向工具箱终结点进行身份验证。 每个工具箱工具的连接确定哪个标识或凭据会到达下游服务。

不要在代理代码中放置下游 API 密钥或 OAuth 令牌。 在工具箱工具引用的项目连接上配置这些凭据。 有关支持的身份验证类型、同意和角色要求的详细信息，请参阅 工具箱身份验证。

连接托管代理

使用 Microsoft 代理框架

维护的 Python 示例使用了 Agent Framework 托管包中的 FoundryToolbox。 该类从 TOOLBOX_ENDPOINT 或从 FOUNDRY_PROJECT_ENDPOINT 和 TOOLBOX_NAME 解析工具箱。 它还对 MCP 请求进行身份验证，并转发托管运行时的每个请求调用 ID。

在初始化示例之前，请安装 Python 3.12 或更高版本、Azure开发人员 CLI （azd） 1.25 或更高版本和microsoft.foundry扩展。

  1. 基于 托管代理工具箱示例初始化一个项目：

    mkdir my-toolbox-agent && cd my-toolbox-agent
azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/azure.yaml

  2. 设置工具箱名称。 此示例从项目终结点构造使用者终结点，并使用以下名称：

    azd env set TOOLBOX_NAME <toolbox-name>

  3. 在本地运行代理：

    azd ai agent run

  4. 在另一个终端中，验证代理是否发现工具箱工具：

    azd ai agent invoke --local "List the tools you can use and briefly describe each one."

响应列出了工具箱从 MCP tools/list返回的工具。 如果响应不包含工具箱工具，请参阅 连接疑难解答。

使用 LangGraph

使用 LangGraph 生成托管代理代码时使用 AzureAIProjectToolbox 。 该集成会将工具箱中的工具加载为 LangChain 工具，并负责消费端端点的身份验证。

  1. 安装 LangChain Azure集成及其托管依赖项：

    pip install "langchain-azure-ai[hosting]>=1.2.8"

  2. 在托管代理环境中设置 FOUNDRY_PROJECT_ENDPOINT 。 运行时在部署后提供此值。 自行对其设置以用于本地开发。

  3. 按工具箱名称加载工具：

import asyncio

from langchain_azure_ai.tools import AzureAIProjectToolbox

async def load_tools():
   toolbox = AzureAIProjectToolbox(toolbox_name="<toolbox-name>")
   tools = await toolbox.get_tools()
   print("\n".join(tool.name for tool in tools))

asyncio.run(load_tools())

输出包含工具箱从 MCP tools/list返回的名称：

<tool-name>
<tool-name>

参考：AzureAIProjectToolbox

  1. 将加载的工具传递给你的 LangGraph 智能体，并运行需要使用一个工具箱工具的提示。 有关完整的实现，请参阅 LangGraph 工具箱示例。

使用 Agent Framework Foundry 托管集成按名称注册工具箱。 AddFoundryToolboxes 根据 FOUNDRY_PROJECT_ENDPOINT 构建消费者端点，在启动时调用 MCP tools/list，并将已发现的工具添加到每个代理请求中。

运行维护的示例之前，请安装 .NET 10 SDK 和Azure CLI。

  1. 从公共 托管工具箱示例开始，或将 Foundry 托管包添加到现有的 Agent Framework 主机。

  2. 为本地开发设置以下环境变量：

    AZURE_AI_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
AZURE_AI_MODEL_DEPLOYMENT_NAME=<model-deployment-name>
TOOLBOX_NAME=<toolbox-name>

    Foundry 向已部署的容器提供 FOUNDRY_PROJECT_ENDPOINT。 将工具箱名称保留在 TOOLBOX_NAME 中；其他 FOUNDRY_* 变量名称由托管运行时预留。

  3. 在 Program.cs 中，使用 AddFoundryResponses 注册代理，然后再使用 AddFoundryToolboxes(credential, toolboxName) 注册工具箱。 构建 Web 应用程序后，请在调用 Run 之前先调用 MapFoundryResponses。 公开示例包括所需的导入、包、代理构建和凭据设置。

  4. 启动主机，然后使用需要工具箱工具的提示调用它。 当主机无法枚举工具箱工具时，/readiness 终结点会返回不健康状态。

本文中的托管代理工具箱集成适用于Python和.NET。 若要从另一个运行时调用 MCP 终结点，请使用 MCP Streamable HTTP 客户端，使用令牌 https://ai.azure.com/.default进行身份验证，并实现托管代理运行时协定。

本文中的托管代理工具箱集成适用于Python和.NET。 若要从另一个运行时调用 MCP 终结点，请使用 MCP Streamable HTTP 客户端，使用令牌 https://ai.azure.com/.default进行身份验证，并实现托管代理运行时协定。

使用 Microsoft Foundry Toolkit for Visual Studio Code 为连接到工具箱的托管代理示例搭建基架。

在搭建项目基架之前，安装 Visual Studio Code、Microsoft Foundry Toolkit 扩展和编程语言的扩展包。

  1. 在活动栏中，选择 Foundry Toolkit。
  2. 在 “我的资源”下，展开项目，然后展开 “工具”。
  3. 在 “工具箱 ”选项卡上，找到工具箱，然后选择 基架代码模板。
  4. 在命令面板中，选择项目文件夹。
  5. 打开生成的 README.md，然后完成其本地运行和部署步骤。
  6. 运行需要工具箱工具的提示，并确认代理调用预期的工具。

将工具箱名称传递给一个托管智能体示例，该示例利用 FOUNDRY_PROJECT_ENDPOINT 构建使用者终结点：

运行这些命令之前，请安装 Azure Developer CLI （azd） 1.25 或更高版本和microsoft.foundry扩展。

  1. 检查工具箱及其当前默认版本：

    azd ai toolbox show <toolbox-name> --output json

    输出使用 endpoint 属性。 此命令返回的终结点标识所选版本，并可用于测试该版本。

  2. 将工具箱名称存储在 azd 环境中：

    azd env set TOOLBOX_NAME <toolbox-name>

  3. 若要在本地运行托管代理，请使用：

    azd ai agent run

    若要改为部署托管代理，请使用：

    azd deploy

如果您的应用程序仅接受完整的 URL，请将 TOOLBOX_ENDPOINT 设置为选择工具箱终结点中未版本化的使用者终结点。

强制实施工具审批

MCP tools/list 返回的每个条目可以包含一个 _meta.tool_configuration.require_approval 值：

价值 所需的运行时行为
always 向用户显示建议的工具名称和参数，等待显式批准，并仅在审批后调用该工具。 对每次调用重复此过程。
never 在没有审批提示的情况下调用该工具。

当require_approval为always时，工具箱 MCP 端点不会阻止tools/call。 代理运行时必须在每次调用之前强制实施该设置。 仅系统提示指令不强制批准。

使用 require_approval: never，除非你的运行时环境能够暂停待处理的工具调用、获取用户的决定，然后恢复或拒绝该调用本身。 若要在工具箱工具上配置值，请参阅 “配置工具审批”。

排查连接问题

症状 原因和解决方法
智能体未返回工具箱工具。 确认工具箱具有默认版本，工具箱名称匹配，代理标识可以访问 Foundry 项目。
启动或就绪失败。 工具箱会统一列出其所有工具来源。 检查代理日志中是否存在失败的连接、不可用的 MCP 服务器或无效的允许工具名称。 修复或删除该源、创建新版本并对其进行升级。
工具返回 401 或 403。 验证在工具的项目连接上配置的代理到工具箱标识和下游身份验证。 这些是单独的授权边界。
工具请求同意。 将同意请求返回到已登录用户，并在同意后恢复呼叫。 查看 工具箱身份验证中的租户和角色要求。
不会显示版本更改。 确认智能体使用未版本化的使用者终结点，并将预期版本提升为 default_version。

相关内容

  • Last updated on