Agent-Beobachtbarkeit

Installieren Sie die Kern-, Überwachbarkeits- und Laufzeitpakete. Diese Pakete sind für alle Agents erforderlich, die Agent 365 Observability verwenden.

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

Wenn Ihr Agent das Hostingpaket Microsoft Agents Hosting verwendet, installieren Sie das Hostingintegrationspaket. Es stellt Middleware bereit, die automatisch Baggage und Scopes von TurnContext übernimmt, einschließlich der Token-Zwischenspeicherung für den Observability-Exporter.

pip install microsoft-agents-a365-observability-hosting

Wenn Ihr Agent eines der unterstützten KI-Frameworks verwendet, installieren Sie die entsprechende Erweiterung für die automatische Instrumentierung, um Telemetrie automatisch ohne manuellen Instrumentierungscode zu erfassen. Konfigurationsdetails finden Sie unter "Automatische Instrumentierung".

# For Semantic Kernel
pip install microsoft-agents-a365-observability-extensions-semantic-kernel

# For OpenAI Agents SDK
pip install microsoft-agents-a365-observability-extensions-openai

# For Microsoft Agent Framework
pip install microsoft-agents-a365-observability-extensions-agent-framework

# For LangChain
pip install microsoft-agents-a365-observability-extensions-langchain

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

Installieren Sie das Beobachtbarkeits- und Laufzeit-Kernpaket. Alle Agents, die Agent 365 Observability verwenden, benötigen dieses Paket.

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

Wenn Ihr Agent das NuGet-Paket Microsoft.Agents.A365.Observability.Hosting verwendet, installieren Sie das Hosting-Integrationspaket. Es stellt Middleware bereit, die das Gepäck automatisch aus dem TurnContext auffüllt und die Tokenzwischenspeicherung für den Observability-Exporter umfasst.

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

Wenn Ihr Agent eines der unterstützten KI-Frameworks verwendet, installieren Sie die entsprechende Erweiterung für die automatische Instrumentierung, um Telemetrie automatisch ohne manuellen Instrumentierungscode zu erfassen. Konfigurationsdetails finden Sie unter "Automatische Instrumentierung".

// For Semantic Kernel
dotnet add package Microsoft.Agents.A365.Observability.Extensions.SemanticKernel

// For OpenAI
dotnet add package Microsoft.Agents.A365.Observability.Extensions.OpenAI

// For Agent Framework
dotnet add package Microsoft.Agents.A365.Observability.Extensions.AgentFramework

Setze die ENABLE_A365_OBSERVABILITY_EXPORTER Umgebungsvariable auf true für Beobachtbarkeit. Diese Einstellung exportiert Protokolle in den Dienst und setzt voraus, dass token_resolver bereitgestellt wird. Ansonsten wird der Konsolen-Exporter verwendet.

from microsoft_agents_a365.observability.core import configure

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

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

Die Tokenlöserfunktion ist von der Protokollierung in der Konsole ausgeschlossen.

Sie können das Exporterverhalten anpassen, indem Sie eine Agent365ExporterOptions Instanz an exporter_options. Wenn exporter_options bereitgestellt wird, hat es Vorrang vor den Parametern token_resolver und cluster_category.

from microsoft_agents_a365.observability.core import configure, Agent365ExporterOptions

configure(
    service_name="my-agent-service",
    service_namespace="my.namespace",
    exporter_options=Agent365ExporterOptions(
        cluster_category="prod",
        token_resolver=token_resolver,
    ),
    suppress_invoke_agent_input=True,
)

In der folgenden Tabelle werden die optionalen Parameter für configure() beschrieben.

Die folgende Tabelle beschreibt die optionalen Eigenschaften für Agent365ExporterOptions.

Setze die ENABLE_A365_OBSERVABILITY_EXPORTER Umgebungsvariable auf true für Beobachtbarkeit. Diese Einstellung exportiert Logs in den Service. Ansonsten wird der Konsolen-Exporter verwendet.

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

Alternativ zu Umweltvariablen kann man die Observabilität programmatisch konfigurieren, indem man einen Konfigurationsanbieter verwendet.

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

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

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

builder.start();

Du kannst auch einen benutzerdefinierten Logger bereitstellen, der die Schnittstelle ILogger implementiert (info, warn, error, event). Geben Sie es dem Konstrukteur weiter, indem Sie withCustomLogger verwenden.

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

builder.start();

Legen Sie EnableAgent365Exporter auf true in appsettings.json fest.

In Program.csAgent365ExporterOptions zur Dienstesammlung hinzufügen. Diese Änderung konfiguriert den Stellvertreter, den der Tracexporter zum Abrufen des Tokens verwendet.

