Configurar o rastreamento para frameworks de agentes de IA (pré-visualização)

Quando os agentes de IA se comportam de forma inesperada em produção, o rastreio dá-lhe visibilidade para identificar rapidamente a causa raiz. O rastreamento capta telemetria detalhada — incluindo chamadas de LLM, invocações de ferramentas e fluxos de decisão de agentes — para que possa depurar problemas, monitorizar a latência e compreender o comportamento dos agentes entre pedidos.

A Microsoft Foundry fornece integrações de traçado para frameworks de agentes populares que requerem alterações mínimas no código. Neste artigo, aprende como:

• Configurar rastreio automático para o Microsoft Agent Framework
• Configure o langchain-azure-ai traçador para LangChain e LangGraph
• Implemente o SDK dos Agentes OpenAI com OpenTelemetry
• Verifique se os vestígios aparecem no portal da Foundry
• Resolver problemas comuns de rastreio

Pré-requisitos

• Um projeto Foundry com rastreio ligado ao Azure Monitor Application Insights.
• Função de Contribuidor ou nível superior no recurso do Application Insights para ingestão de rastreios.
• Acesso ao recurso conectado ao Application Insights para visualizar rastreamentos. Para consultas baseadas em log, poderá também precisar de acesso ao espaço de trabalho associado Log Analytics.
• Python 3.10 ou posterior (obrigatório para todos os exemplos de código neste artigo).
• A langchain-azure-ai versão do pacote 0.1.0 ou posterior (necessária para amostras LangChain e LangGraph).
• Se usares LangChain ou LangGraph, um ambiente Python com pip instalado.

Confirma que consegues ver telemetria

Para visualizar dados de rastreamento, certifique-se de que a sua conta tem acesso ao recurso Insights Aplicativo conectado.

1. No portal Azure, abra o recurso Application Insights ligado ao seu projeto Foundry.

2. Selecionar controlo de acesso (IAM).

3. Atribui um papel apropriado ao teu utilizador ou grupo.

   Se usar consultas baseadas em log, comece por conceder a função Leitor do Log Analytics.

Segurança e privacidade

O rastreamento pode captar informação sensível (por exemplo, entradas do utilizador, saídas de modelos e argumentos e resultados de ferramentas).

• Ative o registo de conteúdos durante o desenvolvimento e a depuração para ver os dados completos de pedidos e respostas. Desative o registo de conteúdos em ambientes de produção para proteger dados sensíveis. Nos exemplos deste artigo, a gravação de conteúdos é controlada por definições como enable_content_recording e OTEL_RECORD_CONTENT.
• Não armazene segredos, credenciais ou tokens em prompts ou parâmetros de ferramentas.

Para mais orientações, consulte Segurança e privacidade.

Configurar rastreio para o Microsoft Agent Framework

O Microsoft Foundry tem integrações nativas com o Microsoft Agent Framework. Agentes construídos com qualquer um dos frameworks emitem automaticamente traços quando o rastreamento está ativado para o seu projeto Foundry — não é necessário código ou pacotes adicionais.

Para verificar se o rastreio está a funcionar:

1. Contacta o teu agente pelo menos uma vez.
2. No portal Foundry, vá a Observabilidade>Rastreios.
3. Confirme que aparece um novo rastreio com intervalos para as operações do seu agente.

Os vestígios normalmente aparecem entre 2 a 5 minutos após a execução do agente. Para configuração avançada, consulte a documentação específica do framework:

• Microsoft Workflows do Agent Framework – Observabilidade

Configurar o rastreamento para LangChain e LangGraph

Use o pacote langchain-azure-ai para emitir spans compatíveis com OpenTelemetry nas operações LangChain e LangGraph. Estes vestígios aparecem na vista Observability>Traces no portal da Foundry.

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

Exemplo: agente LangChain v1 com rastreamento de IA da Azure

Use este exemplo de ponta a ponta para instrumentar um agente LangChain v1 (versão preliminar) usando o langchain-azure-ai traçador. Este traçador implementa as mais recentes convenções semânticas do OpenTelemetry (OTel), para que possa visualizar rastreios detalhados na visualização de observabilidade do Foundry.

LangChain v1: Pacotes de instalação

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

LangChain v1: Configurar ambiente

• APPLICATION_INSIGHTS_CONNECTION_STRING: string de conexão da Azure Monitor Application Insights para rastreamento.
• AZURE_OPENAI_ENDPOINT: O seu Azure URL de endpoint OpenAI.
• AZURE_OPENAI_CHAT_DEPLOYMENT: O nome de implementaçã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 suporta variáveis de ambiente, identidade gerida e início de sessão no VS Code.

Armazene estes valores num .env ficheiro para desenvolvimento local.

