Hostowani agenci programu Foundry

Hostowane agenty w usłudze Microsoft Foundry Agent umożliwiają wdrażanie agentów programu *Agent Framework* jako konteneryzowanych aplikacji w infrastrukturze zarządzanej przez Microsoft. Platforma obsługuje skalowanie, trwałość stanu sesji, zabezpieczenia i zarządzanie cyklem życia, dzięki czemu można skoncentrować się na logice agenta. Agenci hostowani Microsoft Foundry są już ogólnie dostępni.

Dzięki integracji hostingu Agent Framework możesz udostępnić obiekt Agent, w tym przepływ pracy opakowany za pomocą Workflow.as_agent(), za pośrednictwem protokołu Foundry Responses lub Invocations przy użyciu minimalnej ilości kodu.

Kiedy używać hostowanych agentów

Wybierz hostowane przez Foundry agenty, jeśli chcesz:

  • Infrastruktura zarządzana — nie trzeba samodzielnie konfigurować kontenerów, serwerów internetowych ani reguł skalowania.
  • Wbudowane zarządzanie sesjami — platforma utrwala $HOME i przesyła pliki przez kolejki i okresy bezczynności.
  • Tożsamość dedykowanego agenta — każdy wdrożony agent uzyskuje własną tożsamość Entra na potrzeby bezpiecznego dostępu do modeli, narzędzi i usług podrzędnych.
  • Punkty końcowe zgodne z interfejsem OpenAI — klienci mogą korzystać z agenta przy użyciu dowolnego zestawu SDK zgodnego z interfejsem OpenAI za pośrednictwem protokołu Odpowiedzi.

Uwaga / Notatka

Integracja języka Python agent-framework-foundry-hosting jest w wersji przedpremierowej. Agenci hostowani Microsoft Foundry, usługa zarządzanego hostingu, są już ogólnie dostępni.

Wymagania wstępne

  • Subskrypcja platformy Azure
  • Azure Developer CLI (azd) z rozszerzeniem agenta sztucznej inteligencji:

Do testowania lokalnego potrzebne są również następujące elementy:

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

W Foundry platforma dostarcza kontekst użytkownika podmiotu wywołującego oraz kontekst wywołania; infrastruktura hostująca używa ich do izolowania stanu dla poszczególnych użytkowników i przekazywania kontekstu żądania do usług Foundry. W przypadku uruchomień lokalnych ten kontekst platformy nie jest dostępny, dlatego aplikacje muszą w razie potrzeby zapewnić własne mechanizmy tożsamości i zarządzania stanem.

Protokół odpowiedzi

Protokół Responses jest zalecanym punktem wyjścia dla większości agentów. Udostępnia punkt końcowy zgodny z interfejsem OpenAI /responses, a platforma automatycznie zarządza historią konwersacji, przesyłaniem strumieniowym oraz cyklem życia sesji.

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:

Zdolność Typ agenta Wymagania i zachowanie
Odpowiedzi w tle odporne na błędy Tylko przepływ pracy Ustaw wartość ResponsesServerOptions(resilient_background=True). Wyślij żądanie Responses za pomocą store=true i background=true. Po ponownym uruchomieniu host wznowi najnowszy trwały punkt kontrolny przepływu pracy lub odtwarza oryginalne dane wejściowe, jeśli nie istnieje żaden punkt kontrolny. Nie konfiguruj magazynu punktów kontrolnych w przepływie pracy, ponieważ host zarządza nim. Spraw, aby zewnętrzne efekty uboczne były idempotentne, ponieważ operacje wykonane po ostatnim trwałym punkcie kontrolnym mogą się powtórzyć.
Konwersacje sterowane Tylko bez przepływu pracy Ustaw ResponsesServerOptions(steerable_conversations=True) i wyślij żądania odpowiedzi za pomocą polecenia store=true. Zachowaj włączenie jednego łańcucha liniowego, ponownie używając tej samej conversation wartości. Alternatywnie wyślij bezpośrednio poprzedzający previous_response_id i zachowaj rozwiązany agent_session_id. Host odrzuca przestarzałych poprzedników, którzy spowodowaliby rozgałęzienie.

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.

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.

Protokół wywołań

Protokół Wywołania zapewnia pełną kontrolę nad żądaniem HTTP i odpowiedzią. Użyj go, gdy potrzebujesz niestandardowych ładunków, przetwarzania niekonwersacyjnego lub protokołów przesyłania strumieniowego, które nie są zgodne z OpenAI.

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

Warning

Magazyn sesji w pamięci w przykładowym niestandardowym programie obsługi jest tracony po ponownym uruchomieniu. Użyj magazynu trwałego (na przykład Cosmos DB) w środowisku produkcyjnym.

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.

Uwaga / Notatka

Obsługa języka Go dla agentów hostowanych w usłudze Foundry będzie wkrótce dostępna. Aktualny status znajdziesz w repozytorium Agent Framework dla Go.

Tip

Zapoznaj się z przykładami Python lub C#, aby zobaczyć projekty hostowanych agentów. Możesz też użyć polecenia azd ai agent init do utworzenia szkieletu projektu agenta hostowanego od podstaw. Zapoznaj się z tym przewodnikiem Szybki start , aby uzyskać instrukcje krok po kroku.

Uruchamianie lokalnie

Interfejs wiersza polecenia dewelopera Azure (azd) zapewnia najprostszy sposób uruchamiania i testowania hostowanego agenta lokalnie.

Inicjowanie projektu

Utwórz nowy folder i zainicjuj go na podstawie przykładowego manifestu:

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

Tip

Manifest może być ścieżką do lokalnego pliku YAML lub adresu URL zdalnego manifestu.

Ustawianie zmiennych środowiskowych

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

Uruchom hosta agenta

azd ai agent run

Agent host rozpoczyna działanie na http://localhost:8088.

Wywoływanie agenta

azd ai agent invoke --local "Hello!"

Możesz też użyć curl:

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

Lub w programie PowerShell:

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

Wdrażanie do platformy Foundry

Po zweryfikowaniu agenta lokalnie wdróż go w usłudze Microsoft Foundry:

  1. Aprowizuj zasoby (jeśli nie masz jeszcze projektu Foundry):

    azd provision

    Tworzy grupę zasobów z instancją Foundry, projektem, implementacją modelu, Application Insights i rejestrem kontenerów.

  2. Wdróż agenta:

    azd deploy

    Spakietuje to Twojego agenta jako obraz kontenera, wypchnie go do Azure Container Registry i wdroży w usłudze Foundry Agent Service.

Infrastruktura hostingu rozwiązania Foundry automatycznie wprowadza następujące zmienne środowiskowe do kontenera agenta w czasie wykonywania:

Variable Opis
FOUNDRY_PROJECT_ENDPOINT Adres URL punktu końcowego dla projektu Foundry.
AZURE_AI_MODEL_DEPLOYMENT_NAME Nazwa wdrożenia modelu (skonfigurowana podczas azd ai agent init).
APPLICATIONINSIGHTS_CONNECTION_STRING Usługa Application Insights parametry połączenia na potrzeby telemetrii.

Po wdrożeniu agent jest dostępny za pośrednictwem dedykowanego punktu końcowego rozwiązania Foundry i można go również przetestować w portalu Foundry.

Następne kroki

Pojęcia dotyczące hostowanych agentów

  • Last updated on