Rastrear aplicativos LangChain e LangGraph com Microsoft Foundry e Azure Monitor

Use o pacote de integração langchain-azure-ai para emitir rastreamentos OpenTelemetry dos aplicativos LangChain e LangGraph e armazená-los no Aplicativo Azure Insights. Neste artigo, você configurará AzureAIOpenTelemetryTracer, o anexará ao seu executável e inspecionará rastreamentos no Azure Monitor.

O rastreador emite intervalos para execução de agente, chamadas de modelo, execução de ferramentas e operações de recuperação. Você pode usá-lo para aplicativos que executam totalmente localmente, fluxos híbridos que chamam o Serviço do Foundry Agent ou soluções LangGraph de vários agentes.

Pré-requisitos

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

Configurar seu ambiente

Instalar pacotes necessários:

pip install -U "langchain-azure-ai[opentelemetry]" azure-identity

Defina as variáveis de ambiente usadas neste artigo:

import os

# Option 1: Project endpoint (recommended)
os.environ["AZURE_AI_PROJECT_ENDPOINT"] = (
	"https://<resource>.services.ai.azure.com/api/projects/<project>"
)

# Option 2: Direct OpenAI-compatible endpoint + API key
os.environ["OPENAI_BASE_URL"] = (
	"https://<resource>.services.ai.azure.com/openai/v1"
)
os.environ["OPENAI_API_KEY"] = "<your-api-key>"
os.environ["APPLICATION_INSIGHTS_CONNECTION_STRING"] = "InstrumentationKey=0ab1c2d3..."

Para controlar se o conteúdo de mensagens e chamadas de função é registrado no rastreamento, passe enable_content_recording para o construtor AzureAIOpenTelemetryTracer. A gravação de conteúdo é habilitada por padrão.

Criar o rastreador

Crie uma instância de rastreamento e reutilize-a em seu fluxo de trabalho.

import os

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

tracer = AzureAIOpenTelemetryTracer(
	project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredential(),
	name="langchain-tracing-sample",
	agent_id="support-bot",
	trace_all_langgraph_nodes=True,
)

O que este snippet faz: Configura um rastreador que resolve a cadeia de conexão do Application Insights associada a partir do endpoint do projeto Foundry e habilita o rastreamento nos nós do LangGraph. Use agent_id o parâmetro para definir o atributo gen_ai.agent.id ao invocar agentes. O name parâmetro define o nome do rastreador OpenTelemetry.

O rastreador dá suporte a controles comuns para fluxos de trabalho de produção:

• Passar connection_string para direcionar a um recurso específico do Application Insights ou configurar a variável APPLICATION_INSIGHTS_CONNECTION_STRING de ambiente.
• Defina trace_all_langgraph_nodes=True para rastrear todos os nós por padrão.
• Utilize os metadados dos nós como otel_trace: True ou otel_trace: False para incluir ou omitir nós específicos.
• Use message_keys e message_paths quando suas mensagens estiverem aninhadas sob uma forma de estado personalizada, por exemplo chat_history.

Referência:

• AzureAIOpenTelemetryTracer

Rastrear um agente

Comece com um agente LangChain mínimo para que você possa verificar o rastreamento rapidamente. Para o LangGraph, anexe o rastreamento with_config no grafo compilado.

from langchain.agents import create_agent

agent = create_agent(
    model="azure_ai:gpt-5.2", 
    system_prompt="You're an informational agent. Answer questions cheerfully.", 
).with_config(
    {"callbacks": [tracer]}
)

response = agent.invoke({"messages": "what's your name?"})
response["messages"][-1].pretty_print()

================================== Ai Message ==================================

I’m ChatGPT, your AI assistant.

O que este snippet de código faz: Cria um agente simples do LangGraph, anexa o rastreador e invoca o agente com uma mensagem.

Referência:

• LangGraph
• OpenTelemetry

Analisar/Monitorar um executável do LangChain

Comece com um fluxo mínimo de LangChain para que você possa verificar o rastreamento rapidamente.

import os

from azure.identity import DefaultAzureCredential
from langchain_core.prompts import ChatPromptTemplate
from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
	endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
	credential=DefaultAzureCredential(),
	model=os.environ["AZURE_OPENAI_DEPLOYMENT"],
)

prompt = ChatPromptTemplate.from_template(
	"You are concise. Answer in one sentence: {question}"
)
chain = prompt | model

response = chain.invoke(
	{"question": "What does OpenTelemetry help me do?"},
	config={"callbacks": [tracer]},
)

print(response.content)

OpenTelemetry helps you observe requests, latency, dependencies, and failures across your AI workflow.

