Hostovat agenty LangGraph jako agenty hostované v Foundry

Pomocí balíčku langchain_azure_ai.agents.hosting zpřístupníte kompilovaný graf LangGraph prostřednictvím protokolů pro hostované agenty Microsoft Foundry. Hostingový balíček vám umožňuje ponechat logiku agentů LangChain a LangGraph v kódu, zatímco Foundry spravuje hostované běhové prostředí, relace, škálování, identitu a koncové body protokolu.

V tomto článku vytvoříte minimální agenta LangGraph, zveřejníte ho prostřednictvím protokolu Odpovědi nebo Vyvolání, otestujete ho prostřednictvím protokolu HTTP a nasadíte ho do Foundry pomocí rozhraní příkazového řádku pro vývojáře Azure nebo rozšíření Foundry Toolkit Visual Studio Code.

Předpoklady

• Předplatné služby Azure. Vytvořte si ho zdarma.
• Projekt Foundry.
• Nasazený model chatu, například gpt-4.1gpt-5-mini.
• Python 3.10 nebo novější.
• Azure CLI je přihlášen (az login), takže DefaultAzureCredential se může ověřit.

Nainstalujte balíček

Nainstalujte langchain-azure-ai verzi 1.2.4 nebo novější s extra hostitelem:

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

Extra hosting nainstaluje knihovny protokolů Foundry používané hostitelskými servery:

• azure-ai-agentserver-responses pro koncový bod /responses kompatibilní s OpenAI.
• azure-ai-agentserver-invocations pro obecný /invocations koncový bod.

Volba hostitelského protokolu

Hostovaní agenti můžou vystavit jeden nebo více protokolů. Začněte odpověďmi pro většinu konverzačních agentů.

Protocol	Hostitelská třída	Endpoint	Použít, když
Responses	ResponsesHostServer	/responses	Chcete, aby byl chat kompatibilní s OpenAI, streamování, historie odpovědí a vlákno konverzace.
Vyvolání	InvocationsHostServer	/invocations	Chcete vlastní tvar JSON, koncový bod ve stylu webhooku nebo nekonverzační zpracování.

Základní informace o chování protokolu a relacích najdete v tématu Hostovaní agenti a správa relací hostovaného agenta.

Konfigurace proměnných prostředí

Nastavte název koncového bodu projektu a nasazení modelu pro místní vývoj:

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

Pokud se stejný kód spustí jako hostovaný agent v Foundry, platforma vloží FOUNDRY_PROJECT_ENDPOINT. Pokud použijete azd ai agent init s ukázkou azure.yaml, vygenerovaný projekt také používá FOUNDRY_MODEL_NAME pro vybrané nasazení modelu.

Protokol odpovědí

Protokol Odpovědi použijte, pokud chcete koncový bod chatu kompatibilní s OpenAI se streamováním, historií odpovědí a vlákny konverzace.

Vytvoření hostitele odpovědí

Vytvořte soubor s názvem main.py s minimálním agentem LangGraph, který používá model Foundry. Tento vzor odpovídá základní ukázce odpovědí ve zdrojovém langchain-azure-ai úložišti.

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

Co tato ukázka kódu dělá: Vytvoří agenta LangGraph pomocí create_agent od LangChainu, připojí ho ke koncovému bodu modelu projektu Foundry kompatibilnímu s OpenAI a předá zkompilovaný graf do ResponsesHostServer. Hostitel spustí server HTTP a zpřístupňuje graf prostřednictvím POST /responses. Ve výchozím nastavení server vytvoří vazbu na port 8088nebo hodnotu PORT proměnné prostředí, pokud je nastavena.

Spusťte aplikaci místně:

python main.py

Testování koncového bodu Odpovědi

Odešlete požadavek na odpovědi, které nejsou streamované, na místní 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"

Pro streamované odpovědi nastavte stream na hodnotu true. Hostitel generuje události odesílané serverem rozhraní API pro odpovědi, například response.created, response.output_text.deltaa response.completed.

Konverzace

ResponsesHostServer podporuje dva vzory stavu konverzace. Použitý vzor závisí na tom, zda váš zkompilovaný graf obsahuje mechanismus ukládání kontrolních bodů LangGraph.

Konfigurace grafu	Zdroj konverzace	Co hostitel odesílá do grafu v dalších krocích
Graf bez kontrolního bodu	Historie odpovědí z běhového prostředí protokolu	Historie předchozích odpovědí a aktuální vstupní požadavek
Graf zkompilovaný s použitím checkpointeru	Stav kontrolního bodu langgraphu klíčovaný vláknem konverzace nebo odpovědi	Pouze vstup aktuálního požadavku

