Observabilidad del agente

Importante

Debe formar parte del programa de versión preliminar Frontier para obtener acceso anticipado a Microsoft Agent 365. Frontier le conecta directamente con las innovaciones de inteligencia artificial más recientes de Microsoft. Las versiones preliminares de Frontier están sujetas a los términos de vista previa existentes en tus acuerdos con clientes. Dado que estas características siguen en desarrollo, su disponibilidad y funcionalidades pueden cambiar con el tiempo.

Para participar en el ecosistema de Agent 365, añade capacidades de observabilidad de Agent 365 a tu agente. Agent 365 Observability se basa en OpenTelemetry (OTel) y proporciona un marco unificado para capturar telemetría de forma coherente y segura en todas las plataformas de agentes. Al implementar este componente requerido, permites a los administradores de TI monitorizar la actividad de tu agente en el centro de administración de Microsoft y permites que los equipos de seguridad utilicen Defender y Purview para el cumplimiento normativo y la detección de amenazas.

Beneficios clave

• Visibilidad de extremo a extremo: Captura una telemetría completa para cada invocación de agente, incluyendo sesiones, llamadas a herramientas y excepciones, dándote trazabilidad total entre plataformas.
• Seguridad y habilitación de cumplimiento: Introduce registros de auditoría unificados en Defender y Purview, habilitando escenarios de seguridad avanzados e informes de cumplimiento para tu agente.
• Flexibilidad multiplataforma: Basarse en los estándares de OTel y dar soporte a diversos entornos de ejecución y plataformas como Copilot Studio, Foundry y futuros marcos de agente.
• Eficiencia operativa para administradores: Proporcionar observabilidad centralizada en el centro de administración de Microsoft 365, reduciendo el tiempo de resolución de problemas y optimizando la gobernanza con controles de acceso basados en roles para los equipos de TI que gestionan su agente.

Instalación

Use estos comandos para instalar los módulos de observabilidad para los idiomas admitidos por Agent 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

Configuración

Utiliza las siguientes configuraciones para habilitar y personalizar la observabilidad del Agente 365 para tu agente.

Python

Establece la ENABLE_A365_OBSERVABILITY_EXPORTER variable de entorno en true para observabilidad. Esta configuración exporta los registros al servicio. En caso contrario, se utiliza el exportador de consola.

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,
)

El resolutor de tokens está excluido del registro en la consola.

JavaScript

Establece la ENABLE_A365_OBSERVABILITY_EXPORTER variable de entorno en true para observabilidad. Esta configuración exporta los registros al servicio. En caso contrario, se utiliza el exportador de consola.

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();

Como alternativa a las variables de entorno, puedes configurar la observabilidad de forma programática usando un proveedor de configuración.

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

const configProvider = new ObservabilityConfiguration({
  isObservabilityExporterEnabled: () => true,
  // Set log levels as pipe-separated values (for example, 'info|warn|error')
  observabilityLogLevel: () => 'info|warn|error',
});

const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withConfigurationProvider(configProvider)
    .withTokenResolver((agentId, tenantId) => {
      return tokenResolver(agentId, tenantId);
    })
);

builder.start();

También puedes proporcionar un registrador personalizado que implemente la ILogger interfaz (info, warn, error, event). Pásalo al constructor usando withCustomLogger.

const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withCustomLogger({
      info: (message, ...args) => { /* your logging logic */ },
      warn: (message, ...args) => { /* your logging logic */ },
      error: (message, ...args) => { /* your logging logic */ },
      event: (eventName, success, durationMs, message, details) => { /* your logging logic */ }
    })
    .withTokenResolver((agentId, tenantId) => {
      return tokenResolver(agentId, tenantId);
    })
);

builder.start();

.NET

Establezca EnableAgent365Exporter en trueappsettings.json.

En Program.cs, agregue Agent365ExporterOptions a la colección de servicios. Este cambio configura el delegado que usa el exportador de seguimiento para recuperar el token.

Añadir dependencias relacionadas con la observabilidad 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 equipaje

