Agentes de observabilidade

Importante

Você precisa fazer parte do programa de prévia Frontier para obter acesso antecipado ao Microsoft Agent 365. A Frontier conecta você diretamente às mais recentes inovações de IA da Microsoft. Prévias da Frontier estão sujeitas aos termos de pré-visualização existentes dos seus contratos com clientes. Como esses recursos ainda estão em desenvolvimento, sua disponibilidade e capacidades podem mudar ao longo do tempo.

Para participar do ecossistema Agent 365, você deve adicionar capacidades de Observabilidade do Agent 365 ao seu agente. A Observabilidade do Agente 365 se baseia no OpenTelemetry (OTel) e fornece uma estrutura unificada para capturar telemetria de forma consistente e segura em todas as plataformas de agentes. Ao implementar esse componente obrigatório, você permite que administradores de TI monitorem a atividade do seu agente no Microsoft Admin Center (MAC) e permite que equipes de segurança usem o Defender e o Purview para conformidade e detecção de ameaças.

Principais benefícios

• Visibilidade de ponta a ponta: Capture telemetria abrangente para cada invocação de agente, incluindo sessões, chamadas de ferramentas e exceções, garantindo rastreabilidade total entre as plataformas.
• Segurança e Habilitação de Conformidade: Alimente logs unificados de auditoria no Defender e Purview, possibilitando cenários avançados de segurança e relatórios de conformidade para seu agente.
• Flexibilidade Multiplataforma: Construa sobre os padrões OTel e suporte runtimes e plataformas diversas como Copilot Studio, Foundry e futuros frameworks de agentes.
• Eficiência Operacional para Administradores: Fornecer observabilidade centralizada no MAC, reduzindo o tempo de resolução de problemas e melhorando a governança com controles de acesso baseados em funções para equipes de TI que gerenciam seu agente.

Instalação

Use esses comandos para instalar os módulos de observabilidade para as linguagens suportadas pelo Agente 365.

Python

pip install microsoft-agents-a365-observability-core
pip install microsoft-agents-a365-runtime

JavaScript

npm install @microsoft/agents-a365-observability
npm install @microsoft/agents-a365-runtime

.NET

dotnet add package Microsoft.Agents.A365.Observability
dotnet add package Microsoft.Agents.A365.Observability.Runtime

Configuração

Use as seguintes configurações para ativar e personalizar a Observabilidade do Agente 365 para seu agente.

Python

As variáveis do ambiente necessárias para a observabilidade são:

Variável de ambiente	Description
ENABLE_OBSERVABILITY=true	Flag para ativar/desativar o rastreamento. Por padrão: false
ENABLE_A365_OBSERVABILITY_EXPORTER=true	True exporta registros para nosso serviço. Caso contrário, isso volta para o exportador do console

from microsoft_agents_a365.observability.core import config

def token_resolver(agent_id: str, tenant_id: str) -> str | None:
    # Implement secure token retrieval here
    return "Bearer <token>"

config.configure(
    service_name="my-agent-service",
    service_namespace="my.namespace",
    token_resolver=token_resolver,
)

Exclua o resolvedor de token para logar no console.

JavaScript

As variáveis do ambiente necessárias para a observabilidade são:

Variável de ambiente	Description
ENABLE_OBSERVABILITY=true	Flag para ativar/desativar o rastreamento. Por padrão: false
ENABLE_A365_OBSERVABILITY_EXPORTER=true	True Exporte logs para nosso serviço. Caso contrário, recorre ao exportador de console

import { ObservabilityManager } from '@microsoft/agents-a365-observability';

const tokenResolver = (agentId, tenantId) => {
    // Your token resolution logic here
    return "your-token";
};

// Advanced configuration with builder pattern
const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withTokenResolver((agentId, tenantId) => {
      return tokenResolver(agentId, tenantId);
    })
);

builder.start();

.NET

Definir EnableAgent365Exporter como true em appsettings.json.

No Program.cs, chame Agent365ExporterOptions na coleção de serviços. Essa alteração configura o delegado que o exportador de rastreamento usa para recuperar o token.

Adicione dependências relacionadas à observabilidade usando AddA365Tracing().

using Microsoft.Agents.A365.Observability.Runtime;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton(sp =>
    {
        return new Agent365ExporterOptions
        {
            ClusterCategory = "prod",
            TokenResolver = async (agentId, tenantId) =>
            {
                // It's recommended to implement caching in your token provider for performance.
                var token = await tokenProvider.GetObservabilityTokenAsync(agentId, tenantId);
                return token;
            }
        };
    });

builder.AddA365Tracing();

Atributos de bagagem

Use BaggageBuilder para definir informações contextuais que fluem por todos os intervalos em uma requisição. O SDK implementa uma SpanProcessor cópia de todas as entradas de bagagem não vazias para os intervalos recém-iniciados sem sobrescrever atributos existentes.

Python

from microsoft_agents_a365.observability.core.middleware.baggage_builder import BaggageBuilder

with (
    BaggageBuilder()
    .tenant_id("tenant-123")
    .agent_id("agent-456")
    .correlation_id("corr-789")
    .build()
):
    # Any spans started in this context will receive these as attributes
    pass

JavaScript

import { BaggageBuilder } from '@microsoft/agents-a365-observability';

// Create and apply baggage context
using baggageScope = new BaggageBuilder()
  // Core identifiers
  .tenantId('tenant-123')
  .agentId('agent-456')
  .correlationId('correlation-789')  
  .build();

// Execute operations within the baggage context
baggageScope.run(() => {
  // All spans created within this context will inherit the baggage values
  
  // Invoke another agent
  using agentScope = InvokeAgentScope.start(invokeDetails, agentDetails, tenantDetails);
  // ... agent logic
  
  // Execute tools
  using toolScope = ExecuteToolScope.start(toolDetails, agentDetails, tenantDetails);
  // ... tool logic
});

.NET

 using var baggageScope = new BaggageBuilder()
          .TenantId('tenant-123')
          .AgentId('agent-456')
          .CorrelationId('correlation-789')
          .Build();
// Any spans started in this context will receive them as attributes.

Resolver de Tokens

Ao usar o exportador Agent 365, você deve fornecer uma função de resolução de token que retorne token de autenticação. Ao usar o SDK de Observabilidade do Agente 365 com o framework Agent Hosting, você pode gerar tokens usando as TurnContext atividades do agente do From

Python

