Observabilité de l’assistant

Important

Vous devez faire partie du programme Frontier en version préliminaire pour obtenir un accès anticipé à Microsoft Agent 365. Frontier vous connecte directement aux dernières innovations d’IA de Microsoft. Les versions préliminaires Frontier sont soumises aux conditions existantes de vos contrats clients qui régissent les versions préliminaires. Comme ces fonctionnalités sont encore en cours de développement, leur disponibilité et leurs capacités peuvent évoluer au fil du temps.

Pour participer à l’écosystème Agent 365, ajoutez des capacités d’observabilité Agent 365 à votre agent. Agent 365 Observability s’appuie sur OpenTelemetry (OTel) et offre un cadre unifié pour capturer la télémétrie de manière cohérente et sécurisée sur toutes les plateformes agents. En implémentant ce composant requis, vous permettez aux administrateurs informatiques de surveiller l’activité de votre agent dans le centre d’administration Microsoft et de permettre aux équipes de sécurité d’utiliser Defender et Purview pour la conformité et la détection des menaces.

Principaux avantages

• Visibilité de bout en bout : Capturez une télémétrie complète pour chaque invocation d’agent, y compris les sessions, appels d’outils et exceptions, vous offrant ainsi une traçabilité complète sur toutes les plateformes.
• Activation de la sécurité et de la conformité : Alimentez Defender et Purview des journaux d’audit unifiés, permettant ainsi des scénarios de sécurité avancés et des rapports de conformité pour votre agent.
• Flexibilité multiplateforme : Construire sur les standards OTel et supporter des runtimes et plateformes variées comme Copilot Studio, Foundry et les futurs cadres d’agents.
• Efficacité opérationnelle pour les administrateurs : Assurez une observabilité centralisée dans le centre d’administration Microsoft 365, réduisant ainsi le temps de dépannage et améliorant la gouvernance grâce à des contrôles d’accès basés sur les rôles pour les équipes informatiques gérant votre agent.

Installation

Utilisez ces commandes pour installer les modules d’observabilité pour les langues prises en charge par 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

Configuration

Utilisez les paramètres suivants pour activer et personnaliser l’observabilité de l’Agent 365 pour votre agent.

Python

Définissez les variables d’environnement pour l’observabilité :

Variable d’environnement	Description
ENABLE_OBSERVABILITY=true	Signalez pour activer ou désactiver la traçabilité. La valeur par défaut est false.
ENABLE_A365_OBSERVABILITY_EXPORTER=true	Réglez pour true exporter les journaux vers le service. Sinon, l’exportateur console est utilisé.

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

Le résolveur de jeton est exclu de la connexion à la console.

JavaScript

Définissez les variables d’environnement pour l’observabilité :

Variable d’environnement	Description
ENABLE_OBSERVABILITY=true	Signalez pour activer ou désactiver la traçabilité. La valeur par défaut est false.
ENABLE_A365_OBSERVABILITY_EXPORTER=true	Réglez pour true exporter les journaux vers le service. Sinon, l’exportateur console est utilisé.

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

Définissez EnableAgent365Exporter sur true dans appsettings.json.

Dans Program.cs, ajoutez Agent365ExporterOptions à la collection de services. Cette modification configure le délégué que l’exportateur de trace utilise pour récupérer le jeton.

Ajouter des dépendances liées à l’observabilité en utilisant 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();

Attributs de bagage

Permet BaggageBuilder de définir des informations contextuelles qui transitent par toutes les étendues d’une requête. Le SDK implémente un SpanProcessor qui copie toutes les entrées de bagages non vides dans les spans nouvellement lancés sans écraser les attributs existants.

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.

Programme de résolution de jetons

Lorsque vous utilisez l’exportateur Agent 365, vous devez fournir une fonction de programme de résolution de jeton qui renvoie le jeton d’authentification. Lorsque vous utilisez le kit de développement logiciel (SDK) de l’observabilité d’Agent 365 avec l’infrastructure d’hébergement de l’assistant, vous pouvez générer des jetons à l’aide TurnContext des activités de l’assistant

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