Use BaggageBuilder para establecer información contextual que fluye a través de todos los intervalos de una solicitud. El SDK implementa un SpanProcessor que copia todos los elementos de contexto no vacíos a tramos recién iniciados sin modificar los atributos ya presentes.

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.

Resolutor de Tokens

Al usar el exportador de Agent 365, debe proporcionar una función de resolución de tokens que devuelva el token de autenticación. Al usar el SDK de Observabilidad de Agent 365 con el framework de alojamiento del agente, puede generar tokens usando TurnContext de las actividades del agente.

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

Agregue el solucionador de tokens agenticos a la colección de servicios.

using Microsoft.Agents.A365.Observability;

builder.Services.AddAgenticTracingExporter();

En la aplicación del agente, registre el 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}");
        }
    }
}

Instrumentación automática

La instrumentación automática escucha automáticamente las señales de telemetría existentes de marcos de agente (SDK) para seguimientos y las reenvía al servicio de observabilidad de Agent 365. Esta función elimina la necesidad de que los desarrolladores escriban código de monitorización manualmente, simplifica la configuración y garantiza un seguimiento consistente del rendimiento.

Múltiples SDKs y plataformas soportan auto-instrumentación:

Plataforma	SDK y frameworks admitidos
.NET	Semantic Kernel, OpenAI, Agent Framework
Python	Semantic Kernel, OpenAI, Agent Framework, LangChain
Node.js	OpenAI, LangChain

Nota

La compatibilidad con la instrumentación automática varía según la plataforma y la implementación del SDK.

Semantic Kernel

La instrumentación automática requiere el uso del generador de equipaje. Establece el ID del agente y el ID del tenant usando BaggageBuilder.

Python

Instale el paquete .

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

Configure la observabilidad.

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 no es compatible con JavaScript.

.NET

Agregue dependencias a la colección de servicios.

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

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

Establece AgentId y TenantId usando BaggageBuilder. Asegúrate de que el ID que usas al crear un ChatCompletionAgent coincida con el ID de agente que pasas a 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

La instrumentación automática requiere el uso del generador de equipaje. Establece el ID del agente y el ID del tenant usando BaggageBuilder.

Python

Instale el paquete .

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

Configure la observabilidad.

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

Instale el paquete .

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

Configure la observabilidad.

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

Agregue dependencias a la colección de servicios.

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

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

Establece AgentId y TenantId usando BaggageBuilder. Para llamadas a herramientas, inicia una traza usando Trace() en una instancia ChatToolCall.

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>);
    }
}

Marco de trabajo del agente

La instrumentación automática requiere el uso del generador de equipaje. Establece el ID del agente y el ID del tenant usando BaggageBuilder.

Python

Instale el paquete .

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

Configure la observabilidad.

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

El Agent Framework no es compatible con JavaScript.

.NET

Agregue dependencias a la colección de servicios.

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

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

Establece AgentId y TenantId usando 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();
    }
}

Marco de LangChain

La instrumentación automática requiere el uso del constructor de contenedores. Establece el ID del agente y el ID del tenant usando BaggageBuilder.

Python

Instale el paquete .

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

Configure la observabilidad.

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

JavaScript

Instale el paquete .

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

Configure la observabilidad.

import { ObservabilityManager } from '@microsoft/agents-a365-observability';
import { LangChainTraceInstrumentor } from '@microsoft/agents-a365-observability-extensions-langchain';
import * as LangChainCallbacks from '@langchain/core/callbacks/manager';

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

sdk.start();

// Enable LangChain auto-instrumentation
LangChainTraceInstrumentor.instrument(LangChainCallbacks);

// Your LangChain code is now automatically traced

.NET

LangChain no es compatible con .NET.

Instrumentación manual

Utiliza el SDK de observabilidad del Agente 365 para entender el funcionamiento interno del agente. El SDK proporciona tres ámbitos que puedes iniciar: InvokeAgentScope, ExecuteToolScope, y InferenceScope.

Invocación del agente

