Παρατηρησιμότητα παράγοντα

Σημαντικό

Πρέπει να είστε μέρος του προγράμματος προεπισκόπησης Σύνορα για να αποκτήσετε πρώιμη πρόσβαση στον Παράγοντα Microsoft 365. Η Frontier σάς συνδέει απευθείας με τις τελευταίες καινοτομίες τεχνητής νοημοσύνης της Microsoft. Οι προεπισκοπήσεις για τα σύνορα υπόκεινται στους υφιστάμενους όρους προεπισκόπησης των συμβάσεων πελατών σας. Καθώς αυτές οι δυνατότητες είναι ακόμα σε εξέλιξη, η διαθεσιμότητά τους και οι δυνατότητές τους ενδέχεται να αλλάξουν με την πάροδο του χρόνου.

Για να συμμετέχετε στο οικοσύστημα του Παράγοντα 365, πρέπει να προσθέσετε τον Παράγοντα 365 Δυνατότητες τήρησης στον πράκτορά σας. Το Agent 365 Observability βασίζεται στο OpenTelemetry (OTel) και παρέχει ένα ενοποιημένο πλαίσιο για την καταγραφή της τηλεμετρίας με συνέπεια και ασφάλεια σε όλες τις πλατφόρμες αντιπροσώπων. Με την υλοποίηση αυτού του απαιτούμενου στοιχείου, επιτρέπετε στους διαχειριστές IT να παρακολουθούν τη δραστηριότητα του παράγοντα σας στο Κέντρο διαχείρισης της Microsoft (MAC) και να επιτρέπετε στις ομάδες ασφαλείας να χρησιμοποιούν το Defender και το Purview για συμμόρφωση και εντοπισμό απειλών.

Βασικά πλεονεκτήματα

Ορατότητα από άκρο σε άκρο: Καταγράψτε ολοκληρωμένη τηλεμετρία για κάθε κλήση παράγοντα, συμπεριλαμβανομένων περιόδων λειτουργίας, κλήσεων εργαλείων και εξαιρέσεων, δίνοντάς σας πλήρη ιχνηλασιμότητα σε όλες τις πλατφόρμες.
Ασφάλεια και ενεργοποίηση συμμόρφωσης: Τροφοδοσία ενοποιημένων αρχείων καταγραφής ελέγχου στο Defender και το Purview, ενεργοποιώντας σύνθετα σενάρια ασφαλείας και αναφορές συμμόρφωσης για τον πράκτορά σας.
Ευελιξία μεταξύ πλατφορμών: Αξιοποιήστε τα πρότυπα OTel και υποστηρίξτε διαφορετικούς χρόνους εκτέλεσης και πλατφόρμες, όπως το Copilot Studio, το Foundry και μελλοντικά πλαίσια αντιπροσώπων.
Λειτουργική αποτελεσματικότητα για διαχειριστές: Παροχή κεντρικής παρατηρησιμότητας στο MAC, μείωση του χρόνου αντιμετώπισης προβλημάτων και βελτίωση της διαχείρισης με ελέγχους πρόσβασης βάσει ρόλων για ομάδες IT που διαχειρίζονται τον πράκτορά σας.

Εγκατάσταση

Χρησιμοποιήστε αυτές τις εντολές για να εγκαταστήσετε τις λειτουργικές μονάδες παρατηρησιμότητας για τις γλώσσες που υποστηρίζονται από τον παράγοντα 365.

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

Ρύθμιση παραμέτρων

Οι μεταβλητές περιβάλλοντος που απαιτούνται για τη δυνατότητα παρατήρησης είναι οι εξής:

Μεταβλητή περιβάλλοντος	Περιγραφή
`ENABLE_OBSERVABILITY=true`	Σημαία για ενεργοποίηση/απενεργοποίηση ανίχνευσης. Από προεπιλογή
`ENABLE_A365_OBSERVABILITY_EXPORTER=true`	`True` εξαγωγή αρχείων καταγραφής στην υπηρεσία μας. Διαφορετικά, πέφτει πίσω στον εξαγωγέα κονσόλας

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

Εξαίρεση επίλυσης διακριτικών για σύνδεση στην κονσόλα.

Οι μεταβλητές περιβάλλοντος που απαιτούνται για τη δυνατότητα παρατήρησης είναι οι εξής:

Μεταβλητή περιβάλλοντος	Περιγραφή
`ENABLE_OBSERVABILITY=true`	Σημαία για ενεργοποίηση/απενεργοποίηση ανίχνευσης. Από προεπιλογή
`ENABLE_A365_OBSERVABILITY_EXPORTER=true`	`True` εξαγωγή αρχείων καταγραφής στην υπηρεσία μας. Διαφορετικά, εμπίπτει πίσω στον εξαγωγέα κονσόλας

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