Ajoutez le programme de résolution de jeton agentique à votre collection de services.

using Microsoft.Agents.A365.Observability;

builder.Services.AddAgenticTracingExporter();

Dans l’application de l’assistant, inscrivez le jeton.

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

Auto-instrumentation

L’instrumentation automatique écoute automatiquement les signaux de télémétrie existants des frameworks agentiques (SDK) pour les traces et les transfère au service d’observabilité Agent 365. Cette fonctionnalité élimine le besoin pour les développeurs d’écrire manuellement du code de surveillance, simplifie la configuration et assure un suivi cohérent des performances.

Plusieurs SDK et plateformes prennent en charge l’auto-instrumentation :

Plateforme	Kits de développement logiciel (SDK) / Frameworks pris en charge
.NET	Noyau sémantique, OpenAI, cadre d’agents
Python	Noyau sémantique, OpenAI, Agent Framework, LangChain
Node.js	OpenAI

Note

La prise en charge de l’instrumentation automatique varie selon l’implémentation de la plateforme et du SDK.

Noyau sémantique

L’instrumentation automatique nécessite l’utilisation du générateur de bagages. Définissez l’ID de l’agent et l’ID du locataire en utilisant BaggageBuilder.

Python

Installez le package .

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

Configurez l’observabilité.

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

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

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

# Your Semantic Kernel code is now automatically traced

JavaScript

Semantic Kernel n’est pas pris en charge avec JavaScript.

.NET

Ajoutez des dépendances à la collection de services.

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

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

On peut définir AgentId et TenantId en utilisant BaggageBuilder. Assurez-vous que l’identifiant que vous utilisez lors de la création correspond ChatCompletionAgent à celui de l’agent à qui vous transmettez 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

L’instrumentation automatique nécessite l’utilisation du générateur de bagages. Définissez l’ID de l’agent et l’ID du locataire en utilisant BaggageBuilder.

Python

Installez le package .

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

Configurez l’observabilité.

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

Installez le package .

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

Configurez l’observabilité.

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

Ajoutez des dépendances à la collection de services.

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

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

On peut définir AgentId et TenantId en utilisant BaggageBuilder. Pour les appels d’outils, lancez une trace en utilisant Trace() sur une ChatToolCall instance.

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

Cadre d’agent

L’instrumentation automatique nécessite l’utilisation du générateur de bagages. Définissez l’ID de l’agent et l’ID du locataire en utilisant BaggageBuilder.

Python

Installez le package .

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

Configurez l’observabilité.

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 n’est pas pris en charge avec JavaScript.

.NET

Ajoutez des dépendances à la collection de services.

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

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

On peut définir AgentId et TenantId en utilisant 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();
    }
}

Cadre LangChain

L’instrumentation automatique nécessite l’utilisation du générateur de bagages. Définissez l’ID de l’agent et l’ID du locataire en utilisant BaggageBuilder.

Installez le package .

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

Configurez l’observabilité.

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

---

Instrumentation manuelle

Utilisez le SDK d’observabilité de l’agent 365 pour comprendre le fonctionnement interne de l’agent. Le SDK fournit trois portées que vous pouvez commencer : InvokeAgentScope, ExecuteToolScope, et InferenceScope.

Invocation de l’agent

Utilisez cette portée au début de votre processus d’agent. En utilisant la portée de l’agent invoke, vous pouvez capturer des propriétés comme l’agent en cours d’invocation, les données utilisateur de l’agent, et plus encore.

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

Exécution de l’outil

Les exemples suivants montrent comment ajouter le suivi de l’observabilité à l’exécution de l’outil de votre agent. Ce suivi capture la télémétrie à des fins de surveillance et d’audit.

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

Inférence

Les exemples suivants montrent comment instrumenter les appels d’inférence de modèle IA avec le suivi de l’observabilité pour capturer l’utilisation des jetons, les détails du modèle et les métadonnées de réponse.

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

Valider localement