from microsoft_agents.activity import load_configuration_from_env
from microsoft_agents.authentication.msal import MsalConnectionManager
from microsoft_agents.hosting.aiohttp import CloudAdapter
from microsoft_agents.hosting.core import (
    AgentApplication,
    Authorization,
    MemoryStorage,
    TurnContext,
    TurnState,
)
from microsoft_agents_a365.runtime.environment_utils import (
    get_observability_authentication_scope,
)

agents_sdk_config = load_configuration_from_env(environ)

STORAGE = MemoryStorage()
CONNECTION_MANAGER = MsalConnectionManager(**agents_sdk_config)
ADAPTER = CloudAdapter(connection_manager=CONNECTION_MANAGER)
ADAPTER.use(TranscriptLoggerMiddleware(ConsoleTranscriptLogger()))
AUTHORIZATION = Authorization(STORAGE, CONNECTION_MANAGER, **agents_sdk_config)

AGENT_APP = AgentApplication[TurnState](
    storage=STORAGE, adapter=ADAPTER, authorization=AUTHORIZATION, **agents_sdk_config
)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    aau_auth_token = await AGENT_APP.auth.exchange_token(
                        context,
                        scopes=get_observability_authentication_scope(),
                        auth_handler_id="AGENTIC",
                    )
    # cache this auth token and return via token resolver

JavaScript

import {
  TurnState,
  AgentApplication,
  MemoryStorage,
  TurnContext,
} from '@microsoft/agents-hosting';
import { Activity, ActivityTypes } from '@microsoft/agents-activity';
import { getObservabilityAuthenticationScope } from '@microsoft/agents-a365-runtime';

interface ConversationState {
  count: number;
}
type ApplicationTurnState = TurnState<ConversationState>;

const downloader = new AttachmentDownloader();

const storage = new MemoryStorage();

export const agentApplication = new AgentApplication<ApplicationTurnState>({
  authorization: {
        agentic: { } // We have the type and scopes set in the .env file
      },
  storage,
});

agentApplication.onActivity(
  ActivityTypes.Message,
  async (context: TurnContext, state: ApplicationTurnState) => {
    const aauAuthToken = await agentApplication.authorization.exchangeToken(context,'agentic', {
        scopes: getObservabilityAuthenticationScope() 
      } )
    // cache this auth token and return via token resolver
  };

.NET

Adicione o resolvedor de tokens agentes à sua coleção de serviços.

using Microsoft.Agents.A365.Observability;

builder.Services.AddAgenticTracingExporter();

No aplicativo do agente, registre o token.

using Microsoft.Agents.Builder;
using Microsoft.Agents.Core.Models;
using Microsoft.Extensions.Logging;
using Microsoft.Agents.A365.Observability.Caching;
using System;
using System.Threading.Tasks;

public class MyAgent : AgentApplication
{
    private readonly IExporterTokenCache<AgenticTokenStruct> _agentTokenCache;
    private readonly ILogger<MyAgent> _logger;

    public MyAgent(AgentApplicationOptions options, IExporterTokenCache<AgenticTokenStruct> agentTokenCache, ILogger<MyAgent> logger)
        : base(options)
    {
        _agentTokenCache = agentTokenCache ?? throw new ArgumentNullException(nameof(agentTokenCache));
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
    }

    protected async Task MessageActivityAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        using var baggageScope = new BaggageBuilder()
            .TenantId(turnContext.Activity.Recipient.TenantId)
            .AgentId(turnContext.Activity.Recipient.AgenticAppId)
            .Build();

        try
        {
            _agentTokenCache.RegisterObservability(
                turnContext.Activity.Recipient.AgenticAppId,
                turnContext.Activity.Recipient.TenantId,
                new AgenticTokenStruct
                {
                    UserAuthorization = UserAuthorization,
                    TurnContext = turnContext
                },
                EnvironmentUtils.GetObservabilityAuthenticationScope()
            );
        }
        catch (Exception ex)
        {
            _logger.LogWarning($"Error registering for observability: {ex.Message}");
        }
    }
}

Instrumentação automática

A auto-instrumentação escuta automaticamente os frameworks agenticos (SDKs), sinais de telemetria existentes para rastreios e os encaminha para o serviço de observabilidade do Agente 365. Isso elimina a necessidade de os desenvolvedores escreverem código de monitoramento manualmente, simplificando a configuração e garantindo um acompanhamento consistente de desempenho.

Auto-instrumentação é suportada por múltiplos SDKs e plataformas:

Plataforma	SDKs/Frameworks suportados
.NET	Kernel Semântico, OpenAI, Framework de Agentes
Python	Kernel Semântico, OpenAI, Framework de Agentes, LangChain
Node.js	OpenAI

Observação

O suporte à auto-instrumentação varia conforme a plataforma e a implementação do SDK.

Kernel semântico

A instrumentação automotiva requer o uso de um construtor de bagagens. Defina o ID do agente e o ID do locatário usando BaggageBuilder.

Python

Instalar o pacote

pip install microsoft-agents-a365-observability-extensions-semantic-kernel

Configurar a observabilidade

from microsoft_agents_a365.observability.core.config import configure
from microsoft_agents_a365.observability.extensions.semantic_kernel import SemanticKernelInstrumentor

# Configure observability
configure(
    service_name="my-semantic-kernel-agent",
    service_namespace="ai.agents"
)

# Enable auto-instrumentation
instrumentor = SemanticKernelInstrumentor()
instrumentor.instrument()

# Your Semantic Kernel code is now automatically traced

JavaScript

Semantic Kernel não é suportado com JavaScript.

.NET

Adicione dependências à coleção de serviços.

using Microsoft.Agents.A365.Observability.Extensions.SemanticKernel;

builder.Services.AddTracing(config => config.WithSemanticKernel());

Defina AgentId e TenantId use BaggageBuilder. Certifique-se de que o ID usado ao criar um ChatCompletionAgent corresponda ao ID do agente passado para BaggageBuilder.

using Microsoft.Agents.A365.Observability.Extensions.SemanticKernel;
using Microsoft.Agents.A365.Observability.Runtime.Common;
public class MyAgent
{
    public async Task<AgentResponse> ProcessUserRequest(string userInput)
    {
      using var baggageScope = new BaggageBuilder()
          .AgentId(<your-agent-id>) // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. 
          .TenantId(<your-tenant-id>) // NOTE: This will be the tenant ID with which the TokenResolver delegate is invoked.
          .Build();
      
      var chatCompletionAgent = new ChatCompletionAgent
      {
          // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. Should match above.
          Id = <your-agent-id>,
          ...
      };
    }
}

