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

Foundry 智能体服务的智能体工具概述

工具扩展代理在 Microsoft Foundry 代理服务中可以执行的操作。代理本身使用 Foundry 模型来生成文本，但工具允许它采取措施 - 搜索 Web、运行代码、查询数据或调用自己的 API。本文介绍哪些工具、可用的工具类型、如何在代理中使用工具以及如何管理身份验证。它还介绍了发现和配置工具的 Foundry 工具目录。若要使用工具，需要访问 Foundry 项目并有权管理该项目中的工具。

注意

Foundry 工具目录和核心工具框架已正式发布。一些单独的工具仍处于预览状态，如本文中工具列表中所述。每个工具自己的页面也以横幅表示其预览状态。预览版工具受补充使用条款的约束。

什么是工具？

工具是代理可以在聊天期间调用以执行特定任务的功能。当代理收到用户消息时，为代理提供支持的 Foundry 模型根据代理的说明和可用的工具定义决定是否调用工具。代理发送工具请求，由您的应用程序或服务执行，结果将流回到对话中，以便代理可以继续使用准确、最新的信息。

工具使代理能够超越文本生成。例如，代理可以：

在回答之前，在 Web 上搜索当前信息。
运行Python代码以分析数据集并生成图表。
查询文档的向量存储，以将文档的响应记录在数据中。
调用外部 API 来查找客户记录或创建支持票证。

工具类型

Foundry 代理服务提供两类工具：内置工具，可在基本配置后使用，以及允许你自带功能的自定义工具。

内置工具

Foundry 代理服务提供内置工具作为预配置功能。在代理上启用这些工具，服务将处理执行。这些工具不需要外部托管或自定义代码。

最常用的内置工具包括：

Web 搜索 - 将 Web 搜索添加到代理。代理从公共 Web 检索实时数据，并使用内联引文返回答案。此方法是添加 Web 基础设置的推荐方式。有关市场特定筛选等高级场景，请参阅 Grounding with Bing 工具和 Web 基础概述。
Code 解释器 — 允许代理在沙盒环境中编写和运行Python代码，以便生成数据分析、数学和图表。
文件搜索 - 使用矢量搜索为代理提供从上传文件或专有文档中获取的知识。
函数调用 - 定义代理可以调用的自定义函数。应用程序执行函数并返回结果。

有关内置工具的完整列表，请参阅 “所有内置工具”。

自定义工具

使用自定义工具，您可以通过自己的 API、服务或其他代理，扩展您的代理功能或特性。当内置工具未涵盖你的方案时，请使用自定义工具。

最常见的自定义工具选项包括：

模型上下文协议（MCP） - 将代理连接到 MCP 服务器终结点上托管的工具。最适合跨多个智能体共享或由不同团队维护的工具。
代理到代理（A2A）（预览版） - 通过 A2A 兼容的终结点将代理连接到其他代理，以便进行跨代理通信。
OpenAPI 工具 - 使用 OpenAPI 3.0 或 3.1 规范将代理连接到外部 HTTP API。

有关自定义工具选项的完整列表，请参阅 “所有自定义工具”。

工具箱

toolbox是一组精选的工具捆绑包，例如 Web 搜索、Azure AI 搜索、代码解释器、文件搜索、MCP 服务器和 OpenAPI 工具，可以配置一次，并将其公开为单个 MCP 兼容的终结点。无需单独将每个工具附加到每个代理定义，而是在工具箱中定义集合，并将任何代理连接到工具箱终结点。由于工具箱公开了与 MCP 兼容的终结点，因此任何支持 MCP 的运行时都可以使用它-包括使用 Microsoft Agent Framework、LangGraph、GitHub Copilot SDK 和自定义代码生成的代理。

工具箱支持版本控制。创建多个版本，针对特定于版本的终结点测试新版本，然后在准备就绪时将其提升为默认值。连接到工具箱使用者终结点的代理会自动接收升级的默认版本，而无需更改代码。有关详细信息，请参阅 “管理工具箱版本”。

集中管理工具箱中工具的身份验证。工具箱使用 Microsoft Entra ID 和 OAuth 在运行时处理凭据注入、令牌刷新和策略强制实施，因此使用代理无需单独管理每个工具的凭据。有关身份验证详细信息，请参阅设置 MCP 服务器身份验证。

