Foundry 託管代理

Hosted agents 在 Foundry Agent Service 中Microsoft允許您將 Agent Framework 代理部署為容器化應用程式，部署至 Microsoft 管理的基礎設施。 該平台處理擴展性、會話狀態持久性、安全性與生命週期管理，讓您能專注於代理程式的邏輯。 Microsoft Foundry 託管代理程式已普遍提供。

透過 Agent Framework 的託管整合，你只需少量程式碼，即可透過 Foundry Responses 或 Invocations 通訊協定公開 Agent，其中包括以 Workflow.as_agent() 包裝的工作流程。

何時使用託管代理

選擇 Foundry 託管代理，當您希望達成以下目的時：

• 託管基礎設施 ——無需自行配置容器、網頁伺服器或擴展規則。
• 內建會話管理 — 平台能 $HOME 在回合與閒置期間持續存檔並上傳檔案。
• 專用代理身份 — 每個部署的代理都會擁有自己的 Entra 身份，以確保對模型、工具及下游服務的安全存取。
• OpenAI 相容端點 — 客戶端可透過 Responses 協議，使用任何 OpenAI 相容 SDK 與您的客服人員互動。

備註

Python agent-framework-foundry-hosting 整合目前是預發布狀態。 Microsoft Foundry 託管代理服務，作為託管主機服務，已普遍提供。

先決條件

• Azure 訂用帳戶
• Azure 開發者 CLI（azd） 搭配 AI 代理擴充功能：azd ext install azure.ai.agents

本地測試，你還需要：

• 一個Microsoft Foundry專案，包含模型部署（例如 gpt-4o）
• 已安裝並驗證 Azure CLI （az login）

• .NET 10 SDK 或更新版本

安裝主機 NuGet 套件：

dotnet add package Microsoft.Agents.AI.Foundry.Hosting --prerelease
dotnet add package Azure.AI.Projects --prerelease

• Python 3.10 或更新版本

安裝預發布的主機套件、Foundry 客戶端和 Azure 認證套件：

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

在 Foundry 中，平台提供呼叫者的使用者上下文與通話上下文;主機基礎設施利用這些工具來隔離每位使用者的狀態，並將請求上下文轉發給 Foundry 服務。 在本機執行時不會收到該平台的情境資訊，因此應用程式必須在需要時自行提供身分識別與狀態控管機制。

回應協定

回應協議是大多數代理人的推薦起點。 它提供一個相容 /responses OpenAI 的端點，平台自動管理對話歷史、串流和會話生命週期。

using Azure.AI.AgentServer.Core;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;

var projectEndpoint = new Uri(Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set."));
var deployment = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";

AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
    .AsAIAgent(
        model: deployment,
        instructions: "You are a helpful AI assistant.",
        name: "my-agent");

var builder = AgentHost.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.RegisterProtocol("responses", endpoints => endpoints.MapFoundryResponses());

var app = builder.Build();
app.Run();

AgentHost.CreateBuilder會為 Foundry 主機環境預先設定一個應用程式主機。 AddFoundryResponses會將您的代理程式註冊到 Responses 協定處理器，並MapFoundryResponses/responses映射 HTTP 端點。

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.identity import DefaultAzureCredential

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a helpful AI assistant.",
    default_options={"store": False},
)

server = ResponsesHostServer(agent)
server.run()

ResponsesHostServer 包裹你的代理，並透過 Foundry Responses 協定將其公開。 將 store 設 False 為 in default_options 可以避免重複對話紀錄，因為主機架構會自動管理對話紀錄。

呼叫協定

Invocations 協定讓你能完全控制 HTTP 請求與回應。 當你需要自訂有效載荷、非對話式處理，或是不支援 OpenAI 的串流協定時，才會使用它。

使用 C# 中的 Invocations 協定，您可以實現一個自訂 InvocationHandler 来處理來的請求：

using Azure.AI.AgentServer.Core;
using Azure.AI.AgentServer.Invocations;
using Microsoft.Agents.AI;

var builder = AgentHost.CreateBuilder(args);

builder.Services.AddSingleton<AIAgent, MyAgent>();
builder.Services.AddInvocationsServer();
builder.Services.AddScoped<InvocationHandler, MyInvocationHandler>();

builder.RegisterProtocol("invocations", endpoints => endpoints.MapInvocationsServer());

var app = builder.Build();
app.Run();

