In der Foundry gehostete Agents

Hosted Agents in Microsoft Foundry Agent Service können Sie Agent Framework-Agents als containerisierte Anwendungen für Microsoft verwaltete Infrastruktur bereitstellen. Die Plattform behandelt Skalierung, Sitzungszustandspersistenz, Sicherheit und Lebenszyklusverwaltung, damit Sie sich auf die Logik Ihres Agents konzentrieren können. Microsoft Foundry Hosted Agents ist allgemein verfügbar.

Mit der Hostingintegration des Agent-Frameworks können Sie einen Agent, einschließlich eines Workflows, der mit Workflow.as_agent() umschlossen ist, über das Protokoll „Foundry Responses or Invocations“ mit minimalem Code verfügbar machen.

Wann werden gehostete Agents verwendet?

Wählen Sie die von Foundry gehosteten Agents aus, wenn Sie möchten:

  • Verwaltete Infrastruktur – sie müssen keine Container, Webserver oder Skalierungsregeln selbst konfigurieren.
  • Integrierte Sitzungsverwaltung – die Plattform behält $HOME und hochgeladene Dateien über Runden und Leerlaufzeiten hinweg bei.
  • Dedizierte Agentidentität – jeder bereitgestellte Agent erhält seine eigene Entra-Identität, um sicheren Zugriff auf Modelle, Tools und downstream-Dienste zu erhalten.
  • OpenAI-kompatible Endpunkte – Clients können mit Ihrem Agent über das Antwortprotokoll mit jedem openAI-kompatiblen SDK interagieren.

Note

Die Python-agent-framework-foundry-hostingIntegration ist eine Vorabversion. Microsoft Foundry Hosted Agents, der verwaltete Hostingdienst, ist allgemein verfügbar.

Voraussetzungen

Für lokale Tests benötigen Sie außerdem Folgendes:

  • Ein Microsoft Foundry-Projekt mit einer Modellbereitstellung (z. B. gpt-4o)
  • Azure CLI installiert und authentifiziert (az login)

Installieren Sie das Hosting-NuGet-Paket:

dotnet add package Microsoft.Agents.AI.Foundry.Hosting --prerelease
dotnet add package Azure.AI.Projects --prerelease
  • Python 3.10 oder höher

Installieren Sie das Vorabversionshostingpaket, den Foundry-Client und Azure Authentifizierungspaket:

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

In Foundry liefert die Plattform den Benutzerkontext und den Anrufkontext des Anrufers; Die Hostinginfrastruktur verwendet sie, um den Status pro Benutzer zu isolieren und den Anforderungskontext an Foundry-Dienste weiterzuleiten. Lokale Ausführungen empfangen diesen Plattformkontext nicht, daher müssen Anwendungen bei Bedarf eigene Identitäts- und Zustandssteuerelemente bereitstellen.

Antwortprotokoll

Das Antwortprotokoll ist der empfohlene Ausgangspunkt für die meisten Agents. Er bietet einen OpenAI-kompatiblen /responses Endpunkt an, und die Plattform verwaltet den Konversationsverlauf, das Streaming und den Sitzungslebenszyklus automatisch.

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

Der AgentHost.CreateBuilder erstellt einen Anwendungshost, der für die Foundry-Hostingumgebung vorkonfiguriert ist. AddFoundryResponses registriert Ihren Agent mit dem Antwortprotokollhandler und MapFoundryResponses ordnet den /responses HTTP-Endpunkt zu.

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

ResponsesHostServer umschließt Ihren Agenten und macht ihn über das Foundry Responses-Protokoll verfügbar. Bei einem Agent ohne Workflow verwendet history_source="agent_server" standardmäßig den konfigurierten Antwortanbieter des Agent Server als Quelle für den Modellverlauf. Der Host verhindert, dass der nachgeschaltete Modelldienst eine zweite Kopie beibehält, wenn der Client den Verlauf standardmäßig speichert.

Kombinieren Sie die Standard-Verlaufsquelle nicht mit einer HistoryProvider, die über load_messages=True verfügt. Legen Sie außerdem die Fortsetzungsoptionen conversation_id, previous_response_id oder conversation für nachgelagerte Dienste nicht fest. Der Host lehnt diese Konfigurationen ab, um doppelte Verlaufseinträge zu verhindern.

