Microsoft Foundry 模型提供程序

Microsoft Agent Framework 支持从 Microsoft Foundry 项目终结点进行直接模型推理，而应用程序拥有代理定义、工具和业务流程。

有关服务托管的提示和托管代理，请参阅 Microsoft Foundry 代理服务。

入门

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

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

两种集成模式

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

Pattern	生成的类型	Description	何时使用
响应代理	`ChatClientAgent`	你的应用通过编程方式在运行时提供 `AIProjectClient.AsAIAgent(...)`模型、说明和工具。未创建服务器端代理资源。	你拥有代理定义，并且需要一个简单的灵活设置。这是大多数示例中使用的模式。
Foundry 代理（提示或托管）	`FoundryAgent`	服务器托管 — 提示代理已命名和版本控制定义;托管代理是通过特定于代理的终结点访问的部署应用程序。	Foundry 拥有代理定义或托管运行时。请参阅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."));

Warning

DefaultAzureCredential 对于开发来说很方便，但在生产中需要仔细考虑。在生产环境中，请考虑使用特定凭据（例如）， ManagedIdentityCredential以避免延迟问题、意外凭据探测以及回退机制的潜在安全风险。

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

使用代理

响应代理是一种标准 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(...) 支持标准 Agent Framework 工具图面创建的 Foundry 响应代理。有关完整的功能矩阵，请参阅 “工具”概述。

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

Python 中的 Foundry

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

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

Important

本页介绍 Microsoft Foundry 项目和模型终结点。有关 Foundry 代理服务，请参阅 Microsoft Foundry 代理服务。如果您有一个独立的 Azure OpenAI 资源终结点（https://<your-resource>.openai.azure.com），请参考 OpenAI 提供程序页上的 Python 指南。如果要在本地运行受支持的模型，请参阅 Foundry Local 提供程序页。

Python 中的 Foundry 聊天和代理模式

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

安装

pip install agent-framework-foundry

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

Configuration

`FoundryChatClient`

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

`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 使用项目终结点。 FoundryEmbeddingClient 使用单独的模型终结点。

选择正确的 Python 客户端

情景	首选客户端	备注
Azure OpenAI 资源	`OpenAIChatCompletionClient` / `OpenAIChatClient`	使用 OpenAI 提供者页面。
Microsoft Foundry 项目推断	`Agent(client=FoundryChatClient(...))`	使用 Foundry 响应终结点。
Microsoft Foundry 服务托管代理	`FoundryAgent`	建议用于即时代理和 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 工具提供静态工厂方法。这些工厂会返回你传递给 tools=（在 Agent 上）或直接传递给 client.get_response(..., tools=[...]) 的 SDK 工具对象。有关服务托管代理工具，请参阅 Microsoft Foundry 代理服务。

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

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今天公开的每个工具。

工具	出厂时为 `FoundryChatClient`	地位	详情
函数工具	n/a — 传入任何 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	由微软管理、必应提供支持的网络依据。仅限 Azure OpenAI 模型。
图像生成	`get_image_generation_tool`	GA	由 Foundry 托管的图像生成功能。
托管式 MCP	`get_mcp_tool`	GA	Foundry 调用的远程 MCP 服务器。
本地 MCP	n/a — 使用 `MCPStreamableHTTPTool` / `MCPStdioTool`	GA	在进程中运行;适用于任何客户端。
Microsoft Foundry 工具箱	`MCPStreamableHTTPTool` 或 `FoundryToolbox`	Beta	通过 `FoundryChatClient` 上的 MCP 使用；在 `FoundryAgent` 上于服务器端附加。
必应Grounding	`get_bing_grounding_tool`	Experimental	使用必应搜索资源实现自带 Grounding。
必应自定义搜索	`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 代理作为工具。

注释

实验性工厂对 GA Foundry SDK 类型进行了封装，但这些包装器本身在 GA 之前仍可能发生变化。预览工厂封装了 Foundry SDK 类型，这些类型的底层功能仍处于预览阶段，并且可能会发生更改或被移除。两者在进程中首次被使用时，都会发出一个 ExperimentalWarning。

网络搜索变体

Foundry 提供了三个由必应支持的 grounding 选项。选择符合您情况的选项：

get_web_search_tool（GA）— 默认无需设置；必应资源由 Microsoft 管理。仅限 Azure OpenAI 模型。限制为 user_location 和 search_context_size。
get_bing_grounding_tool（实验性）— 使用你自己的必应搜索 Azure 资源实现 Grounding 功能。支持 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 封装了 Grounding with Bing Search Foundry 工具。你需要自行创建 Grounding with Bing Search 资源，并将其作为 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 将 grounding 限制为 Bing 自定义搜索资源中定义的允许列表。

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 代理可以调用它。为一个已存储的 A2A 连接提供 base_url（以及可选的 agent_card_path）或 project_connection_id。

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

有关 A2A 发现、会话和流式处理指南的常规信息，请参阅 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)

使用代理

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

有关托管工具配置的命名版本控制捆绑包，请参阅Microsoft Foundry 工具箱。

Go 中的 Foundry

Go SDK 通过 github.com/microsoft/agent-framework-go/provider/foundryprovider 提供 Microsoft Foundry 代理。

有关直接推理、函数工具、托管工具、MCP 和服务器代理示例，请参阅 Foundry Go 示例。

该包支持两个代理目标：

目标	围棋形状	何时使用
项目支持的模型部署	`foundryprovider.ModelDeployment("gpt-4o-mini")`	你的应用拥有说明、工具和聊天流。
现有的服务器端 Foundry 代理	`foundryprovider.ServerAgent("my-agent")`	代理定义已在 Foundry 中配置。

