Microsoft Foundry

入门

将所需的 NuGet 包添加到项目。

dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.Foundry --prerelease

两种代理类型

Microsoft Foundry 集成公开两种不同的使用模式：

类型	生成的类型	说明	何时使用
响应代理	ChatClientAgent	你的应用通过编程方式在运行时提供 AIProjectClient.AsAIAgent(...)模型、说明和工具。 未创建服务器端代理资源。	你拥有代理定义，并且需要一个简单的灵活设置。 这是大多数示例中使用的模式。
Foundry 智能体（版本化）	FoundryAgent	服务器管理的 - 智能体定义通过 Foundry 门户或通过 AIProjectClient.AgentAdministrationClient 编程方式创建和版本化。 将ProjectsAgentVersion或ProjectsAgentRecord或AgentReference传递给AIProjectClient.AsAIAgent(...)。	需要通过服务 API 在 Foundry 门户中管理严格版本控制的代理定义

响应代理 （直接推理）

通过模型和说明对 AIProjectClient 直接使用 AsAIAgent。 对于大多数情景，这是推荐的起点。

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
        .AsAIAgent(
            model: "gpt-4o-mini",
            name: "Joker",
            instructions: "You are good at telling jokes.");

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

此路径为代码优先，不会创建服务器管理的代理资源。

Foundry 智能体（版本化）

使用 AI Projects SDK 中的原生 AIProjectClient.AgentAdministrationClient API 检索版本控制的代理资源，然后用 AsAIAgent 进行包装。 可以直接在 Foundry 门户中创建和配置代理，也可以通过编程方式创建 AIProjectClient.AgentAdministrationClient和配置代理。

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry;

var aiProjectClient = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential());

// Retrieve an existing agent by name (uses the latest version automatically)
ProjectsAgentRecord jokerRecord = await aiProjectClient.AgentAdministrationClient.GetAgentAsync("Joker");
FoundryAgent agent = aiProjectClient.AsAIAgent(jokerRecord);

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

使用代理

ChatClientAgent （响应）和FoundryAgent（版本控制）都是标准AIAgent实例，支持所有标准操作，包括会话、工具、中间件和流式处理。

AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke.", session));
Console.WriteLine(await agent.RunAsync("Now make it funnier.", session));

有关如何运行和与代理交互的详细信息，请参阅 代理入门教程。

Tools

从 AIProjectClient.AsAIAgent(...) （响应路径）创建的 Foundry 代理支持标准代理框架工具图面 - 请参阅 工具概述 ，了解完整列表和支持的功能矩阵。 对于从带版本的代理定义（FoundryAgent）加载的 Foundry 代理，其工具归 Foundry 代理定义所有，而非归客户端所有。

工具	备注
函数工具	Supported.
工具审批	Supported. 由框架的函数调用聊天客户端提供。
代码解释器	Supported.
文件搜索	Supported.
托管 MCP 工具	Supported.
本地 MCP 工具	Supported.
Foundry 工具箱	Supported.

工具箱

Python 中的 Foundry

在 Python 中，所有特定于 Foundry 的客户端现在都位于 agent_framework.foundry 下。

• agent-framework-foundry 提供云 Foundry 连接器： FoundryChatClient、 FoundryAgent、 FoundryEmbeddingClient和 FoundryMemoryProvider。
• agent-framework-foundry-local 提供用于本地模型执行的FoundryLocalClient。

Python中的 Foundry 聊天和代理模式

情景	Python形状	何时使用
使用 Foundry 响应端点进行简单推理	Agent(client=FoundryChatClient(...))	你的应用拥有代理定义、工具和聊天循环，并且你想要在 Foundry 项目中部署模型。
Foundry 智能体服务中的服务管理智能体	FoundryAgent(...)	你想连接到在 Foundry 门户或通过服务 API 创建和配置的 PromptAgent 或 HostedAgent。

安装

pip install agent-framework-foundry
pip install azure-identity

