Configure o rastreamento para frameworks de agentes 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 e o Kernel Semântico
• Configurar a distribuição Microsoft OpenTelemetry para LangChain e LangGraph
• Instrumentar o SDK de Agentes do OpenAI com o OpenTelemetry
• Verificar se os rastreamentos aparecem no portal do Foundry
• Solucionar problemas comuns de rastreamento

Pré-requisitos

• Um projeto de fundição. Para obter mais informações, consulte Create a Foundry project.
• Rastreamento vinculado a um recurso do Azure Monitor Application Insights. Para configurá-lo, consulte Configurar o rastreamento no Microsoft Foundry.
• Função Colaborador ou superior no recurso Application Insights para a ingestão de rastreamento.
• 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).
• O microsoft-opentelemetry pacote (necessário para exemplos de LangChain e LangGraph).
• Se você usar LangChain ou LangGraph, um ambiente do 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 pelas variáveis OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTde ambiente e OTEL_SEMCONV_STABILITY_OPT_INAZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING.
• 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 e o Kernel Semântico

O Microsoft Foundry tem integrações nativas com o Microsoft Agent Framework e o Kernel Semântico. Os agentes criados com qualquer um dos frameworks emitem rastreamentos automaticamente quando o rastreamento está habilitado para o seu projeto do Foundry — nenhum código ou pacote adicional é necessário.

Para verificar se o rastreamento está funcionando:

1. Execute seu agente pelo menos uma vez.
2. No portal do Foundry, acesse 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 do Microsoft Agent Framework – Observabilidade
• Observabilidade semântica do Kernel

Configurar o rastreamento com bibliotecas de instrumentação OpenInference

Microsoft Foundry dá suporte a bibliotecas de instrumentação OpenInference para rastrear agentes de IA. Esses openinference-* pacotes fornecem instrumentação automática para uma ampla gama de estruturas e podem ser usados para rastrear agentes hospedados (agentes implantados na Foundry) e agentes não-Foundry (agentes hospedados fora do Foundry).

Procure pacotes de instrumentação disponíveis no PyPI. Para LangChain, consulte o exemplo do LangChain da distribuição Microsoft OpenTelemetry, que mostra como habilitar a exportação para o Azure Monitor e a instrumentação automática do LangChain com use_microsoft_opentelemetry.

O requisito principal é correlacionar rastreamentos OpenInference a um agente específico. A forma como você consegue isso depende de onde seu agente é executado:

Agentes hospedados (implantados na Foundry)

Quando você implanta um agente no Foundry usando um dos pacotes de servidor do agente hospedado, a correlação de rastreamento é feita automaticamente. O pacote do servidor:

• Configura a exportação do Azure Monitor para spans do OpenTelemetry.
• Enriquece todos os intervalos com atributos de projeto, nome do agente, versão do agente e ID do agente para que a interface do usuário do Foundry possa consultá-los e exibi-los.

Não requer configuração adicional. Instale o pacote de instrumentação openinference-* adequado para seu framework, e os rastreamentos aparecerão automaticamente no portal do Foundry.

Agentes do LangChain hospedados fora da Foundry

Se o agente não for implantado com um pacote de servidor de agente hospedado do Foundry, configure a exportação para o Azure Monitor e a instrumentação do LangChain com a distribuição Microsoft OpenTelemetry distro. A distribuição pode habilitar o exportador do Azure Monitor e adicionar atributos de identidade do agente aos spans do LangChain:

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    sampling_ratio=1.0,
    instrumentation_options={
        "langchain": {
            "enabled": True,
            "agent_id": "weather_info_agent_771929",
            "agent_name": "Weather information agent",
        },
    },
)

Defina APPLICATIONINSIGHTS_CONNECTION_STRING como o recurso do Application Insights conectado ao seu projeto do Foundry. Para capturar o conteúdo do prompt e da conclusão durante o desenvolvimento, defina OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_AND_EVENTe OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimentalAZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING=true.

Configurar o rastreamento para LangChain e LangGraph

Use a distribuição Microsoft OpenTelemetry para emitir intervalos compatíveis com OpenTelemetry para operações LangChain e LangGraph. Esses rastreamentos aparecem na exibição Observabilidade>Rastreamentos no portal do Foundry.