Pour vérifier que vous avez réussi à intégrer avec le SDK d’observabilité, examinez les journaux de la console générés par votre agent.

Python

Définissez la variable d’environnement ENABLE_A365_OBSERVABILITY_EXPORTER sur false. Ce réglage exporte les spans (traces) vers la console.

JavaScript

Définissez la variable d’environnement ENABLE_A365_OBSERVABILITY_EXPORTER sur false. Ce réglage exporte les spans (traces) vers la console.

.NET

Définissez EnableAgent365Exporter sur false dans appsettings.json. Ce réglage exporte les étendues (traces) vers la console.

Exemples de journaux

Les grumes peuvent avoir un aspect légèrement différent selon la plateforme.

Journal Invoke Agent span

Cet exemple montre une portée d’agent d’invokation typique que l’exportateur de la console imprime lorsque la validation locale est activée.

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

Journal console pour l’outil d’exécution

Cet exemple montre une extension typique d’outil d’exécution que l’exportateur console émet lors de la validation 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": ""
    }
}

Plage d’inférence des logarthiques de console

Cet exemple montre une plage d’inférence typique que l’exportateur de console produit pour validation 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": ""
    }
}

Exigences d’observabilité

Les administrateurs informatiques utilisent les données que vous saisissez dans votre code pour surveiller l’activité de votre agent. Des données incomplètes signifient que vous ne réalisez pas pleinement les avantages de l’observabilité. Les agents doivent fournir les données requises pour recevoir tous les bénéfices attendus. Un processus de validation confirme l’existence de ces données.

En télémétrie, il existe des concepts de portée ou de contexte. Chaque opération effectuée par votre agent existe dans un champ d’action différent. Vous devez inclure les données dans les BaggageScope attributs créés en utilisant les attributs Baggage, ou dans les champs individuels décrits dans l’Instrumentation Manuelle.

Pour valider votre implémentation, suivez les instructions pour valider localement afin de générer des journaux de console pour votre instrumentation. Ensuite, consultez la section Valider pour la publication en magasin afin d’identifier quels attributs sont requis et lesquels sont optionnels. Vous devez définir tous les attributs requis pour réussir la validation.

Examinez les propriétés et valeurs de paramètre requises décrites pour ces classes :

Python

• Les propriétés que vous définissez en utilisant la classe BaggageBuilder peuvent être définies ou écrasées par les propriétés des champs correspondants.

• Définissez les propriétés dans le tableau suivant en utilisant la méthode InvokeAgentScope.start.

  Data	Description
  invoke_agent_details.details.agent_id	Identificateur unique de l’agent IA
  invoke_agent_details.details.agent_name	Nom lisible par l’homme de l’agent IA
  invoke_agent_details.details.agent_auid	ID utilisateur de l’agent (AUID)
  invoke_agent_details.details.agent_upn	Nom d’utilisateur principal de l’agent (UPN)
  invoke_agent_details.details.agent_blueprint_id	Id du blueprint/de l’application de l’agent
  invoke_agent_details.details.tenant_id	ID de locataire de l’agent
  invoke_agent_details.details.conversation_id	Identificateur de la conversation ou de la session
  invoke_agent_details.endpoint	Point de terminaison de l’appel de l’agent
  tenant_details.tenant_id	Identificateur unique du locataire
  request.content	Le contenu de la charge utile envoyé à l’agent pour invocation
  request.execution_type	Type d’invocation indiquant l’origine de la requête (par exemple, HumanToAgent ou AgentToAgent)
  caller_details.caller_id	Identificateur unique de l’appelant
  caller_details.caller_upn	Nom d’utilisateur principal (UPN) de l’appelant
  caller_details.caller_user_id	ID utilisateur de l’appelant
  caller_details.tenant_id	ID de locataire de l’appelant

