Host LangGraph-agents als in Foundry gehoste agents

Gebruik het pakket langchain_azure_ai.agents.hosting om een gecompileerde LangGraph-grafiek beschikbaar te maken via de protocollen voor Microsoft Foundry hosted agents. Met het hostingpakket kunt u de logica van uw LangChain- en LangGraph-agent in code houden terwijl Foundry de gehoste runtime, sessies, schaal, identiteit en protocoleindpunten beheert.

In dit artikel maakt u een minimale LangGraph-agent, maakt u deze beschikbaar via het protocol Antwoorden of Aanroepen, test u deze via HTTP en implementeert u deze in Foundry met de Azure Developer CLI of de Foundry Toolkit Visual Studio Code-extensie.

U leert ook hoe u een bestaand LangGraph-project migreert zonder de bijbehorende code of configuratie te wijzigen.

Prerequisites

• Een Azure-abonnement. Maak er gratis een.
• Een Gieterij-project.
• Een geïmplementeerd chatmodel, zoals gpt-4.1 of gpt-5-mini.
• Python 3.10 of hoger.
• Azure CLI aangemeld (az login), zodat DefaultAzureCredential kan authenticeren.

Installeer het pakket

Installeer langchain-azure-ai versie 1.2.9 of hoger met de hosting extra:

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

De hosting extra installeert de Foundry-protocolbibliotheken die worden gebruikt door de hostservers:

• azure-ai-agentserver-responses voor het openAI-compatibele /responses eindpunt.
• azure-ai-agentserver-invocations voor het algemene /invocations eindpunt.

Een hostingprotocol kiezen

Gehoste agents kunnen een of meer protocollen beschikbaar maken. Begin met antwoorden voor de meeste gespreksagenten.

Zie Gehoste agents en sessies voor achtergrondinformatie over protocolgedrag en gehoste agentsessies beheren.

Omgevingsvariabelen configureren

Stel de naam van het projecteindpunt en de modelimplementatie in voor lokale ontwikkeling:

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

Wanneer dezelfde code in Foundry wordt uitgevoerd als een Hosted agent, injecteert het platform FOUNDRY_PROJECT_ENDPOINT. Als u azd ai agent init met een voorbeeld azure.yaml gebruikt, gebruikt het gegenereerde project ook FOUNDRY_MODEL_NAME voor de geselecteerde modelimplementatie.

Protocol voor antwoorden

Gebruik het protocol Antwoorden als u een openAI-compatibel chat-eindpunt wilt met streaming, antwoordgeschiedenis en gespreksthreading.

Een antwoordhost maken

Maak een bestand met de naam main.py met een minimale LangGraph-agent die gebruikmaakt van een Foundry-model. Dit patroon komt overeen met het basisantwoordenvoorbeeld in de langchain-azure-ai bronopslagplaats.

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

Wat dit codefragment doet: Maakt een LangGraph-agent met LangChain's create_agent, verbindt deze met het OpenAI-compatibele modeleindpunt van het Foundry-project en geeft de gecompileerde grafiek door aan ResponsesHostServer. De host start een HTTP-server en maakt de grafiek beschikbaar via POST /responses. De server verbindt standaard met de poort 8088of met de waarde van de PORT omgevingsvariabele wanneer deze is ingesteld.

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

Voer de app lokaal uit:

python main.py

Het eindpunt voor antwoorden testen

Verzend een niet-streaming Responses-verzoek naar de lokale 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"

Voor streamingreacties stelt u stream in op true. De host stuurt serververzonden gebeurtenissen van de Responses API, zoals response.created, response.output_text.delta en response.completed.

Gesprekken

ResponsesHostServer ondersteunt twee gespreksstatuspatronen. Het patroon dat wordt gebruikt, is afhankelijk van of uw gecompileerde grafiek een LangGraph-controlepunt heeft.

Gebruik een checkpointer wanneer je grafiek de runtime-status van LangGraph, onderbrekingen of node-lokale status over meerdere beurten nodig heeft. Voor lokale tests kunt u een controlepunt in het geheugen gebruiken:

from langgraph.checkpoint.memory import MemorySaver

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

Gebruik voor Hosted Agents in productie een duurzame checkpointer in plaats van een in-memory-checkpointer, zodat de grafiekstatus behouden blijft bij containerherstarts.

Clients vervolgen een Responses-gesprek door previous_response_id of een conversation-ID door te geven. Voor lokale tests koppelt u de vorige antwoord-id in de volgende aanvraag:

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

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