同一个 agent-framework-foundry 包还包括用于 Foundry 模型终结点嵌入的 FoundryEmbeddingClient。

配置

FoundryChatClient

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_MODEL="gpt-4o-mini"

FoundryAgent

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_AGENT_NAME="my-agent"
FOUNDRY_AGENT_VERSION="1.0"

对 Prompt 智能体使用 FOUNDRY_AGENT_VERSION。 托管代理可以省略它。

FoundryEmbeddingClient

FOUNDRY_MODELS_ENDPOINT="https://<apim-instance>.azure-api.net/<foundry-instance>/models"
FOUNDRY_MODELS_API_KEY="<api-key>"
FOUNDRY_EMBEDDING_MODEL="text-embedding-3-small"
FOUNDRY_IMAGE_EMBEDDING_MODEL="Cohere-embed-v3-english"  # optional

FoundryChatClient 和 FoundryAgent 使用项目终结点。 FoundryEmbeddingClient 使用单独的模型终结点。

选择正确的Python客户端

情景	首选客户端	备注
Azure OpenAI 资源	OpenAIChatCompletionClient / OpenAIChatClient	使用 OpenAI 提供者页面。
Microsoft Foundry 项目推断	Agent(client=FoundryChatClient(...))	使用 Foundry 响应终结点。
Microsoft Foundry 服务管理智能体。	FoundryAgent	推荐用于 Prompt 智能体和 HostedAgents。
Microsoft Foundry 模型与端点嵌入	FoundryEmbeddingClient	使用 FOUNDRY_MODELS_ENDPOINT 加 FOUNDRY_EMBEDDING_MODEL / FOUNDRY_IMAGE_EMBEDDING_MODEL 。
Foundry 本地执行环境	Agent(client=FoundryLocalClient(...))	请参阅 Foundry Local。

使用 FoundryChatClient 创建代理

FoundryChatClient 连接到 Foundry 项目中的已部署模型，并使用响应终结点。 当应用应拥有指令、工具和会话处理时，将其与标准 Agent 配对。

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(
        project_endpoint="https://your-project.services.ai.azure.com",
        model="gpt-4o-mini",
        credential=AzureCliCredential(),
    ),
    name="FoundryWeatherAgent",
    instructions="You are a helpful assistant.",
)

FoundryChatClient是用于直接推理的 Foundry 优先Python路径，支持工具、结构化输出和流式处理。

Tools

FoundryChatClient 为每个托管的 Foundry 工具提供静态工厂方法。 工厂返回 SDK 工具对象，你传递给 Agent 上的 tools= 或直接传递给 client.get_response(..., tools=[...])。 对于 FoundryAgent，智能体的工具位于 Foundry 智能体定义本身 - 请参阅 FoundryAgent 中哪些可行哪些不可行。

工厂是类方法，因此你不需要实例即可创建工具：

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(credential=AzureCliCredential()),
    instructions="You can search the web and run code.",
    tools=[
        FoundryChatClient.get_web_search_tool(),
        FoundryChatClient.get_code_interpreter_tool(),
    ],
)

工具支持

下表列出了Python FoundryChatClient今天公开的每个工具。 FoundryAgent 使用相同的工具，但必须在 Foundry 代理定义上配置它们，而不是传入代码。