• Définissez les propriétés dans la table suivante en utilisant la méthode ExecuteToolScope.start.

  Data	Description
  details.tool_name	Nom de l’outil en cours d’exécution
  details.arguments	Arguments ou paramètres d’outils
  details.tool_call_id	Identificateur unique de l’appel d’outil
  details.tool_type	Type de l’outil en cours d’exécution
  details.endpoint	Si un appel d’outil externe est effectué
  agent_details.agent_id	Identificateur unique de l’agent IA
  agent_details.agent_name	Nom lisible par l’homme de l’agent IA
  agent_details.agent_auid	L’identifiant utilisateur de l’agent
  agent_details.agent_upn	Nom d’utilisateur principal de l’agent (UPN)
  agent_details.agent_blueprint_id	Le plan de l’agent ou l’identifiant de l’application
  agent_details.tenant_id	Identifiant locataire pour l’agent.
  agent_details.conversation_id	L’identifiant de conversation pour l’invocation de l’agent.
  tenant_details.tenant_id	Identifiant locataire pour l’agent.

• Définissez les propriétés dans la table suivante en utilisant la méthode InferenceScope.start.

  Data	Description
  details.operationName	Le nom ou type d’opération pour l’inférence
  details.model	Le nom ou identifiant du modèle
  details.providerName	Le nom du fournisseur
  agent_details.agent_id	Identificateur unique de l’agent IA
  agent_details.agent_name	Nom lisible par l’homme de l’agent IA
  agent_details.agent_auid	ID utilisateur de l’agent (AUID)
  agent_details.agent_upn	Nom d’utilisateur principal de l’agent (UPN)
  agent_details.agent_blueprint_id	Le plan de l’agent ou l’identifiant de l’application
  agent_details.tenant_id	Identificateur unique du locataire
  agent_details.conversation_id	Identificateur de la conversation ou de la session
  tenant_details.tenant_id	Identificateur unique du locataire
  request.content	Le contenu de la charge utile envoyé à l’agent pour inférence
  request.execution_type	Type d’invocation indiquant l’origine de la requête (par exemple, HumanToAgent ou AgentToAgent)
  request.source_metadata	Représenter les informations du canal

JavaScript

• Les propriétés que vous définissez en utilisant la classe BaggageBuilder peuvent être définies ou remplacées par les propriétés des champs correspondants.

• Définissez les propriétés dans le tableau suivant en utilisant la méthode InvokeAgentScope.start.

  Data	Description
  invokeAgentDetails.agentAUID	ID utilisateur de l’agent (AUID)
  invokeAgentDetails.agentBlueprintId	Id du blueprint/de l’application de l’agent
  invokeAgentDetails.agentId	Identificateur unique de l’agent IA
  invokeAgentDetails.agentName	Nom lisible par l’homme de l’agent IA
  invokeAgentDetails.agentUPN	Nom d’utilisateur principal de l’agent (UPN)
  invokeAgentDetails.conversationId	Identificateur de la conversation ou de la session
  invokeAgentDetails.endpoint.host	L’adresse hôte du point de terminaison pour l’invocation de l’agent
  invokeAgentDetails.endpoint.port	Le numéro de port du point de terminaison pour l’invocation de l’agent
  invokeAgentDetails.endpoint.protocol	Le point de terminaison du protocole pour l’invocation de l’agent
  invokeAgentDetails.request.content	Le contenu de la charge utile de requête pour l’invocation de l’agent
  invokeAgentDetails.request.executionType	Le type d’invocation de la charge utile de requête pour l’invocation de l’agent
  invokeAgentDetails.request.sourceMetadata.name	Canalisez des informations comme (msteams, email, etc.)
  invokeAgentDetails.tenantId	ID de locataire de l’agent
  tenantDetails.tenantId	Identificateur unique du locataire
  callerDetails.callerId	L’identifiant unique pour l’appelant (aadObjectId)
  callerDetails.callerName	Le nom d’affichage de l’appelant
  callerDetails.callerUpn	Nom d’utilisateur principal (UPN) de l’appelant
  callerDetails.tenantId	ID de locataire de l’appelant

