LangGraph-Agenten als in Foundry gehostete Agenten hosten

Verwenden Sie das Paket langchain_azure_ai.agents.hosting, um ein kompiliertes LangGraph-Diagramm über die Protokolle für Microsoft Foundry hosted Agents verfügbar zu machen. Mit dem Hostingpaket können Sie Ihre LangChain- und LangGraph-Agentlogik im Code beibehalten, während Foundry die gehostete Laufzeit, Sitzungen, Skalierung, Identität und Protokollendpunkte verwaltet.

In diesem Artikel erstellen Sie einen minimalen LangGraph-Agenten, stellen ihn entweder über das Responses- oder das Invocations-Protokoll bereit, testen ihn über HTTP und stellen ihn mit der Azure Developer CLI oder der Foundry Toolkit Visual Studio Code-Erweiterung in Foundry bereit.

Voraussetzungen

  • Ein Azure-Abonnement. Erstellen Sie ein kostenloses Konto.
  • Ein Foundry-Projekt.
  • Ein bereitgestelltes Chatmodell, wie gpt-4.1 oder gpt-5-mini.
  • Python 3.10 oder höher.
  • Azure CLI ist angemeldet (az login), damit DefaultAzureCredential sich authentifizieren kann.

Installiere das Paket

Installieren Sie langchain-azure-ai 1.2.4 oder neuer mit dem Hosting-Extra:

pip install -U "langchain-azure-ai[hosting]>=1.2.4" azure-identity

Das hosting Extra installiert die von den Hostservern verwendeten Foundry-Protokollbibliotheken:

  • azure-ai-agentserver-responses für den OpenAI-kompatiblen /responses Endpunkt.
  • azure-ai-agentserver-invocations für den generischen /invocations Endpunkt.

Auswählen eines Hostingprotokolls

Gehostete Agents können ein oder mehrere Protokolle verfügbar machen. Beginnen Sie für die meisten Konversationsagenten mit Responses.

Protokoll Hostklasse Endpunkt Verwenden Sie, wenn
Antworten ResponsesHostServer /responses Sie möchten OpenAI-kompatiblen Chat, Streaming, Antwortverlauf und Konversations-Threading.
Aufrufe InvocationsHostServer /invocations Sie möchten eine benutzerdefinierte JSON-Struktur, einen Endpunkt im Webhook-Stil oder eine nicht-konversationelle Verarbeitung.

Hintergrundinformationen zu Protokollverhalten und -sitzungen finden Sie unter "Gehostete Agents " und "Verwalten von Gehosteten Agent-Sitzungen".

Umgebungsvariablen konfigurieren

Legen Sie den Projektendpunkt und den Modellbereitstellungsnamen für die lokale Entwicklung fest:

export FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
export FOUNDRY_MODEL_NAME="gpt-4.1"

Wenn derselbe Code als gehosteter Agent in Foundry ausgeführt wird, fügt die Plattform FOUNDRY_PROJECT_ENDPOINT ein. Wenn Sie azd ai agent init mit einem Beispiel azure.yaml verwenden, verwendet das generierte Projekt ebenfalls FOUNDRY_MODEL_NAME für die ausgewählte Modellbereitstellung.

Antwortprotokoll

Verwenden Sie das Responses-Protokoll, wenn Sie einen OpenAI-kompatiblen Chat-Endpunkt mit Streaming, Antwortverlauf und Konversations-Threads benötigen.

Erstellen eines Antworthosts

Erstellen Sie eine Datei main.py mit einem minimalen LangGraph-Agent, der ein Foundry-Modell verwendet. Dieses Muster entspricht dem grundlegenden Antwortbeispiel im langchain-azure-ai Quell-Repository.

import os

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

from langchain_azure_ai.agents.hosting import ResponsesHostServer

_AZURE_AI_SCOPE = "https://ai.azure.com/.default"


def build_chat_model() -> ChatOpenAI:
    project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"].rstrip("/")
    deployment = os.environ.get("FOUNDRY_MODEL_NAME", "gpt-4.1")
    credential = DefaultAzureCredential()
    project = AIProjectClient(endpoint=project_endpoint, credential=credential)
    openai_client = project.get_openai_client()
    token_provider = get_bearer_token_provider(credential, _AZURE_AI_SCOPE)

    return ChatOpenAI(
        model=deployment,
        base_url=str(openai_client.base_url),
        api_key=token_provider,
    )


def main() -> None:
    graph = create_agent(build_chat_model(), tools=[])
    port = int(os.environ.get("PORT", "8088"))
    ResponsesHostServer(graph).run(port=port)


if __name__ == "__main__":
    main()