工具	FoundryChatClient 上的工厂	Status	详情
函数工具	不适用 - 传递任何 Python 可调用对象或 @ai_function	GA	在Python进程中本地调用。
工具审批	n/a - 包装现有工具	GA	可与托管 MCP 和函数工具配合使用。
代码解释器	get_code_interpreter_tool	GA	在 Foundry 上进行沙盒代码执行。
文件搜索	get_file_search_tool	GA	通过 Foundry 矢量存储搜索上传的文件。
Web 搜索	get_web_search_tool	GA	由 Microsoft 管理的 Bing 支持的 Web 基础设置。 仅限 Azure OpenAI 模型。
图像生成	get_image_generation_tool	GA	由 Foundry 托管的图像生成功能。
托管式 MCP	get_mcp_tool	GA	Foundry 调用的远程 MCP 服务器。
本地 MCP	n/a — 使用 MCPStreamableHTTPTool / MCPStdioTool	GA	在进程中运行;适用于任何客户端。
Foundry 工具箱	MCPStreamableHTTPTool 到工具箱 MCP 终结点	GA	通过 MCP 从 FoundryChatClient 使用，在 FoundryAgent 上附加在服务器端。
必应基础设置	get_bing_grounding_tool	Experimental	自带使用必应搜索进行基础设置资源。
必应自定义搜索	get_bing_custom_search_tool	Preview	必应基础设置限制为精选域列表。
Azure AI 搜索	get_azure_ai_search_tool	Experimental	通过 Foundry 连接搜索Azure AI 搜索索引。
SharePoint	get_sharepoint_tool	Preview	在 SharePoint 内容中搜索事实依据答案。
Microsoft Fabric	get_fabric_tool	Preview	查询 Fabric 数据智能体。
内存搜索	get_memory_search_tool	Preview	搜索 Foundry 托管的内存存储库。
计算机应用	get_computer_use_tool	Preview	让代理驱动桌面或浏览器环境。
浏览器自动化	get_browser_automation_tool	Preview	通过 Azure Playwright 连接控制浏览器。
代理对代理（A2A）	get_a2a_tool	Preview	调用另一个 A2A 代理作为工具。

网络搜索变体

Foundry 公开三种 Bing 支持的基础设置选项。 选择符合您情况的选项：

• get_web_search_tool (GA) - 零设置默认；Microsoft 管理的 Bing 资源。 仅限 Azure OpenAI 模型。 限制为 user_location 和 search_context_size。
• get_bing_grounding_tool（实验性）- 自带使用必应搜索进行基础设置 Azure 资源。 支持 count、 freshness、 market、 set_lang和非 OpenAI Foundry 模型。
• get_bing_custom_search_tool（预览版）- 自带必应自定义搜索实例，以将基础设置限制为精选域集。

这三者都在Azure符合性边界之外发送搜索数据。 有关完整比较，请参阅 Web 基础概述 。

client = FoundryChatClient(credential=AzureCliCredential())

# Default (GA): minimal configuration
web_search = client.get_web_search_tool(
    user_location={"city": "Amsterdam", "country": "NL"},
    search_context_size="medium",
)

图像生成

get_image_generation_tool 配置 Foundry 的托管映像生成工具。 模型在响应中生成图像内容 - 没有额外的文件可以管理。

image_gen = FoundryChatClient.get_image_generation_tool(
    model="gpt-image-1",
    size="1024x1024",
    output_format="png",
    quality="high",
)

必应基础设置

get_bing_grounding_tool 包装使用必应搜索进行基础设置 Foundry 工具。 你自己创建使用必应搜索进行基础设置资源并将其添加为 Foundry 项目连接，然后传递连接 ID。

bing = FoundryChatClient.get_bing_grounding_tool(
    connection_id="/subscriptions/.../connections/my-bing",
    market="en-US",
    freshness="Day",
    count=10,
)

必应自定义搜索

get_bing_custom_search_tool 将基础设置为在必应自定义搜索资源上定义的允许列表。

bing_custom = FoundryChatClient.get_bing_custom_search_tool(
    connection_id="/subscriptions/.../connections/my-bing-custom",
    instance_name="docs-only",
    market="en-US",
)

Azure AI 搜索

get_azure_ai_search_tool允许代理通过 Foundry 项目连接查询Azure AI 搜索索引。

ai_search = FoundryChatClient.get_azure_ai_search_tool(
    index_connection_id="/subscriptions/.../connections/my-search",
    index_name="product-docs",
    query_type="vector_semantic_hybrid",
    top_k=5,
)

Sharepoint

