Hospedar agentes de LangGraph como agentes hospedados en Foundry

Utilice el paquete langchain_azure_ai.agents.hosting para exponer un grafo compilado de LangGraph a través de los protocolos para los agentes hospedados de Microsoft Foundry. El paquete de hospedaje le permite mantener la lógica del agente LangChain y LangGraph en el código mientras Foundry administra el tiempo de ejecución hospedado, las sesiones, la escala, la identidad y los puntos de conexión de protocolo.

En este artículo, creará un agente mínimo de LangGraph, lo expondrá mediante el protocolo Responses o Invocations, lo probará mediante HTTP y lo implementará en Foundry con la CLI para desarrolladores de Azure o la extensión Foundry Toolkit para Visual Studio Code.

Prerequisites

• Una suscripción a Azure. Crear uno gratis.
• Un proyecto de Foundry.
• Un modelo de chat implementado, como gpt-4.1 o gpt-5-mini.
• Python 3.10 o posterior.
• CLI de Azure ha iniciado sesión (az login) para que DefaultAzureCredential pueda autenticarse.

Instalar el paquete

Instale langchain-azure-ai la versión 1.2.4 o posterior con el hospedaje adicional:

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

El extra hosting instala las bibliotecas del protocolo Foundry utilizadas por los servidores anfitriones:

• azure-ai-agentserver-responses para el punto de conexión compatible con /responses OpenAI.
• azure-ai-agentserver-invocations para el punto de conexión genérico /invocations .

Elección de un protocolo de hospedaje

Los agentes hospedados pueden exponer uno o varios protocolos. Empiece con Responses para la mayoría de los agentes conversacionales.

Para obtener información general sobre el comportamiento y las sesiones del protocolo, consulte Agentes hospedados y Administrar sesiones de agente hospedado.

Configuración de las variables de entorno

Establezca el punto de conexión del proyecto y el nombre de implementación del modelo para el desarrollo local:

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

Cuando se ejecuta el mismo código que un agente hospedado en Foundry, la plataforma inserta FOUNDRY_PROJECT_ENDPOINT. Si usa azd ai agent init con un ejemplo azure.yaml, el proyecto generado también usa FOUNDRY_MODEL_NAME para la implementación del modelo seleccionado.

Protocolo de respuestas

Utilice el protocolo Responses cuando quiera un endpoint de chat compatible con OpenAI con streaming, historial de respuestas e hilos de conversación.

Creación de un host de respuestas

Cree un archivo denominado main.py con un agente de LangGraph mínimo que use un modelo Foundry. Este patrón se corresponde con el ejemplo básico de Responses en el repositorio de código fuente langchain-azure-ai.

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

Qué hace este fragmento de código: Crea un agente de LangGraph con langChain create_agent, lo conecta al punto de conexión del modelo compatible con OpenAI del proyecto Foundry y pasa el gráfico compilado a ResponsesHostServer. El anfitrión inicia un servidor HTTP y expone el grafo a través de POST /responses. De forma predeterminada, el servidor se enlaza al puerto 8088o al valor de la PORT variable de entorno cuando se establece uno.

Ejecute la aplicación localmente:

python main.py

Probar el endpoint Responses

Envíe una solicitud de respuestas que no sea de streaming al servidor local.

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"

Para las respuestas en streaming, establezca stream en true. El host emite eventos enviados por el servidor de la API de respuestas, como response.created, response.output_text.deltay response.completed.

Conversaciones

ResponsesHostServer admite dos patrones de estado de conversación. El patrón que usa depende de si el gráfico compilado tiene un punto de control langGraph.

Use un punto de control cuando el grafo necesite el estado en tiempo de ejecución de LangGraph, las interrupciones o el estado local del nodo entre turnos. Para las pruebas locales, puede usar un punto de control en memoria:

from langgraph.checkpoint.memory import MemorySaver

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

En el caso de los agentes hospedados de producción, use un punto de control duradero en lugar de un punto de control en memoria, por lo que el estado del grafo sobrevive a los reinicios del contenedor.

