Agent-Einblicke

Wichtig

Sie müssen Teil des Frontier-Vorschauversionsprogramms sein, um Vorabzugriff auf Microsoft Agent 365 zu erhalten. Frontier verbindet Sie direkt mit den neuesten KI-Innovationen von Microsoft. Frontier-Vorschauversionen unterliegen den bestehenden Vorschauversionsbedingungen Ihrer Kundenvereinbarungen. Da sich diese Funktionen noch in der Entwicklung befinden, können sich ihre Verfügbarkeit und Merkmale im Laufe der Zeit ändern.

Um am Agent 365-Ökosystem teilzunehmen, müssen Sie Agent 365 Einblicke-Funktionen zu Ihrem Agent hinzufügen. Der Agent 365 Einblicke baut auf OpenTelemetry (OTel) auf und bietet ein einheitliches Framework zum konsistenten und sicheren Erfassen von Telemetrie auf allen Agentplattformen. Durch die Implementierung dieser erforderlichen Komponente aktivieren Sie IT-Administratoren, die Aktivitäten Ihres Agents im Microsoft Admin Center (MAC) zu überwachen und Sicherheitsteams die Verwendung von Defender und Purview für die Compliance- und Bedrohungserkennung zu ermöglichen.

Wesentliche Vorteile

• End-to-End-Sichtbarkeit: Erfassen Sie umfassende Telemetrie für jeden Agent-Aufruf, einschließlich Sitzungen, Toolanrufe und Ausnahmen, sodass Sie plattformübergreifend vollständig nachverfolgt werden können.
• Sicherheit & Compliance Enablement: Führen Sie einheitliche Überwachungsprotokolle in Defender und Purview ein, um erweiterte Sicherheitsszenarien und Compliance-Berichte für Ihren Agent zu ermöglichen.
• Plattformübergreifende Flexibilität: Bauen Sie auf OTel-Standards auf, und unterstützen Sie verschiedene Laufzeiten und Plattformen wie Copilot Studio, Foundry und zukünftige Agent-Frameworks.
• Betriebseffizienz für Administratoren: Bereitstellen einer zentralen Observability in MAC, Reduzierung der Problembehandlungszeit und Verbesserung der Governance mit rollenbasierten Zugriffssteuerungen für IT-Teams, die Ihren Agent verwalten.

Installation

Verwenden Sie diese Befehle, um die Observability-Module für die von Agent 365 unterstützten Sprachen zu installieren.

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

Konfiguration

Verwenden Sie die folgenden Einstellungen, um die Agent 365 Observability für Ihren Agenten zu aktivieren und anzupassen.

Python

Die für Einblicke erforderlichen Umgebungsvariablen sind:

Umgebungsvariable	Beschreibung
ENABLE_OBSERVABILITY=true	Kennzeichnen, um die Ablaufverfolgung zu aktivieren/zu deaktivieren. Standardmäßig false
ENABLE_A365_OBSERVABILITY_EXPORTER=true	True Exportiert Logs an unseren Service. Andernfalls fällt er auf den Konsolenexporteur zurück

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

Schließen Sie den Tokenlöser aus, um sich bei der Konsole anzumelden.

JavaScript

Die für Einblicke erforderlichen Umgebungsvariablen sind:

Umgebungsvariable	Beschreibung
ENABLE_OBSERVABILITY=true	Kennzeichnen, um die Ablaufverfolgung zu aktivieren/zu deaktivieren. Standardmäßig false
ENABLE_A365_OBSERVABILITY_EXPORTER=true	True Protokolle an unseren Dienst exportieren. Andernfalls Rückfall auf den Konsolenexporteur

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

Legen Sie EnableAgent365Exporter auf true in appsettings.json fest.

In Program.cs, hinzufügen Agent365ExporterOptions zur Dienstauflistung. Diese Änderung konfiguriert die Stellvertretung, die der Ablaufverfolgungsexporteur zum Abrufen des Tokens verwendet.

Einblickbezogene Abhängigkeiten hinzufügen mit 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();

Gepäckattribute

Wird verwendet BaggageBuilder , um Kontextinformationen festzulegen, die über alle Spannen in einer Anforderung fließen. Das SDK implementiert eine SpanProcessor Kopie aller nicht leeren Gepäckeinträge in neu gestartete Abschnitte, ohne vorhandene Attribute zu überschreiben.

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.