Utiliza este ámbito al inicio de tu proceso de agente. Utilizando el ámbito del agente invocado, puedes capturar propiedades como el agente actual que se está invocando, los datos del usuario y más.

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; }
}

Ejecución de herramientas

Los siguientes ejemplos muestran cómo añadir monitorización de observabilidad a la ejecución de herramientas por parte de su agente. Este seguimiento captura la telemetría para fines de monitorización y auditoría.

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; }
}

Inferencia

En los ejemplos siguientes se muestra cómo instrumentar llamadas de inferencia del modelo de IA con seguimiento de observabilidad para capturar el uso de tokens, los detalles del modelo y los metadatos de respuesta.

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 que has integrado correctamente con el SDK de observabilidad, examina los registros de consola generados por tu agente.

Python

Establezca la variable de entorno ENABLE_A365_OBSERVABILITY_EXPORTER en false. Esta configuración exporta los spans (trazas) directamente a la consola.

JavaScript

Establezca la variable de entorno ENABLE_A365_OBSERVABILITY_EXPORTER en false. Esta configuración exporta los spans (trazas) directamente a la consola.

.NET

Establezca EnableAgent365Exporter en falseappsettings.json. Esta configuración exporta los spans (trazas) a la consola.

Registros de muestra

Los registros podrían verse ligeramente diferentes según la plataforma.

Log de consola Invoke agent span

Este ejemplo muestra un intervalo típico de invocación de agente que el exportador de consola imprime cuando se habilita la validación local.

    {
    "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": ""
    }}

Registro de consola para la herramienta de ejecución

Este ejemplo muestra un intervalo típico de herramienta de ejecución que el exportador de consola emite durante la validación 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 inferencia logarítmica en consola

Este ejemplo muestra un intervalo de inferencia típico que el exportador de consola genera para validación 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 observabilidad

Los administradores de TI utilizan los datos que estableces en tu código para monitorizar la actividad de tu agente. Datos incompletos significan que no se comprenden plenamente los beneficios de la observabilidad. Los agentes deben proporcionar los datos necesarios para recibir todos los beneficios esperados. Un proceso de validación verifica que estos datos existen.

Dentro de la telemetría, existen conceptos de alcance o contexto. Cada operación que realiza tu agente existe dentro de un ámbito diferente. Debes incluir los datos dentro de BaggageScope creados usando atributos de Baggage, o dentro de los ámbitos individuales descritos en Instrumentación Manual.

Para validar tu implementación, sigue las instrucciones para validar localmente y generar registros de consola para tu instrumentación. Luego revisa la sección Validar para publicación en tienda para identificar qué atributos se requieren y cuáles son opcionales. Debes establecer todos los atributos requeridos para superar con éxito la validación.

Revisa las propiedades requeridas y los valores de parámetros descritos para estas clases:

Python

• Las propiedades que configuras usando la clase BaggageBuilder pueden ser configuradas o anuladas por las propiedades de los respectivos ámbitos.

• Establezca las propiedades en la siguiente tabla usando el método InvokeAgentScope.start.

  Data	Descripción
  invoke_agent_details.details.agent_id	Identificador único para el agente de IA
  invoke_agent_details.details.agent_name	El nombre comprensible del agente de IA
  invoke_agent_details.details.agent_auid	Identificador de usuario del agente (AUID)
  invoke_agent_details.details.agent_upn	El nombre principal de usuario del agente (UPN)
  invoke_agent_details.details.agent_blueprint_id	El plano técnico del agente o el identificador de aplicación
  invoke_agent_details.details.tenant_id	Identificador de arrendatario del agente
  invoke_agent_details.details.conversation_id	Identificador de la conversación o sesión
  invoke_agent_details.endpoint	Punto final para la invocación del agente
  tenant_details.tenant_id	Identificador único del inquilino
  request.content	El contenido de la carga útil enviado al agente para su invocación
  request.execution_type	Tipo de invocación que indica el origen de la solicitud (por ejemplo, HumanToAgent o AgentToAgent)
  caller_details.caller_id	Identificador único del autor de la llamada
  caller_details.caller_upn	Nombre principal de usuario (UPN) del autor de la llamada
  caller_details.caller_user_id	Identificador de usuario del autor de la llamada
  caller_details.tenant_id	Identificador de inquilino del autor de la llamada

