Hostowani agenci programu Foundry

• .NET 10 SDK lub nowszy

Zainstaluj pakiet NuGet hostingu:

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

• Python 3.10 lub nowszy

Zainstaluj pakiet hostingu wersji wstępnej, klienta programu Foundry i pakiet uwierzytelniania Azure:

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

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

Obiekt AgentHost.CreateBuilder tworzy wstępnie skonfigurowany serwer aplikacji w środowisku hostingu Foundry. AddFoundryResponses rejestruje agenta w procedurze obsługi protokołu Responses i MapFoundryResponses mapuje /responses punkt końcowy 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.",
)

server = ResponsesHostServer(agent)
server.run()

Element ResponsesHostServer opakowuje instancję agenta i uwidacznia ją za pośrednictwem protokołu Foundry Responses. W przypadku agenta, który nie jest agentem przepływu pracy, domyślny element history_source="agent_server" używa skonfigurowanego dostawcy odpowiedzi serwera Agent Server jako źródła historii modelu. Host uniemożliwia usłudze modelu podrzędnego zachowywanie drugiej kopii, gdy klient domyślnie przechowuje historię.

Nie łącz domyślnego źródła historii z elementem HistoryProvider, który ma load_messages=True. Nie ustawiaj również opcji kontynuacji conversation_idusługi , previous_response_idlub conversation podrzędnej. Host odrzuca te konfiguracje, aby zapobiec zduplikowaniu historii.

Użyj ResponsesHostServer(agent, history_source="agent"), gdy dostawca historii agenta lub usługa modelu podrzędnego musi zarządzać historią rozmowy. Ten tryb przekazuje tylko dane wejściowe bieżącego żądania z Agent Server i zachowuje historię agenta oraz sposób działania magazynu usługi. Implementacje niestandardowe SupportsAgentRun muszą używać tego trybu. Parametr store pozostaje oddzielny: wybiera dostawcę odpowiedzi, który utrwala dane wejściowe interfejsu API odpowiedzi i dane wyjściowe w obu trybach.

Host jest właścicielem dostarczonego agenta i może dodać dostawców kontekstu specyficznych dla hostingu. Nie należy ponownie używać agenta z innym hostem ani wywoływać go bezpośrednio po zakończeniu budowy hosta.

Zachowywać stan i obsługiwać długotrwałe rozmowy

ResponsesHostServer Domyślnie konfiguruje magazyny oparte na platformie Foundry. W przypadku agentów niebędących agentami przepływu pracy AgentSessionStoreProvider udostępnia element FoundryAgentSessionStore. W przypadku agentów przepływu pracy element CheckpointStoreProvider udostępnia element FoundryCheckpointStore. FunctionApprovalStoreProvider udostępnia FoundryFunctionApprovalStore dla oczekujących zatwierdzeń. Te repozytoria używają Foundry State Store w środowisku hostowanym oraz lokalnego stanu serwera Agent Server, gdy uruchamiasz je lokalnie.

W przypadku history_source="agent" skonfigurowany magazyn sesji zachowuje stan dostawcy przenoszony przez AgentSession, w tym komunikaty z InMemoryHistoryProvider.

Aby dostosować pamięć, przekaż StoreProvider do function_approval_store_provider lub agent_session_store_provider. Przekaż element ContextScopedStoreProvider do checkpoint_store_provider. Na przykład zaimplementuj SessionStore i StoreProvider[SessionStore] tak, aby używały własnego magazynu sesji dla agenta nieopartego na przepływie pracy.

Zaimportuj ResponsesServerOptions z azure.ai.agentserver.responses i przekaż go do ResponsesHostServer za pomocą parametru options. Dostępne długotrwałe opcje konwersacji zależą od typu agenta:

ResponsesHostServer zgłasza RuntimeError, jeśli włączysz odpowiedzi działające w tle z mechanizmem odporności dla agenta, który nie jest agentem przepływu pracy, lub konwersacje sterowalne dla agenta przepływu pracy. Aby zapoznać się z pełnymi implementacjami, zobacz przykłady niestandardowego magazynu danych, odpornego długotrwałego przepływu pracy i sterowalnego długotrwałego agenta.

Obsługa żądań zgody OAuth

Gdy narzędzie MCP hostowane w usłudze Foundry wymaga zgody użytkownika, ResponsesHostServer zwraca niekompletną odpowiedź z elementem wyjściowym oauth_consent_request . Przedstaw użytkownikowi element consent_link, a następnie kontynuuj, używając identyfikatora niekompletnej odpowiedzi jako previous_response_id, po wyrażeniu zgody przez użytkownika. Host zachowuje sesję agenta dla tej próby i uwidacznia tylko bezwzględne łącza zgody HTTPS.

Za pomocą protokołu Invocations w języku C# implementujesz niestandardowy InvocationHandler, aby przetwarzać przychodzące żądania.

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

Metoda AddInvocationsServer rejestruje usługi protokołu Invocations. Zaimplementowana jest implementacja InvocationHandler w celu zdefiniowania sposobu przetwarzania poszczególnych żądań przez agenta.

Dla uproszczonej konfiguracji użyj InvocationsHostServer z pakietu agent_framework_foundry_hosting. Automatycznie opakowuje agenta w sposób podobny do ResponsesHostServer i zajmuje się zarządzaniem sesjami:

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

Aby uzyskać pełną kontrolę nad obsługą żądań, użyj InvocationAgentServerHost bezpośrednio z pakietu azure.ai.agentserver.invocations i zaimplementuj własną procedurę obsługi wywołań:

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

Kompletny przykład wdrożenia Invocations znajdziesz w przykładzie Telegrama hostowanym w Foundry. Umieszcza usługę API Management przed webhookiem hostowanego agenta i używa tożsamości zarządzanych, usługi Key Vault oraz usługi Cosmos DB do przechowywania trwałej historii konwersacji.