Hantera LangGraph-agenter som Foundry-värdbaserade agenter

Använd paketet langchain_azure_ai.agents.hosting för att exponera en kompilerad LangGraph-graf via protokollen för Microsoft Foundry värdagenter. Med värdpaketet kan du behålla langchain- och LangGraph-agentlogik i kod medan Foundry hanterar värdbaserade runtime-, sessioner, skalnings-, identitets- och protokollslutpunkter.

I den här artikeln skapar du en minimal LangGraph-agent, exponerar den via protokollet Svar eller anrop, testar den via HTTP och distribuerar den till Foundry med Azure Developer CLI eller Foundry Toolkit Visual Studio Code-tillägget.

Du får också lära dig hur du migrerar ett befintligt LangGraph-projekt utan att ändra dess kod eller konfiguration.

Förutsättningar

• Ett Azure-abonnemang. Skapa en kostnadsfritt.
• Ett Foundry-projekt.
• En distribuerad chattmodell, till exempel gpt-4.1 eller gpt-5-mini.
• Python 3.10 eller senare.
• Azure CLI inloggad (az login) så DefaultAzureCredential kan autentisera.

Installera paketet

Installera langchain-azure-ai version 1.2.9 eller senare med värdextra:

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

Tillägget hosting installerar foundry-protokollbiblioteken som används av värdservrarna:

• azure-ai-agentserver-responses för den OpenAI-kompatibla /responses ändpunkten.
• azure-ai-agentserver-invocations för den generiska /invocations slutpunkten.

Välj ett värdprotokoll

Värdagenter kan tillhandahålla ett eller flera protokoll. Börja med Svar för de flesta konversationsagenter.

Bakgrund om protokollbeteende och sessioner finns i Värdbaserade agenter och Hantera värdbaserade agentsessioner.

Konfigurera miljövariabler

Ange projektets slutpunkt och modelldistributionsnamn för lokal utveckling:

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

När samma kod körs som en värdbaserad agent i Foundry matar plattformen in FOUNDRY_PROJECT_ENDPOINT. Om du använder azd ai agent init med ett exempel på azure.yaml, använder det genererade projektet också FOUNDRY_MODEL_NAME för den valda modellinstallationen.

Svarsprotokoll

Använd protokollet Svar när du vill ha en OpenAI-kompatibel chattslutpunkt med direktuppspelning, svarshistorik och konversationstrådar.

Skapa en Responses-värd

Skapa en fil med namnet main.py med en minimal LangGraph-agent som använder en Foundry-modell. Det här mönstret matchar det grundläggande svarsexemplet på langchain-azure-ai källlagringsplatsen.

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

Vad det här kodfragmentet gör: Skapar en LangGraph-agent med LangChains create_agent, ansluter den till Foundry-projektets OpenAI-kompatibla modellslutpunkt och skickar den kompilerade grafen till ResponsesHostServer. Värdprogrammet startar en HTTP-server och gör grafen tillgänglig via POST /responses. Som standard binder servern till port 8088, eller till värdet för PORT miljövariabeln när en anges.

agent = create_deep_agent(...)
ResponsesHostServer(agent).run(port=port)

Kör appen lokalt:

python main.py

Testa svarsslutpunkten

Skicka en begäran om icke-direktuppspelningssvar till den lokala servern.

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"

För strömningssvar anger du stream till true. Värden skickar serverutskickade händelser från Responses API, till exempel response.created, response.output_text.delta och response.completed.

Konversationer

ResponsesHostServer stöder två konversationstillståndsmönster. Mönstret som används beror på om det kompilerade diagrammet har en LangGraph-kontrollpunkt.

Använd en kontrollpunkt när diagrammet behöver Tillstånd för LangGraph-körning, avbrott eller nodlokalt tillstånd mellan svängar. För lokal testning kan du använda en minnesintern kontrollpunkt:

from langgraph.checkpoint.memory import MemorySaver

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

För värdbaserade produktionsagenter använder du en beständig kontrollpunkt i stället för en minnesintern kontrollpunkt så att graftillståndet överlever omstarter av containrar.

Klienter fortsätter en svarskonversation genom att skicka previous_response_id eller ett conversation ID. För lokal testning kedjar du det tidigare svars-ID:t i nästa begäran:

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

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