有关设置步骤，请参阅 “创建和使用 Foundry 工具箱”。

在软件代理中使用工具

若要将工具添加到代理，请在创建或更新代理定义时将其包含在代理的工具列表中。以下示例创建启用了 Web 搜索工具的代理并发送查询：

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, WebSearchTool

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create an agent with web search enabled
agent = project.agents.create_version(
    agent_name="web-search-agent",
    definition=PromptAgentDefinition(
        model="gpt-4.1-mini",
        instructions="You are a helpful assistant that can search the web.",
        tools=[WebSearchTool()],
    ),
)

# Send a query
response = openai.responses.create(
    input="What are the latest updates to Microsoft Foundry?",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)
print(response.output_text)

每个工具类型都有自己的配置。有关所有支持语言的详细设置和代码示例，请参阅“ 工具类型 ”部分中链接的单个工具操作指南。

使用结构化输入在运行时自定义工具行为

默认情况下，创建代理时会修复文件 ID、矢量存储 ID 和 MCP 服务器终结点等工具配置。工具属性中的结构化输入允许在运行时重写这些值，而无需创建新的代理版本。

结构化输入在以下情况下非常有用：

不同的用户需要基于其上下文的不同矢量存储或文件。
你希望跨环境重复使用相同的代理定义（开发、过渡、生产）。
MCP 服务器终结点或身份验证令牌因请求而异。

以下工具属性支持通过结构化输入进行自定义：

工具类型	财产	描述
`file_search`	`vector_store_ids`	矢量存储 ID 的数组。在程序运行时空值会被移除。
`code_interpreter`	`container`、`container.file_ids`	自动容器中的容器 ID 或文件 ID。在程序运行时空值会被移除。
`mcp`	`server_label`、 `server_url`、、 `headers`	MCP 服务器标签、URL 和 HTTP 标头值。

例如，具有模板化向量存储的代理定义：

{
  "tools": [
    {
      "type": "file_search",
      "vector_store_ids": ["vs_base_kb", "{{customer_kb}}"]
    }
  ],
  "structured_inputs": {
    "customer_kb": {
      "description": "Vector store ID for the customer's knowledge base",
      "required": true,
      "schema": { "type": "string" }
    }
  }
}

在运行时，提供实际值：

{
  "agent": { "type": "agent_reference", "name": "support-agent", "version": "1" },
  "input": [{ "type": "text", "text": "How do I upgrade my account?" }],
  "structured_inputs": {
    "customer_kb": "vs_premium_kb_2024"
  }
}

管理工具的身份验证

不同的工具需要不同的身份验证方法。了解这些选项有助于安全地连接工具。

内置工具

大多数内置工具（如代码解释器和文件搜索）通过 Foundry 代理服务自动进行身份验证，无需额外配置。连接到外部数据源（如Azure AI 搜索或SharePoint）的工具使用在 Foundry 项目中配置的 connections。

MCP 服务器

MCP 服务器支持多种身份验证方法，具体取决于服务器：基于密钥的身份验证（API 密钥或令牌）、Microsoft Entra身份验证（托管标识），以及用户级标识传递的 OAuth。

以下示例使用基于密钥的身份验证连接到 MCP 服务器。将凭据存储在项目连接中，然后在创建该工具时引用连接名称：

from azure.ai.projects.models import MCPTool

tool = MCPTool(
    server_label="github",
    server_url="https://api.githubcopilot.com/mcp",
    require_approval="always",
    project_connection_id="my-github-connection",
)

若要Microsoft Entra身份验证，请使用代理标识或项目托管标识而不是连接。服务自动请求令牌。对于 OAuth 身份穿透（每个用户的身份验证），代理服务会生成一个用户在首次使用时进行授权的同意链接。

有关所有方法的详细设置步骤，请参阅 “设置 MCP 服务器身份验证”。

提示

怀疑时，如果 MCP 服务器支持身份验证，请从Microsoft Entra身份验证开始。它无需管理机密并提供内置令牌轮换。

OpenAPI 工具

OpenAPI 工具支持匿名、API 密钥和托管标识身份验证。身份验证配置是工具定义的一部分。

匿名身份验证 - 当 API 不需要凭据时使用：