Verwenden Sie ResponsesHostServer(agent, history_source="agent"), wenn der Verlaufsanbieter des Agents oder der nachgeschaltete Modelldienst den Konversationsverlauf verwalten muss. Dieser Modus übergibt nur die aktuelle Anforderungseingabe vom Agent-Server und behält das Verlaufs- und Dienstspeicherverhalten des Agents bei. Benutzerdefinierte SupportsAgentRun Implementierungen müssen diesen Modus verwenden. Der store-Parameter bleibt separat: Er wählt den Response-Anbieter aus, der die Ein- und Ausgaben der Responses API in beiden Modi speichert.

Der Host besitzt den bereitgestellten Agent und fügt möglicherweise hostingspezifische Kontextanbieter hinzu. Verwenden Sie den Agent nicht für einen anderen Host wieder, und rufen Sie ihn nicht direkt nach dem Erstellen des Hosts auf.

Status beibehalten und zeitintensive Unterhaltungen verarbeiten

ResponsesHostServer konfiguriert standardmäßig Foundry-gestützte Speicher. Für Nicht-Workflow-Agenten stellt AgentSessionStoreProvider ein FoundryAgentSessionStore bereit. CheckpointStoreProvider stellt Workflow-Agenten ein FoundryCheckpointStore bereit. FunctionApprovalStoreProvider stellt eine FoundryFunctionApprovalStore für ausstehende Genehmigungen bereit. Diese Speicher verwenden den Foundry State Store, wenn sie gehostet werden, und den lokalen Status des Agent Server, wenn Sie sie lokal ausführen.

Mit history_source="agent" speichert der konfigurierte Sitzungsspeicher den von AgentSession mitgeführten Provider-Zustand, darunter Nachrichten von InMemoryHistoryProvider.

Um den Speicher anzupassen, übergeben Sie eine StoreProvider an agent_session_store_provider oder function_approval_store_provider. Übergeben Sie eine ContextScopedStoreProvider an checkpoint_store_provider. Implementieren Sie beispielsweise StoreProvider[SessionStore] und SessionStore, um einen eigenen Sitzungsspeicher für Nicht-Workflow-Agenten zu verwenden.

Importieren Sie azure.ai.agentserver.responses aus ResponsesServerOptions und übergeben Sie es über den Parameter options an ResponsesHostServer. Die verfügbaren Optionen für lange Unterhaltungen hängen vom Agenttyp ab:

Fähigkeit Agenttyp Anforderungen und Verhalten
Robuste Hintergrundantworten Nur Arbeitsablauf Legen Sie ResponsesServerOptions(resilient_background=True) fest. Senden Sie die Antwortanforderung mit store=true und background=true. Nach einem Neustart setzt der Host den neuesten dauerhaften Workflowprüfpunkt fort oder gibt die ursprüngliche Eingabe wieder, wenn kein Prüfpunkt vorhanden ist. Konfigurieren Sie den Prüfpunktspeicher im Workflow nicht, da der Host ihn verwaltet. Machen Sie externe Nebenwirkungen idempotent, da sich die Arbeit nach dem letzten dauerhaften Prüfpunkt wiederholen kann.
Steuerbare Gespräche Nur außerhalb von Workflows Festlegen ResponsesServerOptions(steerable_conversations=True) und Senden von Antwortanforderungen mit store=true. Halten Sie Gesprächswechsel in einer linearen Kette, indem Sie denselben conversation-Wert wiederverwenden. Alternativ können Sie den unmittelbar vorhergehenden previous_response_id senden und die aufgelöste agent_session_id Datei beibehalten. Der Host lehnt veraltete Vorläufer ab, die zu einer Fork führen würden.

ResponsesHostServer wird ausgelöst RuntimeError , wenn Sie robuste Hintergrundantworten für einen Nicht-Workflow-Agent oder lenkbare Unterhaltungen für einen Workflow-Agent aktivieren. Vollständige Implementierungen finden Sie in den Beispielen für benutzerdefinierten Speicher, ausfallsicheren, langlebigen Workflow und lenkbare Long-Running-Agent-Beispiele .

Wenn ein von Foundry gehostetes MCP-Tool die Zustimmung des Benutzers erfordert, gibt ResponsesHostServer eine unvollständige Antwort mit einem oauth_consent_request-Ausgabeelement zurück. Präsentieren Sie dem Benutzer consent_link, und fahren Sie dann mit der ID der unvollständigen Antwort als previous_response_id fort, sobald der Benutzer seine Zustimmung erteilt hat. Der Host behält die Agent-Sitzung für diesen erneuten Versuch bei und stellt ausschließlich absolute HTTPS-Einwilligungslinks bereit.

Aufrufeprotokoll