OpenAI

A instrumentação automotiva requer o uso de um construtor de bagagens. Defina o ID do agente e o ID do locatário usando BaggageBuilder.

Python

Instale o pacote.

pip install microsoft-agents-a365-observability-extensions-openai

Configurar a observabilidade

from microsoft_agents_a365.observability.core.config import configure
from microsoft_agents_a365.observability.extensions.openai_agents import OpenAIAgentsTraceInstrumentor

# Configure observability
configure(
    service_name="my-openai-agent",
    service_namespace="ai.agents"
)

# Enable auto-instrumentation
instrumentor = OpenAIAgentsTraceInstrumentor()
instrumentor.instrument()

# Your OpenAI Agents code is now automatically traced

JavaScript

Instalar o pacote

npm install @microsoft/agents-a365-observability-extensions-openai

Configurar a observabilidade

import { ObservabilityManager } from '@microsoft/agents-a365-observability';
import { OpenAIAgentsTraceInstrumentor } from '@microsoft/agents-a365-observability-extensions-openai';

// Configure observability first
const sdk = ObservabilityManager.configure((builder) =>
  builder
    .withService('My Agent Service', '1.0.0')
    .withConsoleExporter(true)
);

// Create and enable the instrumentor
const instrumentor = new OpenAIAgentsTraceInstrumentor({
  enabled: true,
  tracerName: 'openai-agents-tracer',
  tracerVersion: '1.0.0'
});

sdk.start();

instrumentor.enable();

.NET

Adicione dependências à coleção de serviços.

using Microsoft.Agents.A365.Observability.Extensions.OpenAI;

builder.Services.AddTracing(config => config.WithOpenAI());

Defina AgentId e TenantId use BaggageBuilder. Para chamadas de ferramenta, inicie um rastreamento usando Trace() em uma ChatToolCall instância.

using Microsoft.Agents.A365.Observability.Extensions.OpenAI;
using Microsoft.Agents.A365.Observability.Runtime.Common;

public class MyAgent
{
    public async Task<AgentResponse> ProcessUserRequest(string userInput)
    {
      using var baggageScope = new BaggageBuilder()
          .AgentId(<your-agent-id>) // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. 
          .TenantId(<your-tenant-id>) // NOTE: This will be the tenant ID with which the TokenResolver delegate is invoked.
          .Build();
      
      // NOTE: This will be the agent and tenant ID with which the TokenResolver delegate will be invoked. 
      using var scope = chatToolCall.Trace(agentId: <your-agent-id>, <your-tenant-id>);
    }
}

Estrutura do Agente

A instrumentação automotiva requer o uso de um construtor de bagagens. Defina o ID do agente e o ID do tenant usando o BaggageBuilder.

Python

Instalar o pacote

pip install microsoft-agents-a365-observability-extensions-agent-framework

Configurar a observabilidade

from microsoft_agents_a365.observability.core.config import configure
from microsoft_agents_a365.observability.extensions.agentframework.trace_instrumentor import (
    AgentFrameworkInstrumentor,
)

# Configure observability
configure(
    service_name="AgentFrameworkTracingWithAzureOpenAI",
    service_namespace="AgentFrameworkTesting",
)

# Enable auto-instrumentation
AgentFrameworkInstrumentor().instrument()

JavaScript

O Agent Framework não é suportado com JavaScript.

.NET

Adicione dependências à coleção de serviços.

using Microsoft.Agents.A365.Observability.Extensions.AgentFramework;

builder.Services.AddTracing(config => config.WithAgentFramework());

Defina AgentId e TenantId use BaggageBuilder.

using Microsoft.Agents.A365.Observability.Runtime.Common;

public class MyAgent : AgentApplication
{
    protected async Task MessageActivityAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
      using var baggageScope = new BaggageBuilder()
          .AgentId(<your-agent-id>) // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. 
          .TenantId(<your-tenant-id>) // NOTE: This will be the tenant ID with which the TokenResolver delegate is invoked.
          .Build();
    }
}

Estrutura LangChain

A auto-instrumentação requer o uso do bagbage builder. Defina o ID do agente e o ID do locatário usando BaggageBuilder.

Instale o pacote.

pip install microsoft-agents-a365-observability-extensions-langchain

Configurar a observabilidade

from microsoft_agents_a365.observability.core.config import configure
from microsoft_agents_a365.observability.extensions.langchain import CustomLangChainInstrumentor

# Configure observability
configure(
    service_name="my-langchain-agent",
    service_namespace="ai.agents"
)

# Enable auto-instrumentation
CustomLangChainInstrumentor()

# Your LangChain code is now automatically traced

---

Instrumentação manual

O SDK de observabilidade do agente 365 pode ser usado para entender o funcionamento interno do agente. O SDK fornece três escopos que podem ser iniciados: InvokeAgentScope, ExecuteToolScope, e InferenceScope.

Invocação do Agente

Esse escopo deve ser usado no início do processo do seu agente. Com o escopo do agente invocado, você captura propriedades como o agente atual que está sendo invocado, dados do usuário do agente, etc.

Python

from microsoft_agents_a365.observability.core.invoke_agent_scope import InvokeAgentScope
from microsoft_agents_a365.observability.core.invoke_agent_details import InvokeAgentDetails
from microsoft_agents_a365.observability.core.tenant_details import TenantDetails
from microsoft_agents_a365.observability.core.request import Request

invoke_details = InvokeAgentDetails(
    details=agent_details,        # AgentDetails instance
    endpoint=my_endpoint,         # Optional endpoint (with hostname/port)
    session_id="session-42"
)
tenant_details = TenantDetails(tenant_id="tenant-123")
req = Request(content="User asks a question")

with InvokeAgentScope.start(invoke_details, tenant_details, req):
    # Perform agent invocation logic
    response = call_agent(...)

JavaScript

import { 
  InvokeAgentScope, 
  ExecutionType, 
  CallerDetails, 
  EnhancedAgentDetails 
} from '@microsoft/agents-a365-observability';

// Basic agent invocation details
const invokeDetails = {
  agentId: 'email-agent-123',
  agentName: 'Email Assistant',
  ...
  }
};

const tenantDetails = {
  tenantId: 'tenant-789'
};

// Optional: Caller details (human user)
const callerDetails: CallerDetails = {};

// Optional: Caller agent details (for agent-to-agent calls)
const callerAgentDetails: EnhancedAgentDetails = {};