Los clientes continúan una conversación de respuestas pasando el Id. previous_response_id o un conversation. Para las pruebas locales, encadene el identificador de respuesta anterior en la siguiente solicitud:

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

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

Cuando el agente se ejecuta en Foundry, el mismo patrón funciona a través del punto de conexión Responses del agente hospedado. Si los turnos posteriores también necesitan el mismo sistema de archivos del entorno aislado hospedado, incluya agent_session_id o use un Id. conversation. Para obtener más información, consulte Administración de sesiones del agente hospedado.

Participación humana en el bucle

Si su grafo usa llamadas de LangGraph interrupt(), ResponsesHostServer muestra las interrupciones pendientes a través de los elementos de salida de la API estándar de Responses:

• Un function_call elemento denominado __hosted_agent_adapter_interrupt__.
• Un elemento mcp_approval_request con server_label configurado en langgraph.

Los clientes pueden reanudar el grafo enviando un elemento function_call_output cuyo call_id coincida con el ID de interrupción o un elemento mcp_approval_response cuyo approval_request_id coincida con el ID de interrupción. Utilice function_call_output cuando necesite enviar una carga útil enriquecida de LangGraph Command con campos resume, update o goto. Se usa mcp_approval_response para un flujo sencillo de aprobación o rechazo.

Protocolo de invocaciones

Usa InvocationsHostServer cuando quienes realizan las llamadas no puedan usar el formato de solicitud de la API Responses o cuando tu caso de uso no sea una conversación de chat. El host predeterminado de invocaciones acepta una cadena message y una marca stream opcional.

Creación de un host de invocaciones

Use la misma función de creación de modelos del ejemplo respuestas, pero comience InvocationsHostServer en lugar de 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()

Qué hace este fragmento de código: Hospeda el agente de LangGraph a través de POST /invocations. El gestor de puntos de control MemorySaver proporciona continuidad local entre varios turnos para un identificador de sesión concreto. En producción, utilice un sistema de puntos de control persistente para que el estado sobreviva a los reinicios del contenedor.

Probar el punto de conexión Invocations

Envíe una solicitud que no sea de streaming:

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

Las solicitudes que no son de streaming devuelven JSON en esta forma:

{
  "response": "Assistant text"
}

Para las conversaciones de varios turnos, reutilice el encabezado de respuesta x-agent-session-id como el parámetro de consulta agent_session_id en la siguiente solicitud:

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

Las solicitudes de streaming devuelven text/event-stream eventos con cargas de token:

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

La secuencia contiene eventos de token seguidos de un evento de terminal done :

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

event: done
data: {}

Personalización del esquema de solicitud

Para personalizar el cuerpo de la solicitud, cree una subclase de InvocationsHostServer y sobrescriba parse_request. También puede invalidar build_input para asignar los datos analizados a un estado de grafo personalizado.

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

Qué hace este fragmento de código: Acepta una carga útil personalizada de incidencia y la convierte en un único mensaje de usuario antes de que el host invoque el grafo. Para un estado de grafo más complejo, invalide build_input en lugar de aplanar la solicitud al texto.

Implementar

Puede realizar la implementación mediante la CLI de Azure Developer o la extensión de Visual Studio Code Foundry Toolkit. El flujo de la CLI para desarrolladores de Azure usa archivos de ejemplo azure.yaml y Docker. El flujo de extensión proporciona una experiencia de implementación guiada en Visual Studio Code.

El despliegue del agente alojado requiere el rol Foundry Project Manager en el proyecto. Para obtener más información, consulte Implementación de un agente hospedado.

Implementación con la CLI para desarrolladores de Azure

El langchain-azure-ai repositorio de origen incluye ejemplos del agente hospedado que puede ejecutar e implementar mediante la CLI de Azure Developer. El flujo utiliza los valores azure.yaml, Dockerfile y main.py de cada ejemplo. Para obtener más información sobre la configuración del agente hospedado en azure.yaml, consulta Crear un archivo azure.yaml para agentes hospedados.

Instale la extensión del agente de IA e inicie sesión antes de inicializar un ejemplo:

