יכולת התבוננות של סוכן

חשוב

עליך להיות חלק מתוכנית התצוגה המקדימה של Frontier כדי לקבל גישה מוקדמת ל - Microsoft Agent 365. Frontier מחברת אתכם ישירות עם החידושים האחרונים של Microsoft בתחום הבינה המלאכותית. קבל תכונות פורצות דרך מעשיות, שתף את התובנות שלך עם צוותי מוצרים ועזור לעצב את עתיד הבינה המלאכותית. תצוגות מקדימות של Frontier כפופות לתנאי התצוגה המקדימה הקיימים של הסכמי הלקוחות שלך. כאשר תכונות אלה עדיין בפיתוח, הזמינות והיכולות שלהן עשויות להשתנות עם הזמן.'

כדי להשתתף ב- Ecosystem של סוכן 365, עליך להוסיף יכולות Observability של סוכן 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`	דגל להפעלה/השבתה של מעקב. כברירת מחדל `false`
`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`	דגל להפעלה/השבתה של מעקב. כברירת מחדל `false`
`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();

הגדר EnableAgent365Exporter כ- 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 מיישמת העתקה של כל ערכי הכבודה שאינם ריקים לפרסים חדשים שהתחילו, מבלי להחליף תכונות קיימות.

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, עליך לספק פונקציית פותרן אסימון המחזירה אסימון אימות. בעת שימוש ב- SDK של Observability Agent 365 עם מסגרת אירוח סוכן, באפשרותך ליצור אסימונים 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) לאותות טלמטריה לניטור ומעבירה אותם לשירות הנראות של Agent 365. פעולה זו מבטלת את הצורך במפתחים לכתוב קוד ניטור באופן ידני, לפשט את ההגדרה ולהבטיח מעקב עקבי אחר ביצועים.

מכשור אוטומטי נתמך בלוחות SDK ובפלטפורמות מרובות:

פלטפורמה	מסגרות SDK / נתמכות
.NET	Semantic Kernel, OpenAI, Agent Framework
פיתון	הליבה סמנטית, OpenAI, Agent Framework, 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

מכשור אוטומטי דורש שימוש בבונה כבודה. הגדר את מזהה הסוכנות ואת מזהה הדייר באמצעות BaggageBuilder.

התקן את החבילה.

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 Framework

מכשור אוטומטי דורש שימוש בבונה כבודה. הגדר את מזהה הסוכנות ואת מזהה הדייר באמצעות 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; }
}

הסקה

הדוגמאות הבאות מראות כיצד להפעיל קריאות הסקת מודל בינה מלאכותית עם מעקב ניתנות למדידה כדי ללכוד שימוש באסימונים, פרטי מודל ומטה-נתונים של תגובה.

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

אמת באופן מקומי

הגדר את משתנה הסביבה ENABLE_A365_OBSERVABILITY_EXPORTER ל- false. פעולה זו מייצאת טווחים (מעקבים) למסוף.

בדוק את הסוכן שלך עם יכולת התבוננות

לאחר יישום ניתנות לניטור בסוכן שלך, בדוק כדי לוודא שטלמטריה נלכדת כראוי. פעל לפי מדריך הבדיקה כדי להגדיר את הסביבה שלך, ולאחר מכן התמקד בעיקר במקטע הצג יומני יכולת התבוננות כדי לאמת את יישום יכולת התצפית שלך פועל כצפוי.

משוב

האם הדף הזה היה מועיל?

Last updated on 2025-11-19

שתף דרך

יכולת התבוננות של סוכן

היתרונות העיקריים

התקנה

תצורה

מאפייני כבודה

פותר אסימון

מכשור אוטומטי

ליבה סמנטית

OpenAI

מסגרת סוכנים

LangChain Framework

מכשור ידני

זימון סוכן

הרצת כלי

הסקה

אמת באופן מקומי

בדוק את הסוכן שלך עם יכולת התבוננות

משוב

משאבים נוספים