Microsoft Foundry 模型提供者

Microsoft Agent Framework 支援直接從 Microsoft Foundry 專案端點推論模型，而您的應用程式擁有代理定義、工具與編排權。

如需了解由服務管理的 Prompt 和 Hosted Agents，請參閱 Microsoft Foundry Agent Service。

使用者入門

將必要的 NuGet 套件新增至您的專案。

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

兩種整合模式

Microsoft Foundry 整合揭示了兩種不同的使用模式：

Pattern	製造類型	說明	何時使用
回應代理人	`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(...) 建立的 Foundry Responses Agents 支援標準 Agent Framework 工具介面。完整功能矩陣請參閱工具總覽。

Tool	註釋
函式工具	支援。
工具核准	支援。由架構的函式呼叫聊天用戶端提供。
程式碼解譯器	支援。
檔案搜尋	支援。
託管 MCP 工具	支援。
本地 MCP 工具	支援。
Microsoft Foundry 工具箱	支援。

Python 中的鑄造場

在 Python 中，所有 Foundry 專用客戶端現在都位於 agent_framework.foundry。

agent-framework-foundry 提供 Cloud Foundry 連接器：FoundryChatClient、FoundryAgent、FoundryEmbeddingClient、FoundryMemoryProvider和FoundryMemoryProvider。
agent-framework-foundry-local 提供 FoundryLocalClient 本地模型執行功能。

這很重要

本頁涵蓋 Microsoft Foundry 專案及端點模型。關於 Foundry Agent Service，請參見 Microsoft Foundry Agent Service。如果你有獨立的 Azure OpenAI 資源端點（https://<your-resource>.openai.azure.com），請使用 OpenAI 提供者頁面上的 Python 指引。如果你想在本地執行支援模型，請參閱 Foundry 本地供應商頁面。

Python 中的 Foundry 聊天與代理模式

情境	蟒蛇形狀	何時使用
使用 Foundry Responses 終端進行簡單推論	`Agent(client=FoundryChatClient(...))`	你的應用程式擁有代理定義、工具和對話迴圈，你希望模型部署在 Foundry 專案中。
Foundry Agent Service 中的服務受控代理程式	`FoundryAgent(...)`	您想要連線至在 Foundry 入口網站中或透過服務 API 建立與設定的 PromptAgent 或 HostedAgent。

Installation

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 Responses」端點。
Microsoft Foundry 服務管理代理	`FoundryAgent`	推薦用於即時代理和托管代理。
微軟 Foundry 模型-端點嵌入	`FoundryEmbeddingClient`	使用 `FOUNDRY_MODELS_ENDPOINT` 和 `FOUNDRY_EMBEDDING_MODEL` / `FOUNDRY_IMAGE_EMBEDDING_MODEL`。
Foundry 本地執行環境	`Agent(client=FoundryLocalClient(...))`	詳見 Foundry Local。

使用 `FoundryChatClient` 建立一個代理程式

FoundryChatClient 連接 Foundry 專案中的已部署模型，並使用 Responses 端點。當您的應用程式需要掌控指令、工具和工作階段處理時，請將它與標準的 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路徑，支援工具、結構化輸出與串流。

並行重複使用用戶端

一個 FoundryChatClient 實例可以在同一事件迴圈上同時提供非同步通話，包括重疊的串流與非串流通話。

為每個並行執行個體建立個別的 Agent 和 AgentSession，並分別傳遞訊息和選項。使用者提供的中介軟體、工具與回調也必須支援並行性。不要在作業系統執行緒或事件迴圈間共享客戶端，或在呼叫進行時改變設定。

選擇啟用加密推理

FoundryChatClient 預設不會請求 reasoning.encrypted_content 。此預設可防止不支援加密推理的模型請求失敗。

若要啟用支援該功能的部署，請透過代理程式的預設選項啟用：

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="<reasoning-model-deployment>",
        credential=AzureCliCredential(),
    ),
    default_options={"include": ["reasoning.encrypted_content"]},
)

Tools

FoundryChatClient 為每個託管的 Foundry 工具提供靜態工廠函式。這些工廠會傳回您在 Agent 上傳遞給 tools= 或直接傳遞給 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 目前所展示的所有工具。

Tool	`FoundryChatClient` 上的工廠	現況	Detail
函式工具	不適用 — 傳遞任何 Python 可呼叫或 `@ai_function`	GA	在你的 Python 程序中本地調用。
工具核准	不適用 — 包裝現有工具	GA	可搭配託管的 MCP 和函式工具使用。
程式碼解譯器	`get_code_interpreter_tool`	GA	在 Foundry 上進行沙箱化程式碼執行。
檔案搜尋	`get_file_search_tool`	GA	透過 Foundry 向量儲存庫搜尋已上傳的檔案。
網路搜尋	`get_web_search_tool`	GA	由 Microsoft 管理的 Bing 支援網頁基礎。僅限 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	透過 MCP 取用自 `FoundryChatClient`；附加於 `FoundryAgent` 的伺服器端。
Bing 基礎設置	`get_bing_grounding_tool`	Experimental	使用自備的使用 Bing 搜尋的基礎設置。
必應自訂搜尋	`get_bing_custom_search_tool`	預覽	Bing grounding 僅限於精選網域清單。
Azure AI 搜尋服務	`get_azure_ai_search_tool`	Experimental	透過 Foundry 連線搜尋 Azure AI 搜尋服務索引。
SharePoint	`get_sharepoint_tool`	預覽	根據 SharePoint 內容提供答案。
Microsoft Fabric	`get_fabric_tool`	預覽	查詢 Fabric 資料代理程式。
記憶搜尋	`get_memory_search_tool`	預覽	搜尋 Foundry 管理的記憶體儲存庫。
電腦使用	`get_computer_use_tool`	預覽	讓代理程式操作桌面或瀏覽器環境。
瀏覽器自動化	`get_browser_automation_tool`	預覽	透過 Azure Playwright 連線來驅動瀏覽器。
代理對代理（A2A）	`get_a2a_tool`	預覽	將另一個 A2A 代理程式作為工具呼叫。

備註

實驗性工廠會包裝 GA Foundry SDK 類型，但包裝函式本身可能會在 GA 之前改變。預覽工廠會包裝 Foundry SDK 類型，其底層功能仍處於預覽階段，可能會被更改或移除。兩者在某個處理程序中首次使用時，都會發出 ExperimentalWarning。

網路搜尋變體

Foundry 公開了三種 Bing 支持的接地選項。選擇符合你情況的那一種：

get_web_search_tool （GA） — 零設定預設;Bing 資源由 Microsoft 管理。僅限 Azure OpenAI 模型。限制為 user_location 和 search_context_size。
get_bing_grounding_tool (實驗性) — 自備使用 Bing 搜尋的基礎設置 Azure 資源。支援 count、 freshness、 market、 set_lang及非 OpenAI Foundry 模型。
get_bing_custom_search_tool (預覽版) — 自備 Bing 自訂搜尋執行個體，將基礎依據限制於精選的網域集合。

這三者都會將搜尋資料傳送到Azure合規邊界之外。完整比較請參閱網路接地概述。

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",
)

Bing 基礎設置

get_bing_grounding_tool 包裝了使用 Bing 搜尋的基礎設置 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,
)

Bing 自訂搜尋

get_bing_custom_search_tool 會將基礎依據限制為僅使用 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整合標準 Python Agent 體驗，包括工具呼叫、會話及串流回應。本地執行時，請使用獨立的Foundry 本地提供者頁面。

關於已命名、版本化的託管工具配置套件，請參見 Microsoft Foundry Toolbox。

Go 中的 Foundry

Go SDK 透過 github.com/microsoft/agent-framework-go/provider/foundryprovider 提供 Microsoft Foundry 代理程式。

請參閱 Foundry Go 範例，了解直接推論、函式工具、託管工具、MCP 及伺服器代理範例。

該套件支援兩個代理目標：

Target	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"

由 Project 支援的 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 Agent Framework 工具介面，可用於本機工具以及支援的託管工具宣告。

Tool	現況	註釋
函式工具	Supported	函式會在您的 Go 程序中執行。
工具核准	Supported	透過工具自動呼叫迴圈與本地函式工具配合運作。
程式碼解譯器	Supported	請使用 `&hostedtool.CodeInterpreter{}`。
網路搜尋	Supported	請使用 `&hostedtool.WebSearch{}`。
本地 MCP 工具	Supported	用 `tool/mcptool` 來連接 MCP 伺服器並在本地暴露其工具。
託管 MCP 工具	目前尚無 Go Foundry 的相關文件	需要搭配 Go Foundry 代理的 MCP 伺服器時，可以使用本地 MCP 工具。
Microsoft Foundry 工具箱	目前尚未透過 Go 協助程式公開。

對於本機函式工具，可透過 agent.Config.Tools 新增 tool.Tool 值：

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 提供者會將其新增至 response/update 的額外屬性中，作為 ServedModel。

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 記憶體 Go 範例，以查看完整可執行的範例。

目前的 Go 差距

Go 支援目前不包含 Foundry 託管的部署/生命週期/管理 API、嵌入客戶端，或 Microsoft Foundry Toolbox 專用的 Go 輔助工具。這些操作可以使用 Foundry 入口網站或服務 SDK。

下一步

Foundry Local

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-03

Microsoft Foundry 模型提供者

使用者入門

兩種整合模式

回應代理人（直接推論）

使用代理程式

Tools

Python 中的鑄造場

Python 中的 Foundry 聊天與代理模式

Installation

Configuration

FoundryChatClient

FoundryEmbeddingClient

選擇合適的 Python 用戶端

使用 FoundryChatClient 建立一個代理程式

並行重複使用用戶端

選擇啟用加密推理

Tools

工具支援

網路搜尋變體

影像產生

Bing 基礎設置

Bing 自訂搜尋

Azure AI 搜尋服務

SharePoint

Microsoft Fabric

記憶體搜尋

電腦應用

瀏覽器自動化

代理對代理（A2A）

建立嵌入 FoundryEmbeddingClient

使用代理程式

Go 中的 Foundry

Configuration

由 Project 支援的 Foundry 代理程式

現有的伺服器端 Foundry 代理程式

Tools

用戶端標頭與服務模型

Foundry 記憶體提供者

目前的 Go 差距

下一步

意見反應

其他資源

`FoundryChatClient`

`FoundryEmbeddingClient`

使用 `FoundryChatClient` 建立一個代理程式

建立嵌入 `FoundryEmbeddingClient`