get_sharepoint_tool以可通过 Foundry SharePoint 连接访问的 SharePoint 内容为依据生成答案。

sharepoint = FoundryChatClient.get_sharepoint_tool(
    connection_id="/subscriptions/.../connections/my-sharepoint",
)

Microsoft Fabric

get_fabric_tool 通过 Foundry 连接将该代理连接到 Microsoft Fabric 数据代理，以便该代理能够基于你的 Fabric 数据回答问题。

fabric = FoundryChatClient.get_fabric_tool(
    connection_id="/subscriptions/.../connections/my-fabric",
)

内存搜索

get_memory_search_tool 允许代理搜索 Foundry 托管的内存存储，可以选择限定为用户或租户。

memory = FoundryChatClient.get_memory_search_tool(
    memory_store_name="user-preferences",
    scope="{{$userId}}",
)

计算机使用

get_computer_use_tool 配置计算机使用预览工具 - 模型可以通过发出指针和键盘操作来驱动桌面或浏览器环境。

computer = FoundryChatClient.get_computer_use_tool(
    environment="browser",
    display_width=1280,
    display_height=800,
)

浏览器自动化

get_browser_automation_tool通过 Foundry 连接将代理连接到 Azure Playwright Testing 资源。 该代理可以通过 Playwright 驱动真实浏览器。

browser = FoundryChatClient.get_browser_automation_tool(
    connection_id="/subscriptions/.../connections/my-playwright",
)

代理对代理（A2A）

get_a2a_tool 将远程 A2A 代理公开为工具，以便 Foundry 代理可以调用它。 提供 base_url（和可选的 agent_card_path）或 project_connection_id 用于存储的 A2A 连接。

a2a = FoundryChatClient.get_a2a_tool(
    base_url="https://remote-agent.example.com",
    agent_card_path="/.well-known/agent-card.json",
)

有关通用 A2A 指南（发现、会话和流式传输），请参阅代理到代理提供程序页面。

使用 FoundryEmbeddingClient 创建嵌入向量

当需要从 Foundry 模型终结点嵌入文本或图像时使用 FoundryEmbeddingClient 。

from agent_framework.foundry import FoundryEmbeddingClient

async with FoundryEmbeddingClient() as client:
    result = await client.get_embeddings(["hello from Agent Framework"])
    print(result[0].dimensions)

使用 FoundryAgent 连接到服务托管代理

代理定义位于 Foundry 中时使用 FoundryAgent 。 这个推荐的 Python API 适用于 Prompt Agents 和 HostedAgents。

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    project_endpoint="https://your-project.services.ai.azure.com",
    agent_name="my-prompt-agent",
    agent_version="1.0",
    credential=AzureCliCredential(),
)

对于 HostedAgent，请省略 agent_version 并使用托管代理名称。

FoundryAgent 中哪些可行哪些不可行

FoundryAgent 连接到 Foundry 中已存在的智能体（Prompt 智能体或 Hosted 智能体）。 代理的定义（其说明和工具配置）位于 Foundry 中，而不是Python代码中。 这意味着，多个 Agent 级功能的行为方式与它们在 Agent(client=FoundryChatClient(...)) 或其他由聊天客户端支持的代理中的表现不同。

Tools

传递给 FoundryAgent(...) 的工具类型	Behavior
FunctionTool（本地 Python 可调用对象）	支持，但前提是 Foundry 代理上已存在匹配的函数定义。 Foundry 运行时根据代理定义决定向模型公开哪些工具。 当模型调用函数时，Foundry 将返回对客户端的工具调用，框架会在进程中调用本地Python可调用（不在 Foundry 中），然后将结果发送回。 传递 FunctionTool 客户端只是提供该本地实现 - 如果函数未在 Foundry 智能体上声明，模型永远不会调用它。
托管工具（Web 搜索、代码解释器、文件搜索、MCP、图像生成等）	忽视。 必须在 Foundry 代理定义本身上配置这些配置，无论是在 Foundry 门户还是通过服务 API。 在客户端传递它们不会产生任何效果，因为 Foundry 运行时只能识别附加到代理定义上的工具。