// Enhanced invocation with caller context
using scope = InvokeAgentScope.start(
  invokeDetails,
  tenantDetails,
  callerAgentDetails,
  callerDetails
);

try {
  // Record input messages
  scope.recordInputMessages(['Please help me organize my emails', 'Focus on urgent items']);
  
  // Your agent invocation logic here
  const response = await invokeAgent(invokeDetails.request.content);
  
  // Record output messages
  scope.recordOutputMessages(['I found 15 urgent emails', 'Here is your organized inbox']);
  
} catch (error) {
  scope.recordError(error as Error);
  throw error;
}
// Scope automatically disposed at end of using block

.NET

using System;
using System.Threading.Tasks;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

public class MyAgent
{
    public async Task<AgentResponse> ProcessUserRequest(string userInput)
    {
        var agentDetails = new AgentDetails(
            agentId: Guid.NewGuid().ToString(),
            agentName: "MyAgent",
            agentDescription: "Handles user requests.",
            tenantId: "tenant-789"
        );

        var tenantDetails = new TenantDetails(Guid.Parse("11111111-2222-3333-4444-555555555555"));

        var request = new Request(
            content: userInput,
            executionType: ExecutionType.HumanToAgent,
            sessionId: "session-abc",
            channelMetadata: new ChannelMetadata("webchat", "https://webchat.contoso.com")
        );

        var callerDetails = new CallerDetails(
            callerId: "user-123",
            callerName: "Jane Doe",
            callerUpn: "jane.doe@contoso.com",
            callerUserId: "user-uuid-456",
            tenantId: "tenant-789"
        );

        var endpoint = new Uri("https://myagent.contoso.com");

        var invokeAgentDetails = new InvokeAgentDetails(endpoint, agentDetails, sessionId: "session-abc");

        var conversationId = "conv-xyz";

        // Start the scope
        using var scope = InvokeAgentScope.Start(
            invokeAgentDetails: invokeAgentDetails,
            tenantDetails: tenantDetails,
            request: request,
            callerAgentDetails: null,
            callerDetails: callerDetails,
            conversationId: conversationId
        );

        // Record input messages
        scope.RecordInputMessages(new[] { userInput });

        // ... your agent logic here ...

        // Simulate agent processing and output
        var output = $"Processed: {userInput}";
        scope.RecordOutputMessages(new[] { output });

        // Optionally record a single response
        scope.RecordResponse(output);

        return new AgentResponse { Content = output };
    }
}

public class AgentResponse
{
    public string Content { get; set; }
}

Parar execução

Os exemplos a seguir demonstram como instrumentar a execução da ferramenta do seu agente com rastreamento de observabilidade para capturar telemetria para fins de monitoramento e auditoria.

Python

from microsoft_agents_a365.observability.core.execute_tool_scope import ExecuteToolScope
from microsoft_agents_a365.observability.core.tool_call_details import ToolCallDetails

tool_details = ToolCallDetails(
    tool_name="summarize",
    tool_type="function",
    tool_call_id="tc-001",
    arguments="{'text': '...'}",
    description="Summarize provided text",
    endpoint=None  # or endpoint object with hostname/port
)

with ExecuteToolScope.start(tool_details, agent_details, tenant_details):
    result = run_tool(tool_details)

JavaScript

import { ExecuteToolScope } from '@microsoft/agents-a365-observability';

const toolDetails = {
  toolName: 'email-search',
  arguments: JSON.stringify({ query: 'from:boss@company.com', limit: 10 }),
  toolCallId: 'tool-call-456',
  description: 'Search emails by criteria',
  toolType: 'function',
  endpoint: {
    host: 'tools.contoso.com',
    port: 8080,  // Will be recorded since not 443
    protocol: 'https'
  }
};

using scope = ExecuteToolScope.start(toolDetails, agentDetails, tenantDetails);

try {
  // Execute the tool
  const result = await searchEmails(toolDetails.arguments);
  
  // Record the tool execution result
  scope.recordResponse(JSON.stringify(result));
  
  return result;
} catch (error) {
  scope.recordError(error as Error);
  throw error;
}

.NET

using System;
using System.Threading.Tasks;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

public class MyToolAgent
{
    public async Task<ToolResult> ExecuteTool(string toolName, object parameters)
    {
        var agentDetails = new AgentDetails(
            agentId: Guid.NewGuid().ToString(),
            agentName: "ToolAgent",
            agentDescription: "Executes tools for users.",
            agentAUID: "tool-auid-123",
            agentUPN: "toolagent@contoso.com",
            agentBlueprintId: "tool-blueprint-456",
            agentType: AgentType.EntraEmbodied,
            tenantId: "tenant-789"
        );

        var tenantDetails = new TenantDetails(Guid.Parse("11111111-2222-3333-4444-555555555555"));

        var endpoint = new Uri("https://toolagent.contoso.com:8443");

        var toolCallDetails = new ToolCallDetails(
            toolName: toolName,
            arguments: System.Text.Json.JsonSerializer.Serialize(parameters),
            toolCallId: Guid.NewGuid().ToString(),
            description: "Runs a tool operation.",
            toolType: "custom-type",
            endpoint: endpoint
        );

        // Start the scope
        using var scope = ExecuteToolScope.Start(
            toolCallDetails: toolCallDetails,
            agentDetails: agentDetails,
            tenantDetails: tenantDetails
        );

        // ... your tool logic here ...

        // Record response
        var toolOutput = $"Tool '{toolName}' processed with parameters: {System.Text.Json.JsonSerializer.Serialize(parameters)}";
        scope.RecordResponse(toolOutput);

        return new ToolResult { Output = toolOutput };
    }
}

public class ToolResult
{
    public string Output { get; set; }
}

Inferência

Os exemplos a seguir mostram como instrumentar chamadas de inferência de modelos de IA com rastreamento de observabilidade para capturar o uso de tokens, detalhes do modelo e metadados de resposta.

Python

from microsoft_agents_a365.observability.core.inference_scope import InferenceScope
from microsoft_agents_a365.observability.core.inference_call_details import InferenceCallDetails
from microsoft_agents_a365.observability.core.request import Request

inference_details = InferenceCallDetails(
    operationName=SomeEnumOrValue("chat"),
    model="gpt-4o-mini",
    providerName="azure-openai",
    inputTokens=123,
    outputTokens=456,
    finishReasons=["stop"],
    responseId="resp-987"
)
req = Request(content="Explain quantum computing simply.")

with InferenceScope.start(inference_details, agent_details, tenant_details, req):
    completion = call_llm(...)

