Az ügynök megfigyelhetősége

Fontos

A Microsoft Agent 365-höz való korai hozzáféréshez a Frontier előzetes verziójának részeként kell lennie. A Frontier közvetlenül összekapcsolja Önt a Microsoft legújabb AI-innovációival. Gyakorlati ismereteket szerezhet az úttörő funkciókról, megoszthatja észrevételeit a termékcsapatokkal, és segíthet a mesterséges intelligencia jövőjének alakításában. A Frontier előzetesekre az ügyfélszerződések meglévő előzetes feltételei vonatkoznak. Mivel ezek a funkciók még fejlesztés alatt állnak, rendelkezésre állásuk és képességeik idővel változhatnak."

Az Ügynök 365 ökoszisztémában való részvételhez hozzá kell adnia az Ügynök 365 Megfigyelhetőségi képességeket az ügynökhöz. Az Agent 365 Observability az OpenTelemetryre (OTel) épül, és egységes keretrendszert biztosít a telemetriai adatok egységes és biztonságos rögzítéséhez az összes ügynökplatformon. A szükséges összetevő implementálásával lehetővé teszi az informatikai rendszergazdák számára, hogy megfigyeljék az ügynök tevékenységét a Microsoft Felügyeleti központban (MAC), és lehetővé teszik a biztonsági csapatok számára, hogy a Defendert és a Purview-t használják a megfelelőséghez és a fenyegetésészleléshez.

Fő előnyök

Teljes körű láthatóság: Átfogó telemetriai adatok rögzítése minden ügynökhíváshoz, beleértve a munkameneteket, az eszközhívásokat és a kivételeket is, így teljes nyomon követhetőséget biztosít a platformok között.
Biztonság és megfelelőség engedélyezése: Egyesített naplózási naplók becsatornázása a Defenderbe és a Purview-ba, lehetővé téve a speciális biztonsági forgatókönyveket és a megfelelőségi jelentéskészítést az ügynök számára.
Platformfüggetlen rugalmasság: OTel-szabványokra épít, és támogatja a különböző futtatókörnyezeteket és platformokat, például a Copilot Studiót, az Foundryt és a jövőbeli ügynök-keretrendszereket.
Működési hatékonyság rendszergazdáknak: Központosított megfigyelhetőséget biztosít a MAC-ben, csökkenti a hibaelhárítási időt, és javítja az irányítást szerepköralapú hozzáférés-vezérléssel az ügynököt kezelő informatikai csapatok számára.

Installation

Ezekkel a parancsokkal telepítheti az Ügynök 365 által támogatott nyelvek megfigyelhetőségi moduljait.

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

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

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

Konfiguráció

A megfigyelhetőséghez szükséges környezeti változók a következők:

Környezeti változó	Description
`ENABLE_OBSERVABILITY=true`	Jelölő a nyomkövetés engedélyezéséhez/letiltásához. Alapértelmezés szerint `false`
`ENABLE_A365_OBSERVABILITY_EXPORTER=true`	`True` naplókat exportál szolgáltatásunkhoz. Ellenkező esetben visszaesik a konzolexportálóhoz

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

Zárja ki a token feloldót a konzolra való naplózásból.

A megfigyelhetőséghez szükséges környezeti változók a következők:

Környezeti változó	Description
`ENABLE_OBSERVABILITY=true`	Jelölő a nyomkövetés engedélyezéséhez/letiltásához. Alapértelmezés szerint `false`
`ENABLE_A365_OBSERVABILITY_EXPORTER=true`	`True` naplókat exportál szolgáltatásunkhoz. Ellenkező esetben visszaesik a konzolexportálóhoz

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

Be van EnableAgent365Exporter állítvatrue.appsettings.json

Adja Program.cshozzá Agent365ExporterOptions a szolgáltatásgyűjteményhez. Ez a módosítás konfigurálja azt a delegáltat, amelyet a nyomkövetési exportőr használ a jogkivonat lekéréséhez.

Használja a AddA365Tracing() parancsot a megfigyelhetőséggel kapcsolatos függőségek hozzáadásához.

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

Poggyászattribútumok

A BaggageBuilder olyan környezetfüggő információk beállítására használható, amelyek egy kérelem összes részletein átáramlanak. Az SDK a SpanProcessor meglévő attribútumok felülírása nélkül az összes nem létező poggyászbejegyzést átmásolja az újonnan elindított tartományokba.

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

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

Jogkivonat-feloldó

Az Agent 365-exportőr használatakor meg kell adnia egy jogkivonat-feloldó függvényt, amely hitelesítési jogkivonatot ad vissza. Ha az Ügynök 365 Megfigyelhetőségi SDK-t az Ügynök üzemeltetési keretrendszerével használja, az ügynöktevékenységekből származó jogkivonatokat TurnContext hozhat létre

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

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

Adja hozzá az agentic token feloldót a szolgáltatásgyűjteményhez.

using Microsoft.Agents.A365.Observability;

builder.Services.AddAgenticTracingExporter();

Az ügynökalkalmazásban regisztrálja a tokent.

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

Automatikus kialakítás

