Configurar o rastreamento para estruturas de agente de IA (versão prévia)

Quando os agentes de IA se comportam inesperadamente na produção, o rastreamento oferece a visibilidade para identificar rapidamente a causa raiz. O rastreamento captura telemetria detalhada, incluindo chamadas LLM, invocações de ferramentas e fluxos de decisão do agente, para que você possa depurar problemas, monitorar a latência e entender o comportamento do agente entre solicitações.

Microsoft Foundry fornece integrações de rastreamento para estruturas de agente populares que exigem alterações mínimas de código. Neste artigo, você aprenderá a:

• Configurar o rastreamento automático para o Microsoft Agent Framework
• Configurar o langchain-azure-ai rastreador para LangChain e LangGraph
• Instrumentar o SDK do OpenAI Agents com OpenTelemetry
• Verificar se os rastreamentos aparecem no portal do Foundry
• Solucionar problemas comuns de rastreamento

Pré-requisitos

• Um projeto de Foundry com rastreamento conectado ao Azure Monitor Application Insights.
• Colaborador ou função superior no recurso Application Insights para ingestão de rastreamentos.
• Acesso ao recurso do Application Insights conectado para visualização de rastros. Para consultas baseadas em log, talvez você também precise de acesso ao workspace Log Analytics associado.
• Python 3.10 ou posterior (necessário para todos os exemplos de código neste artigo).
• A versão do pacote langchain-azure-ai 0.1.0 ou posterior (necessária para os exemplos de LangChain e LangGraph).
• Se você usar LangChain ou LangGraph, um ambiente Python com pip instalado.

Confirme se você pode exibir a telemetria

Para exibir dados de rastreamento, verifique se sua conta tem acesso ao recurso do Application Insights conectado.

1. No portal do Azure, abra o recurso application insights conectado ao seu projeto do Foundry.

2. Selecione controle de acesso (IAM).

3. Atribua uma função apropriada ao seu usuário ou grupo.

   Se você usar consultas baseadas em log, comece concedendo a função Log Analytics Reader.

Segurança e privacidade

O rastreamento pode capturar informações confidenciais (por exemplo, entradas do usuário, saídas de modelo e argumentos e resultados da ferramenta).

• Habilite a gravação de conteúdo durante o desenvolvimento e a depuração para ver os dados completos de solicitação e resposta. Desabilite o registro de conteúdo em ambientes de produção para proteger dados confidenciais. Nos exemplos deste artigo, a gravação de conteúdo é controlada por configurações como enable_content_recording e OTEL_RECORD_CONTENT.
• Não armazene segredos, credenciais ou tokens em prompts ou argumentos de ferramenta.

Para obter mais diretrizes, consulte Segurança e privacidade.

Configurar o rastreamento para o Microsoft Agent Framework

Microsoft Foundry tem integrações nativas com o Microsoft Agent Framework. Os agentes criados com um framework emitem automaticamente rastreamentos (tracing) quando o tracing está habilitado para seu projeto Foundry—nenhum código adicional ou pacotes são necessários.

Para verificar se o rastreamento está funcionando:

1. Execute seu agente pelo menos uma vez.
2. No portal do Foundry, vá para Observabilidade>Rastreamentos.
3. Confirme se um novo rastreamento aparece com intervalos para as operações do agente.

Os rastros normalmente aparecem em um período de 2 a 5 minutos após a execução do agente. Para obter uma configuração avançada, consulte a documentação específica da estrutura:

• fluxos de trabalho Microsoft Agent Framework – Observabilidade

Configurar o rastreamento para LangChain e LangGraph

Use o langchain-azure-ai pacote para emitir intervalos compatíveis com OpenTelemetry para operações LangChain e LangGraph. Esses rastreamentos aparecem na visualização Observabilidade>Rastreamentos no portal do Foundry.

• Convenções semânticas OpenTelemetry para IA generativa
• Pacote langchain-azure-ai no PyPI

Exemplo: agente LangChain v1 com rastreamento do Azure AI

Use este exemplo de ponta a ponta para instrumentar um agente LangChain v1 (versão prévia) usando o langchain-azure-ai rastreador. Esse rastreamento implementa as convenções semânticas mais recentes do OpenTelemetry (OTel), para que você possa exibir rastreamentos avançados no modo de exibição de observabilidade do Foundry.