O que este snippet de código faz: Executa um pipeline LangChain padrão e envia spans de chat para o OpenTelemetry através de AzureAIOpenTelemetryTracer.

Referência:

• AzureAIChatCompletionsModel
• ChatPromptTemplate

Traçar um grafo do LangGraph

Para o LangGraph, anexe o rastreamento with_config no grafo compilado. Este snippet reutiliza model e tracer de exemplos anteriores.

from langgraph.graph import END, START, MessagesState, StateGraph
from langgraph.prebuilt import ToolNode
from langgraph.checkpoint.memory import MemorySaver
from langchain_core.tools import tool
from langchain_azure_ai.utils.agents import pretty_print

@tool
def play_song_on_spotify(song: str):
    """Play a song on Spotify"""
    # Integrate with Spotify API here.
    return f"Successfully played {song} on Spotify!"

@tool
def play_song_on_apple(song: str):
    """Play a song on Apple Music"""
    # Integrate with Apple Music API here.
    return f"Successfully played {song} on Apple Music!"

tool_node = ToolNode([play_song_on_apple, play_song_on_spotify])
model_with_tools = model.bind_tools([play_song_on_apple, play_song_on_spotify])

def should_continue(state: MessagesState):
    messages = state["messages"]
    last_message = messages[-1]
    return "continue" if getattr(last_message, "tool_calls", None) else "end"

def call_model(state: MessagesState):
    messages = state["messages"]
    response = model_with_tools.invoke(messages)
    return {"messages": [response]}

memory = MemorySaver()
workflow = (
    StateGraph(MessagesState)
    .add_node("agent", call_model)
    .add_node("action", tool_node)
    .add_edge(START, "agent")
    .add_conditional_edges(
        "agent",
        should_continue,
        {
            "continue": "action",
            "end": END,
        },
    )
    .add_edge("action", "agent")
    .compile(checkpointer=memory)
)

Em seguida, você pode executar o grafo como de costume:

from langchain_core.messages import HumanMessage

config = {"configurable": {"thread_id": "1"}, "callbacks": [tracer]}
message = HumanMessage(content="Can you play Taylor Swift's most popular song?")

result = workflow.invoke({"messages": [message]}, config)
pretty_print(result)

================================ Human Message =================================

Can you play Taylor Swift's most popular song?
================================== Ai Message ==================================
Tool Calls:
  play_song_on_spotify (call_xxx)
 Call ID: call_xxx
  Args:
    song: Anti-Hero
================================= Tool Message =================================
Name: play_song_on_spotify

Successfully played Anti-Hero on Spotify!
================================== Ai Message ==================================

I played Taylor Swift's popular song "Anti-Hero" on Spotify.

O que este snippet de código faz: Cria um aplicativo LangGraph simples, marca o nó para rastreamento e emite invoke_agent e o modelo/ferramenta abrange o mesmo rastreamento.

Referência:

• LangGraph
• OpenTelemetry

Entender a estrutura de rastreamento

O rastreador emite intervalos que seguem as convenções semânticas do OpenTelemetry GenAI. Cada tipo de intervalo usa um valor específico gen_ai.operation.name :

Os intervalos também carregam estes atributos principais:

• gen_ai.agent.name — O nome do agente ou do nó.
• gen_ai.agent.id — Defina a partir do agent_id parâmetro do construtor.
• gen_ai.agent.description — Uma descrição do agente.
• gen_ai.provider.name— O provedor de modelo (por exemplo, openai, ). azure.ai.inference
• gen_ai.request.model — O nome do modelo usado para inferência.
• gen_ai.conversation.id — Identificador de thread ou sessão, quando disponível.
• gen_ai.usage.input_tokens / gen_ai.usage.output_tokens — Contagens de tokens das respostas do modelo.
• gen_ai.input.messages / gen_ai.output.messages — Conteúdo da mensagem (quando a gravação de conteúdo está habilitada).

Como o rastreador resolve gen_ai.agent.name

O rastreador resolve o nome do agente do primeiro valor não vazio nesta ordem:

1. agent_name nos metadados do nó.
2. langgraph_node nos metadados do nó (definidos automaticamente pelo LangGraph).
3. agent_type nos metadados do nó.
4. O name argumento nomeado do callback LangChain.
5. langgraph_path (último elemento) se os espaços reservados acima forem genéricos.
6. A ID da cadeia serializada ou o nome da classe.
7. O name parâmetro do AzureAIOpenTelemetryTracer construtor (padrão de fallback).

Como o rastreador resolve gen_ai.agent.id