from azure.ai.projects.models import (
    OpenApiTool,
    OpenApiFunctionDefinition,
    OpenApiAnonymousAuthDetails,
)

weather_tool = OpenApiTool(
    openapi=OpenApiFunctionDefinition(
        name="get_weather",
        spec=openapi_spec,
        description="Retrieve weather information for a location.",
        auth=OpenApiAnonymousAuthDetails(),
    )
)

API 密钥身份验证 - 将密钥存储在项目连接中，然后引用它。 OpenAPI 规范必须包括 securitySchemes 和 security 节：

from azure.ai.projects.models import (
    OpenApiTool,
    OpenApiFunctionDefinition,
    OpenApiKeyAuthDetails,
)

api_tool = OpenApiTool(
    openapi=OpenApiFunctionDefinition(
        name="get_orders",
        spec=openapi_spec,
        description="Look up customer orders.",
        auth=OpenApiKeyAuthDetails(
            project_connection_id="my-api-connection"
        ),
    )
)

有关托管身份配置，请参阅将代理连接到 OpenAPI 工具。

提示

将所有凭据视为机密。仅提供必要的最小标头，不要在提示中包含凭据，并审查服务提供商的数据处理做法。有关控制措施（如 MCP 工具的速率限制和 IP 限制），请参阅使用 AI 网关管理 MCP 工具。

所有内置工具

下表列出了 Foundry 代理服务中提供的所有内置工具。

工具	描述
Web 搜索	从公共 Web 检索实时数据，并使用内联引文返回答案。
代码解释器	在沙盒环境中编写和运行Python代码。
自定义代码解释器（预览版）	自定义代码解释器的资源、Python包和容器应用环境。
文件搜索	使用上传文件或专有文档中的知识来增强代理。
Azure AI 搜索	使用来自现有 Azure AI 搜索索引的数据为智能体提供支持。
Azure Functions	使代理能够调用Azure Functions以执行自定义操作并检索动态数据。
函数调用	定义代理可以调用的自定义函数。应用执行函数并返回结果。
图像生成（预览版）	在对话和工作流中生成图像。
浏览器自动化（预览版）	通过自然语言提示执行浏览器任务。
计算机使用（预览版）	通过其用户界面与计算机系统交互。
Microsoft Fabric（预览版）	连接到 Microsoft Fabric 数据代理进行数据分析。
SharePoint（预览版）	与存储在SharePoint中的专用文档聊天。

提示

有关高级 Web 基础设置场景，请参阅 Grounding with Bing 工具和 Web 基础设置概述。

所有自定义工具

下表列出了用于将自己的功能连接到代理的所有自定义工具选项。

工具	描述
模型上下文协议（MCP）	将你的智能体连接到托管在 MCP 服务器终结点上的工具。
OpenAPI 工具	使用 OpenAPI 3.0 或 3.1 规范将代理连接到外部 API。
Agent-to-Agent (A2A)（预览版）	通过兼容 A2A 的终结点将你的智能体连接到其他智能体。
工具箱	将多个工具捆绑到单个 MCP 终结点，以便在代理之间重复使用。

关键概念

使用这些定义使术语保持一致：

术语	意义
Foundry 工具	可在其中发现、配置和管理代理工具的门户体验。
工具目录	可用工具（包括公共和组织工具）的可浏览列表。
专用工具目录	只有组织中的用户才能发现和配置的工具的组织范围目录。
MCP 服务器	使用模型上下文协议（MCP）公开工具的服务器。
远程 MCP 服务器	发布者托管的 MCP 服务器。通过提供所需的设置（例如终结点和身份验证详细信息）来配置它。
本地 MCP 服务器	你可以自行托管一个 MCP 服务器，并通过提供其远程终结点将其连接到 Foundry。
自定义工具	通过提供你自己的终结点或规范（例如，MCP 终结点、OpenAPI 规范或智能体对智能体 (A2A) 终结点）来添加的工具。
工具箱	一个精心挑选的工具集，配置一次后即可作为一个单一的 MCP 终结点提供，以便多个代理使用。

注意

如果你有兴趣将你的官方远程 MCP 服务器带到所有 Foundry 客户，请填写此表单。

使用非Microsoft服务和服务器时的注意事项