Fügen Sie beobachtbarkeitsbezogene Abhängigkeiten hinzu, indem Sie verwenden AddA365Tracing().

using Microsoft.Agents.A365.Observability.Runtime;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Exporters;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton(sp =>
    {
        return new Agent365ExporterOptions
        {
            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();

Sie können das Exporterverhalten anpassen, indem Sie einen Konfigurations-Delegaten und einen Exporter-Typ an AddA365Tracing() übergeben.

builder.AddA365Tracing(
    configure: tracingBuilder =>
    {
        // Use the builder to add extensions (e.g., WithSemanticKernel(), WithOpenAI())
    },
    agent365ExporterType: Agent365ExporterType.Agent365ExporterAsync
);

In der folgenden Tabelle beschreibt die optionalen Eigenschaften für Agent365ExporterOptions.

from microsoft_agents_a365.observability.core import BaggageBuilder

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

Mithilfe des populate Hilfsprogramms im microsoft-agents-a365-observability-hosting Paket können Sie das BaggageBuilder automatisch von TurnContext ausfüllen. Dieses Tool extrahiert automatisch Anrufer-, Agenten-, Mandanten-, Kommunikationskanal- und Unterhaltungsdetails aus der Aktivität.

from microsoft_agents.hosting.core.turn_context import TurnContext
from microsoft_agents_a365.observability.core import BaggageBuilder
from microsoft_agents_a365.observability.hosting.scope_helpers.populate_baggage import populate

builder = BaggageBuilder()
populate(builder, turn_context)

with builder.build():
    # Baggage is auto-populated from the TurnContext activity
    pass

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

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

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

Sie können die BaggageBuilder aus dem ITurnContext automatisch ausfüllen, indem Sie die Erweiterungsmethode FromTurnContext im Paket Microsoft.Agents.A365.Observability.Hosting verwenden. Diese Methode extrahiert automatisch Anrufer-, Agent-, Mandanten-, Kanal- und Unterhaltungsdetails aus der Aktivität.

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

using var baggageScope = new BaggageBuilder()
    .FromTurnContext(turnContext)
    .Build();

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

Für das digitale Arbeiterszenario, wenn Ihr Agent das Microsoft Agent 365 Observability Hosting Library-Paket verwendet, verwenden Sie AgenticTokenCache, um die Tokenzwischenspeicherung automatisch zu handhaben. Registrieren Sie das Token einmal pro Agent und Mandant während eines Aktivitäts-Handlers, und übergeben Sie es in Ihrer Observability-Konfiguration cache.get_observability_token als token_resolver.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.hosting.token_cache_helpers import (
    AgenticTokenCache,
    AgenticTokenStruct,
)
from microsoft_agents_a365.runtime import get_observability_authentication_scope

# Create a shared cache instance
token_cache = AgenticTokenCache()

# Use the cache as your token resolver in configure()
configure(
    service_name="my-agent-service",
    service_namespace="my.namespace",
    token_resolver=token_cache.get_observability_token,
)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    token_cache.register_observability(
        agent_id="agent-456",
        tenant_id="tenant-123",
        token_generator=AgenticTokenStruct(
            authorization=AGENT_APP.auth,
            turn_context=context,
        ),
        observability_scopes=get_observability_authentication_scope(),
    )

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

Stellen Sie einen Tokenlöser bereit, indem Sie sich bei einer TokenResolver registrieren. Der Delegierte empfängt agentId und tenantId und gibt das Authentifizierungstoken zurück.

using Microsoft.Agents.A365.Observability.Runtime.Tracing.Exporters;

builder.Services.AddSingleton(sp =>
    {
        return new Agent365ExporterOptions
        {
            TokenResolver = async (agentId, tenantId) =>
            {
                // Implement your token retrieval logic here
                return await GetTokenAsync(agentId, tenantId);
            }
        };
    });

Für das Szenario des digitalen Arbeiters: Wenn Ihr Agent das Microsoft.Agents.A365.Observability.Hosting NuGet-Paket verwendet, nutzen Sie die AddAgenticTracingExporter() Methode, um das Token-Caching automatisch durch Dependency Injection zu handhaben.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

Registrieren Sie das Token in der Agent-Anwendung.

using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.App.UserAuth;
using Microsoft.Extensions.Logging;
using Microsoft.Agents.A365.Observability.Hosting.Caching;
using Microsoft.Agents.A365.Observability.Runtime.Common;
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,
                    authHandlerName: "AGENTIC"
                ),
                EnvironmentUtils.GetObservabilityAuthenticationScope()
            );
        }
        catch (Exception ex)
        {
            _logger.LogWarning($"Error registering for observability: {ex.Message}");
        }
    }
}

