Aracı gözlemlenebilirliği

Önemli

Microsoft Agent 365'e erken erişim elde etmek için Frontier önizleme programının bir parçası olmanız gerekir. Frontier sizi Doğrudan Microsoft'un en son yapay zeka yenilikleri ile bağlar. Sınır önizlemeleri, müşteri sözleşmelerinizin mevcut önizleme koşullarına tabidir. Bu özellikler hala geliştirme aşamasında olduğundan, bunların kullanılabilirliği ve özellikleri zaman içinde değişebilir.

Agent 365 ekosistemine katılmak için aracınıza Agent 365 Gözlemlenebilirlik özellikleri eklemeniz gerekir. Agent 365 Gözlemlenebilirliği OpenTelemetry (OTel) üzerinde derlenir ve tüm aracı platformlarında telemetriyi tutarlı ve güvenli bir şekilde yakalamak için birleşik bir çerçeve sağlar. Bu gerekli bileşeni uygulayarak BT yöneticilerinin aracınızın Microsoft Admin Center'daki (MAC) etkinliğini izlemesini ve güvenlik ekiplerinin uyumluluk ve tehdit algılama için Defender ve Purview kullanmasına izin vermelerini sağlarsınız.

Temel avantajlar

Uçtan Uca Görünürlük: Oturumlar, araç çağrıları ve özel durumlar dahil olmak üzere her aracı çağrısı için kapsamlı telemetri yakalayın ve platformlar arasında tam izlenebilirlik elde edin.
Güvenlik ve Uyumluluk Etkinleştirme: Birleştirilmiş denetim günlüklerini Defender ve Purview'a aktararak aracınız için gelişmiş güvenlik senaryoları ve uyumluluk raporlaması sağlar.
Platformlar Arası Esneklik: OTel standartlarını temel alır ve Copilot Studio, Foundry ve gelecekteki aracı çerçeveleri gibi çeşitli çalışma zamanlarını ve platformları destekler.
Yöneticiler için operasyonel verimlilik: MAC'te merkezi gözlemlenebilirlik sağlayarak sorun giderme süresini kısaltın ve aracınızı yöneten BT ekipleri için rol tabanlı erişim denetimleriyle idareyi geliştirin.

Yükleme

Aracı 365 tarafından desteklenen dillere yönelik gözlemlenebilirlik modüllerini yüklemek için bu komutları kullanın.

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

Yapılandırma

Gözlemlenebilirlik için gereken ortam değişkenleri şunlardır:

Ortam değişkeni	Description
`ENABLE_OBSERVABILITY=true`	İzlemeyi etkinleştirmek/devre dışı bırakmak için bayrak ekleyin. Varsayılan olarak
`ENABLE_A365_OBSERVABILITY_EXPORTER=true`	`True` günlükleri hizmetimize aktarın. Aksi takdirde konsol ihracatçısına geri döner

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

Konsolda oturum açmak için belirteç çözümleyicisini hariç tutun.

Gözlemlenebilirlik için gereken ortam değişkenleri şunlardır:

Ortam değişkeni	Description
`ENABLE_OBSERVABILITY=true`	İzlemeyi etkinleştirmek/devre dışı bırakmak için bayrak ekleyin. Varsayılan olarak
`ENABLE_A365_OBSERVABILITY_EXPORTER=true`	`True` günlükleri hizmetimize aktarın. Aksi takdirde konsol ihracatçısına geri döner

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

platformunda EnableAgent365Exporter ayarlama

içinde Program.cs, hizmet koleksiyonuna ekleyin Agent365ExporterOptions . Bu değişiklik, izleme verenin belirteci almak için kullandığı temsilciyi yapılandırıyor.

kullanarak AddA365Tracing()gözlemlenebilirlikle ilgili bağımlılıklar ekleyin.

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

Görüntü öznitelikleri

bir istekteki tüm aralıklarda akan bağlamsal bilgileri ayarlamak için kullanın BaggageBuilder . SDK, var olan özniteliklerin SpanProcessor üzerine yazmadan tüm boş bagaj girişlerini yeni başlatılan aralıklara kopyalar.

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.

Belirteç Çözümleyicisi

Agent 365 dışarı aktarıcısını kullanırken, kimlik doğrulama belirteci döndüren bir belirteç çözümleyici işlevi sağlamanız gerekir. Aracı Barındırma çerçevesi ile Agent 365 Gözlemlenebilirlik SDK'sını kullanırken, aracı etkinliklerinden kullanarak belirteçler TurnContext oluşturabilirsiniz

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

Aracı belirteç çözümleyicisini hizmet koleksiyonunuza ekleyin.

using Microsoft.Agents.A365.Observability;

builder.Services.AddAgenticTracingExporter();

Aracı uygulamasında belirteci kaydedin.

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

Otomatik İzleme:

Otomatik izleme, izlemeler için mevcut telemetri sinyallerini otomatik olarak dinler ve Bunları Agent 365 gözlemlenebilirlik hizmetine iletir. Bu, geliştiricilerin izleme kodunu el ile yazma gereksinimini ortadan kaldırarak kurulumu basitleştirir ve tutarlı performans izleme sağlar.