azd ext install azure.ai.agents
azd auth login

Docker debe ejecutarse localmente porque azd ai agent run compila la imagen de contenedor declarada en el Dockerfile del ejemplo. Para obtener más información sobre los comandos, consulte la referencia de la CLI para desarrolladores de Azure.

Inicializar a partir de un ejemplo de azure.yaml

Cree una nueva carpeta e inicialícela a partir de un ejemplo azure.yaml. Reemplace la azure.yaml dirección URL por el ejemplo que desea usar.

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

Siga las indicaciones de azd ai agent init. Si aún no tiene un proyecto y una implementación de modelos de Foundry, el flujo de inicialización puede guiarle a través de su creación.

Ejecute el contenedor localmente

Ejecute el host del agente localmente a través de azd:

azd ai agent run

El host sirve en http://127.0.0.1:8088. En otro terminal, invoque el punto de conexión del protocolo local directamente:

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

Equivalente de PowerShell:

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

También puede invocar el agente local a través de azd:

azd ai agent invoke --local "Hello!"

Implementar en Foundry

Si el proyecto inicializado usa un nuevo proyecto y una implementación de modelos de Foundry, aprovisione primero los recursos Azure:

azd provision

Despliegue el agente:

azd deploy

La implementación empaqueta el agente en una imagen de contenedor, la inserta en el registro de contenedor aprovisionado y la implementa en el entorno de ejecución del agente hospedado de Foundry.

La infraestructura de hospedaje de Foundry inserta variables de entorno en tiempo de ejecución en el agente, entre las que se incluyen:

• FOUNDRY_PROJECT_ENDPOINT: la dirección URL del punto de conexión del proyecto Foundry donde se implementa el agente.
• FOUNDRY_MODEL_NAME: nombre de implementación del modelo seleccionado durante azd ai agent init.
• APPLICATIONINSIGHTS_CONNECTION_STRING: La cadena de conexión de la instancia de Application Insights del proyecto.

Para obtener información completa sobre los conceptos de implementación, los permisos y la administración, consulte Implementación de un agente hospedado y Administración del ciclo de vida del agente hospedado.

Implementar con la extensión Foundry Toolkit para Visual Studio Code

Para la implementación basada en extensiones, consulte Inicio rápido: Implementación del primer agente hospedado.

Troubleshooting

Use esta lista de comprobación para diagnosticar problemas comunes al desarrollar agentes hospedados con langchain_azure_ai.agents.hosting.

Error en la validación del esquema de Graph

Los hosts predeterminados esperan un gráfico de LangGraph compilado cuyo estado tiene un messages campo, como MessagesState. Si el gráfico usa un esquema de estado personalizado, subclase el host e invalide build_input. En Respuestas, invalide handle_create cuando necesite control total sobre el análisis de solicitudes, la ejecución del grafo y los eventos de respuestas emitidos.

El estado de la conversación no continúa

Para el protocolo Responses, pase previous_response_id o un Id. de conversation en los turnos posteriores. Si su grafo usa un sistema de puntos de control, asegúrese de que esté configurado y sea persistente en el entorno donde se ejecuta el agente.

En el caso del protocolo Invocaciones, la plataforma no almacena el historial de conversaciones. Usa un parámetro de consulta agent_session_id para dirigir las llamadas posteriores al mismo entorno aislado alojado y use su propio almacén de estado o el punto de control de LangGraph para el estado de la conversación.

No se puede acceder al modelo en el contenedor hospedado

Confirme que la versión del agente hospedado incluye FOUNDRY_MODEL_NAMEy que la identidad del agente tiene permiso para llamar al proyecto Foundry. La plataforma establece FOUNDRY_PROJECT_ENDPOINT; el código debe leer esa variable al ejecutarse en Foundry.

Paso siguiente

Contenido relacionado

• Introducción a LangChain y LangGraph con Foundry
• Utilice el servicio de agente Foundry con LangGraph
• Seguimiento de aplicaciones LangChain y LangGraph con Microsoft Foundry y Azure Monitor
• Administrar sesiones del agente hospedado