Installieren des Pakets.

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

Konfigurieren der Beobachtbarkeit

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.extensions.semantickernel.trace_instrumentor 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

Semantischer Kernel wird mit JavaScript nicht unterstützt.

Abhängigkeiten zur Serviceauflistung hinzufügen.

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

builder.AddA365Tracing(configure: config => config.WithSemanticKernel());

Setzen Sie AgentId und TenantId durch Verwendung von BaggageBuilder. Stellen Sie sicher, dass die ID, die Sie beim Erstellen eines ChatCompletionAgent verwenden, mit der Agenten-ID übereinstimmt, die Sie an BaggageBuilder weitergeben.

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

Installieren des Pakets.

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

Konfigurieren der Beobachtbarkeit

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.extensions.openai 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

Installieren des Pakets.

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

Konfigurieren der Beobachtbarkeit

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

Abhängigkeiten zur Serviceauflistung hinzufügen.

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

builder.AddA365Tracing(configure: config => config.WithOpenAI());

Setzen Sie AgentId und TenantId durch Verwendung von BaggageBuilder. Für Toolaufrufe starten Sie einen Trace, indem Sie Trace() auf einer ChatToolCall-Instanz verwenden.

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

Installieren des Pakets.

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

Konfigurieren der Beobachtbarkeit

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

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

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

Agent Framework wird mit JavaScript nicht unterstützt.

Abhängigkeiten zur Serviceauflistung hinzufügen.

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

builder.AddA365Tracing(configure: config => config.WithAgentFramework());

Setzen Sie AgentId und TenantId durch Verwendung 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();
    }
}

Installieren des Pakets.

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

Konfigurieren der Beobachtbarkeit

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

Installieren des Pakets.

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

Konfigurieren der Beobachtbarkeit

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

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

sdk.start();

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

// Your LangChain code is now automatically traced

LangChain wird mit .NET nicht unterstützt.

from microsoft_agents_a365.observability.core import (
    InvokeAgentScope,
    InvokeAgentScopeDetails,
    AgentDetails,
    CallerDetails,
    UserDetails,
    Channel,
    Request,
    ServiceEndpoint,
)

agent_details = AgentDetails(
    agent_id="agent-456",
    agent_name="My Agent",
    agent_description="An AI agent powered by Azure OpenAI",
    agentic_user_id="auid-123",
    agentic_user_email="agent@contoso.com",
    agent_blueprint_id="blueprint-789",
    tenant_id="tenant-123",
)

scope_details = InvokeAgentScopeDetails(
    endpoint=ServiceEndpoint(hostname="myagent.contoso.com", port=443),
)

request = Request(
    content="User asks a question",
    session_id="session-42",
    conversation_id="conv-xyz",
    channel=Channel(name="msteams"),
)

caller_details = CallerDetails(
    user_details=UserDetails(
        user_id="user-123",
        user_email="jane.doe@contoso.com",
        user_name="Jane Doe",
    ),
)

with InvokeAgentScope.start(request, scope_details, agent_details, caller_details):
    # Perform agent invocation logic
    response = call_agent(...)

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

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: "agent-456",
            agentName: "MyAgent",
            agentDescription: "Handles user requests.",
            agenticUserId: "auid-123",
            agenticUserEmail: "agent@contoso.com",
            agentBlueprintId: "blueprint-789",
            tenantId: "tenant-123"
        );

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

        var request = new Request(
            content: userInput,
            sessionId: "session-abc",
            channel: new Channel("msteams"),
            conversationId: "conv-xyz"
        );

        var callerDetails = new CallerDetails(
            userDetails: new UserDetails(
                userId: "user-123",
                userEmail: "jane.doe@contoso.com",
                userName: "Jane Doe"
            )
        );

        // Start the scope
        using var scope = InvokeAgentScope.Start(
            request: request,
            scopeDetails: scopeDetails,
            agentDetails: agentDetails,
            callerDetails: callerDetails
        );

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

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

        var output = $"Processed: {userInput}";
        scope.RecordOutputMessages(new[] { output });

        return new AgentResponse { Content = output };
    }
}

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

from microsoft_agents_a365.observability.core import (
    ExecuteToolScope,
    ToolCallDetails,
    Request,
    ServiceEndpoint,
)

# Use the same agent_details and request instances from the InvokeAgentScope example above

tool_details = ToolCallDetails(
    tool_name="summarize",
    tool_type="function",
    tool_call_id="tc-001",
    arguments="{'text': '...'}",
    description="Summarize provided text",
    endpoint=ServiceEndpoint(hostname="tools.contoso.com", port=8080),
)