• Establezca las propiedades en la siguiente tabla usando el método ExecuteToolScope.start.

  Data	Descripción
  details.tool_name	Nombre de la herramienta que se está ejecutando
  details.arguments	Argumentos o parámetros de herramientas
  details.tool_call_id	El identificador único para la invocación de la herramienta
  details.tool_type	Tipo de la herramienta que se está ejecutando
  details.endpoint	Si se realiza una llamada a una herramienta externa
  agent_details.agent_id	Identificador único para el agente de IA
  agent_details.agent_name	El nombre comprensible del agente de IA
  agent_details.agent_auid	El ID de usuario del agente
  agent_details.agent_upn	El nombre principal de usuario del agente (UPN)
  agent_details.agent_blueprint_id	El esquema del agente o ID de aplicación
  agent_details.tenant_id	Identificación de inquilino del agente.
  agent_details.conversation_id	El ID de conversación para la invocación del agente.
  tenant_details.tenant_id	Identificación de inquilino del agente.

• Establezca las propiedades en la siguiente tabla usando el método InferenceScope.start.

  Data	Descripción
  details.operationName	El nombre o tipo de operación para la inferencia
  details.model	El nombre o identificador del modelo
  details.providerName	El nombre del proveedor
  agent_details.agent_id	Identificador único para el agente de IA
  agent_details.agent_name	El nombre comprensible del agente de IA
  agent_details.agent_auid	Identificador de usuario del agente (AUID)
  agent_details.agent_upn	El nombre principal de usuario del agente (UPN)
  agent_details.agent_blueprint_id	El esquema del agente o ID de aplicación
  agent_details.tenant_id	Identificador único del inquilino
  agent_details.conversation_id	Identificador de la conversación o sesión
  tenant_details.tenant_id	Identificador único del inquilino
  request.content	El contenido de la carga útil enviado al agente para la inferencia
  request.execution_type	Tipo de invocación que indica el origen de la solicitud (por ejemplo, HumanToAgent o AgentToAgent)
  request.source_metadata	Representa la información del canal

JavaScript

• Las propiedades que estableces usando la clase BaggageBuilder pueden ser establecidas o anuladas por las propiedades de los respectivos ámbitos.

• Establezca las propiedades en la siguiente tabla usando el método InvokeAgentScope.start.

  Data	Descripción
  invokeAgentDetails.agentAUID	Identificador de usuario del agente (AUID)
  invokeAgentDetails.agentBlueprintId	El plano técnico del agente o el identificador de aplicación
  invokeAgentDetails.agentId	Identificador único para el agente de IA
  invokeAgentDetails.agentName	El nombre comprensible del agente de IA
  invokeAgentDetails.agentUPN	El nombre principal de usuario del agente (UPN)
  invokeAgentDetails.conversationId	Identificador de la conversación o sesión
  invokeAgentDetails.endpoint.host	La dirección del host del endpoint para la invocación del agente
  invokeAgentDetails.endpoint.port	El número de puerto del punto final para la invocación del agente
  invokeAgentDetails.endpoint.protocol	El punto final del protocolo para la invocación del agente
  invokeAgentDetails.request.content	El contenido de la carga útil de la solicitud para la invocación del agente
  invokeAgentDetails.request.executionType	El tipo de invocación de la carga útil de solicitud para la invocación del agente
  invokeAgentDetails.request.sourceMetadata.name	Canaliza información como (msteams, email, y así sucesivamente)
  invokeAgentDetails.tenantId	Identificador de arrendatario del agente
  tenantDetails.tenantId	Identificador único del inquilino
  callerDetails.callerId	El identificador único para el llamante (aadObjectId)
  callerDetails.callerName	El nombre que se muestra de la persona que llama
  callerDetails.callerUpn	Nombre principal de usuario (UPN) del autor de la llamada
  callerDetails.tenantId	Identificador de inquilino del autor de la llamada

