Osservabilità dell'agente

Importante

Devi far parte del programma di anteprima Frontier per ottenere l'accesso in anteprima a Microsoft Agent 365. Frontier ti mette in contatto diretto con le ultime innovazioni di Microsoft nell'IA. Le anteprime Frontier sono soggette alle condizioni di anteprima esistenti dei tuoi contratti del cliente. Poiché queste funzionalità sono ancora in fase di sviluppo, la disponibilità e le funzionalità possono cambiare nel tempo.

Per partecipare all'ecosistema Agent 365, devi aggiungere le funzionalità di osservabilità di Agent 365 all'agente. L'osservabilità di Agent 365 si basa su OpenTelemetry (OTel) e fornisce un framework unificato per acquisire i dati di telemetria in modo coerente e sicuro in tutte le piattaforme dell'agente. Mediante l'implementazione di questo componente necessario, consenti agli amministratori IT a monitorare l'attività dell'agente nell'interfaccia di amministrazione di Microsoft e consenti ai team di sicurezza di usare Defender e Purview per la conformità e il rilevamento delle minacce.

Vantaggi chiave

• Visibilità end-to-end: acquisisci dati di telemetria completi per ogni chiamata dell'agente, incluse sessioni, chiamate agli strumenti ed eccezioni, offrendo la tracciabilità completa tra le piattaforme.
• Abilitazione di sicurezza e conformità: inserisci log di controllo unificati in Defender e Purview, abilitando scenari di sicurezza avanzati e report di conformità per l'agente.
• Flessibilità multipiattaforma: crea standard OTel e supporta runtime e piattaforme diverse, ad esempio Copilot Studio, Foundry e framework di agenti futuri.
• Efficienza operativa per gli amministratori: offri osservabilità centralizzata in MAC, riduci i tempi di risoluzione dei problemi e migliora la governance con i controlli degli accessi in base al ruolo per i team IT che gestiscono l'agente.

Installazione

Usa questi comandi per installare i moduli di osservabilità per le lingue supportate da 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

Configurazione

Usa le seguenti impostazioni per abilitare e personalizzare l'Osservabilità dell'Agente 365 per il tuo agente.

Python

Le variabili di ambiente necessarie per l'osservabilità sono:

Variabile di ambiente	Descrizione
ENABLE_OBSERVABILITY=true	Flag per abilitare/disabilitare la traccia. Per impostazione predefinita false
ENABLE_A365_OBSERVABILITY_EXPORTER=true	True esporta i registri al nostro servizio. In caso contrario, esegue il fallback all'utilità di esportazione della 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,
)

Escludi lo strumento di risoluzione dei token per accedere alla console.

JavaScript

Le variabili di ambiente necessarie per l'osservabilità sono:

Variabile di ambiente	Descrizione
ENABLE_OBSERVABILITY=true	Flag per abilitare/disabilitare la traccia. Per impostazione predefinita false
ENABLE_A365_OBSERVABILITY_EXPORTER=true	True esporta i log nel servizio. In caso contrario, esegue il fallback all'utilità di esportazione della 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

Impostare EnableAgent365Exporter su true in appsettings.json.

In Program.csaggiungi Agent365ExporterOptions alla raccolta di servizi. Questa modifica configura il delegato usato dall'utilità di esportazione della traccia per recuperare il token.

Aggiungi dipendenze correlate all'osservabilità 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();

Attributi di baggage

Utilizza BaggageBuilder per impostare informazioni contestuali che passano attraverso tutti gli intervalli di una richiesta. L'SDK implementa una SpanProcessor copia di tutte le voci di baggage non interrotte in intervalli appena avviati senza sovrascrivere gli attributi esistenti.

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.

Strumento di risoluzione dei token

Quando si usa l'utilità di esportazione di Agent 365, è necessario fornire una funzione di risoluzione dei token che restituisce il token di autenticazione. Quando si usa l'SDK di osservabilità di Agent 365 con il framework di hosting dell'agente, è possibile generare token usando TurnContext dalle attività dell'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

Aggiungi lo strumento di risoluzione del token agentico alla raccolta di servizi.

using Microsoft.Agents.A365.Observability;

builder.Services.AddAgenticTracingExporter();

Nell'applicazione dell'agente registra il 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}");
        }
    }
}

Strumentazione automatica