with ExecuteToolScope.start(request, tool_details, agent_details) as scope:
    result = run_tool(tool_details)
    scope.record_response(result)

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

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

// Use the same agentDetails and request instances from the InvokeAgentScope example above

var toolCallDetails = new ToolCallDetails(
    toolName: "summarize",
    arguments: "{\"text\": \"...\"}",
    toolCallId: "tc-001",
    description: "Summarize provided text",
    toolType: "function",
    endpoint: new Uri("https://tools.contoso.com:8080")
);

using var scope = ExecuteToolScope.Start(
    request: request,
    details: toolCallDetails,
    agentDetails: agentDetails
);

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

scope.RecordResponse("{\"summary\": \"The text was summarized.\"}");

from microsoft_agents_a365.observability.core import (
    InferenceScope,
    InferenceCallDetails,
    InferenceOperationType,
)

# Use the same agent_details and request instances from the InvokeAgentScope example above

inference_details = InferenceCallDetails(
    operationName=InferenceOperationType.CHAT,
    model="gpt-4o-mini",
    providerName="azure-openai",
    inputTokens=123,
    outputTokens=456,
    finishReasons=["stop"],
)

with InferenceScope.start(request, inference_details, agent_details) as scope:
    completion = call_llm(...)
    scope.record_output_messages([completion.text])
    scope.record_input_tokens(completion.usage.input_tokens)
    scope.record_output_tokens(completion.usage.output_tokens)

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

using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

// Use the same agentDetails and request instances from the InvokeAgentScope example above

var inferenceDetails = new InferenceCallDetails(
    operationName: InferenceOperationType.Chat,
    model: "gpt-4o-mini",
    providerName: "Azure OpenAI",
    inputTokens: 123,
    outputTokens: 456,
    finishReasons: new[] { "stop" }
);

using var scope = InferenceScope.Start(
    request: request,
    details: inferenceDetails,
    agentDetails: agentDetails
);

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

scope.RecordOutputMessages(new[] { "AI response message" });
scope.RecordInputTokens(123);
scope.RecordOutputTokens(456);

from microsoft_agents_a365.observability.core import (
    OutputScope,
    Response,
    SpanDetails,
)

# Use the same agent_details and request instances from the InvokeAgentScope example above

# Get the parent context from the originating scope
parent_context = invoke_scope.get_context()

response = Response(messages=["Here is your organized inbox with 15 urgent emails."])

with OutputScope.start(
    request,
    response,
    agent_details,
    span_details=SpanDetails(parent_context=parent_context),
):
    # Output messages are recorded automatically from the response
    pass

Für JavaScript noch nicht verfügbar.

using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

// Use the same agentDetails and request instances from the InvokeAgentScope example above

// Get the parent context from the originating scope
var parentContext = invokeScope.GetActivityContext();

var response = new Response(new[] { "Here is your organized inbox with 15 urgent emails." });

using var scope = OutputScope.Start(
    request: request,
    response: response,
    agentDetails: agentDetails,
    spanDetails: new SpanDetails(parentContext: parentContext)
);
// Output messages are recorded automatically from the response

Legen Sie die Umgebungsvariable ENABLE_A365_OBSERVABILITY_EXPORTER auf false fest. Diese Einstellung exportiert Bereiche (Ablaufverfolgungen) in die Konsole.

Legen Sie die Umgebungsvariable ENABLE_A365_OBSERVABILITY_EXPORTER auf false fest. Diese Einstellung exportiert Bereiche (Ablaufverfolgungen) in die Konsole.

Legen Sie EnableAgent365Exporter auf false in appsettings.json fest. Diese Einstellung exportiert Bereiche (Ablaufverfolgungen) in die Konsole.

