Hospedar agentes do LangGraph como agentes hospedados pela Foundry

Use o pacote langchain_azure_ai.agents.hosting para expor um grafo compilado do LangGraph por meio dos protocolos para agentes hospedados do Microsoft Foundry . O pacote de hospedagem permite manter em código a lógica dos agentes LangChain e LangGraph, enquanto o Foundry gerencia o ambiente de execução hospedado, as sessões, a escalabilidade, a identidade e os endpoints de protocolo.

Neste artigo, você cria um agente mínimo do LangGraph, expõe-o por meio do protocolo Respostas ou Invocações, testa-o por meio de HTTP e implanta-o no Foundry com a CLI do Desenvolvedor Azure ou a extensão do Foundry Toolkit Visual Studio Code.

Pré-requisitos

• Uma assinatura do Azure. Criar um gratuitamente.
• Um projeto do Foundry.
• Um modelo de chat implantado, como gpt-4.1 ou gpt-5-mini.
• Python 3.10 ou posterior.
• CLI do Azure está conectado (az login) para que DefaultAzureCredential possa autenticar-se.

Instalar o pacote

Instale langchain-azure-ai versão 1.2.4 ou posterior com o extra de hospedagem:

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

O extra hosting instala as bibliotecas de protocolo do Foundry usadas pelos servidores host:

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

Escolher um protocolo de hospedagem

Os agentes hospedados podem expor um ou mais protocolos. Comece com respostas para a maioria dos agentes de conversação.

Para obter informações sobre o comportamento do protocolo e sessões, consulte Os agentes hospedados e gerencie sessões de agente hospedado.

Configurar variáveis de ambiente

Defina o ponto de extremidade do projeto e o nome de implantaçã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 um agente hospedado no Foundry, a plataforma injeta FOUNDRY_PROJECT_ENDPOINT. Se você usar azd ai agent init com um exemplo azure.yaml, o projeto gerado também usará FOUNDRY_MODEL_NAME para a implantação do modelo selecionado.

Protocolo de respostas

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

Criar um host de respostas

Crie um arquivo nomeado main.py com um agente mínimo do LangGraph que usa um modelo de Foundry. Esse padrão corresponde ao exemplo básico de Respostas no repositório de origem 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()

O que este trecho de código faz: Cria um agente LangGraph com create_agent do LangChain, conecta-o ao endpoint de 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 por meio de POST /responses. Por padrão, o servidor se associa à porta 8088ou ao valor da variável de PORT ambiente quando uma é definida.

Execute o aplicativo localmente:

python main.py

Testar o ponto de extremidade de respostas

Envie uma solicitação de respostas 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 como true. O host emite eventos enviados pelo servidor da API de Respostas, como response.created, response.output_text.deltae response.completed.

Conversas

ResponsesHostServer dá suporte a dois padrões de estado de conversa. O padrão que ele usa depende de se o seu grafo compilado inclui um checkpointer do LangGraph.

Use um ponto de verificação quando seu gráfico precisar do estado de runtime do LangGraph, de interrupções ou do estado local do nó entre turnos. Para testes locais, você pode usar um ponto de verificação na 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 ponto de verificação durável em vez de um ponto de verificação na memória para que o estado do gráfico sobreviva às reinicializações do contêiner.

Os clientes dão continuidade a uma conversa no Responses fornecendo previous_response_id ou um ID conversation. Para testes locais, encadeia a ID de resposta anterior na próxima solicitação:

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 por meio do ponto de extremidade de respostas do agente hospedado. Se turnos posteriores também precisarem do mesmo sistema de arquivos do sandbox hospedado, inclua agent_session_id ou use um ID conversation. Para obter detalhes, consulte Gerenciar sessões de agente hospedado.

Humanos no loop

Se o seu gráfico usa chamadas interrupt() do LangGraph, ResponsesHostServer exibe interrupções pendentes por meio de itens de saída padrão da API Responses:

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

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

Protocolo de invocações

Use InvocationsHostServer quando os chamadores não puderem usar a forma de solicitação da API de Respostas ou quando seu cenário não for uma conversa de chat. O host padrão de Invocations aceita uma cadeia de caracteres message e um sinalizador stream opcional.

Criar um host de invocações

Use a mesma função de criação de modelo 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 snippet de código faz: Hospeda o agente do LangGraph por meio de POST /invocations. O ponto de verificação MemorySaver fornece continuidade de vários turnos local para uma determinada ID de sessão. Para produção, use um ponto de verificação durável para que o estado sobreviva às reinicializações de contêiner.

Testar o ponto de extremidade de invocações

Enviar uma solicitação de não streaming:

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

Solicitações que não são de streaming retornam JSON nesta forma:

{
  "response": "Assistant text"
}

Para conversas de múltiplos turnos, reutilize o cabeçalho de resposta x-agent-session-id como o parâmetro de consulta agent_session_id na solicitação seguinte:

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

Solicitações de streaming retornam text/event-stream eventos com payloads de token:

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 por um evento de terminal done :

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

event: done
data: {}

Personalizar o esquema de solicitação