• Définissez les propriétés dans la table suivante en utilisant la méthode ExecuteToolScope.start.

  Data	Description
  details.arguments	Arguments ou paramètres d’outils
  details.endpoint.host	L’adresse hôte du point de terminaison pour l’exécution de l’outil. Obligatoire en cas d’appel externe effectué
  details.endpoint.port	Le numéro de port du point d’accès pour l’exécution de l’outil. Obligatoire en cas d’appel externe effectué
  details.endpoint.protocol	Le protocole du point d’accès pour l’exécution de l’outil. Obligatoire en cas d’appel externe effectué
  details.toolCallId	Identificateur unique de l’appel d’outil
  details.toolName	Nom de l’outil en cours d’exécution
  details.toolType	Type de l’outil en cours d’exécution
  agentDetails.agentId	Identificateur unique de l’agent IA
  agentDetails.agentName	Nom lisible par l’homme de l’agent IA
  agentDetails.conversationId	Identificateur de la conversation ou de la session
  tenantDetails.tenantId	Identificateur unique du locataire

• Définissez les propriétés dans la table suivante en utilisant la méthode InferenceScope.start.

  Data	Description
  details.model	Le nom ou identifiant du modèle
  details.operationName	Le nom ou type d’opération pour l’inférence
  details.providerName	Le nom du fournisseur
  agentDetails.agentId	Identificateur unique de l’agent IA
  agentDetails.agentName	Nom lisible par l’homme de l’agent IA
  agentDetails.conversationId	Identificateur de la conversation ou de la session
  tenantDetails.tenantId	Identificateur unique du locataire

.NET

• Les propriétés que vous définissez en utilisant la classe BaggageBuilder peuvent être définies ou remplacées par les propriétés des champs correspondants.

• Définissez les propriétés dans la table suivante en utilisant la méthode InvokeAgentScope.Start.

  Data	Description
  invokeAgentDetails.details.agentId	Identificateur unique de l’agent.
  invokeAgentDetails.details.agentName	Nom affiché pour l’agent.
  invokeAgentDetails.details.agentAUID	Azure User ID (AUID) pour l’agent.
  invokeAgentDetails.details.agentUPN	Nom principal utilisateur (UPN) pour l’agent.
  invokeAgentDetails.details.agentBlueprintId	Formulaire/ID de demande pour l’agent.
  invokeAgentDetails.details.tenantId	Identifiant locataire pour l’agent.
  invokeAgentDetails.endpoint	URI de terminaison de l’agent à invoquer.
  tenantDetails.tenantId	L’identifiant du locataire.
  request.content	Le contenu de la charge utile fourni à l’agent.
  request.executionType	type d’exécution décrivant la requête.
  request.sourceMetadata.name	Nom de la source lisible par l’humain. Nom du canal.
  conversationId	L’identifiant de conversation pour l’invocation de l’agent.

• Définissez les propriétés dans la table suivante en utilisant la méthode ExecuteToolScope.Start.

  Data	Description
  details.toolName	Nom de l’outil invoqué.
  details.arguments	Les arguments sérialisés étaient transmis à l’outil.
  details.toolCallId	Identifiant pour l’invocation de l’outil.
  details.toolType	Classification de type pour l’outil.
  details.endpoint	Endpoint requis pour l’exécution à distance d’outils.
  agentDetails.agentId	Identificateur unique de l’agent.
  agentDetails.agentName	Nom affiché pour l’agent.
  agentDetails.agentAUID	Azure User ID (AUID) pour l’agent.
  agentDetails.agentUPN	Nom principal utilisateur (UPN) pour l’agent.
  agentDetails.agentBlueprintId	Formulaire/ID de demande pour l’agent.
  agentDetails.tenantId	Identifiant locataire pour l’agent.
  tenantDetails.tenantId	L’identifiant du locataire.