La strumentazione automatica ascolta automaticamente i segnali di telemetria esistenti dei framework agenti (SDK) per le tracce e li inoltra al servizio di osservabilità di Agent 365. Ciò elimina la necessità per gli sviluppatori di scrivere manualmente il codice di monitoraggio, semplificando la configurazione e garantendo un monitoraggio coerente delle prestazioni.

La strumentazione automatica è supportata su più SDK e piattaforme:

Piattaforma	SDK/framework supportati
.NET	Kernel semantico, OpenAI, Agent Framework
Python	Kernel semantico, OpenAI, Agent Framework, LangChain
Node.js	OpenAI

Nota

Il supporto per la strumentazione automatica varia in base all'implementazione della piattaforma e dell'SDK.

Kernel semantico

La strumentazione automatica richiede l'uso del generatore di baggage. Imposta l'ID agente e l'ID tenant usando BaggageBuilder.

Python

Installare il pacchetto

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

Configurare l'osservabilità

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

Il kernel semantico non è supportato con JavaScript.

.NET

Aggiungi dipendenze alla raccolta di servizi.

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

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

Imposta AgentId e TenantId tramite BaggageBuilder. Verifica che l'ID usato durante la creazione di un ChatCompletionAgent corrisponda all'ID agente passato 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 strumentazione automatica richiede l'uso del generatore di baggage. Imposta l'ID agente e l'ID tenant usando BaggageBuilder.

Python

Installare il pacchetto .

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

Configura l'osservabilità.

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

Installare il pacchetto

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

Configurare l'osservabilità

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

Aggiungi dipendenze alla raccolta di servizi.

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

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

Imposta AgentId e TenantId tramite BaggageBuilder. Per le chiamate agli strumenti, avvia una traccia usando Trace() in un'istanza 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>);
    }
}

Framework dell'agente

La strumentazione automatica richiede l'uso del generatore di baggage. Imposta l'ID agente e l'ID tenant usando BaggageBuilder.

Python

Installare il pacchetto

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

Configurare l'osservabilità

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

Agent Framework non è supportato con JavaScript.

.NET

Aggiungi dipendenze alla raccolta di servizi.

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

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

Imposta AgentId e TenantId tramite 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();
    }
}

Framework LangChain

La strumentazione automatica richiede l'uso del generatore di baggage. Imposta l'ID agente e l'ID tenant usando BaggageBuilder.

Installare il pacchetto .

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

Configurare l'osservabilità

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

---

Strumentazione manuale

L'SDK di osservabilità di Agent 365 può essere usato per comprendere il funzionamento interno dell'agente. L'SDK fornisce tre ambiti che possono essere avviati: InvokeAgentScope, ExecuteToolScopee InferenceScope.

Chiamata dell'agente

Questo ambito deve essere usato all'inizio del processo dell'agente. Con l'ambito di chiamata dell'agente si acquisisce proprietà come l'agente corrente richiamato, i dati utente dell'agente e così via.

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

Esecuzione degli strumenti

Gli esempi seguenti illustrano come instrumentare l'esecuzione degli strumenti dell'agente con il rilevamento dell'osservabilità per acquisire i dati di telemetria a scopo di monitoraggio e controllo.

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

Inferenza

Gli esempi seguenti illustrano come instrumentare le chiamate di inferenza del modello di intelligenza artificiale con il rilevamento dell'osservabilità per acquisire l'utilizzo dei token, i dettagli del modello e i metadati della risposta.

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

Convalida in locale

Per verificare che tu abbia integrato con successo con l'SDK di osservabilità, esamina i log della console generati dal tuo agente.

Python

Impostare la variabile di ambiente ENABLE_A365_OBSERVABILITY_EXPORTER su false. Queste esportazioni si estendono (tracce) nella console.

JavaScript

Impostare la variabile di ambiente ENABLE_A365_OBSERVABILITY_EXPORTER su false. Queste esportazioni si estendono (tracce) nella console.

.NET

Impostare EnableAgent365Exporter su false in appsettings.json. Queste esportazioni si estendono (tracce) nella console.

Esempi di log

I log potrebbero apparire leggermente diversi a seconda della piattaforma.

Log console Invoke agent span