此 AddInvocationsServer 方法會註冊呼叫協定服務。 你實作 InvocationHandler 來定義代理如何處理每個請求。

想要輕量化的配置，請使用 InvocationsHostServer 套件中的 agent_framework_foundry_hosting。 它會將您的代理類似於 ResponsesHostServer 一樣封裝，並自動處理會話管理：

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import InvocationsHostServer
from azure.identity import DefaultAzureCredential

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a friendly assistant. Keep your answers brief.",
    default_options={"store": False},
)

server = InvocationsHostServer(agent)
server.run()

為了完全控制請求處理，請直接使用來自InvocationAgentServerHost套件的azure.ai.agentserver.invocations，並實作您自己的呼叫處理器：

import os
from collections.abc import AsyncGenerator

from agent_framework import Agent, AgentSession
from agent_framework.foundry import FoundryChatClient
from azure.ai.agentserver.invocations import InvocationAgentServerHost
from azure.identity import DefaultAzureCredential
from starlette.requests import Request
from starlette.responses import JSONResponse, Response, StreamingResponse

_sessions: dict[str, AgentSession] = {}

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a friendly assistant. Keep your answers brief.",
    default_options={"store": False},
)

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request):
    """Handle streaming multi-turn chat."""
    data = await request.json()
    session_id = request.state.session_id
    stream = data.get("stream", False)
    user_message = data.get("message", None)

    if user_message is None:
        return Response(content="Missing 'message' in request", status_code=400)

    session = _sessions.setdefault(session_id, AgentSession(session_id=session_id))

    if stream:

        async def stream_response() -> AsyncGenerator[str]:
            async for update in agent.run(user_message, session=session, stream=True):
                yield update.text

        return StreamingResponse(
            stream_response(),
            media_type="text/event-stream",
            headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
        )

    response = await agent.run([user_message], session=session, stream=stream)
    return JSONResponse({"response": response.text})


if __name__ == "__main__":
    app.run()

警告

自訂處理器範例中的記憶體會話儲存會在重新啟動時遺失。 在生產環境中使用耐用儲存（例如 Cosmos DB）。

備註

Go 對 Foundry 託管代理的支援即將推出。 最新狀態請參閱 Agent Framework Go 倉庫 。

提示

參考 Python 樣本 或 C# 樣本 以了解託管代理專案的範例。 或者用這個 azd ai agent init 指令從零開始搭建新的託管代理專案。 請參閱這份 快速入門指南 ，了解逐步說明。

在本機執行

Azure 開發者 CLI（azd）提供了最簡單的本地運行與測試主機代理的方式。

初始化專案

建立一個新資料夾，並從範例清單初始化：

mkdir my-hosted-agent && cd my-hosted-agent
azd ai agent init -m <path-to-agent.manifest.yaml>

提示

清單可以是本地 YAML 檔案的路徑，或是遠端清單的 URL。

設定環境變數

export FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="<your-model-deployment>"

執行代理主機

azd ai agent run

代理主機從 http://localhost:8088開始。

召喚代理人

azd ai agent invoke --local "Hello!"

或者使用 curl：

curl -X POST http://localhost:8088/responses \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello!"}'

或者用 PowerShell 來做：

(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "Hello!"}').Content

部署至鑄造廠

一旦你在本地驗證了代理程式，就部署到 Microsoft Foundry：

1. 資源配置 （如果你還沒有 Foundry 專案）：

   azd provision
   

   這會建立一個資源群組，包含 Foundry 實例、專案、模型部署、應用洞察以及容器登錄檔。

2. 部署代理：

   azd deploy
   

   這會將你的代理程式打包成容器映像，推送到 Azure Container Registry，然後部署到 Foundry Agent Service。

Foundry 的主機架構會在執行時自動將以下環境變數注入你的代理容器：

變數	描述
FOUNDRY_PROJECT_ENDPOINT	Foundry 專案的端點網址。
AZURE_AI_MODEL_DEPLOYMENT_NAME	模型部署名稱（在 azd ai agent init 設定時配置）。
APPLICATIONINSIGHTS_CONNECTION_STRING	Application Insights 的遙測連線字串。

部署完成後，代理程式可透過其專用的 Foundry 端點存取，並可從 Foundry 入口網站進行測試。

後續步驟

託管代理概念

• 使用 Foundry SDK 部署託管代理
• 管理託管代理
• Azure Functions 與持久性裝載
• 自行託管 A2A 代理程式
• Python 範例
• C# 範例