Použijte checkpointer, když váš graf potřebuje stav běhového prostředí LangGraph, přerušení nebo lokální stav uzlu napříč interakcemi. Pro místní testování můžete použít kontrolní bod v paměti:

from langgraph.checkpoint.memory import MemorySaver

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

U produkčních hostovaných agentů použijte místo mechanismu ukládání kontrolních bodů do paměti trvalý mechanismus ukládání kontrolních bodů, aby se stav grafu zachoval i po restartu kontejneru.

Klienti pokračují v konverzaci Responses předáním previous_response_id nebo ID conversation. V případě místního testování zřetězte předchozí ID odpovědi v dalším požadavku:

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

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

Když agent běží ve Foundry, stejný postup funguje i prostřednictvím koncového bodu Responses hostovaného agenta. Pokud budou i v dalších tazích potřeba stejný hostovaný souborový systém sandboxu, zahrňte agent_session_id nebo použijte ID conversation. Podrobnosti najdete v tématu Správa relací hostovaného agenta.

člověk ve smyčce

Pokud váš graf používá volání LangGraph interrupt(), ResponsesHostServer zobrazuje nevyřízená přerušení prostřednictvím standardních výstupních položek Responses API:

• Položka function_call s názvem __hosted_agent_adapter_interrupt__.
• Položka mcp_approval_request s parametrem server_label nastaveným na langgraph.

Klienti mohou v grafu pokračovat odesláním buď položky function_call_output, jejíž call_id odpovídá ID přerušení, nebo položky mcp_approval_response, jejíž approval_request_id odpovídá ID přerušení. Použijte function_call_output, když potřebujete odeslat strukturovaný payload LangGraph Command s poli resume, update nebo goto. Použijte mcp_approval_response pro jednoduchý proces schválení nebo zamítnutí.

Protokol vyvolání

Použijte InvocationsHostServer, když vaši volající nemohou použít formát požadavku rozhraní Responses API nebo když váš scénář není chatová konverzace. Výchozí hostitel pro vyvolání přijímá řetězec message a volitelný příznak stream.

Vytvořte hostitele pro Invocations

Použijte stejnou funkci sestavení modelu z příkladu Odpovědi, ale začněte InvocationsHostServer místo 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()

Co tento fragment kódu dělá: Hostuje agenta LangGraph prostřednictvím POST /invocations. MemorySaver mechanismus pro ukládání kontrolních bodů zajišťuje v rámci daného ID relace lokální kontinuitu vícekolových interakcí. V produkčním prostředí použijte trvalý kontrolní bod, takže stav přežije restartování kontejneru.

Otestování koncového bodu Vyvolání

Odeslání požadavku bez streamování:

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

Požadavky bez streamování vrací JSON v tomto tvaru:

{
  "response": "Assistant text"
}

U vícekolových konverzací znovu použijte hlavičku odpovědi x-agent-session-id jako parametr dotazu agent_session_id v dalším požadavku:

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

Požadavky na streamování vracejí události text/event-stream s datovou částí tokenů:

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

Stream obsahuje události tokenu následované událostí terminálu done :

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

event: done
data: {}

Přizpůsobení schématu požadavku

Chcete-li přizpůsobit tělo požadavku, vytvořte podtřídu z InvocationsHostServer a přepište parse_request. Také můžete přepsat build_input, aby mapoval parsovaná data na vlastní stav grafu.

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

Co tato ukázka kódu dělá: Přijímá vlastní datový obsah ticketu a převádí jej na jedinou uživatelskou zprávu předtím, než hostitel spustí graf. Pro složitější stav grafu přepište build_input namísto převedení požadavku na prostý text.

Nasadit

Nasazení můžete provést pomocí Azure Developer CLI nebo rozšíření Foundry Toolkit Visual Studio Code. Postup Azure Developer CLI používá ukázkové azure.yaml soubory a Docker. Průvodce rozšířením poskytuje řízené nasazení v aplikaci Visual Studio Code.

Nasazení hostovaného agenta vyžaduje v projektu roli Foundry Project Manager. Podrobnosti najdete v tématu Nasazení hostovaného agenta.

Nasazení pomocí Azure Developer CLI