Tokenlöser

Wenn Sie den Agent 365-Exporter verwenden, müssen Sie eine Tokenlöserfunktion bereitstellen, die Authentifizierungstoken zurückgibt. Wenn Sie das Agent 365 Observability SDK mit dem Agent Hosting Framework verwenden, können Sie Token mithilfe der TurnContext Agent-Aktivitäten generieren

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

Fügen Sie der Dienstauflistung den agentischen Tokenlöser hinzu.

using Microsoft.Agents.A365.Observability;

builder.Services.AddAgenticTracingExporter();

Registrieren Sie das Token in der Agent-Anwendung.

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

Automatische Instrumentierung

Die automatische Instrumentierung lauscht automatisch auf agentische Frameworks (SDKs) vorhandene Telemetriesignale für Ablaufverfolgungen und leitet sie an den Agent 365-Observability-Dienst weiter. Dadurch ist es für Entwickler nicht erforderlich, Überwachungscode manuell zu schreiben, das Setup zu vereinfachen und eine konsistente Leistungsnachverfolgung sicherzustellen.

Die automatische Instrumentierung wird über mehrere SDKs und Plattformen hinweg unterstützt:

Plattform	Unterstützte SDKs / Frameworks
.NET	Semantischer Kernel, OpenAI, Agent Framework
Python	Semantischer Kernel, OpenAI, Agent Framework, LangChain
Node.js	OpenAI

Anmerkung

Die Unterstützung für die automatische Instrumentierung variiert je nach Plattform- und SDK-Implementierung.

Semantischer Kernel

Die automatische Instrumentierung erfordert die Verwendung des Gepäckbauers. Legen Sie die Agent-ID und die Mandanten-ID mithilfe von BaggageBuilder.

Python

Installieren des Pakets

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

Konfigurieren des Einblicks

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

Der semantische Kernel wird mit JavaScript nicht unterstützt.

.NET

Abhängigkeiten zur Dienstauflistung hinzufügen.

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

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

Festlegen AgentId und TenantId Verwenden von BaggageBuilder. Stellen Sie sicher, dass die ID, die beim Erstellen einer ChatCompletionAgent Id verwendet wird, mit der agent-ID übereinstimmt, die an 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

Die automatische Instrumentierung erfordert die Verwendung des Gepäckbauers. Legen Sie die Agent-ID und die Mandanten-ID mithilfe von BaggageBuilder.

Python

Installieren Sie das -Paket.

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

Konfigurieren von Einblicken.

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

Installieren des Pakets

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

Konfigurieren des Einblicks

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

Abhängigkeiten zur Dienstauflistung hinzufügen.

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

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

Festlegen AgentId und TenantId Verwenden von BaggageBuilder. Starten Sie für Toolaufrufe eine Ablaufverfolgung mithilfe Trace() einer ChatToolCall Instanz.

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

Agenten-Framework

Die automatische Instrumentierung erfordert die Verwendung des Gepäckbauers. Legen Sie die Agent-ID und die Mandanten-ID mithilfe von BaggageBuilder fest.

Python

Installieren des Pakets

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

Konfigurieren des Einblicks

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 wird mit JavaScript nicht unterstützt.

.NET

Abhängigkeiten zur Dienstauflistung hinzufügen.

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

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

Festlegen AgentId und TenantId Verwenden von 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();
    }
}

LangChain-Framework

Die automatische Instrumentierung erfordert die Verwendung von BaggageBuilder. Legen Sie die Agent-ID und die Mandanten-ID mithilfe von BaggageBuilder.

Installieren Sie das -Paket.

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

Konfigurieren des Einblicks

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

---

Manuelle Instrumentierung

Agent 365 Observability SDK kann verwendet werden, um die interne Arbeit des Agents zu verstehen. Das SDK bietet drei Bereiche, die gestartet werden können: InvokeAgentScope, , ExecuteToolScopeund InferenceScope.

Agent-Aufruf

Dieser Bereich sollte zu Beginn des Agent-Prozesses verwendet werden. Mit dem Aufruf-Agent-Bereich erfassen Sie Eigenschaften wie den aktuellen Agent, der aufgerufen wird, Agent-Benutzerdaten usw.

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