Funktionsweise dieses Codeausschnitts: Erstellt einen LangGraph-Agent mit LangChains create_agent, verbindet ihn mit dem OpenAI-kompatiblen OpenAI-Modellendpunkt des Foundry-Projekts und übergibt das kompilierte Diagramm an ResponsesHostServer. Der Host startet einen HTTP-Server und stellt den Graphen über POST /responses bereit. Standardmäßig bindet der Server an den Port 8088oder an den Wert der PORT Umgebungsvariable, wenn eine festgelegt ist.

Führen Sie die App lokal aus:

python main.py

Testen des Endpunkts "Antworten"

Senden Sie eine Antwortanforderung ohne Streaming an den lokalen Server.

Bash:

curl -sS -H "Content-Type: application/json" \
  -X POST http://localhost:8088/responses \
  -d '{"input":"Give me one practical tip for testing hosted agents.","stream":false}'

PowerShell:

$body = @{
  input = "Give me one practical tip for testing hosted agents."
  stream = $false
} | ConvertTo-Json

Invoke-RestMethod `
    -Uri http://localhost:8088/responses `
    -Method Post `
    -Body $body `
    -ContentType "application/json"

Setzen Sie für Streaming-Antworten stream auf true. Der Host sendet vom API-Server übermittelte Ereignisse wie z. B. response.created, response.output_text.delta und response.completed.

Gespräche

ResponsesHostServer unterstützt zwei Muster zur Verwaltung des Konversationsstatus. Das von ihr verwendete Muster hängt davon ab, ob das kompilierte Diagramm über einen LangGraph-Prüfpunkt verfügt.

Diagrammkonfiguration Konversationsquelle Was der Host zu einem späteren Zeitpunkt an das Diagramm sendet
Graph ohne Prüfpunkt Antwortverlauf aus der Protokolllaufzeit Vorheriger Antwortverlauf sowie die aktuelle Anforderungseingabe
Graph, der mit einem Checkpointer erstellt wurde LangGraph-Checkpoint-Status, indiziert nach dem Konversations- oder Antwort-Thread Nur aktuelle Anforderungseingabe

Verwenden Sie einen Checkpointer, wenn Ihr Graph den LangGraph-Laufzeitstatus, Interrupts oder einen knotenlokalen Status über mehrere Durchläufe hinweg benötigt. Für lokale Tests können Sie einen Speicherprüfpunkt verwenden:

from langgraph.checkpoint.memory import MemorySaver

graph = create_agent(
    build_chat_model(),
    tools=[],
    checkpointer=MemorySaver(),
)

Verwenden Sie für Hosted Agents in der Produktion einen dauerhaften Checkpointer anstelle eines speicherinternen Checkpointers, damit der Graph-Zustand auch nach einem Neustart des Containers erhalten bleibt.

Clients setzen eine Antworten-Unterhaltung fort, indem sie previous_response_id oder eine conversation-ID übergeben. Verketten Sie für lokale Tests die vorherige Antwort-ID in der nächsten Anforderung:

POST http://localhost:8088/responses
Content-Type: application/json

{
  "input": "Can you make that more concise?",
  "previous_response_id": "<previous-response-id>",
  "stream": false
}

Wenn der Agent in Foundry ausgeführt wird, funktioniert dasselbe Muster über den Antworten-Endpunkt für gehostete Agents. Wenn in späteren Interaktionen ebenfalls dasselbe gehostete Sandbox-Dateisystem benötigt wird, fügen Sie agent_session_id ein oder verwenden Sie eine conversation-ID. Ausführliche Informationen finden Sie unter Verwalten gehosteter Agentsitzungen.

Human-in-the-Loop

Wenn Ihr Graph LangGraph-Aufrufe interrupt() verwendet, macht ResponsesHostServer ausstehende Unterbrechungen über standardmäßige Ausgabeelemente der Antworten-API verfügbar:

  • Ein function_call Element mit dem Namen __hosted_agent_adapter_interrupt__.
  • Ein mcp_approval_request-Element, bei dem server_label auf langgraph festgelegt ist.

Clients können den Graphen fortsetzen, indem sie entweder ein function_call_output-Element senden, dessen call_id mit der Interrupt-ID übereinstimmt, oder ein mcp_approval_response-Element, dessen approval_request_id mit der Interrupt-ID übereinstimmt. Verwenden Sie function_call_output, wenn Sie eine umfangreiche LangGraph-Command-Nutzlast mit resume-, update- oder goto-Feldern senden müssen. Verwenden Sie mcp_approval_response für einen einfachen Genehmigungs- oder Ablehnungsablauf.

Aufrufeprotokoll

Verwenden Sie InvocationsHostServer, wenn Ihre Anrufer das Anfrageformat der Responses API nicht verwenden können oder wenn Ihr Szenario keine Chat-Konversation ist. Der Standardhost für Invocations akzeptiert eine message-Zeichenfolge und ein optionales stream-Flag.