• Establezca las propiedades en la siguiente tabla usando el método ExecuteToolScope.start.

  Data	Descripción
  details.arguments	Argumentos o parámetros de herramientas
  details.endpoint.host	La dirección del host del endpoint para la ejecución de la herramienta. Obligatorio si se realiza una llamada externa
  details.endpoint.port	El número de puerto del endpoint para la ejecución de la herramienta. Obligatorio si se realiza una llamada externa
  details.endpoint.protocol	El protocolo del endpoint para la ejecución de la herramienta. Obligatorio si se realiza una llamada externa
  details.toolCallId	El identificador único para la invocación de la herramienta
  details.toolName	Nombre de la herramienta que se está ejecutando
  details.toolType	Tipo de la herramienta que se está ejecutando
  agentDetails.agentId	Identificador único para el agente de IA
  agentDetails.agentName	El nombre comprensible del agente de IA
  agentDetails.conversationId	Identificador de la conversación o sesión
  tenantDetails.tenantId	Identificador único del inquilino

• Establezca las propiedades en la siguiente tabla usando el método InferenceScope.start.

  Data	Descripción
  details.model	El nombre o identificador del modelo
  details.operationName	El nombre o tipo de operación para la inferencia
  details.providerName	El nombre del proveedor
  agentDetails.agentId	Identificador único para el agente de IA
  agentDetails.agentName	El nombre comprensible del agente de IA
  agentDetails.conversationId	Identificador de la conversación o sesión
  tenantDetails.tenantId	Identificador único del inquilino

.NET

• Las propiedades que estableces usando la clase BaggageBuilder pueden ser establecidas o anuladas por las propiedades de los respectivos ámbitos.

• Establezca las propiedades en la siguiente tabla usando el método InvokeAgentScope.Start.

  Data	Descripción
  invokeAgentDetails.details.agentId	Identificador único del agente.
  invokeAgentDetails.details.agentName	Muestra el nombre del agente.
  invokeAgentDetails.details.agentAUID	Azure id. de usuario (AUID) para el agente.
  invokeAgentDetails.details.agentUPN	Nombre principal de usuario (UPN) para el agente.
  invokeAgentDetails.details.agentBlueprintId	Plano o ID de solicitud para el agente.
  invokeAgentDetails.details.tenantId	Identificación de inquilino del agente.
  invokeAgentDetails.endpoint	URI del endpoint del agente a invocar.
  tenantDetails.tenantId	El identificador del inquilino.
  request.content	El contenido de la carga útil se suministra al agente.
  request.executionType	Tipo de ejecución que describe la solicitud.
  request.sourceMetadata.name	Nombre en lenguaje humano de la fuente. Nombre del canal.
  conversationId	El ID de conversación para la invocación del agente.

• Establezca las propiedades en la siguiente tabla usando el método ExecuteToolScope.Start.

  Data	Descripción
  details.toolName	Nombre de la herramienta que se está invocando.
  details.arguments	Los argumentos serializados pasan a la herramienta.
  details.toolCallId	Identificador para la invocación de herramientas.
  details.toolType	Clasificación de tipos para la herramienta.
  details.endpoint	Endpoint necesario para la ejecución remota de herramientas.
  agentDetails.agentId	Identificador único del agente.
  agentDetails.agentName	Muestra el nombre del agente.
  agentDetails.agentAUID	Azure id. de usuario (AUID) para el agente.
  agentDetails.agentUPN	Nombre principal de usuario (UPN) para el agente.
  agentDetails.agentBlueprintId	Plano o ID de solicitud para el agente.
  agentDetails.tenantId	Identificación de inquilino del agente.
  tenantDetails.tenantId	El identificador del inquilino.