使用连接的非微软服务和服务器（“非微软服务”）受您与服务提供商之间条款的约束。非 Microsoft 产品是您使用 Microsoft 在线服务时适用的协议之下的非 Microsoft 服务。连接到非Microsoft 服务时，某些数据（如提示内容）会发送到非Microsoft服务，或者应用程序可能会从非Microsoft服务接收数据。你负责使用非微软服务和数据，以及与使用相关的任何费用。

第三方（而非 Microsoft 的公司）创建您选择连接的非 Microsoft 服务（包括远程 MCP 服务器）。 Microsoft不会测试或验证这些服务器。 Microsoft 对您或其他人使用任何非 Microsoft 服务不负任何责任。

仔细查看并跟踪添加到 Foundry 代理服务的 MCP 服务器。依赖于受信任的服务提供商本身托管的服务器，而不是代理。

MCP 工具可以传递远程 MCP 服务器可能需要进行身份验证的自定义标头。将任何凭据视为机密：

只需提供最低限度的必要标头。
不要在提示中包含凭据。
如果记录审核请求，请避免记录机密或敏感提示内容。
查看服务提供商的数据处理做法，包括数据保留和位置。

在门户中发现和管理工具

在 Foundry 门户中，转到项目并选择 “生成>工具 ”以打开 Foundry 工具。在此处，可以浏览工具目录、配置工具并将其添加到代理。如果需要仅在组织内可见的工具，请创建专用工具目录。

若要在构建的同时体验工具，请使用 Agents 沙盒。有关详细信息，请参阅 Microsoft Foundry Playgrounds。

目录中的工具类型

工具目录包括三种类型的条目：

远程 MCP 服务器：发布者托管服务器并提供静态或动态终结点。按照配置指南提供所需的设置，例如终结点和身份验证详细信息。

本地 MCP 服务器：自行托管服务器，然后通过提供其终结点将其连接到 Foundry。若要生成和注册自己的服务器，请参阅生成和注册 MCP 服务器。若要将 MCP 终结点连接到代理，请参阅 “连接到 MCP 服务器”。

Custom：从Azure逻辑应用连接器转换的 MCP 服务器。这些服务器需要其他配置才能转换为远程 MCP 服务器。

筛选和搜索

Foundry 工具提供以下筛选器，可帮助你找到正确的工具：

滤波器	描述
发布者	Microsoft或非Microsoft发布者
类别	数据库、分析、Web 等类别
注册表	公共：目录中的公共远程和本地 MCP 服务器。 Logic Apps 连接器：将 Azure 逻辑应用连接器转换为远程 MCP 服务器，以用于专用工具目录。
支持的身份验证	MCP 服务器支持的身份验证方法。有关详细信息，请参阅身份验证方法。

选择工具时，Foundry 工具会显示配置该工具所需的设置详细信息。

管理配置的工具

在工具列表中，可以找到配置的工具，以及终结点和身份验证设置等详细信息。还可以向代理添加工具。

在删除工具之前，请检查哪些代理使用它。删除工具可能会中断依赖于它的运行。

可用性和限制

工具可用性因模型和区域而异。

有关跨工具的最新模型和区域支持详细信息，请参阅有关在 Foundry 代理服务中使用工具的最佳做法。

故障排除

使用这些检查来解决常见问题：

找不到工具目录：确认你位于正确的项目中，然后转到“生成>工具”。
工具可见，但无法对其进行配置：查看该工具所需的身份验证和配置输入，并验证你是否有权访问任何依赖服务。
您的代理不调用工具：请参阅 Foundry 代理服务工具使用最佳实践中的验证指南。

反馈

此页面是否有帮助？

Last updated on 2026-05-06

Foundry 智能体服务的智能体工具概述

什么是工具？

工具类型

内置工具

自定义工具

工具箱

在软件代理中使用工具

使用结构化输入在运行时自定义工具行为

管理工具的身份验证

内置工具

MCP 服务器

OpenAPI 工具

所有内置工具

所有自定义工具

关键概念

使用非Microsoft服务和服务器时的注意事项

在门户中发现和管理工具

目录中的工具类型

筛选和搜索

管理配置的工具

可用性和限制

故障 排除

相关内容

反馈

其他资源

故障排除