JavaScript

import { InferenceScope, InferenceOperationType } from '@microsoft/agents-a365-observability';

const inferenceDetails = {
  operationName: InferenceOperationType.CHAT,
  model: 'gpt-4',
  providerName: 'openai',
  inputTokens: 150,
  outputTokens: 75,
  finishReasons: ['stop'],
  responseId: 'resp-123456'
};

using scope = InferenceScope.start(inferenceDetails, agentDetails, tenantDetails);

try {
  // Record input messages
  scope.recordInputMessages(['Summarize the following emails for me...']);
  
  // Call the LLM
  const response = await callLLM();
  
  // Record detailed telemetry with granular methods
  scope.recordOutputMessages(['Here is your email summary...']);
  scope.recordInputTokens(145);  // Update if different from constructor
  scope.recordOutputTokens(82);  // Update if different from constructor
  scope.recordResponseId('resp-789123');
  scope.recordFinishReasons(['stop', 'max_tokens']);
  
  return response.text;
} catch (error) {
  scope.recordError(error as Error);
  throw error;
}

.NET

using System;
using System.Threading.Tasks;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

public class MyInferenceAgent
{
    public async Task<InferenceResult> RunInference(string input)
    {
        var agentDetails = new AgentDetails(
            agentId: Guid.NewGuid().ToString(),
            agentName: "InferenceAgent",
            agentDescription: "Performs generative AI inference.",
            agentAUID: "inference-auid-123",
            agentUPN: "inferenceagent@contoso.com",
            agentBlueprintId: "inference-blueprint-456",
            agentType: AgentType.EntraEmbodied,
            tenantId: "tenant-789"
        );

        var tenantDetails = new TenantDetails(Guid.Parse("11111111-2222-3333-4444-555555555555"));

        var inferenceDetails = new InferenceCallDetails(
            operationName: InferenceOperationType.Chat,
            model: "gpt-4",
            providerName: "OpenAI",
            inputTokens: 42,
            outputTokens: 84,
            finishReasons: new[] { "stop", "length" },
            responseId: "response-xyz"
        );

        // Start the scope
        using var scope = InferenceScope.Start(
            details: inferenceDetails,
            agentDetails: agentDetails,
            tenantDetails: tenantDetails
        );

        // ... your inference logic here ...

        // Record input/output messages and other telemetry
        scope.RecordInputMessages(new[] { input, "additional context" });
        scope.RecordOutputMessages(new[] { "AI response message" });
        scope.RecordInputTokens(42);
        scope.RecordOutputTokens(84);
        scope.RecordResponseId("response-xyz");
        scope.RecordFinishReasons(new[] { "stop", "length" });
        scope.RecordThoughtProcess("Reasoning step 1; step 2");

        return new InferenceResult { Output = "AI response message" };
    }
}

public class InferenceResult
{
    public string Output { get; set; }
}

Validar localmente

Para verificar se você integrou com sucesso com o SDK de observabilidade, examine os logs do console gerados pelo seu agente.

Python

Defina a variável de ambiente ENABLE_A365_OBSERVABILITY_EXPORTER como false. Isso exporta os spans (traces) para o console.

JavaScript

Defina a variável de ambiente ENABLE_A365_OBSERVABILITY_EXPORTER como false. Isso exporta os spans (traces) para o console.

.NET

Definir EnableAgent365Exporter como false em appsettings.json. Isso exporta os spans (traces) para o console.

Registros de exemplo

Os troncos podem parecer um pouco diferentes dependendo da plataforma.

Log do console Invoke agent span

Este exemplo ilustra um típico intervalo de agente de invocação impresso pelo exportador do console quando a validação local está habilitada.

    {
    "name": "invoke_agent Azure OpenAI Agent",
    "context": {
        "trace_id": "0x4bd8f606688c3f3347d69c1b6539c957",
        "span_id": "0x0766d68605234692",
        "trace_state": "[]"
    },
    "kind": "SpanKind.CLIENT",
    "parent_id": null,
    "start_time": "2025-11-24T16:16:54.017403Z",
    "end_time": "2025-11-24T16:17:09.373357Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "operation.source": "SDK",
        "correlation.id": "aaaa0000-bb11-2222-33cc-444444dddddd",
        "gen_ai.conversation.item.link": "http://localhost:56150/_connector",
        "gen_ai.agent.upn": "Delivery Agent",
        "gen_ai.agent.user.id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
        "gen_ai.caller.id": "bbbbbbbb-cccc-dddd-2222-333333333333",
        "gen_ai.caller.name": "Alex Wilber",
        "gen_ai.caller.upn": "Sample UPN",
        "gen_ai.channel.name": "msteams",
        "gen_ai.system": "az.ai.agent365",
        "gen_ai.operation.name": "invoke_agent",
        "gen_ai.agent.id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
        "gen_ai.agent.name": "Azure OpenAI Agent",
        "gen_ai.agent.description": "An AI agent powered by Azure OpenAI",
        "gen_ai.agent.applicationid": "00001111-aaaa-2222-bbbb-3333cccc4444",
        "gen_ai.conversation.id": "__PERSONAL_CHAT_ID__",
        "tenant.id": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
        "session.id": "__PERSONAL_CHAT_ID__",
        "gen_ai.execution.type": "HumanToAgent",
        "gen_ai.input.messages": "[\"hi, what can you do\"]",
        "gen_ai.output.messages": "[\"Hi! I can assist you with a variety of tasks, including answering questions, providing information on a wide range of topics, helping with problem-solving, offering writing assistance, and more. Just let me know what you need help with!\"]"
    },
    "events": [],
    "links": [],
    "resource": {
        "attributes": {
            "telemetry.sdk.language": "python",
            "telemetry.sdk.name": "opentelemetry",
            "telemetry.sdk.version": "1.38.0",
            "service.namespace": "MyAgentTesting",
            "service.name": "MyAgentTracing"
        },
        "schema_url": ""
    }}

Log do console para a ferramenta de execução

Este exemplo mostra um intervalo típico de ferramenta de execução emitido pelo exportador do console durante a validação local.