Wanneer de agent in Foundry draait, werkt hetzelfde patroon via het Responses-eindpunt van de gehoste agent. Als u later ook hetzelfde gehoste sandboxbestandssysteem nodig hebt, neem dan agent_session_id op of gebruik een conversation-ID. Zie Gehoste agentsessies beheren voor meer informatie.

Menselijke-inbreng

Als uw grafiek LangGraph-aanroepen interrupt() gebruikt, toont ResponsesHostServer openstaande interrupts via standaard outputitems van de Responses API:

• Een function_call item met de naam __hosted_agent_adapter_interrupt__.
• Een mcp_approval_request item met server_label ingesteld op langgraph.

Clients kunnen de grafiek hervatten door een function_call_output item te verzenden waarvan call_id het overeenkomt met de interrupt-id of een mcp_approval_response item waarvan approval_request_id de interrupt-id overeenkomt. Gebruik function_call_output wanneer u een rijke LangGraph Command payload met resume, update of goto-velden moet verzenden. Gebruik mcp_approval_response deze functie voor een eenvoudige goedkeurings- of afkeuringsstroom.

Protocol voor aanroepen

Gebruik InvocationsHostServer deze functie wanneer uw bellers de aanvraagvorm voor de antwoord-API niet kunnen gebruiken of wanneer uw scenario geen chatgesprek is. De standaardhost voor aanroepen accepteert een message tekenreeks en een optionele stream vlag.

Een aanroephost maken

Gebruik dezelfde modelbouwfunctie uit het voorbeeld Antwoorden, maar begin InvocationsHostServer in plaats van 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()

Wat dit codefragment doet: Host de LangGraph-agent via POST /invocations. De MemorySaver checkpointer biedt lokale continuïteit over meerdere interacties heen voor een opgegeven sessie-ID. Gebruik voor productie een robuust checkpointmechanisme, zodat de status behouden blijft na het opnieuw opstarten van containers.

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

Het eindpunt voor aanroepen testen

Een niet-streamingaanvraag verzenden:

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

Niet-streamingaanvragen retourneren JSON in deze vorm:

{
  "response": "Assistant text"
}

Voor gesprekken met meerdere beurten hergebruikt u de x-agent-session-id responseheader als queryparameter agent_session_id in het volgende verzoek:

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

Streamingverzoeken geven text/event-stream gebeurtenissen met payloads met tokens terug:

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

De stream bevat token gebeurtenissen gevolgd door een terminal done gebeurtenis:

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

event: done
data: {}

Het aanvraagschema aanpassen

Als u de aanvraagtekst wilt aanpassen, maakt u een subklasse van InvocationsHostServer en overschrijft u parse_request. U kunt ook build_input overschrijven om de geparseerde gegevens toe te wijzen aan een aangepaste graaftoestand.

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

Wat dit codefragment doet: Accepteert een aangepaste nettolading van een ticket en converteert deze naar één gebruikersbericht voordat de host de grafiek aanroept. Gebruik build_input voor complexere grafiekstatussen in plaats van het verzoek tot tekst af te vlakken.

Deploy

U kunt implementeren met behulp van de Azure Developer CLI of de Foundry Toolkit Visual Studio Code-extensie. De Azure Cli-stroom voor ontwikkelaars maakt gebruik van voorbeeldbestanden azure.yaml en Docker. De extensiestroom biedt een begeleide implementatie-ervaring in Visual Studio Code.

Voor de implementatie van gehoste agents is de rol Foundry Project Manager op het project vereist. Zie Een gehoste agent implementeren voor meer informatie.

Implementeren met Azure Developer CLI

De langchain-azure-ai bronopslagplaats bevat voorbeelden van gehoste agents die u kunt uitvoeren en implementeren met behulp van de Azure Developer CLI. De flow maakt gebruik van de azure.yaml, Dockerfile en main.py van elke sample. Zie azure.yaml meer informatie over de configuratie van de hosted-agent in.

Installeer de AI-agentextensie en meld u aan voordat u een voorbeeld initialiseert:

azd ext install azure.ai.agents
azd auth login

Docker moet lokaal actief zijn omdat azd ai agent run de containerimage bouwt die is opgegeven in de Dockerfile van het voorbeeld. Zie de naslaginformatie Azure Developer CLI voor meer informatie.

Initialiseer met een voorbeeldbestand 'azure.yaml'

Maak een nieuwe map en initialiseer deze op basis van een voorbeeld azure.yaml. Vervang de azure.yaml URL door het voorbeeld dat u wilt gebruiken.

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

Volg de aanwijzingen van azd ai agent init. Als u nog geen Foundry-project en modelimplementatie hebt, kan de initialisatiestroom u helpen bij het maken ervan.