• Eigenschaften, die Sie mit der BaggageBuilder-Klasse festlegen, könnten von den Eigenschaften der jeweiligen Bereiche festgelegt 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 (UPN) des Agents
  invoke_agent_details.details.agent_blueprint_id	Die Blueprint-/Anwendungs-ID des Agents
  invoke_agent_details.details.tenant_id	Die Mandanten-ID für den Agenten
  invoke_agent_details.details.conversation_id	Der Bezeichner für das Gespräch oder die 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 Nutzlastinhalt, der zum Aufruf an den Agenten gesendet wird
  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 Tools, das ausgeführt wird
  details.arguments	Werkzeugargumente oder -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 (UPN) des Agents
  agent_details.agent_blueprint_id	Der Agenten-Blueprint oder die Anwendungs-ID
  agent_details.tenant_id	Die Mandanten-ID des Agents.
  agent_details.conversation_id	Die Konversationskennung für den Agentenaufruf.
  tenant_details.tenant_id	Die Mandanten-ID des Agents.

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

  Daten	Beschreibung
  details.operationName	Der Operationsname oder -typ für die Schlussfolgerung
  details.model	Der Modellname oder die Kennung
  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 (UPN) des Agents
  agent_details.agent_blueprint_id	Der Agenten-Blueprint oder die Anwendungs-ID
  agent_details.tenant_id	Der eindeutige Bezeichner für den Mandanten
  agent_details.conversation_id	Der Bezeichner für das Gespräch oder die Sitzung
  tenant_details.tenant_id	Der eindeutige Bezeichner für den Mandanten
  request.content	Der Nutzlastinhalt wurde dem Agent für Rückschlüsse ü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

• Eigenschaften, die du mit der BaggageBuilder-Klasse setzt, können von den Eigenschaften der jeweiligen Scopes festgelegt 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 Blueprint-/Anwendungs-ID des Agents
  invokeAgentDetails.agentId	Der eindeutige Bezeichner für den KI-Agent
  invokeAgentDetails.agentName	Der lesbare Name des KI-Agenten
  invokeAgentDetails.agentUPN	Der Benutzerprinzipalname (UPN) des Agents
  invokeAgentDetails.conversationId	Der Bezeichner für das Gespräch oder die 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 Agent-Aufruf
  invokeAgentDetails.request.executionType	Die Art des Aufrufs der Anfragenutzlast für den Agent-Aufruf
  invokeAgentDetails.request.sourceMetadata.name	Kanalinformationen wie (msteams, email, und so weiter)
  invokeAgentDetails.tenantId	Die Mandanten-ID für den Agenten
  tenantDetails.tenantId	Der eindeutige Bezeichner für den Mandanten
  callerDetails.callerId	Der eindeutige Identifikator für den Aufrufer (aadObjectId)
  callerDetails.callerName	Der Anzeigename des Anrufers
  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	Werkzeugargumente oder -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 Tools, das ausgeführt wird
  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 das Gespräch oder die 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 oder die Kennung
  details.operationName	Der Operationsname oder -typ für die Schlussfolgerung
  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 das Gespräch oder die Sitzung
  tenantDetails.tenantId	Der eindeutige Bezeichner für den Mandanten

• Eigenschaften, die du mit der BaggageBuilder-Klasse setzt, können von den Eigenschaften der jeweiligen Scopes festgelegt 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 Benutzer-ID (AUID) für den Agent.
  invokeAgentDetails.details.agentUPN	User Principal Name (UPN) für den Agenten.
  invokeAgentDetails.details.agentBlueprintId	Bauplan/Anwendungs-ID für den Agenten.
  invokeAgentDetails.details.tenantId	Die Mandanten-ID des Agents.
  invokeAgentDetails.endpoint	Endpunkt-URI des zu aufrufenden Agenten.
  tenantDetails.tenantId	Die Kennung des Mieters.
  request.content	Der Nutzlastinhalt, der dem Agenten bereitgestellt wird.
  request.executionType	Ausführungstyp, der die Anfrage beschreibt.
  request.sourceMetadata.name	Menschlich lesbarer Name der Quelle. Kanalname.
  conversationId	Die Konversationskennung für den Agentenaufruf.

• 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 den Werkzeugaufruf.
  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 Benutzer-ID (AUID) für den Agent.
  agentDetails.agentUPN	User Principal Name (UPN) für den Agenten.
  agentDetails.agentBlueprintId	Bauplan/Anwendungs-ID für den Agenten.
  agentDetails.tenantId	Die Mandanten-ID des Agents.
  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 den Inferenzvorgang.
  details.model	Modellname, der zur Erfüllung der Inferenzanfrage verwendet wird.
  details.providerName	Der Anbieter, der für den Inferenzaufruf verantwortlich ist.
  agentDetails.agentId	Der eindeutige Bezeichner für den Agent.
  agentDetails.agentName	Anzeigename für den Agenten.
  agentDetails.agentAUID	Azure Benutzer-ID (AUID) für den Agent.
  agentDetails.agentUPN	User Principal Name (UPN) für den Agenten.
  agentDetails.agentBlueprintId	Bauplan/Anwendungs-ID für den Agenten.
  agentDetails.tenantId	Die Mandanten-ID des Agents.
  tenantDetails.tenantId	Die Kennung des Mieters.
  parentId	Für die explizite Verwaltung des übergeordneten Bereichs. In den meisten Fällen nicht zwingend erforderlich.