Otomatik izleme birden çok SDK ve platformda desteklenir:

Platform	Desteklenen altyapılar:
.NET	Semantik Çekirdek, OpenAI, Aracı Çerçevesi
Piton	Semantik Çekirdek, OpenAI, Aracı Çerçevesi, LangChain
Node.js	OpenAI

Not

Otomatik izleme desteği platform ve SDK uygulamasına göre değişir.

Semantik Çekirdek

Otomatik izleme için bagaj oluşturucunun kullanılması gerekir. kullanarak BaggageBuilderaracı kimliğini ve kiracı kimliğini ayarlayın.

Paketi kaldırma

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

Gözlemlenebilirliği yapılandırma

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

Hizmet koleksiyonuna bağımlılıklar ekleyin.

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

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

ayarlama AgentId ve TenantId kullanma BaggageBuilder. Oluştururken ChatCompletionAgent kullanılan kimliğin aracı kimliği ile BaggageBuildereşleştiğinden emin olun.

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

Otomatik izleme için bagaj oluşturucunun kullanılması gerekir. kullanarak BaggageBuilderaracı kimliğini ve kiracı kimliğini ayarlayın.

Paketi kaldırma

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

Gözlemlenebilirliği yapılandırın.

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

Paketi kaldırma

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

Gözlemlenebilirliği yapılandırma

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

Hizmet koleksiyonuna bağımlılıklar ekleyin.

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

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

ayarlama AgentId ve TenantId kullanma BaggageBuilder. Araç çağrıları için bir örnekte kullanarak Trace() bir ChatToolCall izleme başlatın.

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

Agent Framework

Otomatik izleme için bagaj oluşturucunun kullanılması gerekir. Bagaj Oluşturucu kullanarak aracı kimliğini ve kiracı kimliğini ayarlayın.

Paketi kaldırma

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

Gözlemlenebilirliği yapılandırma

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

Hizmet koleksiyonuna bağımlılıklar ekleyin.

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

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

ayarlama AgentId ve TenantId kullanma BaggageBuilder.

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

public class MyAgent : AgentApplication
{
    protected async Task MessageActivityAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
      using var baggageScope = new BaggageBuilder()
          .AgentId(<your-agent-id>) // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. 
          .TenantId(<your-tenant-id>) // NOTE: This will be the tenant ID with which the TokenResolver delegate is invoked.
          .Build();
    }
}

LangChain Framework

Otomatik izleme için bagaj oluşturucunun kullanılması gerekir. kullanarak BaggageBuilderaracı kimliğini ve kiracı kimliğini ayarlayın.

Paketi kaldırma

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

Gözlemlenebilirliği yapılandırma

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

El ile İzleme

Aracı 365 gözlemlenebilirlik SDK'sı, aracının iç çalışmasını anlamak için kullanılabilir. SDK başlatılabilir üç kapsam sağlar: InvokeAgentScope, ExecuteToolScopeve InferenceScope.

Aracı Çağırma

Bu kapsam, aracı işleminizin başlangıcında kullanılmalıdır. Çağırma aracısı kapsamıyla, çağrılan geçerli aracı, aracı kullanıcı verileri vb. gibi özellikleri yakalarsınız.

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

Araç Yürütme

Aşağıdaki örneklerde, izleme ve denetim amacıyla telemetriyi yakalamak için aracınızın araç yürütmesini gözlemlenebilirlik izleme ile izleme işleminin nasıl izleneceği gösterilmektedir.

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

Çıkarım

Aşağıdaki örneklerde, belirteç kullanımını, model ayrıntılarını ve yanıt meta verilerini yakalamak için gözlemlenebilirlik izlemesi ile yapay zeka modeli çıkarım çağrılarının nasıl izlenip izleneceği gösterilmektedir.

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

Yerel Olarak Doğrula

Ortam değişkenini ayarlayın/ Bu işlem, span'ları (izlemeleri) konsola aktarır.

Aracınızı gözlemlenebilirlikle test etme

Aracınızda gözlemlenebilirlik uyguladıktan sonra telemetrinin doğru yakalandığından emin olmak için test edin. Ortamınızı ayarlamak için test kılavuzunu izleyin, ardından gözlemlenebilirlik uygulamanızın beklendiği gibi çalıştığını doğrulamak için öncelikle Gözlemlenebilirlik günlüklerini görüntüle bölümüne odaklanın.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-12-02

Aracılığıyla paylaş

Aracı gözlemlenebilirliği

Temel avantajlar

Yükleme

Yapılandırma

Görüntü öznitelikleri

Belirteç Çözümleyicisi

Otomatik İzleme:

Semantik Çekirdek

OpenAI

Agent Framework

LangChain Framework

El ile İzleme

Aracı Çağırma

Araç Yürütme

Çıkarım

Yerel Olarak Doğrula

Aracınızı gözlemlenebilirlikle test etme

Geri Bildirim

Ek kaynaklar