简言之：无法在构造时添加新工具。模型可以调用的每个工具（包括本地Python函数）都必须已是 Foundry 中的代理定义的一部分。 将 FunctionTool 传递给 FoundryAgent(...)仅提供调用 Foundry 定义函数时在Python进程中运行的本地实现;它不会向代理注册新工具。

上下文提供程序

context_providers=[...] 仅提供部分支持。 上下文提供程序是否起作用，取决于提供程序试图执行 什么 操作：

上下文提供程序行为	可与 FoundryAgent 配合使用？
添加额外的上下文作为消息（例如，检索的内存、RAG 代码段、用户配置文件信息）	Yes. 注入的上下文随请求一起转发。
持久化或观察对话（例如，将轮次写入外部存储）。	Yes. 在本地围绕请求/响应运行。
动态添加工具（例如 SkillsProvider，或任何从 invoking() 返回工具的提供程序）	否，除非工具已是 Foundry 代理定义的一部分。 Foundry 运行时针对 Foundry 中附加到智能体的工具执行模型；仅本地存在的工具不会暴露给模型，也不会被调用。

如果需要动态工具选择、技能加载或任何其他依赖于在运行时添加的工具的行为，请改用 Agent(client=FoundryChatClient(...)) - 该路径在本地拥有模型循环，并支持完整的工具类型和工具添加上下文提供程序集。

运行选项（default_options 和 agent.run(...) 选项）

你传递给 FoundryAgent(default_options=...) 或 agent.run(..., **options) 的选项（例如 temperature、top_p、max_tokens、instructions、tool_choice、response_format、metadata 等）并非全部被遵守。 由于 Foundry 中的代理定义是权威来源，因此许多选项会被静默忽略。

对于 提示代理，框架在将请求发送到 Foundry 响应 API 之前显式删除或替代以下内容：

选项	FoundryAgent 的行为
model	忽视。 模型取自 Foundry 代理定义。
tools、tool_choice、parallel_tool_calls	已从请求正文中移除。 必须在 Foundry 代理定义上声明工具（请参阅上一部分）。 FunctionTool 可调用对象仍会在本地绑定用于函数调用，但工具列表本身不会发送给该服务。
instructions 和系统/开发者消息	忽视。 Foundry 智能体自身的指令是权威的。 在发送请求之前，系统/开发人员消息将从消息列表中剥离。
conversation_id	已使用，并映射到 Foundry 智能体会话当它引用一个时。
extra_body	转发后，与框架设置的 agent_reference 负载合并。
采样参数（temperature、、top_pmax_tokensseedfrequency_penaltypresence_penaltystop...）、metadata、user、、store、等。 response_format	转发 到响应 API。 Foundry 是否实际应用它们取决于代理和模型配置（代理定义可以替代或约束它们），因此不要依赖它们对提示代理生效。

对于 托管代理，相同的客户端剥离适用，但除此之外的所有内容都取决于特定托管代理实现的内容。 托管代理可以接受、忽略或重新解释转发的任何选项。 将运行时选项视为建议性的，并针对你正在调用的托管智能体验证实际行为。

连接到已部署的（托管）Foundry 智能体。

对于运行服务器端会话 (/agents/{name}/sessions) 的 HostedAgents，使用带有 allow_preview=True 的 FoundryAgent 以选择加入预览版响应界面。

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    agent_name="my-hosted-agent",
    credential=AzureCliCredential(),
    allow_preview=True,
)

需要自行管理基础服务会话（例如，将会话绑定到特定租户或用户）时，请通过预览 AIProjectClient API 创建会话并将其包装为 agent.get_session(...)：

from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import VersionRefIndicator

service_session = await project_client.beta.agents.create_session(
    agent_name="my-hosted-agent",
    isolation_key="user-123",
    version_indicator=VersionRefIndicator(agent_version="1.0"),
)
session = agent.get_session(service_session.agent_session_id)

