Microsoft Foundry

入门

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

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

两种代理类型

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

响应代理 （直接推理）

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

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));

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

工具箱

Python的铸造厂

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

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

Python中的 Foundry 聊天和代理模式

安装

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 Agents”使用 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客户端

使用 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路径，支持工具、结构化输出和流式处理。

使用 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 并使用托管代理名称。

连接到已部署的（主机托管的）Foundry 代理

对于运行服务端会话的 HostedAgents（/agents/{name}/sessions），使用FoundryAgent 和allow_preview=True以参与预览“Responses 界面”，并传递version="v2"：

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

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

需要自行管理基础服务会话（例如，将会话绑定到特定租户或用户）时，请通过预览 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

两种消耗模式

获取工具箱

使用FoundryChatClient.get_toolbox()来检索工具箱：

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

async with AzureCliCredential() as credential:
    client = FoundryChatClient(credential=credential)
    toolbox = await client.get_toolbox("research_toolbox")

    async with Agent(client=client, name="ResearchAgent", tools=toolbox) as agent:
        result = await agent.run("Summarize recent findings.")
        print(result.text)

如果 version 省略，get_toolbox 会在两个请求中解析默认版本。 锁定特定版本以避免额外的往返：

toolbox = await client.get_toolbox("research_toolbox", version="v3")

隐式平展

无需编写 toolbox.tools。 框架可以自动识别normalize_toolsToolboxVersionObject并进行平整化处理。 所有这些都有效：

# Single toolbox
agent = Agent(client=client, tools=toolbox)

# Toolbox in a list
agent = Agent(client=client, tools=[toolbox])

# Mix local function tools with a toolbox
agent = Agent(client=client, tools=[get_internal_metrics, toolbox])

# Combine multiple toolboxes
agent = Agent(client=client, tools=[toolbox_a, toolbox_b])

筛选工具 select_toolbox_tools

如果工具箱捆绑了多个工具，但代理只需要一个子集，则用于 select_toolbox_tools 在提取后缩小集范围。 这可以避免向模型发送不必要的工具定义，从而减少令牌使用情况，并阻止模型调用不打算公开的工具：

from agent_framework.foundry import select_toolbox_tools, get_toolbox_tool_name

# Filter by tool name
tools = select_toolbox_tools(toolbox, include_names=["web_search", "code_interpreter"])

# Filter by tool type
tools = select_toolbox_tools(toolbox, include_types=["mcp", "web_search"])

# Filter with a custom predicate
tools = select_toolbox_tools(toolbox, predicate=lambda t: "search" in (get_toolbox_tool_name(t) or ""))

帮助程序函数 get_toolbox_tool_name(tool) 并 get_toolbox_tool_type(tool) 分别返回工具条目的选择名称和原始类型。 FoundryHostedToolType是一个TypeAlias（Literal["code_interpreter", "file_search", "image_generation", "mcp", "web_search"] | str），用于include_types / exclude_types的IDE引导式补全。

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: {"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 终结点时，必须通过get_bearer_token_provider(credential, "https://ai.azure.com/.default")提供 Entra ID 承载令牌（例如，通过header_provider）。
• 同意流处理是运行时关注的问题。 如果工具箱 MCP 工具在CONSENT_REQUIRED期间触发agent.run()，它会在运行时处理，而不是在提取工具箱时进行处理。

Samples