LangChain v1: Configuração do traçador

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 de modelos (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 prompts

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 contexto de runtime e definir uma ferramenta de informação do utilizador

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 ativado, todas as operações LangChain v1 (chamadas LLM, invocações de ferramentas, passos de agente) emitem spans OpenTelemetry usando as convenções semânticas mais recentes. Estes rastos aparecem na visualização Observability>Traces no portal Foundry e estão ligados ao recurso do Application Insights.

Verifique os seus vestígios LangChain v1

Depois de executar o agente:

1. Espere 2–5 minutos para que os vestígios se propaguem.
2. No portal Foundry, vá a Observabilidade>Rastreios.
3. Procure um rasto com o nome que especificou (por exemplo, "Agente de informação meteorológica").
4. Expanda o traçado para visualizar os spans para chamadas de LLM, invocações de ferramentas e passos do agente.

Se não vires rastos, consulta a secção Resolução de Problemas Comuns.

Exemplo: agente LangGraph com rastreamento de IA do Azure

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

LangGraph: Pacotes de instalação

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

LangGraph: Configurar ambiente

• APPLICATION_INSIGHTS_CONNECTION_STRING: string de conexão da Azure Monitor Application Insights para rastreamento.
• AZURE_OPENAI_ENDPOINT: O seu Azure URL de endpoint OpenAI.
• AZURE_OPENAI_CHAT_DEPLOYMENT: O nome de implementação do modelo de chat.
• AZURE_OPENAI_VERSION: Versão da API, por exemplo 2024-08-01-preview.

Armazene estes valores num .env ficheiro para desenvolvimento local.

Configuração do traçador 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 de modelos (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)

Construir o fluxo de trabalho 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 traçado

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 o langchain-azure-ai ativado, a sua execução LangGraph emite intervalos compatíveis com o OpenTelemetry para chamadas de modelo, invocações de ferramentas e transições de grafos. Estes rastreios fluem para o Application Insights e aparecem na vista Observability>Rastreios no portal Foundry.

Verifique os seus traços LangGraph

Depois de executar o agente:

1. Espere 2–5 minutos para que os vestígios se propaguem.
2. No portal Foundry, vá a Observabilidade>Rastreios.
3. Procure um rastreio com o nome que especificou (por exemplo, "Music Player Agent").
4. Expanda o traço para ver os intervalos para nós de grafo, invocações de ferramentas e chamadas de modelo.

Se não vires rastos, consulta a secção Resolução de Problemas Comuns.

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

Esta configuração mínima mostra como ativar o traçado de IA Azure numa aplicação LangChain 0.3 usando o traçador langchain-azure-ai e AzureChatOpenAI.

LangChain 0.3: Pacotes de instalação

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

LangChain 0.3: Configurar ambiente

• APPLICATION_INSIGHTS_CONNECTION_STRING: Cadeia de conexão do Application Insights para monitorização. Para encontrar este valor, abra o seu recurso Application Insights no portal Azure, selecione Visão Geral e copie a Connection String.
• AZURE_OPENAI_ENDPOINT: Azure URL do endpoint OpenAI.
• AZURE_OPENAI_CHAT_DEPLOYMENT: Nome de implementaçã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: Traçador e configuração do 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 garantir que as operações do LangChain 0.3 sejam rastreadas. Depois de executar a tua cadeia ou agente, os traços aparecem na vista de Observabilidade>Traços no portal da Foundry dentro de 2-5 minutos.

Configurar rastreamento para o SDK do OpenAI Agents

O SDK OpenAI Agents suporta instrumentação OpenTelemetry. Use o seguinte excerto para configurar o traçado e exportar os intervalos para o Azure Monitor. Se APPLICATION_INSIGHTS_CONNECTION_STRING não estiver definido, o exportador volta à consola 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 registos no portal da Fundição

1. Iniciar sessão no Microsoft Foundry. Certifica-te de que a opção New Foundry está ativada. Estes passos referem-se à Foundry (nova).
2. Confirma que o rastreio está ligado ao teu projeto. Se necessário, siga o Configurar rastreamento no Microsoft Foundry.
3. Contacta o teu agente pelo menos uma vez.
4. No portal Foundry, vá a Observabilidade>Rastreios.
5. Confirme que aparece um novo rastreio com intervalos para as operações do seu agente.

Os vestígios normalmente aparecem entre 2 a 5 minutos após a execução do agente. Se os rastros continuarem a não aparecer depois deste período, consulte Solucionar problemas comuns.

Resolver problemas comuns

Próximos passos

• Aprenda conceitos e arquitetura essenciais na visão geral do rastreio de agentes.
• Se ainda não ativaste o traçado, vê Configurar traçado no Microsoft Foundry.
• Visualize as métricas de saúde e desempenho dos agentes com o Painel de Monitorização de Agentes.
• Explore as capacidades mais amplas de observabilidade em IA generativa.