LangChain v1: Instalar pacotes

pip install \
  langchain-azure-ai \
  langchain \
  langgraph \
  langchain-openai \
  azure-identity \
  python-dotenv \
  rich

LangChain v1: Configurar o ambiente

• APPLICATION_INSIGHTS_CONNECTION_STRING: string de conexão do Application Insights do Azure Monitor para rastreamento.
• AZURE_OPENAI_ENDPOINT: URL do ponto de extremidade do Azure OpenAI.
• AZURE_OPENAI_CHAT_DEPLOYMENT: o nome da implantação do modelo de chat.
• AZURE_OPENAI_VERSION: versão da API, por exemplo 2024-08-01-preview.
• O SDK resolve as credenciais do Azure usando DefaultAzureCredential, que dá suporte a variáveis de ambiente, identidade gerenciada e logon do VS Code.

Armazene esses valores em um .env arquivo para desenvolvimento local.

LangChain v1: Configuração do rastreamento

from dotenv import load_dotenv
import os
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

load_dotenv(override=True)

azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=True,
    name="Weather information agent",
    id="weather_info_agent_771929",
)

tracers = [azure_tracer]

LangChain v1: Configuração do modelo (Azure OpenAI)

import os
import azure.identity
from langchain_openai import AzureChatOpenAI

token_provider = azure.identity.get_bearer_token_provider(
    azure.identity.DefaultAzureCredential(),
    "https://ai.azure.com/.default",
)

model = AzureChatOpenAI(
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    openai_api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    azure_ad_token_provider=token_provider,
)

LangChain v1: Definir ferramentas e prompt

from dataclasses import dataclass
from langchain_core.tools import tool

system_prompt = """You are an expert weather forecaster, who speaks in puns.

You have access to two tools:

- get_weather_for_location: use this to get the weather for a specific location
- get_user_location: use this to get the user's location

If a user asks you for the weather, make sure you know the location.
If you can tell from the question that they mean wherever they are,
use the get_user_location tool to find their location."""

# Mock user locations keyed by user id (string)
USER_LOCATION = {
    "1": "Florida",
    "2": "SF",
}

@dataclass
class UserContext:
    user_id: str

@tool
def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

LangChain v1: Usar o contexto de tempo de execução e definir uma ferramenta de informações sobre o usuário

from langgraph.runtime import get_runtime
from langchain_core.runnables import RunnableConfig

@tool
def get_user_info(config: RunnableConfig) -> str:
    """Retrieve user information based on user ID."""
    runtime = get_runtime(UserContext)
    user_id = runtime.context.user_id
    return USER_LOCATION[user_id]

LangChain v1: Criar o agente

from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver
from dataclasses import dataclass

@dataclass
class WeatherResponse:
    conditions: str
    punny_response: str

checkpointer = InMemorySaver()

agent = create_agent(
    model=model,
    prompt=system_prompt,
    tools=[get_user_info, get_weather],
    response_format=WeatherResponse,
    checkpointer=checkpointer,
)

LangChain v1: executar o agente com rastreamento

from rich import print

def main():
    config = {"configurable": {"thread_id": "1"}, "callbacks": [azure_tracer]}
    context = UserContext(user_id="1")

    r1 = agent.invoke(
        {"messages": [{"role": "user", "content": "what is the weather outside?"}]},
        config=config,
        context=context,
    )
    print(r1.get("structured_response"))

    r2 = agent.invoke(
        {"messages": [{"role": "user", "content": "Thanks"}]},
        config=config,
        context=context,
    )
    print(r2.get("structured_response"))

if __name__ == "__main__":
    main()

Com langchain-azure-ai habilitado, todas as operações do LangChain v1 (chamadas LLM, invocações de ferramentas, etapas do agente) emitem spans do OpenTelemetry usando as convenções semânticas mais recentes. Esses traços aparecem na visão de Observabilidade>Traços no portal do Foundry e estão vinculados ao recurso do Application Insights.

Verificar os rastreamentos do LangChain v1

Depois de executar o agente:

1. Aguarde de 2 a 5 minutos para que os traços se propaguem.
2. No portal do Foundry, vá para Observabilidade>Rastreamentos.
3. Procure um traço com o nome especificado (por exemplo, "Agente de informações meteorológicas").
4. Expanda o rastreamento para ver intervalos para chamadas LLM, invocações de ferramentas e etapas do agente.

Se você não vir traços, consulte a seção Solucionar problemas comuns.

Exemplo: agente do LangGraph com rastreamento do Azure IA

Este exemplo mostra um agente simples do LangGraph instrumentado com langchain-azure-ai para emitir rastreamentos compatíveis com o OpenTelemetry para etapas de grafo, chamadas de ferramenta e invocações de modelo.

LangGraph: instalar pacotes

pip install \
  langchain-azure-ai \
  langgraph>=1.0.0 \
  langchain>=1.0.0 \
  langchain-openai \
  azure-identity \
  python-dotenv

LangGraph: Configurar o ambiente

• APPLICATION_INSIGHTS_CONNECTION_STRING: string de conexão do Application Insights do Azure Monitor para rastreamento.
• AZURE_OPENAI_ENDPOINT: URL do ponto de extremidade do Azure OpenAI.
• AZURE_OPENAI_CHAT_DEPLOYMENT: o nome da implantação do modelo de chat.
• AZURE_OPENAI_VERSION: versão da API, por exemplo 2024-08-01-preview.

Armazene esses valores em um .env arquivo para desenvolvimento local.

Configuração do rastreamento do LangGraph

import os
from dotenv import load_dotenv
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

load_dotenv(override=True)

azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=os.getenv("OTEL_RECORD_CONTENT", "true").lower() == "true",
    name="Music Player Agent",
)

LangGraph: Ferramentas

from langchain_core.tools import tool

@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!"

tools = [play_song_on_apple, play_song_on_spotify]

LangGraph: Configuração do modelo (Azure OpenAI)

import os
import azure.identity
from langchain_openai import AzureChatOpenAI

token_provider = azure.identity.get_bearer_token_provider(
    azure.identity.DefaultAzureCredential(),
    "https://ai.azure.com/.default",
)

model = AzureChatOpenAI(
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    openai_api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    azure_ad_token_provider=token_provider,
).bind_tools(tools, parallel_tool_calls=False)

Criar o fluxo de trabalho do LangGraph

from langgraph.graph import END, START, MessagesState, StateGraph
from langgraph.prebuilt import ToolNode
from langgraph.checkpoint.memory import MemorySaver

tool_node = ToolNode(tools)

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.invoke(messages)
    return {"messages": [response]}

workflow = StateGraph(MessagesState)
workflow.add_node("agent", call_model)
workflow.add_node("action", tool_node)

workflow.add_edge(START, "agent")
workflow.add_conditional_edges(
    "agent",
    should_continue,
    {
        "continue": "action",
        "end": END,
    },
)
workflow.add_edge("action", "agent")

memory = MemorySaver()
app = workflow.compile(checkpointer=memory)

LangGraph: Executar com rastreamento

from langchain_core.messages import HumanMessage

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

for event in app.stream({"messages": [input_message]}, config, stream_mode="values"):
    event["messages"][-1].pretty_print()

Com langchain-azure-ai habilitado, a execução do LangGraph emite intervalos compatíveis com OpenTelemetry para chamadas de modelo, invocações de ferramenta e transições de grafo. Esses rastreamentos são enviados para o Application Insights e aparecem na exibição Observabilidade>Rastreamentos no portal do Foundry.

Verificar os rastreamentos do LangGraph

Depois de executar o agente:

1. Aguarde de 2 a 5 minutos para que os traços se propaguem.
2. No portal do Foundry, vá para Observabilidade>Rastreamentos.
3. Procure um rastreamento com o nome especificado (por exemplo, "Agente do Player de Música").
4. Expanda o rastreamento para ver intervalos para nós de grafo, invocações de ferramenta e chamadas de modelo.

Se você não vir traços, consulte a seção Solucionar problemas comuns.

Exemplo: Configuração do LangChain 0.3 com rastreamento de IA do Azure

Essa configuração mínima mostra como habilitar o rastreamento de IA do Azure em um aplicativo LangChain 0.3 usando o langchain-azure-ai tracer e AzureChatOpenAI.

LangChain 0.3: Instalar pacotes