Para personalizar o corpo da solicitação, crie uma subclasse de InvocationsHostServer e sobrescreva parse_request. Você também pode substituir 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 snippet de código faz: aceita um payload de tíquete personalizado e o converte em uma única mensagem de usuário antes que o host invoque o gráfico. Para um estado do grafo mais complexo, sobrescreva build_input em vez de converter a solicitação em texto simples.

Implantar

Você pode implantar usando a CLI do Desenvolvedor do Azure ou a extensão de Visual Studio Code do Foundry Toolkit. O fluxo da CLI do Desenvolvedor Azure usa arquivos de exemplo azure.yaml e Docker. O fluxo de extensão fornece uma experiência de implantação guiada no Visual Studio Code.

A implantação do agente hospedado requer a função Foundry Project Manager no projeto. Para obter detalhes, consulte Implantar um agente hospedado.

Implantar com a Azure Developer CLI

O langchain-azure-ai repositório de origem inclui exemplos de agente hospedado que você pode executar e implantar usando a CLI do Desenvolvedor do Azure. O fluxo usa azure.yaml, Dockerfile e main.py de cada amostra. Para obter detalhes sobre a configuração do agente hospedado em azure.yaml, consulte Autor azure.yaml para agentes hospedados.

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

azd ext install azure.ai.agents
azd auth login

O Docker deve estar em execução localmente porque azd ai agent run cria a imagem de contêiner declarada no Dockerfile do exemplo. Para obter detalhes do comando, consulte a referência da CLI do desenvolvedor Azure.

Inicialize a partir de um arquivo azure.yaml de exemplo

Crie uma nova pasta e inicialize-a a partir de um exemplo azure.yaml. Substitua a azure.yaml URL pelo exemplo que você deseja 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 você ainda não tiver um projeto do Foundry e uma implantação de modelo, o fluxo de inicialização poderá guiá-lo durante a criação deles.

Executar o contêiner localmente

Execute o host do agente localmente por meio de azd:

azd ai agent run

O host serve em http://127.0.0.1:8088. Em outro terminal, invoque diretamente o ponto de extremidade do protocolo local:

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

Equivalente do PowerShell:

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

Você também pode invocar o agente local por meio de azd:

azd ai agent invoke --local "Hello!"

Implantar no Foundry

Se o projeto inicializado usar um novo projeto do Foundry e uma implantação de modelo, provisione os recursos de Azure primeiro:

azd provision

Implante o agente:

azd deploy

A implantação empacota o agente em uma imagem de contêiner, faz push dela para o registro de contêiner provisionado e a implanta no runtime do agente hospedado do Foundry.

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

• FOUNDRY_PROJECT_ENDPOINT: A URL do endpoint do projeto do Foundry no qual o agente está implantado.
• FOUNDRY_MODEL_NAME: o nome da implantação do modelo selecionado durante azd ai agent init.
• APPLICATIONINSIGHTS_CONNECTION_STRING: a cadeia de conexão da instância do Application Insights do projeto.

Para obter conceitos completos de implantação, permissões e detalhes de gerenciamento, consulte Implantar um agente hospedado e gerenciar o ciclo de vida do agente hospedado.

Implantar usando a extensão Foundry Toolkit para o Visual Studio Code

Para implantação baseada em extensão, consulte Início Rápido: Implantar seu primeiro agente hospedado.

Solução de problemas

Use esta lista de verificação para diagnosticar problemas comuns ao desenvolver agentes hospedados com langchain_azure_ai.agents.hosting.

Falha na validação do esquema do Graph

Os hosts padrão esperam um grafo LangGraph compilado cujo estado tem um campo messages, como MessagesState. Se o seu grafo usar um esquema de estado personalizado, crie uma subclasse do host e sobrescreva build_input. Em Respostas, sobrescreva handle_create quando precisar de controle total sobre o processamento da solicitação, a execução do gráfico e os eventos de respostas emitidos.

O estado da conversa não continua

Para o protocolo Responses, passe previous_response_id ou um ID conversation nos turnos seguintes. Se o gráfico usar um ponto de verificação, verifique se o ponto de verificação está configurado e é durável para o ambiente em que o agente é executado.

Para o protocolo Invocações, a plataforma não armazena o histórico de conversas. Use um parâmetro de consulta agent_session_id para direcionar chamadas posteriores ao mesmo sandbox hospedado e use seu próprio armazenamento de estado ou o ponto de verificação do LangGraph para manter o estado da conversa.

O modelo não pode ser acessado no contêiner hospedado

Confirme se a versão do agente hospedado inclui FOUNDRY_MODEL_NAME e se a identidade do agente tem permissão para fazer chamadas ao projeto Foundry. A plataforma define FOUNDRY_PROJECT_ENDPOINT; seu código deve ler essa variável quando for executado no Foundry.

Próxima etapa

Conteúdo relacionado

• Introdução a LangChain e LangGraph com o Foundry
• Usar o Serviço de Agente do Foundry com o LangGraph
• Rastrear aplicativos LangChain e LangGraph com o Microsoft Foundry e o Azure Monitor
• Gerenciar sessões de agente hospedado