De container lokaal uitvoeren

Voer de agenthost lokaal uit via azd:

azd ai agent run

De host draait op http://127.0.0.1:8088. Roep in een andere terminal het lokale protocoleindpunt rechtstreeks aan:

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

PowerShell-equivalent:

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

U kunt de lokale agent ook aanroepen via azd:

azd ai agent invoke --local "Hello!"

Implementeren in Foundry

Als het geïnitialiseerde project gebruikmaakt van een nieuw Foundry-project en een nieuwe modelimplementatie, richt u eerst de Azure resources in:

azd provision

Rol de agent uit:

azd deploy

De implementatie verpakt de agent in een containerinstallatiekopie, pusht deze naar het ingerichte containerregister en implementeert deze naar de runtime van de Foundry Hosted Agent.

De Foundry-hostinginfrastructuur injecteert runtime-omgevingsvariabelen in de agent, waaronder:

• FOUNDRY_PROJECT_ENDPOINT: de eindpunt-URL voor het Foundry-project waar de agent is geïmplementeerd.
• FOUNDRY_MODEL_NAME: De naam van de modelimplementatie geselecteerd tijdens azd ai agent init.
• APPLICATIONINSIGHTS_CONNECTION_STRING: de verbindingsreeks voor het Application Insights-exemplaar van het project.

Zie Een gehoste agent implementeren en de levenscyclus van gehoste agents beheren voor volledige implementatieconcepten, machtigingen en beheer.

Implementeren met Foundry Toolkit Visual Studio Code-extensie

Zie quickstart: Uw eerste gehoste agent implementeren voor implementatie op basis van extensies.

Een bestaande agent hosten

Als uw toepassing al werkt met LangSmith of de LangGraph CLI, gebruikt u de langchain_azure_ai.agents.hosting.run module om de agent naadloos op Foundry te hosten zonder de code of configuratie ervan te wijzigen.

Start vanaf de hoofdmap van het project een Responses-host:

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

Als u dezelfde graaf beschikbaar wilt maken via het Invocations-protocol, stelt u --protocol in op invocations. Als langgraph.json u meerdere grafieken definieert, geeft u de grafieknaam door als het eerste argument. Gebruik --config <path> dit als het configuratiebestand zich niet op het standaardpad langgraph.json bevindt. Voorbeeld:

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

Gebruik dezelfde moduleopdracht als het containerinvoerpunt wanneer u de bestaande toepassing implementeert in Foundry.

Configureer bijvoorbeeld de opdracht in azure.yaml. De belangrijkste instelling is het startpunt.

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

Gebruik deze controlelijst om veelvoorkomende problemen vast te stellen bij het ontwikkelen van gehoste agents met langchain_azure_ai.agents.hosting.

Validatie van grafiekschema mislukt

De standaardhosts verwachten een gecompileerde LangGraph-grafiek waarvan de status een messages veld heeft, zoals MessagesState. Als uw graaf gebruikmaakt van een aangepast statusschema, moet u de host subklasseren en build_input overschrijven. Overschrijf voor Responses handle_create wanneer u volledige controle nodig hebt over het parseren van verzoeken, de uitvoering van de grafiek en de gegenereerde Responses-gebeurtenissen.

De gespreksstatus wordt niet voortgezet

Voor het Responses-protocol geeft u previous_response_id of een conversation-ID door in latere beurten. Als uw graaf een checkpointer gebruikt, controleer dan of de checkpointer is geconfigureerd en persistent is voor de omgeving waarin de agent wordt uitgevoerd.

Voor het protocol Invocations slaat het platform de gespreksgeschiedenis niet op. Gebruik een agent_session_id queryparameter om latere aanroepen naar dezelfde gehoste sandbox te routeren en gebruik uw eigen statusarchief of LangGraph-controlepunt voor gespreksstatus.

Het model kan niet worden bereikt in de gehoste container

Controleer of de versie van de gehoste agent FOUNDRY_MODEL_NAME bevat en of de agentidentiteit gemachtigd is om het Foundry-project aan te roepen. Het platform stelt FOUNDRY_PROJECT_ENDPOINT in; je code moet die variabele uitlezen wanneer die in Foundry wordt uitgevoerd.

Volgende stap

Verwante inhoud

• Aan de slag met LangChain en LangGraph met Foundry
• Foundry Agent Service gebruiken met LangGraph
• LangChain- en LangGraph-apps traceren met Microsoft Foundry en Azure Monitor
• Gehoste agentsessies beheren