O rastreador resolve o ID do agente de:

1. agent_id nos metadados do nó (substituição individual por nó).
2. O agent_id parâmetro do construtor (padrão para todos os segmentos).

Personalizar atributos com metadados de nó

Você pode definir agent_name, agent_id e agent_description para cada nó usando metadados do LangGraph. Qualquer chave de metadados que começa com gen_ai. também é encaminhada como um atributo de intervalo.

config = {
    "callbacks": [tracer],
    "metadata": {
        "agent_name": "support-bot",
        "agent_id": "support-bot-v2",
        "agent_description": "Handles customer support requests",
        "thread_id": "session-abc-123",
    },
}
result = graph.invoke({"messages": [message]}, config)

Ao usar o LangGraph, você também pode definir metadados por nó na definição do grafo:

workflow = StateGraph(MessagesState)
workflow.add_node(
    "planner",
    planner_fn,
    metadata={
        "agent_name": "PlannerAgent",
        "agent_id": "planner-v1",
        "otel_agent_span": True,
    },
)

Referência:

• Intervalos de agente do OpenTelemetry GenAI
• Intervalos do OpenTelemetry GenAI

Exibir rastreamentos no Azure Monitor

Os rastreamentos são enviados para Aplicativo Azure Insights e podem ser consultados usando Azure Monitor:

1. Acesse o portal Azure.

2. Navegue até o Aplicativo Azure Insights que você configurou.

3. Usando a barra de navegação à esquerda, selecione Investigar>Agentes (Versão Prévia).

4. Você verá um painel mostrando execuções de agente, modelo e ferramentas. Use essa exibição para entender a atividade geral de seus agentes.

5. Selecione Exibir Rastreamentos com Execuções do Agente. O painel lateral mostra todos os rastros gerados pelas execuções do agente.

   

6. Selecione um dos rastros. Você deve ver os detalhes.

   

Exibir rastreamentos no Plano de Controle do Foundry

Se você implantou sua solução LangGraph ou LangChain, poderá registrar essa implantação no Foundry Control Plane para obter visibilidade e governança.

Registre seu aplicativo no Plano de Controle do Foundry para exibir rastreamentos no portal do Foundry.

Siga estas etapas:

1. Verifique se você atende aos requisitos para usar a capacidade de agente personalizado do Plano de Controle do Foundry.

   • Um gateway de IA configurado no seu recurso do Foundry. A Foundry usa Gerenciamento de API do Azure para registrar agentes como APIs.

   • Um agente que você implanta e expõe por meio de um endpoint acessível. O ponto de extremidade pode ser público ou acessível a partir da rede onde você implanta o recurso Foundry.

2. Verifique se você tem a observabilidade configurada no projeto.

3. Ao configurar a classe AzureAIOpenTelemetryTracer, use o ponto de extremidade do projeto no qual você deseja que o agente seja registrado. Verifique se você configurou agent_id.

4. Vá para o portal do Foundry.

5. Na barra de ferramentas, selecione Operar.

6. No painel Visão geral , selecione Registrar agente.

7. O assistente de registro é exibido. Primeiro, conclua os detalhes sobre o agente que você deseja registrar.

   • URL do agente: o ponto de extremidade (URL) onde o agente opera e recebe solicitações.
   • Protocolo: o protocolo de comunicação que o seu agente suporta.
   • ID do Agente OpenTelemetry: o agent_id parâmetro que você configurou na AzureAIOpenTelemetryTracer classe.
   • Project: o projeto configurado para receber rastros na classe AzureAIOpenTelemetryTracer.
   • Nome do agente: o nome do agente (pode ser o mesmo que agent_id).

8. Acione o agente para garantir que ele tenha processos.

9. Na barra de ferramentas, selecione Operar.

10. No painel esquerdo, selecione Ativos.

11. Selecione o agente que você criou.

12. A seção Traces mostra uma entrada para cada chamada HTTP feita ao endpoint do agente.

    Para ver os detalhes, selecione uma entrada.

    

Solucionar problemas

• Se nenhum rastreamento for exibido, verifique se connection_string está configurado ou se o endpoint do projeto expõe a telemetria.
• Se o conteúdo da mensagem aparecer redigido, defina enable_content_recording=True no AzureAIOpenTelemetryTracer construtor.
• Se alguns nós do LangGraph estiverem ausentes, defina trace_all_langgraph_nodes=True ou adicione metadados otel_trace: Truede nó.

Conteúdo relacionado

• Introdução ao langchain-azure-ai
• Usar o LangGraph com o Serviço de Agente
• Configurar integrações de rastreamento para estruturas de agente