Tool-Ausführung

Die folgenden Beispiele veranschaulichen, wie Sie die Toolausführung Ihres Agents mit Observability Tracking instrumentieren, um Telemetrie für Überwachungs- und Überwachungszwecke zu erfassen.

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

Rückschluss

Die folgenden Beispiele zeigen, wie Sie KI-Modellableitungsaufrufe mit Observability Tracking zur Erfassung der Tokennutzung, Modelldetails und Antwortmetadaten instrumentieren.

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

Lokal überprüfen

Um zu überprüfen, dass Sie erfolgreich mit dem Observability-SDK integriert wurden, prüfen Sie die von Ihrem Agenten generierten Konsolenprotokolle.

Python

Legen Sie die Umgebungsvariable ENABLE_A365_OBSERVABILITY_EXPORTER auf false fest. Diese Exporte umfassen (Ablaufverfolgungen) bis zur Konsole.

JavaScript

Legen Sie die Umgebungsvariable ENABLE_A365_OBSERVABILITY_EXPORTER auf false fest. Diese Exporte umfassen (Ablaufverfolgungen) bis zur Konsole.

.NET

Legen Sie EnableAgent365Exporter auf false in appsettings.json fest. Diese Exporte umfassen (Ablaufverfolgungen) bis zur Konsole.

Beispielprotokolle

Die Logs können je nach Plattform leicht unterschiedlich aussehen.

Konsolenprotokoll Aufruf-Agenten-Spanne

Dieses Beispiel veranschaulicht eine typische Aufruf-Agenten-Spanne, die vom Konsolenexporter ausgedruckt wird, wenn die lokale Validierung aktiviert ist.

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

Konsolenlog für das Ausführungstool

Dieses Beispiel zeigt eine typische Ausführungs-Tool-Spannweite, die vom Konsolenexporter während der lokalen Validierung ausgesendet wird.

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

Inferenzspanne des Konsolenlogs

Dieses Beispiel zeigt eine typische Inferenzspanne aus dem Konsolenexporteur, der für die lokale Validierung verwendet wird.

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

Anforderungen an die Beobachtbarkeit

IT-Administratoren nutzen die in Ihrem Code eingestellten Daten, um die Aktivitäten Ihres Agenten zu überwachen. Unvollständige Daten bedeuten, dass die Vorteile der Beobachtbarkeit nicht vollständig ausgeschöpft werden. Agenten müssen die erforderlichen Daten bereitstellen, um alle erwarteten Vorteile zu erhalten. Ein Validierungsprozess überprüft, ob diese Daten existieren.

Innerhalb der Telemetrie gibt es Konzepte wie Umfang oder Kontext. Jede Operation, die Ihr Agent ausführt, liegt in einem anderen Rahmen. Die Daten müssen in die BaggageScope mit Baggage erstellten Attribute oder in den einzelnen Scopes gemäß Manual Instrumentation enthalten sein.