När agenten körs i Foundry fungerar samma mönster via slutpunkten för svar från värdbaserade agenter. Om senare interaktioner också behöver samma hostade sandbox-filsystem inkluderar du agent_session_id eller använder ett conversation-ID. Mer information finns i Hantera värdbaserade agentsessioner.

Människa i processen

Om din graf använder LangGraph-interrupt()anrop visar ResponsesHostServer väntande avbrott via standardobjekt i Responses API-utdata:

• Ett function_call objekt med namnet __hosted_agent_adapter_interrupt__.
• Ett mcp_approval_request objekt med server_label värdet langgraph.

Klienter kan återuppta diagrammet genom att antingen skicka ett function_call_output objekt vars matchar avbrotts-ID call_id :t eller ett mcp_approval_response objekt vars matchar avbrotts-ID approval_request_id :t. Använd function_call_output när du behöver skicka en utökad LangGraph-nyttolast Command med resume-, update- eller goto-fält. Använd mcp_approval_response för ett enkelt flöde för att godkänna eller avvisa.

Anropsprotokoll

Använd InvocationsHostServer när dina anropare inte kan använda formen För svars-API-begäran eller när ditt scenario inte är en chattkonversation. Den förvalda Invocations-värden accepterar en sträng message och en valfri flagga stream.

Skapa en värd för anrop

Använd samma modellskapande funktion från exemplet Svar, men starta InvocationsHostServer i stället för 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()

Vad det här kodfragmentet gör: Är värd för LangGraph-agenten via POST /invocations. Kontrollpunktsverktyget MemorySaver ger lokal kontinuitet för flera svängar för ett visst sessions-ID. För produktion använder du en beständig kontrollpunkt så att tillståndet överlever omstarter av containrar.

agent = create_deep_agent(...)
InvocationsHostServer(agent).run(port=port)

Testa slutpunkten för anrop

Skicka en begäran som inte är direktuppspelning:

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

Icke-strömmande begäranden returnerar JSON i den här formen:

{
  "response": "Assistant text"
}

För konversationer i flera omgångar återanvänder du svarshuvudet x-agent-session-id som frågeparametern agent_session_id i nästa begäran:

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

Strömmande begäranden returnerar text/event-stream-händelser med tokeninnehåll:

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

Strömmen innehåller tokenhändelser följt av en terminalhändelse done :

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

event: done
data: {}

Anpassa begärandeschemat

Anpassa begärandetexten genom att underklassa InvocationsHostServer och åsidosätta parse_request. Du kan också åsidosätta build_input för att mappa tolkade data till ett anpassat diagramtillstånd.

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

Vad det här kodfragmentet gör: Accepterar en anpassad biljettnyttolast och konverterar den till ett meddelande för en enskild användare innan värden anropar diagrammet. För mer komplexa graftillstånd, åsidosätt build_input i stället för att förenkla begäran till text.

Rulla ut

Du kan distribuera med hjälp av Azure Developer CLI eller Foundry Toolkit Visual Studio Code-tillägget. CLI-flödet Azure Developer använder exempelfiler azure.yaml och Docker. Tilläggsflödet ger en guidad distributionsupplevelse i Visual Studio Code.

Distribution av värdbaserad agent kräver rollen Foundry Project Manager i projektet. Mer information finns i Distribuera en värdbaserad agent.

Distribuera med Azure Developer CLI

Källlagringsplatsen langchain-azure-ai innehåller värdbaserade agentexempel som du kan köra och distribuera med hjälp av Azure Developer CLI. Flödet använder varje provs azure.yaml, Dockerfile och main.py. Mer information om konfigurationen för värdbaserad agent i azure.yaml finns i Skapa azure.yaml för värdbaserade agenter.

Installera AI-agenttillägget och logga in innan du initierar ett exempel:

azd ext install azure.ai.agents
azd auth login

Docker måste köras lokalt eftersom azd ai agent run skapar containeravbildningen som deklarerats i exemplets Dockerfile. Mer information om kommandon finns i cli-referensen Azure Developer.

Initiera med hjälp av ett exempel på azure.yaml

Skapa en ny mapp och initiera den från ett exempel azure.yaml. azure.yaml Ersätt URL:en med det exempel som du vill använda.

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

Följ anvisningarna från azd ai agent init. Om du inte redan har ett Foundry-projekt och en modelldistribution kan initieringsflödet vägleda dig genom att skapa dem.

Kör containern lokalt

Kör värden för agenten lokalt via azd:

azd ai agent run

