Microsoft Foundry 工具箱是托管工具配置的命名、版本控制的服务器端捆绑包,例如代码解释器、文件搜索、图像生成、MCP 和 Web 搜索。 工具箱允许你在 Foundry 中管理工具配置一次,并在代理之间重复使用它。
代理框架支持 Toolbox 的使用。 通过 Foundry 门户或 azure-ai-projects SDK 创建和更新工具箱版本。
重要
FoundryToolbox 由 beta agent-framework-foundry-hosting 包提供,可以在稳定发布之前进行更改。
对于由服务管理的 FoundryAgent,请将工具箱附加到 Foundry 中的代理定义。
对于使用 Microsoft Agent Framework 构建的托管代理,请使用来自 Microsoft.Agents.AI.Foundry.Hosting 的 AddFoundryToolboxes,如以下示例所示。
使用一个启用了隐式 using 的 .NET 10 Web 项目,并确保 Microsoft.Agents.AI.Foundry、Microsoft.Agents.AI.Foundry.Hosting 和 DotNetEnv 的版本相互匹配。 将 TOOLBOX_NAME 设置为现有工具箱,将 FOUNDRY_MODEL 设置为你的模型部署。 Foundry 向已部署的主机提供 FOUNDRY_PROJECT_ENDPOINT。 对于本地模型访问,请使用Azure CLI设置FOUNDRY_PROJECT_ENDPOINT和登录。 托管部署回退到 azd 管理的 AZURE_AI_MODEL_DEPLOYMENT_NAME。 当 FOUNDRY_PROJECT_ENDPOINT 可用时,托管集成会加载工具箱工具。
using DotNetEnv;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;
// Load .env file if present (for local development)
Env.TraversePath().Load();
string endpoint = System.Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = FirstNonBlank(
System.Environment.GetEnvironmentVariable("FOUNDRY_MODEL"),
System.Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME"),
"gpt-4o")!;
string toolboxName = FirstNonBlank(
System.Environment.GetEnvironmentVariable("TOOLBOX_NAME"),
"my-toolset")!;
// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
// Use a chained credential: try a temporary dev token first (for local Docker debugging),
// then fall back to DefaultAzureCredential (for local dev via dotnet run / managed identity in production).
.AsAIAgent(
model: deploymentName,
Use the available tools to answer user questions.
If a tool is not available for a request, let the user know clearly.
""",
name: System.Environment.GetEnvironmentVariable("AGENT_NAME") ?? "hosted-toolbox-agent",
description: "Hosted agent backed by Foundry Toolbox MCP tools");
// ── Build the host ────────────────────────────────────────────────────────────
var builder = WebApplication.CreateBuilder(args);
// Register the agent and response handler
// Register Foundry Toolbox: connects to the MCP proxy at startup and makes tools available.
// The toolbox name must match a toolbox registered in your Foundry project.
// When FOUNDRY_PROJECT_ENDPOINT is absent (e.g., in local development without Foundry
// infrastructure), startup succeeds without error and no toolbox tools are loaded.
#if USE_LOCAL_AGENT_FRAMEWORK_SOURCE
#endif
var app = builder.Build();
app.MapFoundryResponses();
app.Run();
同一托管注册支持那些在其工具箱连接上配置为按用户进行 OAuth 同意的工具。 用户仍然需要具备所需的权限并获得同意;不需要单独的主机注册限制。
有关项目文件和部署说明,请参阅 Hosted-Toolbox。 有关按用户进行的同意配置,请参阅 Hosted-Toolbox-AuthPaths。
安装软件包
pip install agent-framework-foundry-hosting agent-framework-foundry --pre
FoundryToolbox从agent_framework.foundry导入,由agent-framework-foundry-hosting提供。
配置工具箱
为 Toolbox MCP 明确设置一个端点:
TOOLBOX_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<name>/mcp?api-version=v1"
或者让 FoundryToolbox 构造终结点:
FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
TOOLBOX_NAME="<toolbox-name>"
托管代理示例在本地优先使用 FOUNDRY_MODEL,并在托管时回退到由 azd 管理的 AZURE_AI_MODEL_DEPLOYMENT_NAME。
使用 Azure 开发人员 CLI 部署示例
当前Python示例使用一个azure.yaml来定义托管代理、连接、工具箱和环境变量映射。 将 Azure 开发人员 CLI 1.34.2 或更高版本与统一的 microsoft.foundry 扩展配合使用:
azd ext install microsoft.foundry
azd provision
azd deploy --all
请先进行预配,以便 Foundry 项目的托管标识在管理员授予连接的 Azure 资源所需角色之前存在。 从包含 azure.yaml的初始化项目目录运行后续命令。
对于配置了 Entra 直通的工具,Foundry 会转发当前调用方的标识。 调用方仍需要访问目标资源,托管应用程序必须转发平台调用上下文,而不是重用先前请求的标头。
有关完整的环境、角色分配、本地运行、部署和调用序列,请参阅 Python Foundry 工具箱示例。
启用工具箱工具搜索
工具箱工具搜索使模型的初始工具列表保持较小。 将 ToolSearchToolboxTool 添加到包含其 MCP 工具的工具箱版本中。 模型最初可以看到 tool_search , call_tool然后根据需要发现基础 MCP 工具。
在运行此示例之前升级 Foundry SDK:
pip install --upgrade "azure-ai-projects>=2.4.0"
Python示例使用 2.4.0 或更高版本创建一个同时包含 和 的新工具箱版本。 它连接到该确切版本,不会删除现有版本。 如果希望在运行开始时显示完整的基础工具列表,请删除工具搜索条目。
请参阅 Foundry Chat Client with Toolbox tool search 了解版本创建和 MCP 连接模式。
将 FoundryToolbox 与托管代理配合使用
FoundryToolbox解析其终结点,使用提供的Azure凭据对每个 MCP 请求进行身份验证,转发 Foundry 每请求调用 ID,并参与代理的连接生命周期。 它会解析每个操作边界上的平台标头,并在有效请求标识发生更改时重新连接其 MCP 会话。 因此,长期存在的 Toolbox 不会保留先前调用方的呼叫 ID。
示例在请求范围的智能体工厂中创建工具箱、客户端和凭据,以实现确定性的所有权和清理。 当相关资源由请求拥有时,使用此工厂模式,但它不是仅用于保持工具箱调用 ID 最新的必需项。
import asyncio
import os
from contextlib import AsyncExitStack
from types import TracebackType
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.ai.agentserver.core import AgentConfig, get_request_context
from azure.identity.aio import AzureCliCredential, ManagedIdentityCredential
from dotenv import load_dotenv
def create_agent() -> Agent:
"""Create request-owned SDK resources and close them with the agent."""
endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model = os.environ.get("FOUNDRY_MODEL") or os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
credential = (
ManagedIdentityCredential(client_id=os.environ.get("FOUNDRY_AGENT_INSTANCE_CLIENT_ID"))
if AgentConfig.from_env().is_hosted
else AzureCliCredential()
)
class RequestClient(FoundryChatClient):
async def __aenter__(self) -> RequestClient:
return self
async def __aexit__(
self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None
) -> None:
async with AsyncExitStack() as cleanup:
cleanup.push_async_callback(credential.close)
cleanup.push_async_callback(self.project_client.close)
cleanup.push_async_callback(self.client.close)
toolbox = FoundryToolbox(credential)
client = RequestClient(
project_endpoint=endpoint,
model=model,
credential=credential,
default_headers=get_request_context().platform_headers(),
)
return Agent(
client=client,
instructions="You are a friendly assistant. Keep your answers brief.",
tools=toolbox,
)
async def main() -> None:
load_dotenv()
server = ResponsesHostServer(agent=create_agent, history_source="agent_server")
await server.run_async()
当工具箱代码解释器生成一个文件且助手响应中提及该文件名时,托管的响应适配器会发出包含容器和文件 ID 的本机 container_file_citation 批注。 响应客户端可以使用这些 ID 通过容器文件 API 发现并下载生成的文件。
公开工具箱技能
工具箱可以通过 MCP 公开代理技能。 如果只有技能应对模型可见,请设置load_tools=False,然后将工具箱添加为工具,以便其 MCP 会话建立连接,并将as_skills_provider()用作上下文提供程序。
import asyncio
import os
from contextlib import AsyncExitStack
from types import TracebackType
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.ai.agentserver.core import AgentConfig, get_request_context
from azure.identity.aio import AzureCliCredential, ManagedIdentityCredential
from dotenv import load_dotenv
def create_agent() -> Agent:
"""Keep skill caches, credentials and the MCP lifecycle request-owned."""
endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model = os.environ.get("FOUNDRY_MODEL") or os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
credential = (
ManagedIdentityCredential(client_id=os.environ.get("FOUNDRY_AGENT_INSTANCE_CLIENT_ID"))
if AgentConfig.from_env().is_hosted
else AzureCliCredential()
)
class RequestClient(FoundryChatClient):
async def __aenter__(self) -> RequestClient:
return self
async def __aexit__(
self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None
) -> None:
async with AsyncExitStack() as cleanup:
cleanup.push_async_callback(credential.close)
cleanup.push_async_callback(self.project_client.close)
cleanup.push_async_callback(self.client.close)
# tools= connects the MCP session; context_providers= reads skills from that same session.
toolbox = FoundryToolbox(credential, load_tools=False)
skills_provider = toolbox.as_skills_provider(disable_load_skill_approval=True)
client = RequestClient(
project_endpoint=endpoint,
model=model,
credential=credential,
default_headers=get_request_context().platform_headers(),
)
return Agent(
client=client,
name=os.environ.get("AGENT_NAME", "hosted-toolbox-mcp-skills"),
instructions="You are a helpful assistant.",
tools=toolbox,
context_providers=[skills_provider],
)
async def main() -> None:
load_dotenv()
server = ResponsesHostServer(agent=create_agent, history_source="agent_server")
await server.run_async()
技能操作的审批功能默认保持启用。 仅在受信任的无人值守场景中禁用单独审批。
将工具箱及其技能提供程序放在一起,以便两者都使用相同的 MCP 会话。 对于长期存在的工具箱,当有效的平台标头标识更改时,技能发现缓存将被替换。 与技能一起使用的自定义 header_provider 必须从环境状态解析,例如闭包或 ContextVar,因为技能和资源读取不接收函数运行时参数。
使用带有 FoundryAgent 的工具箱
将工具箱附加到 Foundry 中的提示代理或托管代理定义。
FoundryAgent使用已存储的工具配置;在客户端传递工具箱不会将其添加到托管代理。
通过 MCP 与FoundryToolbox连接
使用 FoundryToolbox 配合 ResponsesHostServer,将托管代理连接到 Toolbox MCP 终结点。 该包装器对 MCP 请求进行身份验证,并转发当前托管请求的调用方上下文,以实现按用户的身份透传。
当客户端、凭据和工具箱需要一个清理边界时,请求范围的 agent 工厂仍然是最简单的选项。 还支持长期存在的 Toolbox,并且当平台标头标识发生更改时,会在操作前重新连接。
import asyncio
import os
from contextlib import AsyncExitStack
from types import TracebackType
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.ai.agentserver.core import AgentConfig, get_request_context
from azure.identity.aio import AzureCliCredential, ManagedIdentityCredential
from dotenv import load_dotenv
def create_agent() -> Agent:
"""Create request-owned SDK resources and close them with the agent."""
endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model = os.environ.get("FOUNDRY_MODEL") or os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
credential = (
ManagedIdentityCredential(client_id=os.environ.get("FOUNDRY_AGENT_INSTANCE_CLIENT_ID"))
if AgentConfig.from_env().is_hosted
else AzureCliCredential()
)
class RequestClient(FoundryChatClient):
async def __aenter__(self) -> RequestClient:
return self
async def __aexit__(
self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None
) -> None:
async with AsyncExitStack() as cleanup:
cleanup.push_async_callback(credential.close)
cleanup.push_async_callback(self.project_client.close)
cleanup.push_async_callback(self.client.close)
toolbox = FoundryToolbox(credential)
client = RequestClient(
project_endpoint=endpoint,
model=model,
credential=credential,
default_headers=get_request_context().platform_headers(),
)
return Agent(
client=client,
instructions="You are a friendly assistant. Keep your answers brief.",
tools=toolbox,
)
async def main() -> None:
load_dotenv()
server = ResponsesHostServer(agent=create_agent, history_source="agent_server")
await server.run_async()
设置 TOOLBOX_ENDPOINT,或同时设置 FOUNDRY_PROJECT_ENDPOINT 和 TOOLBOX_NAME,如 配置工具箱 中所述。 为本地运行设置 FOUNDRY_MODEL;托管部署将回退到由 azd 管理的 AZURE_AI_MODEL_DEPLOYMENT_NAME。
处理 OAuth 同意请求
当工具箱或 MCP 操作需要 OAuth 同意时,流式处理和非流式处理 FoundryAgent,FoundryChatClient 调用会返回带有同意链接的 Content(type="oauth_consent_request"),而不是空助手消息。 将此内容作为用户输入请求处理,并将其 consent_link 呈现给用户。
客户端仅显示具有 HTTPS 协议和有效主机的链接。 缺少或无效的链接将被忽略并记录。
Limitations
- 工具箱中的 MCP 工具通过 Foundry
project_connection_id使用服务器端身份验证;代理框架客户端不保存上游 MCP 持有者令牌。 - 将 Toolbox 用作 MCP 服务器时,需要对 Toolbox 端点进行客户端 Entra ID 身份验证。
- 同意流响应(例如
CONSENT_REQUIRED,在代理运行时处理),而不是在创建工具箱连接时处理。
Samples
| Sample | 说明 |
|---|---|
| foundry_toolbox/main.py |
FoundryToolbox 使用托管响应代理 |
| foundry_toolbox_mcp_skills/main.py | 由工具箱支持的代理技能 |
| foundry_chat_client_with_toolbox.py | 根据 MCP 通过 tool_search 和 call_tool 按需发现工具箱 |
| foundry_chat_client_with_toolbox_skills.py | 由工具箱支持的技能配置 |
| invoke_foundry_toolbox_mcp | 工作流端 MCP 消耗 |
Go 可以调用附加了工具箱的服务托管代理,或通过标准 MCP 集成使用工具箱终结点。 它不提供其他选项卡中显示的专用 FoundryToolbox 或 AddFoundryToolboxes 帮助程序。
将工具箱与服务管理的智能体配合使用
将工具箱附加到 Foundry 中的代理定义,然后通过 foundryprovider.NewAgent 和 foundryprovider.ServerAgent("<agent-name>") 调用该现有代理。 该服务拥有存储的 Toolbox 配置。
将单个本地或托管工具声明传递给模型部署代理不会附加工具箱。 有关建立连接,请参阅 现有的服务器端 Foundry 代理。
通过 MCP 进行连接
若要从应用程序管理的 Go 智能体使用工具箱工具:
- 获取现有工具箱的 MCP 终结点。
- 将应用程序拥有的 HTTP 客户端配置为使用Azure凭据
https://ai.azure.com/.default对工具箱请求进行身份验证。 根据需要刷新令牌,并将凭据转发限制到预期的工具箱终结点。 - 通过
mcp.StreamableClientTransport.HTTPClient传入该客户端,并在Endpoint中指定工具箱终结点。 - 调用
mcptool.Connect,然后mcptool.ListTools,并在agent.Config.Tools中注册返回的工具。 - 在代理使用其工具时,保持 MCP 会话打开,并在这些操作完成后将其关闭。
这遵循与本地 MCP 工具相同的发现和调用模式。 请参阅“连接到 MCP 服务器”以获取 Go 传输和工具注册 API。
Go 集成限制
通用 Go MCP 集成不提供托管的工具箱生命周期、平台标头标识转发或工具箱支持的技能适配器,如.NET和Python示例中所述。 在应用程序中配置身份验证和资源所有权,而不是假设这些帮助程序自动运行。