Um Ihre Implementierung zu validieren, folgen Sie den Anweisungen zur lokalen Validierung zur Erstellung von Konsolenprotokollen für Ihre Instrumentierung. Dann überprüfe ich den Abschnitt [Validieren für erforderliche Attribute](#validate für rewuired Attribute), um herauszufinden, welche Attribute erforderlich und welche optional sind. Alle erforderlichen Attribute müssen gesetzt werden, um die Validierung erfolgreich zu bestehen.

Überprüfen Sie die erforderlichen Eigenschaften und Parameterwerte, die für diese Klassen beschrieben sind:

Python

• Eigenschaften, die mit der BaggageBuilder-Klasse gesetzt werden, können von den Eigenschaften der jeweiligen Scopes gesetzt oder überschrieben werden.

• Setzen Sie die Eigenschaften in der folgenden Tabelle mit der Methode InvokeAgentScope.start.

  Daten	Beschreibung
  invoke_agent_details.details.agent_id	Der eindeutige Bezeichner für den KI-Agent
  invoke_agent_details.details.agent_name	Der lesbare Name des KI-Agenten
  invoke_agent_details.details.agent_auid	Die Agent-Benutzer-ID (AUID)
  invoke_agent_details.details.agent_upn	Der Benutzerprinzipalname des Agents (UPN)
  invoke_agent_details.details.agent_blueprint_id	Die Agent-Blueprint-/Anwendungs-ID
  invoke_agent_details.details.tenant_id	Die Mandanten-ID für den Agent
  invoke_agent_details.details.conversation_id	Der Bezeichner für die Unterhaltung oder Sitzung
  invoke_agent_details.endpoint	Der Endpunkt für den Agent-Aufruf
  tenant_details.tenant_id	Der eindeutige Bezeichner für den Mandanten
  request.content	Der Inhalt der Nutzlast, der zum Aufruf an den Agenten gesendet wurde
  request.execution_type	Invocation-Typ, der den Ursprung der Anfrage angibt (zum Beispiel HumanToAgent oder AgentToAgent)
  caller_details.caller_id	Der eindeutige Bezeichner für den Aufrufer
  caller_details.caller_upn	Der Benutzerprinzipalname (UPN) des Aufrufers
  caller_details.caller_user_id	Die Benutzer-ID des Anrufers
  caller_details.tenant_id	Die Mandanten-ID des Anrufers

• Setzen Sie die Eigenschaften in der folgenden Tabelle mit der Methode ExecuteToolScope.start.

  Daten	Beschreibung
  details.tool_name	Der Name des auszuführenden Tools
  details.arguments	Toolargumente/Parameter
  details.tool_call_id	Der eindeutige Bezeichner für den Toolaufruf
  details.tool_type	Der Typ des auszuführenden Tools
  details.endpoint	Wenn ein externer Werkzeugaufruf durchgeführt wird
  agent_details.agent_id	Der eindeutige Bezeichner für den KI-Agent
  agent_details.agent_name	Der lesbare Name des KI-Agenten
  agent_details.agent_auid	Die Agent-Benutzer-ID
  agent_details.agent_upn	Der Benutzerprinzipalname des Agents (UPN)
  agent_details.agent_blueprint_id	Die Agent-Blueprint-/Anwendungs-ID
  agent_details.tenant_id	Mieter-ID des Maklers.
  agent_details.conversation_id	Die Konversations-ID für die Agenten-Invocation.
  tenant_details.tenant_id	Mieter-ID des Maklers.

• Setzen Sie die Eigenschaften in der folgenden Tabelle mit der Methode InferenceScope.start.

  Daten	Beschreibung
  details.operationName	Der Vorgangsname/-typ für die Ableitung
  details.model	Der Modellname/-bezeichner
  details.providerName	Der Name des Anbieters
  agent_details.agent_id	Der eindeutige Bezeichner für den KI-Agent
  agent_details.agent_name	Der lesbare Name des KI-Agenten
  agent_details.agent_auid	Die Agent-Benutzer-ID (AUID)
  agent_details.agent_upn	Der Benutzerprinzipalname des Agents (UPN)
  agent_details.agent_blueprint_id	Die Agent-Blueprint-/Anwendungs-ID
  agent_details.tenant_id	Der eindeutige Bezeichner für den Mandanten
  agent_details.conversation_id	Der Bezeichner für die Unterhaltung oder Sitzung
  tenant_details.tenant_id	Der eindeutige Bezeichner für den Mandanten
  request.content	Der Nutzlastinhalt wurde dem Agenten zur Schlussfolgerung übermittelt
  request.execution_type	Invocation-Typ, der den Ursprung der Anfrage angibt (zum Beispiel HumanToAgent oder AgentToAgent)
  request.source_metadata	Stellen Sie die Kanalinformationen dar

JavaScript

• Eigenschaften, die mit der BaggageBuilder-Klasse gesetzt werden, können von den Eigenschaften der jeweiligen Scopes gesetzt oder überschrieben werden.

• Setzen Sie die Eigenschaften in der folgenden Tabelle mit der Methode InvokeAgentScope.start.

  Daten	Beschreibung
  invokeAgentDetails.agentAUID	Die Agent-Benutzer-ID (AUID)
  invokeAgentDetails.agentBlueprintId	Die Agent-Blueprint-/Anwendungs-ID
  invokeAgentDetails.agentId	Der eindeutige Bezeichner für den KI-Agent
  invokeAgentDetails.agentName	Der lesbare Name des KI-Agenten
  invokeAgentDetails.agentUPN	Der Benutzerprinzipalname des Agents (UPN)
  invokeAgentDetails.conversationId	Der Bezeichner für die Unterhaltung oder Sitzung
  invokeAgentDetails.endpoint.host	Die Host-Adresse des Endpunkts für den Agentenaufruf
  invokeAgentDetails.endpoint.port	Die Portnummer des Endpunkts für den Agentenaufruf
  invokeAgentDetails.endpoint.protocol	Das Protokoll-Endpunkt für den Agentenaufruf
  invokeAgentDetails.request.content	Der Inhalt der Anfragenutzlast für den Agentenaufruf
  invokeAgentDetails.request.executionType	Die Art des Aufrufs der Anfragenutzlast für den Agentenaufruf
  invokeAgentDetails.request.sourceMetadata.name	Kanalinformationen wie (msteams, email, und so weiter)
  invokeAgentDetails.tenantId	Die Mandanten-ID für den Agent
  tenantDetails.tenantId	Der eindeutige Bezeichner für den Mandanten
  callerDetails.callerId	Die eindeutige Identifikatorin für den Aufrufer (aadObjectId)
  callerDetails.callerName	Der Anzeigename des Aufrufers
  callerDetails.callerUpn	Der Benutzerprinzipalname (UPN) des Aufrufers
  callerDetails.tenantId	Die Mandanten-ID des Anrufers

• Setzen Sie die Eigenschaften in der folgenden Tabelle mit der Methode ExecuteToolScope.start.

  Daten	Beschreibung
  details.arguments	Toolargumente/Parameter
  details.endpoint.host	Die Host-Adresse des Endpunkts für die Ausführung des Werkzeugs. Erforderlich, wenn externer Anruf tätigt wird
  details.endpoint.port	Die Portnummer des Endpunkts für die Ausführung des Werkzeugs. Erforderlich, wenn externer Anruf tätigt wird
  details.endpoint.protocol	Das Protokoll des Endpunkts für die Ausführung des Werkzeugs. Erforderlich, wenn externer Anruf tätigt wird
  details.toolCallId	Der eindeutige Bezeichner für den Toolaufruf
  details.toolName	Der Name des auszuführenden Tools
  details.toolType	Der Typ des auszuführenden Tools
  agentDetails.agentId	Der eindeutige Bezeichner für den KI-Agent
  agentDetails.agentName	Der lesbare Name des KI-Agenten
  agentDetails.conversationId	Der Bezeichner für die Unterhaltung oder Sitzung
  tenantDetails.tenantId	Der eindeutige Bezeichner für den Mandanten

• Setzen Sie die Eigenschaften in der folgenden Tabelle mit der Methode InferenceScope.start.

  Daten	Beschreibung
  details.model	Der Modellname/-bezeichner
  details.operationName	Der Vorgangsname/-typ für die Ableitung
  details.providerName	Der Name des Anbieters
  agentDetails.agentId	Der eindeutige Bezeichner für den KI-Agent
  agentDetails.agentName	Der lesbare Name des KI-Agenten
  agentDetails.conversationId	Der Bezeichner für die Unterhaltung oder Sitzung
  tenantDetails.tenantId	Der eindeutige Bezeichner für den Mandanten

.NET

• Eigenschaften, die mit der BaggageBuilder-Klasse gesetzt werden, können von den Eigenschaften der jeweiligen Scopes gesetzt oder überschrieben werden.

• Setzen Sie die Eigenschaften in der folgenden Tabelle mit der Methode InvokeAgentScope.Start.

  Daten	Beschreibung
  invokeAgentDetails.details.agentId	Der eindeutige Bezeichner für den Agent.
  invokeAgentDetails.details.agentName	Anzeigename für den Agenten.
  invokeAgentDetails.details.agentAUID	Azure User ID (AUID) für den Agenten.
  invokeAgentDetails.details.agentUPN	User Principal Name (UPN) für den Agenten.
  invokeAgentDetails.details.agentBlueprintId	Bauplan/Anwendungs-ID für den Agenten.
  invokeAgentDetails.details.tenantId	Mieter-ID des Maklers.
  invokeAgentDetails.endpoint	Endpunkt-URI des zu aufrufenden Agenten.
  tenantDetails.tenantId	Die Kennung des Mieters.
  request.content	Der Nutzlastinhalt wurde dem Agenten geliefert.
  request.executionType	Ausführungstyp, der die Anfrage beschreibt.
  request.sourceMetadata.name	Menschlich lesbarer Name der Quelle. Kanalname.
  conversationId	Die Konversations-ID für die Agenten-Invocation.

• Setzen Sie die Eigenschaften in der folgenden Tabelle mit der Methode ExecuteToolScope.Start.

  Daten	Beschreibung
  details.toolName	Name des aufgerufenen Werkzeugs.
  details.arguments	Serialisierte Argumente wurden an das Tool weitergegeben.
  details.toolCallId	Identifikator für die Werkzeug-Invocation.
  details.toolType	Typklassifizierung für das Werkzeug.
  details.endpoint	Erforderlicher Endpunkt für die Fernausführung des Werkzeugs.
  agentDetails.agentId	Der eindeutige Bezeichner für den Agent.
  agentDetails.agentName	Anzeigename für den Agenten.
  agentDetails.agentAUID	Azure User ID (AUID) für den Agenten.
  agentDetails.agentUPN	User Principal Name (UPN) für den Agenten.
  agentDetails.agentBlueprintId	Bauplan/Anwendungs-ID für den Agenten.
  agentDetails.tenantId	Mieter-ID des Maklers.
  tenantDetails.tenantId	Die Kennung des Mieters.

• Setzen Sie die Eigenschaften in der folgenden Tabelle mit der Methode InferenceScope.Start.

  Daten	Beschreibung
  details.operationName	Telemetriekennung für die Schlussoperation.
  details.model	Modellname, der zur Erfüllung der Inferenzanfrage verwendet wird.
  details.providerName	Der Anbieter, der für den Schlussruf verantwortlich ist.
  agentDetails.agentId	Der eindeutige Bezeichner für den Agent.
  agentDetails.agentName	Anzeigename für den Agenten.
  agentDetails.agentAUID	Azure User ID (AUID) für den Agenten.
  agentDetails.agentUPN	User Principal Name (UPN) für den Agenten.
  agentDetails.agentBlueprintId	Bauplan/Anwendungs-ID für den Agenten.
  agentDetails.tenantId	Mieter-ID des Maklers.
  tenantDetails.tenantId	Die Kennung des Mieters.
  parentId	Für explizite Verwaltung des Elternumfangs. In den meisten Fällen nicht zwingend erforderlich.

Validieren für Store-Publishing

Verwenden Sie Konsolenlogs, um Ihre Observability-Integration für den Agenten vor der Veröffentlichung zu validieren, indem Sie den erforderlichen Aufruf-Agenten, das ausführende Tool und die Inferenz-Scopes implementieren. Vergleiche dann die Logs deines Agenten mit den folgenden Attributlisten, um sicherzustellen, dass alle erforderlichen Attribute vorhanden sind; Erobere Attribute auf jedem Scope oder über den Gepäckbauer und füge optionale Attribute nach eigenem Ermessen hinzu.

Für weitere Informationen zu den Anforderungen an die Ladenveröffentlichung siehe die Richtlinien zur Store-Validierung.

InvokeAgentScope-Attribute

Die folgende Liste fasst die erforderlichen und optionalen Telemetrieattribute zusammen, die beim Starten eines aufgezeichnet werden 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"
    },

ExecuteToolScope-Attribute

Die folgende Liste fasst die erforderlichen und optionalen Telemetrieattribute zusammen, die beim Starten eines aufgezeichnet werden 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"
    },

InferenceScope-Attribute

Die folgende Liste fasst die erforderlichen und optionalen Telemetrieattribute zusammen, die beim Starten eines aufgezeichnet werden 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"
    }

Testen Ihres Agents mit Einblick

Nachdem Sie Observability in Ihrem Agenten implementiert haben, testen Sie, ob Telemetrie korrekt erfasst wird. Befolgen Sie das Testhandbuch, um Ihre Umgebung einzurichten, und konzentrieren Sie sich in erster Linie auf den Abschnitt Observability-Protokolle anzeigen, um zu prüfen, ob ihre Einblick-Implementierung wie erwartet funktioniert.