Alojar agentes LangGraph como agentes alojados na Foundry

Utilize o pacote langchain_azure_ai.agents.hosting para expor um grafo LangGraph compilado através dos protocolos para agentes alojados do Microsoft Foundry. O pacote de alojamento permite-lhe manter a lógica dos seus agentes LangChain e LangGraph em código, enquanto o Foundry gere o tempo de execução hospedado, sessões, escala, identidade e endpoints de protocolo.

Neste artigo, crias um agente LangGraph mínimo, expões-no através do protocolo Responses ou Invocations, testas-no através de HTTP e implementas-no no Foundry com a CLI Azure Developer ou a extensão Foundry Toolkit Visual Studio Code.

Pré-requisitos

• Uma assinatura do Azure. Crie um gratuitamente.
• Um projeto da Foundry.
• Um modelo de chat implementado, como gpt-4.1 ou gpt-5-mini.
• Python 3.10 ou posterior.
• CLI do Azure logado (az login) para que DefaultAzureCredential possa autenticar.

Instale o pacote

Instale langchain-azure-ai a versão 1.2.4 ou posterior com o adicional de alojamento:

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

O hosting extra instala as bibliotecas de protocolos Foundry usadas pelos servidores anfitriões:

• azure-ai-agentserver-responses para o endpoint /responses compatível com OpenAI.
• azure-ai-agentserver-invocations para o endpoint genérico /invocations.

Escolha um protocolo de alojamento

Agentes alojados podem expor um ou mais protocolos. Comece pelas Respostas para a maioria dos agentes conversacionais.

Para obter contexto sobre o comportamento e as sessões do protocolo, consulte Agentes alojados e Gerir sessões de agentes alojados.

Configurar variáveis de ambiente

Defina o endpoint do projeto e o nome de implementação do modelo para desenvolvimento local:

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

Quando o mesmo código é executado como agente Alojado no Foundry, a plataforma injeta FOUNDRY_PROJECT_ENDPOINT. Se usar azd ai agent init com um exemplo azure.yaml, o projeto gerado também usa FOUNDRY_MODEL_NAME para a implementação do modelo selecionado.

Protocolo de Respostas

Utilize o protocolo Responses quando quiser um endpoint de chat compatível com a OpenAI, com streaming, histórico de respostas e encadeamento de conversas.

Crie um anfitrião de Respostas

Crie um ficheiro nomeado main.py com um agente LangGraph mínimo que utilize um modelo Foundry. Este padrão corresponde à amostra básica de Respostas no langchain-azure-ai repositório de origem.

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

O que este excerto faz: Cria um agente LangGraph com o LangChain create_agent, liga-o ao endpoint do modelo compatível com OpenAI do projeto Foundry e passa o grafo compilado para ResponsesHostServer. O host inicia um servidor HTTP e expõe o grafo através de POST /responses. Por defeito, o servidor associa-se à porta 8088, ou ao valor da variável de ambiente PORT quando esta estiver definida.

Executa a aplicação localmente:

python main.py

Teste o endpoint Respostas

Envie um pedido Responses sem streaming para o 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 respostas de streaming, defina stream para true. O host emite eventos enviados pelo servidor da API de Respostas, como response.created, response.output_text.delta, e response.completed.

Conversas

ResponsesHostServer suporta dois padrões de estado de conversa. O padrão que utiliza depende de o seu grafo compilado ter um checkpointer LangGraph.

Utilize um checkpointer quando o seu grafo precisar do estado de execução do LangGraph, de interrupções ou de estado local ao nó entre interações. Para testes locais, pode usar um ponto de verificação em memória:

from langgraph.checkpoint.memory import MemorySaver

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

Para agentes hospedados de produção, use um checkpointer durável em vez de um checkpointer em memória para que o estado do grafo sobreviva aos reinícios do contentor.

Os clientes continuam uma conversa no Responses fornecendo previous_response_id ou um ID conversation. Para testes locais, encadeie o ID de resposta anterior no pedido seguinte:

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

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

Quando o agente é executado no Foundry, o mesmo padrão funciona através do endpoint Hosted agent Responses. Se turnos posteriores também precisarem do mesmo sistema de ficheiros sandbox alojado, inclua agent_session_id ou use um conversation ID. Para mais detalhes, consulte Gerir sessões de agentes alojados.

Humano no ciclo

Se o seu grafo usar chamadas LangGraph interrupt(), ResponsesHostServer apresenta as interrupções pendentes através de itens de saída padrão da Responses API:

• Um function_call elemento chamado __hosted_agent_adapter_interrupt__.
• Um mcp_approval_request item com server_label definido para langgraph.

Os clientes podem retomar o grafo enviando um elemento function_call_output cujo call_id corresponda ao ID da interrupção ou um elemento mcp_approval_response cujo approval_request_id corresponda ao ID da interrupção. Use function_call_output quando precisar de enviar um payload LangGraph Command avançado com os campos resume, update ou goto. Use mcp_approval_response para um fluxo simples de aprovação ou rejeição.

Protocolo de invocações

Use InvocationsHostServer quando os seus chamadores não puderem usar o formulário de pedido da API de Respostas ou quando o seu cenário não for uma conversa por chat. O host predefinido de Invocations aceita uma cadeia de caracteres message e um sinalizador opcional stream.

Criar um host de Invocações

Use a mesma função de construção de modelos do exemplo Respostas, mas comece InvocationsHostServer em vez 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()

O que este excerto faz: Aloja o agente LangGraph através de POST /invocations. O MemorySaver checkpointer fornece continuidade local multi-turno para um dado ID de sessão. Para produção, usa um checkpointer durável para que o estado sobreviva aos reinícios do contentor.

Teste o endpoint de Invocations