{
    "name": "execute_tool get_weather",
    "context": {
        "trace_id": "0xa9a1be6323bd52476d6a28b8893c6aa8",
        "span_id": "0x1dec90d34ecc0823",
        "trace_state": "[]"
    },
    "kind": "SpanKind.INTERNAL",
    "parent_id": "0x2e727b4c133cbd50",
    "start_time": "2025-11-24T18:47:55.960305Z",
    "end_time": "2025-11-24T18:47:55.962306Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "operation.source": "SDK",
        "correlation.id": "aaaa0000-bb11-2222-33cc-444444dddddd",
        "gen_ai.conversation.item.link": "http://localhost:56150/_connector",
        "gen_ai.agent.upn": "Delivery Agent",
        "gen_ai.agent.user.id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
        "gen_ai.execution.type": "HumanToAgent",
        "gen_ai.channel.name": "msteams",
        "gen_ai.system": "az.ai.agent365",
        "gen_ai.operation.name": "execute_tool",
        "gen_ai.agent.id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
        "gen_ai.agent.name": "Azure OpenAI Agent",
        "gen_ai.agent.description": "An AI agent powered by Azure OpenAI",
        "gen_ai.agent.applicationid": "00001111-aaaa-2222-bbbb-3333cccc4444",
        "gen_ai.conversation.id": "__PERSONAL_CHAT_ID__",
        "tenant.id": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
        "gen_ai.tool.name": "get_weather",
        "gen_ai.tool.arguments": "current location",
        "gen_ai.tool.type": "function",
        "gen_ai.tool.call.id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "gen_ai.tool.description": "Executing get_weather tool"
    },
    "events": [],
    "links": [],
    "resource": {
        "attributes": {
            "telemetry.sdk.language": "python",
            "telemetry.sdk.name": "opentelemetry",
            "telemetry.sdk.version": "1.38.0",
            "service.namespace": "MyAgentTesting",
            "service.name": "MyAgentTracing"
        },
        "schema_url": ""
    }
}

Intervalo de inferência logarítmica do console

Este exemplo demonstra uma saída típica de intervalo de inferência do exportador de console usado para validação local.

{
    "name": "Chat gpt-4o-mini",
    "context": {
        "trace_id": "0xceb86559a6f7c2c16a45ec6e0b201ae1",
        "span_id": "0x475beec8c1c4fa56",
        "trace_state": "[]"
    },
    "kind": "SpanKind.CLIENT",
    "parent_id": "0x959a854f18fa2c22",
    "start_time": "2025-11-24T18:04:07.061703Z",
    "end_time": "2025-11-24T18:04:09.506951Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "operation.source": "SDK",
        "correlation.id": "aaaa0000-bb11-2222-33cc-444444dddddd",
        "gen_ai.conversation.item.link": "http://localhost:56150/_connector",
        "gen_ai.agent.upn": "Delivery Agent",
        "gen_ai.agent.user.id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
        "gen_ai.execution.type": "HumanToAgent",
        "gen_ai.channel.name": "msteams",
        "gen_ai.system": "az.ai.agent365",
        "gen_ai.agent.id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
        "gen_ai.agent.name": "Azure OpenAI Agent",
        "gen_ai.agent.description": "An AI agent powered by Azure OpenAI",
        "gen_ai.agent.applicationid": "00001111-aaaa-2222-bbbb-3333cccc4444",
        "gen_ai.conversation.id": "__PERSONAL_CHAT_ID__",
        "tenant.id": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
        "gen_ai.input.messages": "hi, what can you do",
        "gen_ai.operation.name": "Chat",
        "gen_ai.request.model": "gpt-4o-mini",
        "gen_ai.provider.name": "Azure OpenAI",
        "gen_ai.output.messages": "\"Hello! I can help answer questions, provide information, assist with problem-solving, offer writing suggestions, and more. Just let me know what you need!\"",
        "gen_ai.usage.input_tokens": "33",
        "gen_ai.usage.output_tokens": "32",
        "gen_ai.response.finish_reasons": "[\"stop\"]"
    },
    "events": [],
    "links": [],
    "resource": {
        "attributes": {
            "telemetry.sdk.language": "python",
            "telemetry.sdk.name": "opentelemetry",
            "telemetry.sdk.version": "1.38.0",
            "service.namespace": "MyAgentTesting",
            "service.name": "MyAgentTracing"
        },
        "schema_url": ""
    }
}

Requisitos de observabilidade

Administradores de TI usam os dados que você define no seu código para monitorar a atividade do seu agente. Dados incompletos significam que os benefícios da observabilidade não são totalmente realizados. Os agentes devem fornecer os dados necessários para receber todos os benefícios esperados. Um processo de validação verificará a existência desses dados.

Dentro da telemetria, existem conceitos de escopo ou contexto. Cada operação que seu agente realiza existe dentro de um escopo diferente. Os dados devem ser incluídos nos BaggageScope atributos criados usando bagagem, ou dentro dos escopos individuais conforme descrito em Instrumentação Manual.