• Establezca las propiedades en la siguiente tabla usando el método InferenceScope.Start.

  Data	Descripción
  details.operationName	Identificador de telemetría para la operación de inferencia.
  details.model	Nombre del modelo utilizado para satisfacer la solicitud de inferencia.
  details.providerName	Proveedor responsable de la llamada de inferencia.
  agentDetails.agentId	Identificador único del agente.
  agentDetails.agentName	Muestra el nombre del agente.
  agentDetails.agentAUID	Azure id. de usuario (AUID) para el agente.
  agentDetails.agentUPN	Nombre principal de usuario (UPN) para el agente.
  agentDetails.agentBlueprintId	Plano o ID de solicitud para el agente.
  agentDetails.tenantId	Identificación de inquilino del agente.
  tenantDetails.tenantId	El identificador del inquilino.
  parentId	Para la gestión explícita del ámbito parental. No es obligatorio en la mayoría de los casos.

Validar para la publicación en la tienda

Antes de publicar, utiliza los registros de consola para validar la integración de observabilidad del agente implementando los ámbitos requeridos de invocar agente, herramienta de ejecución e inferencia. Luego compara los registros de tu agente con las siguientes listas de atributos para verificar que todos los atributos requeridos estén presentes. Captura atributos en cada ámbito o a través del constructor de contexto, e incluye atributos opcionales según tu criterio.

Para más información sobre los requisitos de publicación en tiendas, consulte las directrices de validación de tiendas.

Atributos InvokeAgentScope

La siguiente lista resume los atributos de telemetría necesarios y opcionales registrados al iniciar un 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.platformid": "Optional",
        "gen_ai.agent.type": "Optional",
        "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.agent.platformid": "Optional",
        "gen_ai.caller.agent.type": "Optional",
        "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

La siguiente lista resume los atributos de telemetría necesarios y opcionales registrados al iniciar un 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.platformid": "Optional",
        "gen_ai.agent.type": "Optional",
        "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": "Optional",
        "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",
        "hiring.manager.id": "Optional",        
        "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 de InferenceScope

La siguiente lista resume los atributos de telemetría necesarios y opcionales registrados al iniciar un 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.platformid": "Optional",
        "gen_ai.agent.type": "Optional",
        "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": "Optional",
        "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"
    }

Prueba tu agente con observabilidad

Después de implementar la observabilidad en tu agente, prueba que la telemetría se captura correctamente. Sigue la guía de pruebas para configurar tu entorno. Luego céntrate principalmente en la sección Ver registros de observabilidad para validar que tu implementación de observabilidad está funcionando como se espera.

Comprobación:

• Vaya a: https://admin.cloud.microsoft/#/agents/all
• Selecciona tu agente > Actividad
• Deberías ver las sesiones y las llamadas de herramientas

Solución de problemas

Esta sección describe problemas comunes al implementar y utilizar la observabilidad.

Sugerencia

La Guía de Resolución de Problemas del Agente 365 contiene recomendaciones de alto nivel para la solución de problemas, mejores prácticas y enlaces a contenido de solución de problemas para cada parte del ciclo de vida del desarrollo del Agente 365.

Los datos de observabilidad no aparecen

Síntomas:

• El agente está huyendo
• No hay telemetría en el centro de administración
• No se puede ver la actividad de los agentes

Causa principal:

• La observabilidad no está habilitada
• Errores de configuración
• Problemas con la resolución de tokens

Soluciones: Prueba los siguientes pasos para resolver el problema:

• Verificar que la observabilidad esté activada

  Activa las banderas de observabilidad en tu entorno.

  # .env file
  ENABLE_A365_OBSERVABILITY_EXPORTER=true
  

• Comprobar la configuración del resolutor de tokens

  Asegúrate de que tu código implemente correctamente el resolvedor de tokens. Consulta directamente el código más reciente en el SDK.

• Comprobar errores en los registros

  Utiliza el az webapp log tail comando para buscar en los registros errores relacionados con la observabilidad.

  # Look for observability-related errors
  az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"
  

• Verificar exportación de telemetría

  Confirma que la telemetría se ha generado y exportado como se espera.

  • Añadir exportador de consola para pruebas
  • Comprueba si la telemetría se genera localmente

Aprende más sobre cómo probar la observabilidad:

• Guía de pruebas - Consulta los registros de observabilidad
• Configuración de observabilidad