Envie um pedido que não seja transmitido:

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

As solicitações sem streaming devolvem JSON com esta estrutura:

{
  "response": "Assistant text"
}

Para conversas com várias interações, reutilize o cabeçalho de resposta x-agent-session-id como o parâmetro de consulta agent_session_id no pedido seguinte:

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

Os pedidos de transmissão em fluxo devolvem eventos text/event-stream com cargas úteis de tokens:

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

O fluxo contém eventos de token seguidos de um evento terminal done :

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

event: done
data: {}

Personalizar o esquema de pedidos

Para personalizar o corpo do pedido, crie uma subclasse de InvocationsHostServer e redefina parse_request. Também pode sobrescrever build_input para mapear os dados analisados para um 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()

O que este excerto faz: Aceita um payload de ticket personalizado e converte-o numa única mensagem de utilizador antes de o host invocar o gráfico. Para um estado do gráfico mais complexo, sobreponha build_input em vez de converter o pedido em texto simples.

Deploy

Pode implementar usando a CLI Azure Developer ou a extensão Foundry Toolkit Visual Studio Code. O fluxo CLI do Azure Developer utiliza ficheiros de exemplo azure.yaml e Docker. O fluxo de extensão proporciona uma experiência de implementação guiada no Visual Studio Code.

A implementação de agentes alojados requer a função de Foundry Project Manager no projeto. Para mais detalhes, consulte Implementar um agente alojado.

Implantar com a CLI do Azure Developer

O langchain-azure-ai repositório de origem inclui amostras de agentes alojados que pode executar e implementar usando a CLI do Azure Developer. O fluxo utiliza o azure.yaml, Dockerfile e main.py de cada amostra. Para detalhes sobre a configuração do agente hospedado em azure.yaml, veja Author azure.yaml para agentes hospedados.

Instale a extensão do agente de IA e inicie sessão antes de inicializar um exemplo:

azd ext install azure.ai.agents
azd auth login

O Docker deve estar a correr localmente porque azd ai agent run constrói a imagem do contentor declarada no Dockerfile da amostra. Para detalhes dos comandos, consulte a referência Azure Developer CLI .

Inicializar a partir de um exemplo azure.yaml

Crie uma nova pasta e inicialize-a a partir de um sample azure.yaml. Substitua o azure.yaml URL pelo exemplo que pretende 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 as instruções de azd ai agent init. Se ainda não tiver um projeto e implementação de modelos no Foundry, o fluxo de inicialização pode guiá-lo na sua criação.

Executar um contêiner localmente

Execute localmente o host do agente através de azd:

azd ai agent run

O host é executado em http://127.0.0.1:8088. Noutro terminal, invoque diretamente o endpoint local do protocolo:

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

Equivalente ao PowerShell:

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

Também é possível invocar o agente local através de azd:

azd ai agent invoke --local "Hello!"

Deslocação para a Fundição

Se o projeto inicializado usar um novo projeto Foundry e implementação de modelos, provisione primeiro os recursos Azure:

azd provision

Instalar o agente:

azd deploy

A implementação empacota o agente numa imagem de contentor, envia-o para o registo de contentores provisionado e distribui-o para o runtime do agente Foundry Hosted.

A infraestrutura de alojamento da Foundry injeta variáveis do ambiente de runtime no agente, incluindo:

• FOUNDRY_PROJECT_ENDPOINT: O URL do endpoint do projeto Foundry onde o agente está alojado.
• FOUNDRY_MODEL_NAME: O nome de implementação do modelo selecionado durante azd ai agent init.
• APPLICATIONINSIGHTS_CONNECTION_STRING: A cadeia de ligação da instância do Application Insights do projeto.

Para conceitos completos de implementação, permissões e detalhes de gestão, consulte Implementar um agente Alojado e Gerir o ciclo de vida do agente Alojado.

Implementar com a extensão Foundry Toolkit para o Visual Studio Code

Para implementação baseada em extensões, veja Quickstart: Implemente o seu primeiro agente alojado.

Resolução de problemas

Use esta lista de verificação para diagnosticar problemas comuns durante o desenvolvimento de agentes alojados com langchain_azure_ai.agents.hosting.

Falha na validação de esquemas de grafos

Os hosts padrão esperam um grafo LangGraph compilado cujo estado tenha um messages campo, como MessagesState. Se o seu grafo usar um esquema de estado personalizado, subclasse o host e substitua build_input. Para Respostas, substitua handle_create quando precisar de controlo total sobre a análise sintática de pedidos, execução de grafos e eventos de Respostas emitidos.

O estado de conversa não continua

Para o protocolo Responses, forneça previous_response_id ou um ID de conversation em interações posteriores. Se o teu grafo usar um mecanismo de checkpoint, certifica-te de que esse mecanismo está configurado para garantir durabilidade no ambiente onde o agente é executado.

No protocolo Invocations, a plataforma não armazena o histórico de conversas. Use um parâmetro de consulta agent_session_id para encaminhar as chamadas seguintes para o mesmo sandbox alojado e use o seu próprio armazenamento de estado ou o checkpointer do LangGraph para o estado da conversação.

O modelo não pode ser alcançado no contentor alojado

Confirme que a versão do agente alojado inclui FOUNDRY_MODEL_NAME, e que a identidade do agente tem permissão para invocar o projeto Foundry. A plataforma define FOUNDRY_PROJECT_ENDPOINT; o teu código deve ler essa variável ao correr no Foundry.

Passo seguinte

Conteúdo relacionado

• Comece a usar LangChain e LangGraph com a Foundry
• Utilize o Foundry Agent Service com o LangGraph
• Monitorize aplicações LangChain e LangGraph com Microsoft Foundry e Azure Monitor
• Gerir sessões de agentes alojadas