Ρύθμιση παραμέτρων του true στο appsettings.json

Στο Program.cs, προσθέστε Agent365ExporterOptions το στη συλλογή υπηρεσίας. Αυτή η αλλαγή ρυθμίζει τις παραμέτρους της παραπομπής που χρησιμοποιεί ο εξαγωγέας ανίχνευσης για την ανάκτηση του διακριτικού.

Προσθέστε εξαρτήσεις που σχετίζονται με την παρατηρησιμότητα χρησιμοποιώντας το 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();

Χαρακτηριστικά εικόνας

Χρησιμοποιήστε το για να ορίσετε BaggageBuilder πληροφορίες βάσει περιεχομένου που ρέουν σε όλα τα τμήματα μιας αίτησης. Το SDK εφαρμόζει ένα SpanProcessor αντίγραφο όλων των καταχωρήσεων καμίας αποσκευής σε τμήματα που μόλις ξεκίνησαν, χωρίς να αντικαθιστά υπάρχοντα χαρακτηριστικά.

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.

Επίλυση διακριτικού

Όταν χρησιμοποιείτε τον παράγοντα εξαγωγέα 365, πρέπει να παρέχετε μια συνάρτηση επίλυσης διακριτικού που επιστρέφει διακριτικό ελέγχου ταυτότητας. Όταν χρησιμοποιείτε το Agent 365 Observability SDK με το πλαίσιο φιλοξενίας παράγοντα, μπορείτε να δημιουργήσετε διακριτικά χρησιμοποιώντας τις TurnContext δραστηριότητες του παράγοντα

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

Προσθέστε την επίλυση διακριτικού παράγοντα στη συλλογή υπηρεσίας σας.

using Microsoft.Agents.A365.Observability;

builder.Services.AddAgenticTracingExporter();

Στην εφαρμογή παράγοντα, καταχωρήστε το διακριτικό.

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

Κωδικός ενορχήστρωσης

Η αυτόματη λειτουργία οργάνων αυτόματης λειτουργίας παρακολουθεί αυτόματα τα υπάρχοντα σήματα τηλεμετρίας πλαισίων παράγοντα (SDK) για ίχνη και τα προωθεί στην υπηρεσία δυνατότητας τήρησης του Παράγοντα 365. Αυτό εξαλείφει την ανάγκη για τους προγραμματιστές να συντάσσουν κώδικα παρακολούθησης με μη αυτόματο τρόπο, απλοποιώντας τη ρύθμιση και εξασφαλίζοντας συνεπή παρακολούθηση των επιδόσεων.

Η αυτόματη λειτουργία οργάνων υποστηρίζεται σε πολλά SDK και πλατφόρμες:

Πλατφόρμα	Υποστηριζόμενα SDK / Πλαίσια
.ΔΊΧΤΥ	Σημασιολογικός πυρήνας, OpenAI, Πλαίσιο παράγοντα
Python	Σημασιολογικός πυρήνας, OpenAI, Πλαίσιο παράγοντα, LangChain
Node.js	OpenAI

Σημείωμα

Η υποστήριξη για τα αυτόματα όργανα μέτρησης ποικίλλει ανάλογα με την εφαρμογή πλατφόρμας και SDK.

Σημασιολογικός πυρήνας

Η αυτόματη λειτουργία οργάνων απαιτεί τη χρήση του κατασκευαστή αποσκευών. Ορισμός αναγνωριστικού παράγοντα και αναγνωριστικού μισθωτή με χρήση του BaggageBuilder.

Εγκατάσταση του πακέτου

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

Ρύθμιση παραμέτρων παρατηρησιμότητας

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

Προσθέστε εξαρτήσεις στη συλλογή υπηρεσίας.

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

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

Ορισμός AgentId και TenantId χρήση BaggageBuilderτου . Βεβαιωθείτε ότι το αναγνωριστικό που χρησιμοποιήθηκε κατά τη δημιουργία αντιστοιχιών ChatCompletionAgent με το αναγνωριστικό παράγοντα μεταβιβάστηκε στο 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

Εγκαταστήστε το πακέτο.

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

Ρυθμίστε τις παραμέτρους της δυνατότητας παρατήρησης.

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

Εγκατάσταση του πακέτου

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

Ρύθμιση παραμέτρων παρατηρησιμότητας

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

Προσθέστε εξαρτήσεις στη συλλογή υπηρεσίας.

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

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

Ορισμός AgentId και TenantId χρήση BaggageBuilderτου . Για κλήσεις εργαλείων, ξεκινήστε μια ανίχνευση χρησιμοποιώντας Trace() σε μια ChatToolCall παρουσία.

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