response = await agent.run("Hello!", session=session)

使用代理

FoundryChatClient 和 FoundryAgent 都与标准 Python Agent 体验（包括工具调用、会话和流式处理响应）集成。 在本地运行时，请使用单独的 Foundry 本地供应商页面。

工具箱

Foundry 工具箱是在 Microsoft Foundry 项目中配置的托管工具配置（代码解释器、文件搜索、图像生成、MCP、Web 搜索）的命名、版本控制的服务器端捆绑包。 工具箱允许在 Foundry 门户中管理工具配置一次，并在代理之间重复使用它。

代理框架仅涵盖 消耗 — 创建和更新工具箱版本是通过 Foundry 门户或原始 azure-ai-projects SDK （azure-ai-projects>=2.1.0） 完成的。

FoundryAgent vs FoundryChatClient

代理类型	工具箱行为
FoundryAgent （托管）	工具箱的附加操作在服务器端进行。 不需要客户端接线。
FoundryChatClient （直接推理）	使用 MCPStreamableHTTPTool 对抗工具箱的 MCP 终结点。

两种消耗模式

Pattern	说明
托管代理附加组件	工具配置在 Foundry 运行时上执行。 将工具箱连接到托管的 Foundry 代理。
MCP	使用 MCPStreamableHTTPTool 对抗工具箱的 MCP 终结点。 适用于任何聊天客户端，而不仅仅是 FoundryChatClient。

使用工具箱 MCP 端点进行直接推理

对于 FoundryChatClient 直接推理，将 MCPStreamableHTTPTool 指向工具箱的 MCP 终结点。 当工具箱提供了特定代理不应调用的工具时，请在 MCPStreamableHTTPTool 上使用 allowed_tools。

MCP 消耗路径

还可以将 MCPStreamableHTTPTool 指向工具箱的 MCP 终结点 URL，以便将工具箱用作 MCP 服务器。

MCP 终结点 URL 显示在 Foundry 门户上，或遵循以下格式：

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

因为客户端直接连接到 Foundry 工具箱终结点，你必须使用 Entra ID 持有者令牌通过 header_provider 进行身份验证：

from azure.identity.aio import DefaultAzureCredential
from azure.identity.aio import get_bearer_token_provider
from agent_framework import Agent, MCPStreamableHTTPTool

credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")

mcp_tool = MCPStreamableHTTPTool(
    name="research_mcp",
    url="https://<your-toolbox-mcp-endpoint>",
    header_provider=lambda _kwargs: {"Authorization": f"Bearer {token_provider()}"},
)

async with Agent(client=client, name="MCPAgent", tools=[mcp_tool]) as agent:
    result = await agent.run("Search for recent papers on LLM agents.")
    print(result.text)

Limitations

• 工具箱中的 MCP 工具使用服务器端身份验证。 通过 project_connection_id （在 Foundry 项目中配置的 OAuth 连接）处理对上游 MCP 服务器的身份验证。 客户端永远不会保存上游服务器的持有者令牌。
• 将工具箱用作 MCP 服务器需要客户端身份验证。 当你将 MCPStreamableHTTPTool 指向工具箱的 MCP 终结点时，你必须通过 header_provider 提供 Entra ID 持有者令牌（例如，通过 get_bearer_token_provider(credential, "https://ai.azure.com/.default")）。
• 同意流处理是运行时关注的问题。 如果工具箱 MCP 工具在 agent.run() 期间触发 CONSENT_REQUIRED，它会在运行时处理，而不是在工具箱提取期间。

Samples

Sample	说明
foundry_chat_client_with_toolbox.py	使用 MCPStreamableHTTPTool 的工具箱 MCP 使用量
foundry_chat_client_with_toolbox_skills.py	由工具箱支持的技能配置
invoke_foundry_toolbox_mcp	MCP 使用路径 MCPStreamableHTTPTool