Para validar sua implementação, siga as instruções para validar localmente e gerar logs de console para sua instrumentação. Depois, revise a seção [Validar para atributos exigidos](#validate-para-atributos requeridos) para identificar quais atributos são necessários e quais são opcionais. Todos os atributos exigidos devem ser definidos para passar com sucesso na validação.

Revise as propriedades e valores de parâmetros necessários descritos para essas classes:

Python

• Propriedades definidas usando a classe BaggageBuilder podem ser definidas ou sobrescrevidas pelas propriedades dos respectivos escopos.

• Defina as propriedades na tabela a seguir usando o método InvokeAgentScope.start.

  Dados	Description
  invoke_agent_details.details.agent_id	O identificador exclusivo para o agente de IA
  invoke_agent_details.details.agent_name	O nome legível pelo ser humano do agente de IA
  invoke_agent_details.details.agent_auid	A ID do usuário do agente (AUID)
  invoke_agent_details.details.agent_upn	O nome da entidade de usuário do agente (UPN)
  invoke_agent_details.details.agent_blueprint_id	A ID do blueprint/aplicativo do agente
  invoke_agent_details.details.tenant_id	A ID do locatário do agente
  invoke_agent_details.details.conversation_id	O identificador da conversa ou sessão
  invoke_agent_details.endpoint	O ponto de extremidade para a invocação do agente
  tenant_details.tenant_id	O identificador exclusivo para o locatário
  request.content	O conteúdo da carga útil enviado ao agente para invocação
  request.execution_type	Tipo de invocação indicando a origem da solicitação (por exemplo, HumanToAgent ou AgentToAgent)
  caller_details.caller_id	O identificador exclusivo para o chamador
  caller_details.caller_upn	O UPN (nome da entidade de usuário) do chamador
  caller_details.caller_user_id	A ID do usuário do chamador
  caller_details.tenant_id	A ID do locatário do chamador

• Defina as propriedades na tabela seguinte usando o método ExecuteToolScope.start.

  Dados	Description
  details.tool_name	O nome da ferramenta que está sendo executada
  details.arguments	Argumentos/parâmetros da ferramenta
  details.tool_call_id	O identificador exclusivo para a chamada de ferramenta
  details.tool_type	O tipo da ferramenta que está sendo executada
  details.endpoint	Se uma chamada de ferramenta externa for feita
  agent_details.agent_id	O identificador exclusivo para o agente de IA
  agent_details.agent_name	O nome legível pelo ser humano do agente de IA
  agent_details.agent_auid	O ID de usuário do agente
  agent_details.agent_upn	O nome da entidade de usuário do agente (UPN)
  agent_details.agent_blueprint_id	A ID do blueprint/aplicativo do agente
  agent_details.tenant_id	ID de inquilino do corretor.
  agent_details.conversation_id	O ID da conversa para a invocação do agente.
  tenant_details.tenant_id	ID de inquilino do corretor.

• Defina as propriedades na tabela a seguir usando o método InferenceScope.start.

  Dados	Description
  details.operationName	O nome/tipo da operação para a inferência
  details.model	O nome/identificador do modelo
  details.providerName	Nome do provedor
  agent_details.agent_id	O identificador exclusivo para o agente de IA
  agent_details.agent_name	O nome legível pelo ser humano do agente de IA
  agent_details.agent_auid	A ID do usuário do agente (AUID)
  agent_details.agent_upn	O nome da entidade de usuário do agente (UPN)
  agent_details.agent_blueprint_id	A ID do blueprint/aplicativo do agente
  agent_details.tenant_id	O identificador exclusivo para o locatário
  agent_details.conversation_id	O identificador da conversa ou sessão
  tenant_details.tenant_id	O identificador exclusivo para o locatário
  request.content	O conteúdo da carga útil enviado ao agente para inferência
  request.execution_type	Tipo de invocação indicando a origem da solicitação (por exemplo, HumanToAgent ou AgentToAgent)
  request.source_metadata	Represente as informações do canal

JavaScript

• Propriedades definidas usando a classe BaggageBuilder podem ser definidas ou sobrescrevidas pelas propriedades dos respectivos escopos.

• Defina as propriedades na tabela a seguir usando o método InvokeAgentScope.start.

  Dados	Description
  invokeAgentDetails.agentAUID	A ID do usuário do agente (AUID)
  invokeAgentDetails.agentBlueprintId	A ID do blueprint/aplicativo do agente
  invokeAgentDetails.agentId	O identificador exclusivo para o agente de IA
  invokeAgentDetails.agentName	O nome legível pelo ser humano do agente de IA
  invokeAgentDetails.agentUPN	O nome da entidade de usuário do agente (UPN)
  invokeAgentDetails.conversationId	O identificador da conversa ou sessão
  invokeAgentDetails.endpoint.host	O endereço do host do endpoint para a invocação do agente
  invokeAgentDetails.endpoint.port	O número da porta do endpoint para a invocação do agente
  invokeAgentDetails.endpoint.protocol	O ponto final do protocolo para a invocação do agente
  invokeAgentDetails.request.content	O conteúdo da carga útil de requisição para a invocação do agente
  invokeAgentDetails.request.executionType	O tipo de invocação da carga útil de requisição para a invocação do agente
  invokeAgentDetails.request.sourceMetadata.name	Canalize informações como (msteams, email, e assim por diante)
  invokeAgentDetails.tenantId	A ID do locatário do agente
  tenantDetails.tenantId	O identificador exclusivo para o locatário
  callerDetails.callerId	O identificador único para o chamador (aadObjectId)
  callerDetails.callerName	O nome de exibição do chamador
  callerDetails.callerUpn	O UPN (nome da entidade de usuário) do chamador
  callerDetails.tenantId	A ID do locatário do chamador

• Defina as propriedades na tabela seguinte usando o método ExecuteToolScope.start.

  Dados	Description
  details.arguments	Argumentos/parâmetros da ferramenta
  details.endpoint.host	O endereço host do endpoint para a execução da ferramenta. É obrigatório se for feita uma chamada externa
  details.endpoint.port	O número da porta do endpoint para a execução da ferramenta. É obrigatório se for feita uma chamada externa
  details.endpoint.protocol	O protocolo do endpoint para a execução da ferramenta. É obrigatório se for feita uma chamada externa
  details.toolCallId	O identificador exclusivo para a chamada de ferramenta
  details.toolName	O nome da ferramenta que está sendo executada
  details.toolType	O tipo da ferramenta que está sendo executada
  agentDetails.agentId	O identificador exclusivo para o agente de IA
  agentDetails.agentName	O nome legível pelo ser humano do agente de IA
  agentDetails.conversationId	O identificador da conversa ou sessão
  tenantDetails.tenantId	O identificador exclusivo para o locatário

• Defina as propriedades na tabela a seguir usando o método InferenceScope.start.

  Dados	Description
  details.model	O nome/identificador do modelo
  details.operationName	O nome/tipo da operação para a inferência
  details.providerName	Nome do provedor
  agentDetails.agentId	O identificador exclusivo para o agente de IA
  agentDetails.agentName	O nome legível pelo ser humano do agente de IA
  agentDetails.conversationId	O identificador da conversa ou sessão
  tenantDetails.tenantId	O identificador exclusivo para o locatário

.NET

• Propriedades definidas usando a classe BaggageBuilder podem ser definidas ou sobrescrevidas pelas propriedades dos respectivos escopos.

• Defina as propriedades na tabela a seguir usando o método InvokeAgentScope.Start.

  Dados	Description
  invokeAgentDetails.details.agentId	O identificador exclusivo do agente.
  invokeAgentDetails.details.agentName	Nome de exibição do agente.
  invokeAgentDetails.details.agentAUID	Azure User ID (AUID) para o agente.
  invokeAgentDetails.details.agentUPN	Nome Principal do Usuário (UPN) para o agente.
  invokeAgentDetails.details.agentBlueprintId	Projeto/ID de aplicação para o agente.
  invokeAgentDetails.details.tenantId	ID de inquilino do corretor.
  invokeAgentDetails.endpoint	URI do endpoint do agente a ser invocado.
  tenantDetails.tenantId	O identificador do inquilino.
  request.content	O conteúdo da carga útil fornecido ao agente.
  request.executionType	Tipo de execução que descreve a solicitação.
  request.sourceMetadata.name	Nome legível para humanos da fonte. Nome do canal.
  conversationId	O ID da conversa para a invocação do agente.

• Defina as propriedades na tabela a seguir usando o método ExecuteToolScope.Start.

  Dados	Description
  details.toolName	Nome da ferramenta que está sendo invocada.
  details.arguments	Argumentos serializados eram passados para a ferramenta.
  details.toolCallId	Identificador para a invocação da ferramenta.
  details.toolType	Classificação de tipos para a ferramenta.
  details.endpoint	Endpoint necessário para execução remota de ferramentas.
  agentDetails.agentId	O identificador exclusivo do agente.
  agentDetails.agentName	Nome de exibição do agente.
  agentDetails.agentAUID	Azure User ID (AUID) para o agente.
  agentDetails.agentUPN	Nome Principal do Usuário (UPN) para o agente.
  agentDetails.agentBlueprintId	Projeto/ID de aplicação para o agente.
  agentDetails.tenantId	ID de inquilino do corretor.
  tenantDetails.tenantId	O identificador do inquilino.

• Defina as propriedades na tabela a seguir usando o método InferenceScope.Start.

  Dados	Description
  details.operationName	Identificador de telemetria para a operação de inferência.
  details.model	Nome do modelo usado para satisfazer o pedido de inferência.
  details.providerName	O provedor responsável pela chamada de inferência.
  agentDetails.agentId	O identificador exclusivo do agente.
  agentDetails.agentName	Nome de exibição do agente.
  agentDetails.agentAUID	Azure User ID (AUID) para o agente.
  agentDetails.agentUPN	Nome Principal do Usuário (UPN) para o agente.
  agentDetails.agentBlueprintId	Projeto/ID de aplicação para o agente.
  agentDetails.tenantId	ID de inquilino do corretor.
  tenantDetails.tenantId	O identificador do inquilino.
  parentId	Para gerenciamento explícito do escopo dos pais. Não é obrigatório na maioria dos casos.

Validar para publicação em lojas

Use logs de console para validar sua integração de observabilidade para o agente antes de publicar, implementando o invoke agent, a ferramenta de execução e os escopos de inferência necessários. Depois, compare os registros do seu agente com as seguintes listas de atributos para verificar se todos os atributos necessários estão presentes; Capture atributos em cada mira ou pelo construtor de bagagem, e inclua atributos opcionais a seu critério.

Para mais informações sobre os requisitos de publicação em loja, consulte as diretrizes de validação da loja.

Atributos InvokeAgentScope

A lista a seguir resume os atributos de telemetria necessários e opcionais registrados quando você inicia um InvokeAgentScope.

"attributes": {
        "correlation.id": "Optional",
        "gen_ai.agent.applicationid": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "gen_ai.agent.thought.process": "Optional",
        "gen_ai.agent.upn": "Required",
        "gen_ai.agent.user.id": "Required",
        "gen_ai.caller.agent.applicationid": "Required (if execution type is agent to agent)",
        "gen_ai.caller.agent.id": "Required (if execution type is agent to agent)",
        "gen_ai.caller.agent.name": "Required (if execution type is agent to agent)",
        "gen_ai.caller.client.ip": "Required",
        "gen_ai.caller.id": "Required",
        "gen_ai.caller.name": "Optional",
        "gen_ai.caller.upn": "Required",
        "gen_ai.channel.link": "Optional",
        "gen_ai.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "gen_ai.conversation.item.link": "Optional",
        "gen_ai.execution.type": "Required",
        "gen_ai.input.messages": "Required",
        "gen_ai.operation.name": "Required (Set by the SDK)",
        "gen_ai.output.messages": "Required",
        "gen_ai.system": "Optional",
        "hiring.manager.id": "Optional",
        "operation.source": "Required (SDK sets a default value)",
        "server.address": "Required",
        "server.port": "Required",
        "session.id": "Optional",
        "session.description": "Optional",
        "tenant.id": "Required"
    },

Atributos ExecuteToolScope

A lista a seguir resume os atributos de telemetria necessários e opcionais registrados quando você inicia um ExecuteToolScope.

"attributes": {
        "correlation.id": "Optional",
        "gen_ai.agent.applicationid": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "gen_ai.agent.upn": "Required",
        "gen_ai.agent.user.id": "Required",
        "gen_ai.caller.client.ip": "Required",
        "gen_ai.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "gen_ai.conversation.item.link": "Optional",
        "gen_ai.execution.type": "HumanToAgent",
        "gen_ai.operation.name": "Required (Set by the SDK)",
        "gen_ai.system": "Optional",
        "gen_ai.tool.arguments": "Required",
        "gen_ai.tool.call.id": "Required",
        "gen_ai.tool.description": "Optional",
        "gen_ai.tool.name": "Required",
        "gen_ai.tool.type": "Required",
        "operation.source": "Required (SDK sets a default value)",
        "server.address": "Required (if tool call is external)",
        "server.port": "Required (if tool call is external)",
        "session.id": "Optional",
        "session.description": "Optional",
        "tenant.id": "Required"
    },

Atributos InferenceScope

A lista a seguir resume os atributos de telemetria necessários e opcionais registrados quando você inicia um InferenceScope.

"attributes": {
        "correlation.id": "Optional",
        "gen_ai.agent.applicationid": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "gen_ai.agent.thought.process": "Optional",
        "gen_ai.agent.upn": "Required",
        "gen_ai.agent.user.id": "Required",
        "gen_ai.caller.client.ip": "Required",
        "gen_ai.channel.link": "Optional",
        "gen_ai.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "gen_ai.conversation.item.link": "Optional",
        "gen_ai.execution.type": "Required",
        "gen_ai.input.messages": "Required",
        "gen_ai.operation.name": "Chat",
        "gen_ai.output.messages": "Required",
        "gen_ai.provider.name": "Required",
        "gen_ai.request.model": "Required",
        "gen_ai.response.finish_reasons": "Optional",
        "gen_ai.usage.input_tokens": "Optional",
        "gen_ai.usage.output_tokens": "Optional",
        "hiring.manager.id": "Optional",
        "operation.source": "Required (SDK sets a default value)",
        "session.description": "Optional",
        "session.id": "Optional",
        "tenant.id": "Required"
    }

Teste seu agente com observabilidade

Depois de implementar a observabilidade no seu agente, teste para garantir que a telemetria está sendo capturada corretamente. Siga o guia de testes para configurar seu ambiente e então foque principalmente na seção Visualizar logs de observabilidade para validar que sua implementação de observabilidade está funcionando como esperado.