Värden fungerar på http://127.0.0.1:8088. Anropa den lokala protokollslutpunkten direkt i en annan terminal:

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

PowerShell-motsvarighet:

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

Du kan också anropa den lokala agenten via azd:

azd ai agent invoke --local "Hello!"

Distribuera till Foundry

Om det initierade projektet använder ett nytt Foundry-projekt och en ny modelldistribution etablerar du först Azure-resurserna:

azd provision

Distribuera agenten:

azd deploy

Distributionen paketerar agenten i en containeravbildning, push-överför den till det etablerade containerregistret och distribuerar den till Foundry Hosted Agent Runtime.

Foundrys värdinfrastruktur injicerar miljövariabler för körningsmiljön i agenten, inklusive:

• FOUNDRY_PROJECT_ENDPOINT: Slutpunkts-URL:en för Foundry-projektet där agenten distribueras.
• FOUNDRY_MODEL_NAME: Namnet på modelldistributionen som valdes under azd ai agent init.
• APPLICATIONINSIGHTS_CONNECTION_STRING: Connection string för projektets Application Insights-instans.

Fullständiga distributionsbegrepp, behörigheter och hanteringsinformation finns i Distribuera en värdbaserad agent och Hantera värdbaserad agentlivscykel.

Distribuera med Foundry Toolkit Visual Studio Code-tillägget

Information om tilläggsbaserad distribution finns i Snabbstart: Distribuera din första värdbaserade agent.

Vara värd för en befintlig agent

Om ditt program redan fungerar med LangSmith eller LangGraph CLI använder du modulen langchain_azure_ai.agents.hosting.run för att sömlöst vara värd för agenten på Foundry utan att ändra dess kod eller konfiguration.

Starta en Responses-värdtjänst i projektroten:

python -m langchain_azure_ai.agents.hosting.run --protocol responses

Om du vill exponera samma graf via anropsprotokollet anger du --protocol till invocations. Om langgraph.json definierar flera grafer skickar du grafnamnet som det första argumentet. Använd --config <path> om konfigurationsfilen inte finns på standardsökvägen langgraph.json . Ett exempel:

python -m langchain_azure_ai.agents.hosting.run agent --protocol invocations

Använd samma modulkommando som containerns startpunkt när du distribuerar det befintliga programmet till Foundry.

Konfigurera till exempel kommandot i azure.yaml. Den viktigaste inställningen är startpunkten.

services:
  my-agent:
    host: azure.ai.agent
    kind: hosted
    codeConfiguration:
      runtime: python_3_13
      entryPoint: '-m langchain_azure_ai.agents.hosting.run --protocol responses'
      ...
    ...

Troubleshooting

Använd den här checklistan för att diagnostisera vanliga problem när du utvecklar värdbaserade agenter med langchain_azure_ai.agents.hosting.

Verifieringen av diagramschemat misslyckas

Standardvärdarna förväntar sig en kompilerad LangGraph-graf vars tillstånd har ett messages fält, till exempel MessagesState. Om diagrammet använder ett anpassat tillståndsschema underklassar du värden och åsidosätter build_input. För Responses, åsidosätt handle_create när du behöver fullständig kontroll över parsning av förfrågningar, exekvering av grafen och genererade Responses-händelser.

Konversationstillståndet fortsätter inte

För Responses-protokollet ska du skicka med previous_response_id eller ett conversation-ID i senare omgångar. Om din graf använder en kontrollpunktshanterare ska du se till att kontrollpunktshanteraren är korrekt konfigurerad och beständig för miljön där agenten körs.

För protokollet Anrop lagrar plattformen inte konversationshistorik. Använd en agent_session_id frågeparameter för att styra senare anrop till samma hostade sandbox-miljö och använd din egen tillståndslagring eller LangGraph checkpointer för konversationens tillstånd.

Det går inte att nå modellen i den värdbaserade containern

Bekräfta att den värdbaserade agentversionen innehåller FOUNDRY_MODEL_NAMEoch att agentidentiteten har behörighet att anropa Foundry-projektet. Plattformen anger FOUNDRY_PROJECT_ENDPOINT; din kod ska läsa den variabeln när den körs i Foundry.

Nästa steg

Relaterat innehåll

• Kom igång med LangChain och LangGraph med Foundry
• Använd Foundry Agent Service med LangGraph
• Spåra LangChain- och LangGraph-appar med Microsoft Foundry och Azure Monitor
• Hantera värdbaserade agentsessioner