Zdrojové langchain-azure-ai úložiště obsahuje ukázky hostovaného agenta, které můžete spustit a nasadit pomocí rozhraní příkazového řádku pro vývojáře Azure. Tok používá azure.yaml, Dockerfile a main.py každého vzorku. Podrobnosti o konfiguraci hostovaného agenta v azure.yamlnajdete v článku Vytvoření souboru azure.yaml pro hostované agenty.

Před inicializací ukázky nainstalujte rozšíření agenta AI a přihlaste se:

azd ext install azure.ai.agents
azd auth login

Docker musí být spuštěn místně, protože azd ai agent run sestaví image kontejneru deklarovanou v souboru Dockerfile ukázky. Podrobnosti o příkazu najdete v referenčních informacích k rozhraní příkazového řádku pro vývojáře Azure.

Inicializovat z ukázkového souboru azure.yaml

Vytvořte novou složku a inicializujete ji z ukázky azure.yaml. azure.yaml Nahraďte adresu URL ukázkou, kterou chcete použít.

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

Postupujte podle pokynů z azd ai agent init. Pokud ještě nemáte projekt Foundry a nasazení modelu, průvodce inicializací vás může provést jejich vytvořením.

Místní spuštění kontejneru

Spusťte hostitelského agenta lokálně pomocí azd:

azd ai agent run

Hostitel slouží na http://127.0.0.1:8088. V jiném terminálu přímo volejte koncový bod místního protokolu:

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

Ekvivalent PowerShellu:

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

Místní agenta můžete vyvolat také prostřednictvím azd:

azd ai agent invoke --local "Hello!"

Nasazení do Foundry

Pokud inicializovaný projekt využívá nový projekt Foundry a nasazení modelu, nejprve zřiďte prostředky Azure:

azd provision

Nasazení agenta:

azd deploy

Nasazení zabalí agenta do kontejnerové image, nahraje ji do zřízeného kontejnerového registru a nasadí ji do hostovaného běhového prostředí agenta Foundry.

Hostingová infrastruktura Foundry vkládá do agenta proměnné prostředí za běhu, včetně:

• FOUNDRY_PROJECT_ENDPOINT: Adresa URL koncového bodu projektu Foundry, kde je agent nasazen.
• FOUNDRY_MODEL_NAME: Název nasazení modelu vybraný během azd ai agent init.
• APPLICATIONINSIGHTS_CONNECTION_STRING: Připojovací řetězec pro instanci služby Application Insights daného projektu.

Úplné koncepty nasazení, oprávnění a podrobnosti správy najdete v tématu Nasazení hostovaného agenta a správa životního cyklu hostovaného agenta.

Nasazení pomocí rozšíření Foundry Toolkit pro Visual Studio Code

Informace o nasazení založeném na rozšíření najdete v tématu Rychlý start: Nasazení prvního hostovaného agenta.

Troubleshooting

Tento kontrolní seznam použijte k diagnostice běžných problémů při vývoji hostovaných agentů pomocí langchain_azure_ai.agents.hosting.

Ověření schématu grafu se nezdařilo

Výchozí hostitelé očekávají zkompilovaný graf LangGraph, jehož stav má messages pole, například MessagesState. Pokud váš graf používá vlastní schéma stavu, vytvořte podtřídu hostitele a přepište build_input. Pro Responses přepište handle_create, pokud potřebujete úplnou kontrolu nad zpracováním požadavků, spouštěním grafu a emitovanými událostmi Responses.

Stav konverzace nepokračuje

U protokolu Responses v dalších kolech předejte previous_response_id nebo ID conversation. Pokud graf používá kontrolní boder, ujistěte se, že je kontrolní boder nakonfigurovaný a odolný pro prostředí, ve kterém běží agent.

Pro protokol Vyvolání platforma neukládá historii konverzací. Pomocí parametru agent_session_id dotazu můžete směrovat pozdější volání do stejného hostovaného sandboxu a pro stav konverzace použít vlastní úložiště stavů nebo kontrolní bod LangGraph.

Model není dostupný v hostovaném kontejneru.

Ověřte, že hostovaná verze agenta zahrnuje FOUNDRY_MODEL_NAMEa že identita agenta má oprávnění volat projekt Foundry. Platforma nastaví FOUNDRY_PROJECT_ENDPOINT; váš kód by měl tuto proměnnou načíst při běhu ve Foundry.

Další krok

Nasazení hostovaného agenta

Související obsah

• Začněte s LangChain a LangGraph ve Foundry
• Použijte službu Foundry Agent s LangGraph
• Trasování aplikací LangChain a LangGraph pomocí Microsoft Foundry a Azure Monitoru
• Správa relací hostovaného agenta