Configuration

设置 Foundry 项目的端点和模型部署：

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

项目支持的 Foundry 代理

当你想在代码中创建 Agent Framework 代理，并从你的 Go 应用程序中传入说明、工具、中间件和上下文提供程序时，请使用 ModelDeployment。

import (
    "context"
    "os"

    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
)

endpoint := os.Getenv("FOUNDRY_PROJECT_ENDPOINT")
model := os.Getenv("FOUNDRY_MODEL")

token, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    panic(err)
}

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You are good at telling jokes.",
        Config: agent.Config{
            Name: "Joker",
        },
    },
)

resp, err := a.RunText(context.Background(), "Tell me a joke about a pirate.").Collect()

现有的服务器端 Foundry 代理

当想要调用 Foundry 中已配置的代理时使用 ServerAgent 。服务器端代理拥有其指令和工具，因此 AgentConfig.Instructions 此目标将被忽略。

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ServerAgent("my-agent"),
    foundryprovider.AgentConfig{
        Config: agent.Config{
            Name: "my-agent",
        },
    },
)

resp, err := a.RunText(ctx, "Summarize the current project status.").Collect()

Tools

项目支持的 Foundry 代理支持标准的 Go 代理框架工具接口，用于本地工具和受支持的托管工具声明。

工具	地位	备注
函数工具	支持	函数在 Go 进程中运行。
工具审批	支持	通过工具自动调用循环与本地函数工具配合工作。
代码解释器	支持	使用 `&hostedtool.CodeInterpreter{}`。
Web 搜索	支持	使用 `&hostedtool.WebSearch{}`。
本地 MCP 工具	支持	使用 `tool/mcptool` 连接到 MCP 服务器，并在本地暴露其工具。
托管 MCP 工具	Go Foundry 目前暂无相关文档说明	需要具有 Go Foundry 代理的 MCP 服务器时，请使用本地 MCP 工具。
Microsoft Foundry 工具箱	当前未通过 Go 帮助程序公开。

对于本地函数工具，请通过 tool.Tool 添加 agent.Config.Tools 值：

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You are a helpful assistant.",
        Config: agent.Config{
            Tools: []tool.Tool{weatherTool},
        },
    },
)

对于托管代码执行，请传递托管工具声明：

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You solve problems with code.",
        Config: agent.Config{
            Tools: []tool.Tool{&hostedtool.CodeInterpreter{}},
        },
    },
)

客户端标头和所提供的模型

Foundry 每次运行接受 x-client-* 个标头。使用 foundryprovider.WithClientHeader 或 foundryprovider.WithClientHeaders 添加它们：

resp, err := a.RunText(
    ctx,
    "Hello!",
    foundryprovider.WithClientHeader("x-client-scenario", "docs"),
).Collect()

当 Foundry 返回 x-ms-served-model 响应标头时，Go 提供程序会将其作为 ServedModel 添加到 response/update 的附加属性中。

if servedModel, ok := resp.AdditionalProperties["ServedModel"].(string); ok {
    fmt.Println(servedModel)
}

Foundry 内存提供程序

当你希望 Agent Framework 代理在每次运行前后从 Foundry 托管的内存存储库中检索并更新内容时，请使用 foundryprovider.NewMemoryProvider。

import (
    "log/slog"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
)

memoryProvider := foundryprovider.NewMemoryProvider(
    endpoint,
    tokenCredential,
    "memory-store-sample",
    func(*agent.Session) string { return "user-123" },
    foundryprovider.MemoryProviderConfig{
        Logger: slog.Default(),
    },
)

a := foundryprovider.NewAgent(
    endpoint,
    tokenCredential,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "Use known memories about the user when responding.",
        Config: agent.Config{
            Name:             "FoundryMemoryAgent",
            ContextProviders: []agent.ContextProvider{memoryProvider},
        },
    },
)

该终结点必须是项目范围的Microsoft Foundry 终结点，并且内存存储必须已存在于该项目中。范围回调应返回稳定的用户、租户或聊天分区键。

Tip

有关完整的可运行示例，请参阅 Foundry memory Go 示例。

当前 Go 差距

Go 支持当前不包括 Foundry 托管的部署/生命周期/管理员 API、嵌入客户端或适用于 Microsoft Foundry 工具箱的特定于 Go 的帮助程序。对于这些操作，请使用 Foundry 门户或服务 SDK。

后续步骤

Foundry Local

反馈

此页面是否有帮助？

Last updated on 2026-08-13

Microsoft Foundry 模型提供程序

入门

两种集成模式

响应代理 （直接推理）

使用代理

Tools

Python 中的 Foundry

Python 中的 Foundry 聊天和代理模式

安装

Configuration

FoundryChatClient

FoundryEmbeddingClient

选择正确的 Python 客户端

使用 FoundryChatClient 创建代理

Tools

工具支持

网络搜索变体

图像生成

必应基础支撑

必应自定义搜索

Azure AI 搜索

SharePoint

Microsoft Fabric

内存搜索

计算机使用

浏览器自动化

代理对代理（A2A）

使用 FoundryEmbeddingClient 创建嵌入向量

使用代理

Go 中的 Foundry

Configuration

项目支持的 Foundry 代理

现有的服务器端 Foundry 代理

Tools

客户端标头和所提供的模型

Foundry 内存提供程序

当前 Go 差距

后续步骤

反馈

其他资源

响应代理（直接推理）

`FoundryChatClient`

`FoundryEmbeddingClient`

使用 `FoundryChatClient` 创建代理

使用 `FoundryEmbeddingClient` 创建嵌入向量