public class MyAgent
{
    public async Task<AgentResponse> ProcessUserRequest(string userInput)
    {
      using var baggageScope = new BaggageBuilder()
          .AgentId(<your-agent-id>) // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. 
          .TenantId(<your-tenant-id>) // NOTE: This will be the tenant ID with which the TokenResolver delegate is invoked.
          .Build();
      
      // NOTE: This will be the agent and tenant ID with which the TokenResolver delegate will be invoked. 
      using var scope = chatToolCall.Trace(agentId: <your-agent-id>, <your-tenant-id>);
    }
}

Πλαίσιο αντιπροσώπων

Η αυτόματη λειτουργία οργάνων απαιτεί τη χρήση του κατασκευαστή αποσκευών. Ορισμός αναγνωριστικού παράγοντα και αναγνωριστικού μισθωτή με χρήση της ιδιότητας BaggageBuilder.

Εγκατάσταση του πακέτου

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

Ρύθμιση παραμέτρων παρατηρησιμότητας

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

Προσθέστε εξαρτήσεις στη συλλογή υπηρεσίας.

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

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

Ορισμός AgentId και TenantId χρήση 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

Η αυτόματη λειτουργία οργάνων απαιτεί τη χρήση του εργαλείου δόμησης αποσκευών. Ορισμός αναγνωριστικού παράγοντα και αναγνωριστικού μισθωτή με χρήση του BaggageBuilder.

Εγκαταστήστε το πακέτο.

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

Ρύθμιση παραμέτρων παρατηρησιμότητας

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

Μη αυτόματη μέτρηση

Το SDK παρατηρησιμότητας του παράγοντα 365 μπορεί να χρησιμοποιηθεί για την κατανόηση της εσωτερικής λειτουργίας του παράγοντα. Το SDK παρέχει τρεις εμβέλειες που μπορούν να ξεκινήσουν: InvokeAgentScope, ExecuteToolScopeκαι InferenceScope.

Κλήση εντολών

Αυτή η εμβέλεια θα πρέπει να χρησιμοποιηθεί στην αρχή της διαδικασίας του παράγοντα. Με την εμβέλεια του παράγοντα κλήσης, καταγράφετε ιδιότητες όπως ο τρέχων παράγοντας που καλείται, τα δεδομένα χρήστη παράγοντα κ.λπ.

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

Εκτέλεση εργαλείου

Τα παρακάτω παραδείγματα επιδεικνύουν τον τρόπο με τον οποίο μπορείτε να οργάνωνετε την εκτέλεση εργαλείων του παράγοντα σας με παρακολούθηση της παρατηρησιμότητας για τη καταγραφή τηλεμετρίας για σκοπούς παρακολούθησης και ελέγχου.

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

Συμπέρασμα

Τα παρακάτω παραδείγματα δείχνουν πώς μπορείτε να οργάνων κλήσεις παρεμβολής μοντέλου AI με παρακολούθηση παρατηρησιμότητας για να καταγράψετε τη χρήση διακριτικού, λεπτομέρειες μοντέλου και μετα-δεδομένα απόκρισης.

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

Επικύρωση τοπικά

Αποθηκεύστε τη μεταβλητή περιβάλλοντος. Αυτή η εξαγωγή εκτείνεται (ανιχνεύσεις) στην κονσόλα.

Ελέγξτε τον πράκτορά σας με δυνατότητα παρατήρησης

Μετά την εφαρμογή της παρατηρησιμότητας στον πράκτορά σας, δοκιμάστε για να εξασφαλίσετε ότι η τηλεμετρία καταγράφεται σωστά. Ακολουθήστε τον οδηγό δοκιμών για να ρυθμίσετε το περιβάλλον σας και, στη συνέχεια, εστιάστε κυρίως στην ενότητα Προβολή αρχείων καταγραφής παρατηρήσεων για να επικυρώσετε ότι η υλοποίηση της δυνατότητας παρατήρησης λειτουργεί όπως αναμένεται.

Ανάδραση

Ήταν χρήσιμη αυτή η σελίδα;

Last updated on 2025-12-02

Κοινοποίηση μέσω

Παρατηρησιμότητα παράγοντα

Βασικά πλεονεκτήματα

Εγκατάσταση

Ρύθμιση παραμέτρων

Χαρακτηριστικά εικόνας

Επίλυση διακριτικού

Κωδικός ενορχήστρωσης

Σημασιολογικός πυρήνας

OpenAI

Πλαίσιο αντιπροσώπων

Πλαίσιο LangChain

Μη αυτόματη μέτρηση

Κλήση εντολών

Εκτέλεση εργαλείου

Συμπέρασμα

Επικύρωση τοπικά

Ελέγξτε τον πράκτορά σας με δυνατότητα παρατήρησης

Ανάδραση

Πρόσθετοι πόροι