Az automatikus rendszerállapot automatikusan figyeli az ügynöki keretrendszerek (SDK-k) meglévő telemetriai jeleit a nyomkövetésekhez, és továbbítja őket az Agent 365 megfigyelhetőségi szolgáltatásnak. Ez szükségtelenné teszi, hogy a fejlesztők manuálisan írjanak monitorozási kódot, egyszerűsítse a telepítést és biztosítsa a konzisztens teljesítménykövetést.

Az automatikus rendszerezés több SDK-ban és platformon is támogatott:

Plattform	Támogatott SDK-k / keretrendszerek
.NET	Szemantikus kernel, OpenAI, Ügynök-keretrendszer
Python	Szemantikus kernel, OpenAI, Ügynök-keretrendszer, LangChain
Node.js	OpenAI

Megjegyzés:

Az automatikus instrumentálás támogatása platformonként és SDK-implementációnként változik.

Szemantikus kernel

Az automatikus instrumentáláshoz a "baggage builder" használata szükséges. Ügynökazonosító és bérlőazonosító beállítása a BaggageBuilder eszközzel.

A csomag telepítése

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

Megfigyelhetőség konfigurálása

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

Függőségek hozzáadása a szolgáltatásgyűjteményhez.

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

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

Állítsa be a AgentId és TenantId elemeket a BaggageBuilder segítségével. Győződjön meg arról, hogy a ChatCompletionAgent létrehozásakor használt azonosító megegyezik az ügynökazonosítóval, amelyet a BaggageBuilder-hez adtak meg.

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

Az automatikus instrumentáláshoz a "baggage builder" használata szükséges. Ügynökazonosító és bérlőazonosító beállítása a BaggageBuilder eszközzel.

Telepítse a csomagot.

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

Konfigurálja a megfigyelhetőséget.

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

A csomag telepítése

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

Megfigyelhetőség konfigurálása

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

Függőségek hozzáadása a szolgáltatásgyűjteményhez.

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

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

Állítsa be a AgentId és TenantId elemeket a BaggageBuilder segítségével. Az eszközhívások esetén indítson nyomkövetést Trace() egy ChatToolCall példányon.

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

Ügynök-keretrendszer

Az automatikus instrumentáláshoz a "baggage builder" használata szükséges. Ügynök- és bérlőazonosító beállítása a BaggageBuilder használatával.

A csomag telepítése

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

Megfigyelhetőség konfigurálása

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

Függőségek hozzáadása a szolgáltatásgyűjteményhez.

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

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

Állítsa be a AgentId és TenantId elemeket a BaggageBuilder segítségével.

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

Az automatikus kialakításhoz a poggyászszerkesztő használata szükséges. Ügynökazonosító és bérlőazonosító beállítása a BaggageBuilder eszközzel.

Telepítse a csomagot.

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

Megfigyelhetőség konfigurálása

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

Manuális instrumentálás

Az Ügynök 365 megfigyelhetőségi SDK az ügynök belső működésének megértésére használható. Az SDK három elindítható hatókört biztosít: InvokeAgentScope, ExecuteToolScopeés InferenceScope.

Ügynök meghívása

Ezt a hatókört az ügynökfolyamat elején kell használni. Az ügynök hatókörének meghívásával olyan tulajdonságokat rögzíthet, mint az aktuálisan meghívott ügynök, az ügynök felhasználói adatai stb.

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

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

Eszköz végrehajtása

Az alábbi példák bemutatják, hogyan alakíthatja az ügynök eszközvégrehajtását megfigyelhető nyomon követéssel a telemetriai adatok monitorozási és naplózási célú rögzítéséhez.

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)

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;

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

Következtetés

Az alábbi példák bemutatják, hogyan lehet az AI-modellek következtetési hívásait megfigyelhető nyomon követéssel rögzíteni a tokenhasználat, a modell részletei és a válasz metaadatainak rögzítéséhez.

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

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

Helyi érvényesítés

Állítsa a környezeti változót ENABLE_A365_OBSERVABILITY_EXPORTER a következőre false: . Ez az exportálás nyomkövetéseket küld a konzolra.

Az ügynök megfigyelhetőségének tesztelése

Miután implementálta a megfigyelhetőséget az ügynökben, tesztelje, hogy a telemetriai adatok helyesen kerülnek-e rögzítésre. Kövesse a tesztelési útmutatót a környezet beállításához, majd elsősorban a Megfigyelhetőségi naplók megtekintése szakaszra összpontosítva ellenőrizze, hogy a megfigyelhetőségi implementáció a várt módon működik-e.

Visszacsatolás

Hasznos volt ez az oldal?

Last updated on 2025-11-20

Megosztás:

Az ügynök megfigyelhetősége

Fő előnyök

Installation

Konfiguráció

Poggyászattribútumok

Jogkivonat-feloldó

Automatikus kialakítás

Szemantikus kernel

OpenAI

Ügynök-keretrendszer

LangChain-keretrendszer

Manuális instrumentálás

Ügynök meghívása

Eszköz végrehajtása

Következtetés

Helyi érvényesítés

Az ügynök megfigyelhetőségének tesztelése

Visszacsatolás

További források