Microsoft Foundry 模型提供者

使用者入門

將所需的 NuGet 套件加入你的專案。

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

此路徑為程式碼優先，不會建立伺服器管理的代理資源。

使用代理程式

回應代理程式是標準 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 工具介面。 完整功能矩陣請參閱 工具總覽 。

Python 中的鑄造場

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

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

Python 中的 Foundry 聊天與代理模式

Installation

pip install agent-framework-foundry

同一 agent-framework-foundry 套件也包含 FoundryEmbeddingClient 透過 Foundry 專案進行文字嵌入，或透過 Foundry Models 端點進行文字與影像嵌入。

Configuration

FoundryChatClient

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

FoundryEmbeddingClient 搭配專案端點

FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
FOUNDRY_EMBEDDING_MODEL="text-embedding-3-small"

專案支援的內嵌會使用 Foundry 專案中的 OpenAI 內嵌部署。 使用非同步的令牌憑證（如 AzureCliCredential.）來認證。

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

使用 Foundry Models 端點來處理影像嵌入，或用於部署到該端點的文字模型。 如果兩個端點環境變數都已設定，且你沒有傳遞明確的端點或專案客戶端，則 FOUNDRY_MODELS_ENDPOINT 會優先處理。

FoundryChatClient 使用專案端點。 FoundryEmbeddingClient 支援專案支援的文字嵌入，以及模型端點文字或影像嵌入。

選擇合適的 Python 用戶端

使用 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 目前所展示的所有工具。

網路搜尋變體

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_tool透過回覆 API 設定原生電腦操作。 Foundry SDK 工具尚未預覽，但共享的代理框架 ComputerSafetyCheck 與電腦 Content 建構器仍處於實驗階段。 你的應用程式執行排序動作、審查安全檢查，並回傳截圖。 完整的請求與結果流程，請參見 原生電腦使用。

computer = FoundryChatClient.get_computer_tool()

此工廠需要 azure-ai-projects 2.3.0 或更新版本。 較舊但仍受支援的 SDK 版本仍可匯入 FoundryChatClient，但呼叫 get_computer_tool() 會引發 ImportError，並提供升級指引。

get_computer_use_tool 仍可用於單獨的 Computer Use 預覽 API：

preview_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 專案中嵌入 OpenAI 部署的文字時，請搭配專案端點使用 FoundryEmbeddingClient 。

import os

from agent_framework.foundry import FoundryEmbeddingClient
from azure.identity.aio import AzureCliCredential

async with AzureCliCredential() as credential:
    async with FoundryEmbeddingClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["FOUNDRY_EMBEDDING_MODEL"],
        credential=credential,
    ) as client:
        result = await client.get_embeddings(["hello from Agent Framework"])
        print(result[0].dimensions)

針對影像嵌入，請改為設定 FOUNDRY_MODELS_ENDPOINT、FOUNDRY_MODELS_API_KEY 和 FOUNDRY_IMAGE_EMBEDDING_MODEL。 不要在同一個 FoundryEmbeddingClient 中，將 project 端點設定與 models 端點引數或用戶端混在一起。

使用代理程式

FoundryChatClient整合標準 Python Agent 體驗，包括工具呼叫、會話及串流回應。 本地執行時，請使用獨立的Foundry 本地提供者頁面。

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

Go 中的 Foundry

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

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

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

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

對於本機函式工具，可透過 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 端點，且該記憶體儲存必須已存在於該專案中。 範圍回呼應傳回穩定的使用者、租用戶或交談分割區索引鍵。

目前的 Go 差距

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