Invocations-Host erstellen

Verwenden Sie die gleiche Modellerstellungsfunktion aus dem Beispiel "Antworten", beginnen Sie jedoch InvocationsHostServer anstelle von ResponsesHostServer.

import os

from langchain.agents import create_agent
from langgraph.checkpoint.memory import MemorySaver

from langchain_azure_ai.agents.hosting import InvocationsHostServer


def main() -> None:
    graph = create_agent(
        build_chat_model(),
        tools=[],
        checkpointer=MemorySaver(),
    )
    port = int(os.environ.get("PORT", "8088"))
    InvocationsHostServer(graph).run(port=port)


if __name__ == "__main__":
    main()

Funktionsweise dieses Codeausschnitts: Hosten des LangGraph-Agents über POST /invocations. Der MemorySaver Checkpointer bietet lokale Kontinuität über mehrere Interaktionen für eine angegebene Sitzungs-ID. Verwenden Sie im Produktionseinsatz einen persistenten Checkpointer, damit der Status bei Container-Neustarts erhalten bleibt.

Den Endpunkt für Aufrufe testen

Senden einer Nicht-Streaming-Anforderung:

curl -i -X POST http://localhost:8088/invocations \
  -H "Content-Type: application/json" \
  -d '{"message":"My name is Alice.","stream":false}'

Anfragen ohne Streaming geben JSON in folgender Struktur zurück:

{
  "response": "Assistant text"
}

Verwenden Sie bei mehrteiligen Unterhaltungen den x-agent-session-id Antwortheader als agent_session_id Abfrageparameter für die nächste Anfrage:

curl -X POST "http://localhost:8088/invocations?agent_session_id=<session-id>" \
  -H "Content-Type: application/json" \
  -d '{"message":"What is my name?"}'

Streaming-Anfragen geben text/event-stream-Ereignisse mit Token-Nutzdaten zurück:

curl -N -X POST http://localhost:8088/invocations \
  -H "Content-Type: application/json" \
  -d '{"message":"Count to 5.","stream":true}'

Der Datenstrom enthält Tokenereignisse, gefolgt von einem Terminalereignis done :

data: {"token": "..."}

event: done
data: {}

Anpassen des Anforderungsschemas

Um den Anforderungs-Text anzupassen, leiten Sie eine Unterklasse von InvocationsHostServer ab und überschreiben Sie parse_request. Sie können auch außer Kraft setzen build_input , um die analysierten Daten einem benutzerdefinierten Diagrammzustand zuzuordnen.

from starlette.requests import Request

from langchain_azure_ai.agents.hosting import InvocationsHostServer


class TicketHostServer(InvocationsHostServer):
    async def parse_request(self, request: Request) -> tuple[str, bool]:
        data = await request.json()
        ticket_id = data["ticket_id"]
        description = data["description"]
        stream = bool(data.get("stream", False))
        return f"Summarize ticket {ticket_id}: {description}", stream


if __name__ == "__main__":
    TicketHostServer(graph).run()

Funktionsweise dieses Codeausschnitts: Akzeptiert eine benutzerdefinierte Ticketnutzlast und konvertiert sie in eine einzelne Benutzernachricht, bevor der Host das Diagramm aufruft. Bei komplexeren Graphzuständen überschreiben Sie build_input, anstatt die Anfrage zu Text zu reduzieren.

Deploy

Sie können die Bereitstellung mit der Azure Developer CLI oder der Foundry Toolkit Visual Studio Code-Erweiterung durchführen. Der Azure Entwickler-CLI-Fluss verwendet Beispieldateien azure.yaml und Docker. Der Erweiterungsablauf ermöglicht eine geführte Bereitstellung in Visual Studio Code.

Für die Bereitstellung des gehosteten Agents ist im Projekt die Rolle Foundry Project Manager erforderlich. Ausführliche Informationen finden Sie unter Bereitstellen eines gehosteten Agents.

Bereitstellen mit der Azure Developer CLI

Das langchain-azure-ai Quell-Repository enthält Beispiele für gehostete Agent, die Sie mithilfe der Azure Developer CLI ausführen und bereitstellen können. Der Flow verwendet die Werte azure.yaml, Dockerfile und main.py jeder Probe. Details zur Konfiguration für gehostete Agents finden Sie in azure.yaml, siehe azure.yaml für gehostete Agents erstellen.

Installieren Sie die AI-Agent-Erweiterung, und melden Sie sich an, bevor Sie ein Beispiel initialisieren:

azd ext install azure.ai.agents
azd auth login

Docker muss lokal laufen, da azd ai agent run das im Dockerfile des Beispiels deklarierte Container-Image erstellt. Weitere Informationen finden Sie in der Azure Developer CLI-Referenz.