• Convenções semânticas OpenTelemetry para IA generativa
• Exemplo de LangChain da distribuição OpenTelemetry da Microsoft

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 a distribuição Microsoft OpenTelemetry. A distro habilita a instrumentação automática do LangChain com as convenções semânticas mais recentes do OpenTelemetry (OTel), para que você possa visualizar rastreamentos detalhados na visão de observabilidade do Foundry.

LangChain v1: Instalar pacotes

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

LangChain v1: Configurar o ambiente

• APPLICATIONINSIGHTS_CONNECTION_STRING: cadeia de conexão do Application Insights do Azure Monitor para rastreamento.
• AZURE_OPENAI_ENDPOINT: sua URL do ponto de extremidade do OpenAI do Azure.
• 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
from microsoft.opentelemetry import use_microsoft_opentelemetry

load_dotenv(override=True)

use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    sampling_ratio=1.0,
    instrumentation_options={
        "langchain": {
            "enabled": True,
            "agent_id": "weather_info_agent_771929",
            "agent_name": "Weather information agent",
        },
    },
)

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://cognitiveservices.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"}}
    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 a distribuição Microsoft OpenTelemetry habilitada, todas as operações do LangChain v1 (chamadas LLM, invocações de ferramentas, etapas do agente) emitem intervalos opentelemetry usando as convenções semânticas mais recentes. Esses rastreamentos aparecem na visualização Observabilidade>Rastreamentos no portal do Foundry e estão vinculados ao seu 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, acesse 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 de 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 LangGraph com rastreamento de IA do Azure

Este exemplo mostra um agente simples do LangGraph instrumentado com a distribuição Microsoft OpenTelemetry para emitir rastreamentos compatíveis com OpenTelemetry para etapas de grafo, chamadas de ferramenta e invocações de modelo.

LangGraph: instalar pacotes

pip install \
  microsoft-opentelemetry \
  "langgraph>=1.0.0" \
  "langchain>=1.0.0" \
  langchain-openai \
  azure-identity \
  python-dotenv

LangGraph: Configurar o ambiente

• APPLICATIONINSIGHTS_CONNECTION_STRING: cadeia de conexão do Application Insights do Azure Monitor para rastreamento.
• AZURE_OPENAI_ENDPOINT: sua URL do ponto de extremidade do OpenAI do Azure.
• 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

from dotenv import load_dotenv
from microsoft.opentelemetry import use_microsoft_opentelemetry

load_dotenv(override=True)

use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    sampling_ratio=1.0,
    instrumentation_options={
        "langchain": {
            "enabled": True,
            "agent_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://cognitiveservices.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"}}
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 a distribuição Microsoft OpenTelemetry habilitada, a execução do LangGraph emite intervalos em conformidade com o OpenTelemetry para chamadas de modelo, invocações de ferramenta e transições de grafo. Esses rastreamentos fluem 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, acesse Observabilidade>Rastreamentos.
3. Procure um rastreamento com o nome especificado (por exemplo, "Agente do Player de Música").
4. Expanda o rastreamento para ver os 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 a distribuição Microsoft OpenTelemetry e AzureChatOpenAI.

LangChain 0.3: Instalar pacotes

pip install \
  "langchain>=0.3,<0.4" \
  langchain-openai \
  microsoft-opentelemetry \
  python-dotenv

LangChain 0.3: Configurar o ambiente

• APPLICATIONINSIGHTS_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 OpenAI do Azure.
• AZURE_OPENAI_CHAT_DEPLOYMENT: nome da implantação do modelo de bate-papo.
• 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 microsoft.opentelemetry import use_microsoft_opentelemetry
from langchain_openai import AzureChatOpenAI

load_dotenv(override=True)

# Enable Azure Monitor export and LangChain auto-instrumentation
use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    sampling_ratio=1.0,
    instrumentation_options={
        "langchain": {
            "enabled": True,
            "agent_id": "trip_planner_orchestrator_v3",
            "agent_name": "Trip Planner Orchestrator",
        },
    },
)

# Model: Azure OpenAI
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,
)

Com a distro inicializada, as operações do LangChain 0.3 são instrumentadas automaticamente em todo o ambiente. Depois de executar sua cadeia ou agente, os rastreamentos aparecem na exibição Observabilidade>Rastreamentos no portal do 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

Verifique os rastreamentos no portal do Foundry

1. Entre no Microsoft Foundry. Verifique se o interruptor da Nova Fundição está ativado. Estas 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, acesse 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 rastreamentos ainda não aparecerem depois desse tempo, consulte Solucionar problemas comuns.

Solucionar problemas comuns

Conteúdo relacionado

• 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.