pip install \
  "langchain>=0.3,<0.4" \
  langchain-openai \
  langchain-azure-ai \
  python-dotenv

LangChain 0.3: Configurar o ambiente

• APPLICATION_INSIGHTS_CONNECTION_STRING: cadeia de conexão do Application Insights para rastreamento. Para encontrar esse valor, abra o recurso do Application Insights no portal Azure, selecione Overview e copie a cadeia de caracteres Connection.
• AZURE_OPENAI_ENDPOINT: URL do ponto de extremidade do Azure OpenAI.
• AZURE_OPENAI_CHAT_DEPLOYMENT: nome da implantação do modelo de chat.
• AZURE_OPENAI_VERSION: versão da API, por exemplo 2024-08-01-preview.
• AZURE_OPENAI_API_KEY: Chave de API do Azure OpenAI.

LangChain 0.3: Configuração de rastreamento e modelo

import os
from dotenv import load_dotenv
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer
from langchain_openai import AzureChatOpenAI

load_dotenv(override=True)

# Tracer: emits spans conforming to updated OTel spec
azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=True,
    name="Trip Planner Orchestrator",
    id="trip_planner_orchestrator_v3",
)
tracers = [azure_tracer]

# Model: Azure OpenAI with callbacks for tracing
llm = AzureChatOpenAI(
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    temperature=0.2,
    callbacks=tracers,
)

Anexe callbacks=[azure_tracer] às suas cadeias, ferramentas ou agentes para assegurar que as operações do LangChain 0.3 sejam totalmente rastreadas. Depois de executar sua cadeia ou agente, os rastreamentos aparecem na visualização Observabilidade>Rastreamentos no portal da Foundry dentro de 2 a 5 minutos.

Configurar rastreamento para o SDK de agentes do OpenAI

O SDK de Agentes da OpenAI dá suporte à instrumentação OpenTelemetry. Use o snippet a seguir para configurar os intervalos de rastreamento e exportação para Azure Monitor. Se APPLICATION_INSIGHTS_CONNECTION_STRING não estiver definido, o exportador retornará ao console para depuração local.

Antes de executar o exemplo, instale os pacotes necessários:

pip install opentelemetry-sdk opentelemetry-instrumentation-openai-agents azure-monitor-opentelemetry-exporter

import os
from opentelemetry import trace
from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter

# Configure tracer provider + exporter
resource = Resource.create({
    "service.name": os.getenv("OTEL_SERVICE_NAME", "openai-agents-app"),
})
provider = TracerProvider(resource=resource)

conn = os.getenv("APPLICATION_INSIGHTS_CONNECTION_STRING")
if conn:
    from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
    provider.add_span_processor(
        BatchSpanProcessor(AzureMonitorTraceExporter.from_connection_string(conn))
    )
else:
    provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

trace.set_tracer_provider(provider)

# Instrument the OpenAI Agents SDK
OpenAIAgentsInstrumentor().instrument(tracer_provider=trace.get_tracer_provider())

# Example: create a session span around your agent run
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("agent_session[openai.agents]"):
    # ... run your agent here
    pass

Verificar rastreamentos no portal do Foundry

1. Entre no Microsoft Foundry. Verifique se o interruptor da Nova Fundição está ativado. Essas etapas se referem ao Foundry (novo).
2. Confirme se o rastreamento está conectado ao seu projeto. Caso necessário, siga Configurar o rastreamento no Microsoft Foundry.
3. Execute seu agente pelo menos uma vez.
4. No portal do Foundry, vá para Observabilidade>Rastreamentos.
5. Confirme se um novo rastreamento aparece com intervalos para as operações do agente.

Os rastros normalmente aparecem em um período de 2 a 5 minutos após a execução do agente. Se os traços ainda não aparecerem após esse período, confira Solucionar problemas comuns.

Solucionar problemas comuns

Próximas etapas

• Conheça os principais conceitos e a arquitetura na visão geral do rastreamento do Agente.
• Se você ainda não habilitou o rastreamento, consulte Conseque o rastreamento no Microsoft Foundry.
• Visualize as métricas de integridade e desempenho do agente com o Painel de Monitoramento do Agente.
• Explore as funcionalidades de observabilidade mais amplas na Observabilidade na IA generativa.