Initialisieren aus einem Beispiel für azure.yaml

Erstellen Sie einen neuen Ordner, und initialisieren Sie ihn aus einem Beispiel azure.yaml. Ersetzen Sie die azure.yaml URL durch das Beispiel, das Sie verwenden möchten.

mkdir my-langchain-agent
cd my-langchain-agent

azd ai agent init -m https://github.com/langchain-ai/langchain-azure/blob/main/samples/hosting/langgraph-hosted-agents/responses/01_basic/azure.yaml

Folgen Sie den Anweisungen von azd ai agent init. Wenn Sie noch nicht über ein Foundry-Projekt und eine Modellbereitstellung verfügen, kann der Initialisierungsfluss Sie durch die Erstellung führen.

Den Container lokal ausführen

Führen Sie den Agent-Host lokal über azd aus:

azd ai agent run

Der Host wird auf http://127.0.0.1:8088 bereitgestellt. Rufen Sie in einem anderen Terminal den lokalen Protokollendpunkt direkt auf:

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

PowerShell-Entsprechung:

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

Sie können den lokalen Agent auch über azdFolgendes aufrufen:

azd ai agent invoke --local "Hello!"

Bereitstellen in Foundry

Wenn das initialisierte Projekt ein neues Foundry-Projekt und eine Modellbereitstellung verwendet, stellen Sie zuerst die Azure Ressourcen bereit:

azd provision

Bereitstellen des Agents:

azd deploy

Die Bereitstellung verpackt den Agenten in ein Container-Image, überträgt es in die bereitgestellte Containerregistrierung und stellt es für die von Foundry gehostete Agent-Laufzeit bereit.

Die Foundry-Hostinginfrastruktur fügt Laufzeitumgebungsvariablen in den Agent ein, einschließlich:

  • FOUNDRY_PROJECT_ENDPOINT: Die Endpunkt-URL für das Foundry-Projekt, in dem der Agent bereitgestellt wird.
  • FOUNDRY_MODEL_NAME: Der Name der Modellbereitstellung, der während azd ai agent init ausgewählt wurde.
  • APPLICATIONINSIGHTS_CONNECTION_STRING: Die Verbindungszeichenfolge für die Application Insights-Instanz des Projekts.

Vollständige Bereitstellungskonzepte, Berechtigungen und Verwaltungsdetails finden Sie unter Bereitstellen eines gehosteten Agents und Verwalten des Lebenszyklus des gehosteten Agents.

Bereitstellen mit der Visual Studio Code-Erweiterung Foundry Toolkit

Informationen zur erweiterungsbasierten Bereitstellung finden Sie in der Schnellstartanleitung: Bereitstellen Ihres ersten gehosteten Agents.

Troubleshooting

Verwenden Sie diese Checkliste, um häufige Probleme beim Entwickeln von gehosteten Agents mit langchain_azure_ai.agents.hostingzu diagnostizieren.

Fehler bei der Diagrammschemaüberprüfung

Die Standard-Hosts erwarten einen kompilierten LangGraph-Graphen, dessen Zustand ein Feld messages enthält, wie etwa MessagesState. Wenn Ihr Diagramm ein benutzerdefiniertes Statusschema verwendet, leiten Sie eine Unterklasse vom Host ab und überschreiben Sie build_input. Für Responses überschreiben Sie handle_create, wenn Sie die vollständige Kontrolle über das Request-Parsing, die Graphausführung und die ausgegebenen Responses-Ereignisse benötigen.

Der Konversationsstatus wird nicht fortgeführt

Übergeben Sie beim Antworten-Protokoll in späteren Interaktionen previous_response_id oder eine conversation ID. Wenn Ihr Diagramm einen Checkpointer verwendet, stellen Sie sicher, dass der Checkpointer für die Umgebung konfiguriert und dauerhaft ist, in der der Agent ausgeführt wird.

Für das Aufrufprotokoll speichert die Plattform keinen Unterhaltungsverlauf. Verwenden Sie einen agent_session_id Query-Parameter, um spätere Aufrufe an dieselbe gehostete Sandbox zu leiten, und verwenden Sie für den Gesprächszustand Ihren eigenen Zustandsspeicher oder den LangGraph-Checkpointer.

Das Modell kann im gehosteten Container nicht erreicht werden.

Vergewissern Sie sich, dass die Hosted-Agent-Version FOUNDRY_MODEL_NAME enthält und dass die Agentidentität über die Berechtigung verfügt, das Foundry-Projekt aufzurufen. Die Plattform setzt FOUNDRY_PROJECT_ENDPOINT; Ihr Code sollte diese Variable auslesen, wenn er in Foundry ausgeführt wird.

Nächster Schritt

Bereitstellen eines gehosteten Agents

Verwandte Inhalte

  • Last updated on