• Définissez les propriétés dans le tableau suivant en utilisant la méthode InferenceScope.Start.

  Data	Description
  details.operationName	Identifiant de télémétrie pour l’opération d’inférence.
  details.model	Le nom du modèle était utilisé pour satisfaire la demande d’inférence.
  details.providerName	Le fournisseur responsable de l’appel d’inférence.
  agentDetails.agentId	Identificateur unique de l’agent.
  agentDetails.agentName	Nom affiché pour l’agent.
  agentDetails.agentAUID	Azure User ID (AUID) pour l’agent.
  agentDetails.agentUPN	Nom principal utilisateur (UPN) pour l’agent.
  agentDetails.agentBlueprintId	Formulaire/ID de demande pour l’agent.
  agentDetails.tenantId	Identifiant locataire pour l’agent.
  tenantDetails.tenantId	L’identifiant du locataire.
  parentId	Pour une gestion explicite du champ parental. Ce n’est pas obligatoire dans la plupart des cas.

Validation pour l’édition en magasin

Avant de publier, utilisez les journaux de la console pour valider votre intégration d’observabilité pour l’agent en implémentant les champs d’invocation, d’outil d’exécution et d’inférence requis. Ensuite, comparez les journaux de votre agent avec les listes d’attributs suivantes pour vérifier que tous les attributs requis sont présents. Capturez les attributs sur chaque lunette ou via le constructeur de bagages, et incluez des attributs optionnels à votre discrétion.

Pour plus d’informations sur les exigences de publication en magasin, consultez les directives de validation des magasins.

Attributs InvokeAgentScope

La liste suivante résume les attributs de télémétrie requis et optionnels enregistrés lorsque vous commencez un InvokeAgentScopefichier .

"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"
    },

Attributs ExecuteToolScope

La liste suivante résume les attributs de télémétrie requis et optionnels enregistrés lorsque vous commencez un ExecuteToolScopefichier .

"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"
    },

Attributs InferenceScope

La liste suivante résume les attributs de télémétrie requis et optionnels enregistrés lorsque vous commencez un InferenceScopefichier .

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

Tester votre assistant avec l’observabilité

Après avoir implémenté l’observabilité dans votre agent, testez pour vous assurer que la télémétrie est correctement capturée. Suivez le guide de test pour configurer votre environnement. Ensuite, concentrez-vous principalement sur la section des journaux d’observabilité de la vue pour valider que votre implémentation d’observabilité fonctionne comme prévu.

Vérification :

• Accédez à https://admin.cloud.microsoft/#/agents/all.
• Sélectionnez votre agent > Activité
• Vous devriez voir les sessions et les appels d’outils

Résolution des problèmes

Cette section décrit les problèmes courants lors de la mise en œuvre et de l’utilisation de l’observabilité.

Conseil / Astuce

Le Guide de dépannage de l’Agent 365 contient des recommandations générales de dépannage, les meilleures pratiques et des liens vers du contenu de dépannage pour chaque étape du cycle de développement de l’Agent 365.

Les données d’observabilité n’apparaissent pas

Symptômes :

• L’agent est en fuite
• Pas de télémétrie dans le centre administratif
• Impossible de voir l’activité des agents

Cause racine :

• L’observabilité n’est pas activée
• Erreurs de configuration
• Problèmes de résolution de jetons

Solutions : Essayez les étapes suivantes pour résoudre le problème :

• Vérifier que l’observabilité est activée

  Activez les drapeaux d’observabilité dans votre environnement.

  # .env file
  ENABLE_OBSERVABILITY=true
  ENABLE_A365_OBSERVABILITY_EXPORTER=true
  

• Vérifier la configuration du résolveur de jeton

  Assurez-vous que votre code implémente correctement le résolveur de jetons. Vérifiez directement le code le plus récent dans le SDK.

• Vérifier les erreurs dans les journaux

  Utilisez la az webapp log tail commande pour rechercher dans les journaux des erreurs liées à l’observabilité.

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

• Vérifier l’exportation de télémétrie

  Confirmez que la télémétrie est générée et exportée comme prévu.

  • Ajouter l’exportateur console pour les tests
  • Vérifiez si la télémétrie est générée localement

En savoir plus sur les tests d’observabilité :

• Guide de test - Consultez les journaux d’observabilité
• Configuration de l’observabilité