Questo esempio illustra uno span tipico di invoke agent stampato dall'esportatore della console quando la validazione locale è attivata.

    {
    "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 console per lo strumento di esecuzione

Questo esempio mostra una tipica span di strumento di esecuzione emessa dall'esportatore console durante la validazione locale.

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

Intervallo di inferenza dei log della console

Questo esempio dimostra un tipico output di intervallo di inferenza dall'esportatore console utilizzato per la validazione locale.

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

Requisiti di osservabilità

Gli amministratori IT utilizzano i dati che inserisci nel tuo codice per monitorare l'attività del tuo agente. Dati incompleti significano che i benefici dell'osservabilità non sono pienamente realizzati. Gli agenti devono fornire i dati necessari per ricevere tutti i benefici attesi. Un processo di validazione verificherà che questi dati esistano.

All'interno della telemetria esistono concetti di ambito o contesto. Ogni operazione che il tuo agente esegue esiste in un ambito diverso. I dati devono essere inclusi all'interno degli BaggageScopeattributi creati usando Baggage, o all'interno degli ambiti individuali come descritto in Strumentazione Manuale.

Per validare la tua implementazione, segui le istruzioni per validare localmente e generare log console per la tua strumentazione. Successivamente si ripassa la sezione [Valida per attributi richiesti] (#validate-per-richiedi attributi) per identificare quali attributi sono richiesti e quali opzionali. Tutti gli attributi richiesti devono essere impostati per superare con successo la validazione.

Rivedere le proprietà richieste e i valori dei parametri descritti per queste classi:

Python

• Le proprietà impostate tramite la classe BaggageBuilder possono essere impostate o sovrascritte dalle proprietà dei rispettivi ambiti.

• Imposta le proprietà nella tabella seguente usando il metodo InvokeAgentScope.start.

  Data	Descrizione
  invoke_agent_details.details.agent_id	Identificatore univoco per l'agente di intelligenza artificiale
  invoke_agent_details.details.agent_name	Nome leggibile dell'agente di intelligenza artificiale
  invoke_agent_details.details.agent_auid	ID utente agente (AUID)
  invoke_agent_details.details.agent_upn	Nome dell'entità utente dell'agente (UPN)
  invoke_agent_details.details.agent_blueprint_id	ID progetto/applicazione dell'agente
  invoke_agent_details.details.tenant_id	ID tenant per l'agente
  invoke_agent_details.details.conversation_id	Identificatore della conversazione o della sessione
  invoke_agent_details.endpoint	Endpoint per la chiamata dell'agente
  tenant_details.tenant_id	Identificatore univoco per il tenant
  request.content	Il contenuto del payload inviato all'agente per l'invocazione
  request.execution_type	Tipo di invocazione che indica l'origine della richiesta (ad esempio, HumanToAgent o AgentToAgent)
  caller_details.caller_id	Identificatore univoco per il chiamante
  caller_details.caller_upn	Nome dell'entità utente (UPN) del chiamante
  caller_details.caller_user_id	ID utente del chiamante
  caller_details.tenant_id	ID tenant del chiamante

• Imposta le proprietà nella tabella seguente usando il metodo ExecuteToolScope.start.

  Data	Descrizione
  details.tool_name	Nome dello strumento da eseguire
  details.arguments	Argomenti/parametri dello strumento
  details.tool_call_id	Identificatore univoco per la chiamata allo strumento
  details.tool_type	Tipo dello strumento in esecuzione
  details.endpoint	Se viene effettuata una chiamata di uno strumento esterno
  agent_details.agent_id	Identificatore univoco per l'agente di intelligenza artificiale
  agent_details.agent_name	Nome leggibile dell'agente di intelligenza artificiale
  agent_details.agent_auid	L'ID utente dell'agente
  agent_details.agent_upn	Nome dell'entità utente dell'agente (UPN)
  agent_details.agent_blueprint_id	ID progetto/applicazione dell'agente
  agent_details.tenant_id	ID inquilino per l'agente.
  agent_details.conversation_id	L'ID della conversazione per l'invocazione dell'agente.
  tenant_details.tenant_id	ID inquilino per l'agente.

• Imposta le proprietà nella tabella seguente usando il metodo InferenceScope.start.

  Data	Descrizione
  details.operationName	Nome/tipo dell'operazione per l'inferenza
  details.model	Nome/identificatore del modello
  details.providerName	Il nome del fornitore
  agent_details.agent_id	Identificatore univoco per l'agente di intelligenza artificiale
  agent_details.agent_name	Nome leggibile dell'agente di intelligenza artificiale
  agent_details.agent_auid	ID utente agente (AUID)
  agent_details.agent_upn	Nome dell'entità utente dell'agente (UPN)
  agent_details.agent_blueprint_id	ID progetto/applicazione dell'agente
  agent_details.tenant_id	Identificatore univoco per il tenant
  agent_details.conversation_id	Identificatore della conversazione o della sessione
  tenant_details.tenant_id	Identificatore univoco per il tenant
  request.content	Il contenuto del payload inviato all'agente per l'inferenza
  request.execution_type	Tipo di invocazione che indica l'origine della richiesta (ad esempio, HumanToAgent o AgentToAgent)
  request.source_metadata	Rappresenta le informazioni sul canale

JavaScript

• Le proprietà impostate tramite la classe BaggageBuilder possono essere impostate o sovrascritte dalle proprietà dei rispettivi ambiti.

• Imposta le proprietà nella tabella seguente usando il metodo InvokeAgentScope.start.

  Data	Descrizione
  invokeAgentDetails.agentAUID	ID utente agente (AUID)
  invokeAgentDetails.agentBlueprintId	ID progetto/applicazione dell'agente
  invokeAgentDetails.agentId	Identificatore univoco per l'agente di intelligenza artificiale
  invokeAgentDetails.agentName	Nome leggibile dell'agente di intelligenza artificiale
  invokeAgentDetails.agentUPN	Nome dell'entità utente dell'agente (UPN)
  invokeAgentDetails.conversationId	Identificatore della conversazione o della sessione
  invokeAgentDetails.endpoint.host	L'indirizzo host dell'endpoint per l'invocazione dell'agente
  invokeAgentDetails.endpoint.port	Il numero di porta dell'endpoint per l'invocazione dell'agente
  invokeAgentDetails.endpoint.protocol	L'endpoint del protocollo per l'invocazione dell'agente
  invokeAgentDetails.request.content	Il contenuto del payload della richiesta per l'invocazione dell'agente
  invokeAgentDetails.request.executionType	Il tipo di invocazione del payload di richiesta per l'invocazione dell'agente
  invokeAgentDetails.request.sourceMetadata.name	Canalizza informazioni come (msteams, email, e così via)
  invokeAgentDetails.tenantId	ID tenant per l'agente
  tenantDetails.tenantId	Identificatore univoco per il tenant
  callerDetails.callerId	L'identificatore univoco per il chiamante (aadObjectId)
  callerDetails.callerName	Nome visualizzato del chiamante
  callerDetails.callerUpn	Nome dell'entità utente (UPN) del chiamante
  callerDetails.tenantId	ID tenant del chiamante

• Imposta le proprietà nella tabella seguente usando il metodo ExecuteToolScope.start.

  Data	Descrizione
  details.arguments	Argomenti/parametri dello strumento
  details.endpoint.host	L'indirizzo host dell'endpoint per l'esecuzione dello strumento. Richiesto se viene effettuata una chiamata esterna
  details.endpoint.port	Il numero di porta dell'endpoint per l'esecuzione dello strumento. Richiesto se viene effettuata una chiamata esterna
  details.endpoint.protocol	Il protocollo dell'endpoint per l'esecuzione dello strumento. Richiesto se viene effettuata una chiamata esterna
  details.toolCallId	Identificatore univoco per la chiamata allo strumento
  details.toolName	Nome dello strumento da eseguire
  details.toolType	Tipo dello strumento in esecuzione
  agentDetails.agentId	Identificatore univoco per l'agente di intelligenza artificiale
  agentDetails.agentName	Nome leggibile dell'agente di intelligenza artificiale
  agentDetails.conversationId	Identificatore della conversazione o della sessione
  tenantDetails.tenantId	Identificatore univoco per il tenant

• Imposta le proprietà nella tabella seguente usando il metodo InferenceScope.start.

  Data	Descrizione
  details.model	Nome/identificatore del modello
  details.operationName	Nome/tipo dell'operazione per l'inferenza
  details.providerName	Il nome del fornitore
  agentDetails.agentId	Identificatore univoco per l'agente di intelligenza artificiale
  agentDetails.agentName	Nome leggibile dell'agente di intelligenza artificiale
  agentDetails.conversationId	Identificatore della conversazione o della sessione
  tenantDetails.tenantId	Identificatore univoco per il tenant

.NET

• Le proprietà impostate tramite la classe BaggageBuilder possono essere impostate o sovrascritte dalle proprietà dei rispettivi ambiti.

• Imposta le proprietà nella tabella seguente usando il metodo InvokeAgentScope.Start.

  Data	Descrizione
  invokeAgentDetails.details.agentId	Identificatore univoco dell'agente.
  invokeAgentDetails.details.agentName	Mostra il nome dell'agente.
  invokeAgentDetails.details.agentAUID	Azure User ID (AUID) per l'agente.
  invokeAgentDetails.details.agentUPN	Nome Principale Utente (UPN) per l'agente.
  invokeAgentDetails.details.agentBlueprintId	Progetto o ID della domanda per l'agente.
  invokeAgentDetails.details.tenantId	ID inquilino per l'agente.
  invokeAgentDetails.endpoint	URI endpoint dell'agente da invocare.
  tenantDetails.tenantId	L'identificatore dell'inquilino.
  request.content	Il contenuto del payload fornito all'agente.
  request.executionType	Tipo di esecuzione che descrive la richiesta.
  request.sourceMetadata.name	Nome leggibile per l'uomo della fonte. Nome del canale.
  conversationId	L'ID della conversazione per l'invocazione dell'agente.

• Imposta le proprietà nella tabella seguente usando il metodo ExecuteToolScope.Start.

  Data	Descrizione
  details.toolName	Nome dello strumento che viene invocato.
  details.arguments	Gli argomenti serializzati passavano allo strumento.
  details.toolCallId	Identificatore per l'invocazione dello strumento.
  details.toolType	Classificazione dei tipi per lo strumento.
  details.endpoint	Endpoint richiesto per l'esecuzione remota degli strumenti.
  agentDetails.agentId	Identificatore univoco dell'agente.
  agentDetails.agentName	Mostra il nome dell'agente.
  agentDetails.agentAUID	Azure User ID (AUID) per l'agente.
  agentDetails.agentUPN	Nome Principale Utente (UPN) per l'agente.
  agentDetails.agentBlueprintId	Progetto o ID della domanda per l'agente.
  agentDetails.tenantId	ID inquilino per l'agente.
  tenantDetails.tenantId	L'identificatore dell'inquilino.

• Imposta le proprietà nella tabella seguente usando il metodo InferenceScope.Start.

  Data	Descrizione
  details.operationName	Identificatore di telemetria per l'operazione di inferenza.
  details.model	Nome del modello utilizzato per soddisfare la richiesta di inferenza.
  details.providerName	Il fornitore responsabile della chiamata di inferenza.
  agentDetails.agentId	Identificatore univoco dell'agente.
  agentDetails.agentName	Mostra il nome dell'agente.
  agentDetails.agentAUID	Azure User ID (AUID) per l'agente.
  agentDetails.agentUPN	Nome Principale Utente (UPN) per l'agente.
  agentDetails.agentBlueprintId	Progetto o ID della domanda per l'agente.
  agentDetails.tenantId	ID inquilino per l'agente.
  tenantDetails.tenantId	L'identificatore dell'inquilino.
  parentId	Per una gestione esplicita dell'ambito genitore. Non è obbligatorio nella maggior parte dei casi.

Valida per l'editoria in negozio

Usa i log della console per validare l'integrazione dell'osservabilità per l'agente prima di pubblicare implementando l'agente di invocazione, lo strumento di esecuzione e gli ambiti di inferenza richiesti. Poi confronta i log del tuo agente con le seguenti liste di attributi per verificare che tutti gli attributi richiesti siano presenti; Cattura gli attributi su ciascun telescopio o tramite il baggage builder, e includi attributi opzionali a tua discrezione.

Per maggiori informazioni sui requisiti di pubblicazione dei negozi, consulta le linee guida per la validazione dei negozi.

Attributi InvokeAgentScope

L'elenco seguente riassume gli attributi di telemetria richiesti e opzionali registrati quando si avvia 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.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"
    },

Attributi ExecuteToolScope

L'elenco seguente riassume gli attributi di telemetria richiesti e opzionali registrati quando si avvia 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.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"
    },

Attributi InferenceScope

L'elenco seguente riassume gli attributi di telemetria richiesti e opzionali registrati quando si avvia 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.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"
    }

Testare l'agente con l'osservabilità

Dopo aver implementato l'osservabilità nel tuo agente, verifica che la telemetria venga catturata correttamente. Segui la guida ai test per configurare l'ambiente, quindi concentrati principalmente sulla sezione Visualizzare i log di osservabilità per verificare che l'implementazione dell'osservabilità funzioni come previsto.