Das Aufrufprotokoll bietet Ihnen die vollständige Kontrolle über die HTTP-Anforderung und -Antwort. Verwenden Sie sie, wenn Sie benutzerdefinierte Nutzlasten, nicht unterhaltungsbezogene Verarbeitung oder Streamingprotokolle benötigen, die nicht mit OpenAI kompatibel sind.

Mit dem Invocations-Protokoll in C# implementieren Sie einen benutzerdefinierten InvocationHandler, um eingehende Anforderungen zu verarbeiten:

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

Die AddInvocationsServer Methode registriert die Invocations-Protokolldienste. Sie implementieren InvocationHandler , um zu definieren, wie Ihr Agent jede Anforderung verarbeitet.

Verwenden Sie InvocationsHostServer für ein einfaches Setup aus dem agent_framework_foundry_hosting Paket. Es umschließt Ihren Agenten ähnlich wie ResponsesHostServer und behandelt die Sitzungsverwaltung automatisch.

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

Um die vollständige Kontrolle über die Anforderungsverarbeitung zu erhalten, verwenden Sie InvocationAgentServerHost direkt aus dem Paket azure.ai.agentserver.invocations, und implementieren Sie Ihren eigenen Aufrufhandler:

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

Warnung

Der speicherinterne Sitzungsspeicher im benutzerdefinierten Handlerbeispiel geht beim Neustart verloren. Verwenden Sie langlebige Lagerung (z. B. Cosmos DB) in der Produktion.

Eine vollständige Bereitstellung für Invocations finden Sie im von Foundry gehosteten Telegram-Beispiel. Es platziert API Management vor den gehosteten Agent-Webhooks und verwendet verwaltete Identitäten, Key Vault und Cosmos DB für einen persistenten Gesprächsverlauf.

Note

Go-Unterstützung für in Foundry gehostete Agenten ist bald verfügbar. Den neuesten Status finden Sie im Agent Framework Go-Repository .

Tip

In den Beispielen Python oder in den Beispielen C# finden Sie Beispiele für ein gehostetes Agentprojekt. Oder verwenden Sie den azd ai agent init Befehl, um ein neues gehostetes Agent-Projekt von Grund auf neu zu erstellen. In dieser Schnellstartanleitung finden Sie schrittweise Anleitungen.

Lokales Ausführen

Die Azure Developer CLI (azd) bietet die einfachste Möglichkeit, Ihren gehosteten Agent lokal auszuführen und zu testen.

Initialisieren eines Projekts

Einen neuen Ordner erstellen und es mit einem Beispielmanifest initialisieren.

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

Tip

Das Manifest kann ein Pfad zu einer lokalen YAML-Datei oder eine URL zu einem Remotemanifest sein.

Festlegen von Umgebungsvariablen

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

Starten Sie den Agenthost

azd ai agent run

Der Agent-Host wird auf http://localhost:8088 gestartet.

Agenten aufrufen

azd ai agent invoke --local "Hello!"

Oder verwenden Sie curl:

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

Oder in PowerShell:

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

Bereitstellen in Foundry

Nachdem Sie Ihren Agent lokal überprüft haben, stellen Sie ihn für Microsoft Foundry bereit:

  1. Bereitstellen von Ressourcen (wenn Sie noch kein Foundry-Projekt haben):

    azd provision

    Dadurch wird eine Ressourcengruppe mit einer Foundry-Instanz, einem Projekt, einer Modellbereitstellung, Application Insights und einer Containerregistrierung erstellt.

  2. Bereitstellen des Agents:

    azd deploy

    Dadurch wird Ihr Agent als Containerimage verpackt, an Azure Container Registry verschoben und im Foundry Agent Service bereitgestellt.

Die Foundry-Hostinginfrastruktur fügt automatisch die folgenden Umgebungsvariablen zur Laufzeit in Ihren Agentcontainer ein:

Variable Description
FOUNDRY_PROJECT_ENDPOINT Die Endpunkt-URL für das Foundry-Projekt.
AZURE_AI_MODEL_DEPLOYMENT_NAME Der Name der Modellbereitstellung (konfiguriert während azd ai agent init).
APPLICATIONINSIGHTS_CONNECTION_STRING Die Verbindungszeichenfolge für Application Insights für Telemetrie.

Nach der Bereitstellung ist Ihr Agent über seinen dedizierten Foundry-Endpunkt zugänglich und kann auch über das Foundry-Portal getestet werden.

Nächste Schritte

Konzepte gehosteter Agenten

  • Last updated on