Observabilidade do agente

Instale os principais pacotes de observabilidade e runtime. Todos os agentes que usam a Observabilidade do Agente 365 precisam desses pacotes.

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

Se o agente usar o pacote Microsoft Agents Hosting, instale o pacote de integração de hospedagem. Ele fornece middleware que preenche automaticamente a bagagem e os escopos a partir do TurnContext, e inclui o armazenamento de tokens para o exportador de observabilidade.

pip install microsoft-agents-a365-observability-hosting

Se o agente usar uma das estruturas de IA com suporte, instale a extensão de instrumentação automática correspondente para capturar automaticamente a telemetria sem código de instrumentação manual. Para obter detalhes de configuração, consulte Instrumentação automática.

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

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

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

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

Instale os principais pacotes de observabilidade e runtime. Todos os agentes que usam a Observabilidade do Agente 365 precisam desses pacotes.

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

Se o agente usar o pacote de hospedagem de @microsoft/agentes , instale o pacote de integração de hospedagem. Ele fornece middleware que preenche automaticamente a bagagem e os escopos a partir do TurnContext, e inclui o armazenamento de tokens para o exportador de observabilidade.

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

Se o agente usar uma das estruturas de IA com suporte, instale a extensão de instrumentação automática correspondente para capturar automaticamente a telemetria sem código de instrumentação manual. Para obter detalhes de configuração, consulte Instrumentação automática.

// For OpenAI Agents SDK
npm install @microsoft/agents-a365-observability-extensions-openai

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

Instale o pacote central de observabilidade e tempo de execução. Todos os agentes que usam a Observabilidade do Agente 365 precisam desse pacote.

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

Se o agente usar o Microsoft. Agents.A365.Observability.Hosting NuGet package, instale o pacote de integração de hospedagem. Ele fornece um middleware que preenche automaticamente a bagagem do TurnContext e inclui cache de tokens para o exportador de observabilidade.

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

Se o agente usar uma das estruturas de IA com suporte, instale a extensão de instrumentação automática correspondente para capturar automaticamente a telemetria sem código de instrumentação manual. Para obter detalhes de configuração, consulte Instrumentação automática.

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

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

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

Defina a ENABLE_A365_OBSERVABILITY_EXPORTER variável do ambiente como true para observalidade. Essa configuração exporta logs para o serviço e requer que seja fornecido um token_resolver. Caso contrário, o exportador de console é utilizado.

from microsoft_agents_a365.observability.core import configure

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

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

O resolver de tokens é excluído do login no console.

Você pode personalizar o comportamento do exportador passando uma Agent365ExporterOptions instância para exporter_options. Quando exporter_options for fornecido, ele terá precedência sobre os parâmetros token_resolver e cluster_category.

from microsoft_agents_a365.observability.core import configure, Agent365ExporterOptions

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

A tabela a seguir descreve os parâmetros opcionais para configure().

A tabela a seguir descreve as propriedades opcionais para Agent365ExporterOptions.

Defina a ENABLE_A365_OBSERVABILITY_EXPORTER variável do ambiente como true para observalidade. Essa configuração exporta logs para o serviço e requer que um resolvedor de token seja fornecido. Caso contrário, o exportador de console é utilizado.

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

// Define a token resolver to authenticate with the observability service for exporting logs
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();

Como alternativa às variáveis de ambiente, você pode configurar a observabilidade programaticamente usando um provedor de configuração por meio do método withConfigurationProvider. Se você também usar métodos de construtor individuais (como withExporterOptions ou withClusterCategory), os métodos individuais do construtor têm precedência sobre os valores do provedor de configuração.

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

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

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

builder.start();

Você pode personalizar o comportamento do exportador passando uma Agent365ExporterOptions instância para withExporterOptions. Essa opção permite controlar o envio em lote, os tempos limite e o modo de rota.

import {
  ObservabilityManager,
  Agent365ExporterOptions,
} from '@microsoft/agents-a365-observability';
import { ClusterCategory } from '@microsoft/agents-a365-runtime';

const exporterOptions = new Agent365ExporterOptions();
exporterOptions.maxQueueSize = 10;

const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withClusterCategory(ClusterCategory.prod)
    .withExporterOptions(exporterOptions)
    .withTokenResolver(tokenResolver)
);

builder.start();

A tabela a seguir descreve as propriedades opcionais para Agent365ExporterOptions.

Você também pode fornecer um logger personalizado que implemente a ILogger interface (info, warn, error, event). Passe para o Builder usando withCustomLogger.

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

builder.start();

Definir EnableAgent365Exporter como true em appsettings.json.

No Program.cs, adicione Agent365ExporterOptions à coleção de serviços. Essa alteração configura o delegado que o exportador de rastreamento usa para recuperar o token.

Adicione dependências relacionadas à observabilidade usando AddA365Tracing().

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

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton(sp =>
    {
        return new Agent365ExporterOptions
        {
            TokenResolver = async (agentId, tenantId) =>
            {
                // It's recommended to implement caching in your token provider for performance.
                var token = await tokenProvider.GetObservabilityTokenAsync(agentId, tenantId);
                return token;
            }
        };
    });

builder.AddA365Tracing();

Você pode personalizar o comportamento do exportador passando um delegado de configuração e tipo de exportador para AddA365Tracing().

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

A tabela a seguir descreve as propriedades opcionais para Agent365ExporterOptions.

from microsoft_agents_a365.observability.core import BaggageBuilder

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

Você pode preencher automaticamente o BaggageBuilder a partir do TurnContext, usando o auxiliar populate no pacote microsoft-agents-a365-observability-hosting. Esse auxiliar extrai automaticamente os detalhes do chamador, agente, inquilino, canal e conversa da atividade.

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

builder = BaggageBuilder()
populate(builder, turn_context)

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

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

// Create and apply baggage context
const baggageScope = new BaggageBuilder()
  // Core identifiers
  .tenantId('tenant-123')
  .agentId('agent-456')
  .conversationId('conv-789')
  .build();

// Execute operations within the baggage context
baggageScope.run(() => {
  // All spans created within this context will inherit the baggage values

  // Invoke another agent
  const agentScope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
  // ... agent logic

  // Execute tools
  const toolScope = ExecuteToolScope.start(request, toolDetails, agentDetails);
  // ... tool logic
});

Você pode preencher automaticamente o BaggageBuilder a partir do TurnContext, usando o auxiliar fromTurnContext no pacote @microsoft/agents-a365-observability-hosting. Esse auxiliar extrai automaticamente os detalhes do chamador, agente, inquilino, canal e conversa da atividade.

import { BaggageBuilder } from '@microsoft/agents-a365-observability';
import { BaggageBuilderUtils } from '@microsoft/agents-a365-observability-hosting';

const baggageScope = BaggageBuilderUtils.fromTurnContext(new BaggageBuilder(), context)
  .invokeAgentServer(context.activity.serviceUrl, 3978)
  .build();

await baggageScope.run(async () => {
  // Baggage is auto-populated from the TurnContext activity
});

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

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

Você pode preencher automaticamente o BaggageBuilder do ITurnContext usando o método de extensão FromTurnContext no pacote Microsoft.Agents.A365.Observability.Hosting. Esse método extrai automaticamente os detalhes do chamador, agente, inquilino, canal e conversa da atividade.

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

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

from microsoft_agents.activity import load_configuration_from_env
from microsoft_agents.authentication.msal import MsalConnectionManager
from microsoft_agents.hosting.aiohttp import CloudAdapter
from microsoft_agents.hosting.core import (
    AgentApplication,
    Authorization,
    MemoryStorage,
    TurnContext,
    TurnState,
)
from microsoft_agents_a365.runtime import (
    get_observability_authentication_scope,
)

agents_sdk_config = load_configuration_from_env(environ)

STORAGE = MemoryStorage()
CONNECTION_MANAGER = MsalConnectionManager(**agents_sdk_config)
ADAPTER = CloudAdapter(connection_manager=CONNECTION_MANAGER)
ADAPTER.use(TranscriptLoggerMiddleware(ConsoleTranscriptLogger()))
AUTHORIZATION = Authorization(STORAGE, CONNECTION_MANAGER, **agents_sdk_config)

AGENT_APP = AgentApplication[TurnState](
    storage=STORAGE, adapter=ADAPTER, authorization=AUTHORIZATION, **agents_sdk_config
)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    aau_auth_token = await AGENT_APP.auth.exchange_token(
                        context,
                        scopes=get_observability_authentication_scope(),
                        auth_handler_id="AGENTIC",
                    )
    # cache this auth token and return via token resolver

Para o cenário de trabalhador digital, se o agente usar o pacote Microsoft Agent 365 Observability Hosting Library, use AgenticTokenCache para gerenciar o cache de tokens automaticamente. Registre o token uma vez por agente e locatário durante um manipulador de atividades e passe cache.get_observability_token como token_resolver na configuração de observabilidade.

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

# Create a shared cache instance
token_cache = AgenticTokenCache()

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

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

import {
  TurnState,
  AgentApplication,
  MemoryStorage,
  TurnContext,
} from '@microsoft/agents-hosting';
import { ActivityTypes } from '@microsoft/agents-activity';
import { getObservabilityAuthenticationScope } from '@microsoft/agents-a365-runtime';

interface ConversationState {
  count: number;
}
type ApplicationTurnState = TurnState<ConversationState>;

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

Para o cenário de trabalho digital, se o agente usar o pacote @microsoft/agents-a365-observability-hosting, use AgenticTokenCacheInstance para gerenciar o cache de token automaticamente. Chame RefreshObservabilityToken uma vez por agente e inquilino durante um manipulador de atividades e passe AgenticTokenCacheInstance.getObservabilityToken como o parâmetro tokenResolver na configuração de observabilidade.

import { ObservabilityManager } from '@microsoft/agents-a365-observability';
import { AgenticTokenCacheInstance } from '@microsoft/agents-a365-observability-hosting';
import { getObservabilityAuthenticationScope } from '@microsoft/agents-a365-runtime';

// Use the cache as your token resolver in configure()
const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withTokenResolver((agentId, tenantId) =>
      AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId)
    )
);

builder.start();

agentApplication.onActivity(
  ActivityTypes.Message,
  async (context: TurnContext, state: ApplicationTurnState) => {
    const agentId = context.activity.recipient?.agenticAppId || '';
    const tenantId = context.activity.recipient?.tenantId || '';

    await AgenticTokenCacheInstance.RefreshObservabilityToken(
      agentId,
      tenantId,
      context,
      agentApplication.authorization,
      getObservabilityAuthenticationScope()
    );
  }
);

Forneça um resolvedor de tokens registrando-se Agent365ExporterOptions com um TokenResolver Delegado. O delegado recebe o agentId e o tenantId e retorna um token de autenticação.

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

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

Para o cenário de trabalho digital, se o agente usar o pacote NuGet Microsoft.Agents.A365.Observability.Hosting, use o método AddAgenticTracingExporter() para lidar automaticamente com o cache de token por meio de injeção de dependência.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

No aplicativo do agente, registre o token.

using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.App.UserAuth;
using Microsoft.Extensions.Logging;
using Microsoft.Agents.A365.Observability.Hosting.Caching;
using Microsoft.Agents.A365.Observability.Runtime.Common;
using System;
using System.Threading.Tasks;

public class MyAgent : AgentApplication
{
    private readonly IExporterTokenCache<AgenticTokenStruct> _agentTokenCache;
    private readonly ILogger<MyAgent> _logger;

    public MyAgent(AgentApplicationOptions options, IExporterTokenCache<AgenticTokenStruct> agentTokenCache, ILogger<MyAgent> logger)
        : base(options)
    {
        _agentTokenCache = agentTokenCache ?? throw new ArgumentNullException(nameof(agentTokenCache));
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
    }

    protected async Task MessageActivityAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        using var baggageScope = new BaggageBuilder()
            .TenantId(turnContext.Activity.Recipient.TenantId)
            .AgentId(turnContext.Activity.Recipient.AgenticAppId)
            .Build();

        try
        {
            _agentTokenCache.RegisterObservability(
                turnContext.Activity.Recipient.AgenticAppId,
                turnContext.Activity.Recipient.TenantId,
                new AgenticTokenStruct(
                    userAuthorization: UserAuthorization,
                    turnContext: turnContext,
                    authHandlerName: "AGENTIC"
                ),
                EnvironmentUtils.GetObservabilityAuthenticationScope()
            );
        }
        catch (Exception ex)
        {
            _logger.LogWarning($"Error registering for observability: {ex.Message}");
        }
    }
}

Instale o pacote.

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

Configurar a observabilidade

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.extensions.semantickernel.trace_instrumentor import SemanticKernelInstrumentor

# Configure observability
configure(
    service_name="my-semantic-kernel-agent",
    service_namespace="ai.agents"
)

# Enable auto-instrumentation
instrumentor = SemanticKernelInstrumentor()
instrumentor.instrument()

# Your Semantic Kernel code is now automatically traced

não há suporte para Kernel semântico com JavaScript.

Adicione dependências à coleção de serviços.

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

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

Defina AgentId e TenantId usando BaggageBuilder. Certifique-se de que o ID que você usa ao criar um ChatCompletionAgent corresponde ao ID do agente que você passa para 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>,
          ...
      };
    }
}

Instale o pacote.

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

Configurar a observabilidade

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.extensions.openai import OpenAIAgentsTraceInstrumentor

# Configure observability
configure(
    service_name="my-openai-agent",
    service_namespace="ai.agents"
)

# Enable auto-instrumentation
instrumentor = OpenAIAgentsTraceInstrumentor()
instrumentor.instrument()

# Your OpenAI Agents code is now automatically traced

Instale o pacote.

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

Configurar a observabilidade

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

// Create and enable the instrumentor
const instrumentor = new OpenAIAgentsTraceInstrumentor({
  enabled: true,
  tracerName: 'openai-agents-tracer',
  tracerVersion: '1.0.0'
});

sdk.start();

instrumentor.enable();

Adicione dependências à coleção de serviços.

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

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

Defina AgentId e TenantId usando BaggageBuilder. Para chamadas de ferramenta, inicie um rastreamento usando Trace() em uma instância 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>);
    }
}

Instale o pacote.

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

Configurar a observabilidade

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

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

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

O Agent Framework não é suportado com JavaScript.

Adicione dependências à coleção de serviços.

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

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

Defina AgentId e TenantId usando 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();
    }
}

Instale o pacote.

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

Configurar a observabilidade

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

Instale o pacote.

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

Configurar a observabilidade

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

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

sdk.start();

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

// Your LangChain code is now automatically traced

Não há suporte para LangChain com .NET.

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

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

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

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

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

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

import {
  InvokeAgentScope,
  InvokeAgentScopeDetails,
  AgentDetails,
  CallerDetails,
  UserDetails,
  Channel,
  Request,
  ServiceEndpoint,
} from '@microsoft/agents-a365-observability';

// Use the same agentDetails instance across all scopes in a request
const agentDetails: AgentDetails = {
  agentId: 'agent-456',
  agentName: 'Email Assistant',
  agentDescription: 'An AI agent powered by Azure OpenAI',
  agentAuid: 'auid-123',
  agentEmail: 'agent@contoso.com',
  agentBlueprintId: 'blueprint-789',
  tenantId: 'tenant-123',
};

const scopeDetails: InvokeAgentScopeDetails = {
  endpoint: { host: 'myagent.contoso.com', port: 443 } as ServiceEndpoint,
};

// Use the same request instance across all scopes in a request
const request: Request = {
  content: 'Please help me organize my emails',
  sessionId: 'session-42',
  conversationId: 'conv-xyz',
  channel: { name: 'msteams' } as Channel,
};

// Optional: Caller details (human user, or agent-to-agent)
const callerDetails: CallerDetails = {
  userDetails: {
    userId: 'user-123',
    userEmail: 'jane.doe@contoso.com',
    userName: 'Jane Doe',
  } as UserDetails,
};

const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails, callerDetails);

try {
  await scope.withActiveSpanAsync(async () => {
    // Record input messages
    scope.recordInputMessages(['Please help me organize my emails', 'Focus on urgent items']);

    // Your agent invocation logic here
    const response = await invokeAgent(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;
} finally {
  scope.dispose();
}

Se o agente usar o @microsoft/agents-a365-observability-hosting pacote, você poderá usar ScopeUtils.populateInvokeAgentScopeFromTurnContext para criar o escopo com detalhes do agente, detalhes do chamador e informações de canal derivadas automaticamente do TurnContext.

import { InvokeAgentScopeDetails, AgentDetails, ServiceEndpoint } from '@microsoft/agents-a365-observability';
import { ScopeUtils } from '@microsoft/agents-a365-observability-hosting';

const agentDetails: AgentDetails = { agentId: 'agent-456' };
const scopeDetails: InvokeAgentScopeDetails = {
  endpoint: { host: 'myagent.contoso.com', port: 443 } as ServiceEndpoint,
};

const scope = ScopeUtils.populateInvokeAgentScopeFromTurnContext(
  agentDetails,
  scopeDetails,
  context,     // TurnContext
  authToken    // authentication token string
);

try {
  await scope.withActiveSpanAsync(async () => {
    // Agent details, caller details, and channel are auto-populated from context
    const response = await invokeAgent(context.activity.text);
    scope.recordOutputMessages([response]);
  });
} finally {
  scope.dispose();
}

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

public class MyAgent
{
    public async Task<AgentResponse> ProcessUserRequest(string userInput)
    {
        var agentDetails = new AgentDetails(
            agentId: "agent-456",
            agentName: "MyAgent",
            agentDescription: "Handles user requests.",
            agenticUserId: "auid-123",
            agenticUserEmail: "agent@contoso.com",
            agentBlueprintId: "blueprint-789",
            tenantId: "tenant-123"
        );

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

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

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

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

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

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

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

        return new AgentResponse { Content = output };
    }
}

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

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

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

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

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

import { ExecuteToolScope, ToolCallDetails } from '@microsoft/agents-a365-observability';

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

const toolDetails: ToolCallDetails = {
  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'
  },
};

const scope = ExecuteToolScope.start(request, toolDetails, agentDetails);

try {
  return await scope.withActiveSpanAsync(async () => {
    // Execute the tool
    const result = await searchEmails(toolDetails.arguments);

    // Record the tool execution result
    scope.recordResponse(result);

    return result;
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

Se o agente usar o pacote @microsoft/agents-a365-observability-hosting, use ScopeUtils.populateExecuteToolScopeFromTurnContext para criar o escopo com os detalhes do agente derivados automaticamente do TurnContext.

import { ToolCallDetails } from '@microsoft/agents-a365-observability';
import { ScopeUtils } from '@microsoft/agents-a365-observability-hosting';

const toolDetails: ToolCallDetails = {
  toolName: 'email-search',
  arguments: JSON.stringify({ query: 'from:boss@company.com' }),
  toolCallId: 'tool-call-456',
  toolType: 'function',
};

const scope = ScopeUtils.populateExecuteToolScopeFromTurnContext(
  toolDetails,
  context,     // TurnContext
  authToken    // authentication token string
);

try {
  await scope.withActiveSpanAsync(async () => {
    const result = await searchEmails(toolDetails.arguments);
    scope.recordResponse(JSON.stringify(result));
  });
} finally {
  scope.dispose();
}

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

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

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

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

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

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

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

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

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

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

import { InferenceScope, InferenceDetails, InferenceOperationType } from '@microsoft/agents-a365-observability';

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

const inferenceDetails: InferenceDetails = {
  operationName: InferenceOperationType.CHAT,
  model: 'gpt-4o-mini',
  providerName: 'azure-openai',
};

const scope = InferenceScope.start(request, inferenceDetails, agentDetails);

try {
  return await scope.withActiveSpanAsync(async () => {
    // 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);
    scope.recordOutputTokens(82);
    scope.recordFinishReasons(['stop']);

    return response.text;
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

Se o agente usar o @microsoft/agents-a365-observability-hosting pacote, você poderá usar ScopeUtils.populateInferenceScopeFromTurnContext para criar o escopo com detalhes do agente derivados automaticamente do TurnContext.

import { InferenceDetails, InferenceOperationType } from '@microsoft/agents-a365-observability';
import { ScopeUtils } from '@microsoft/agents-a365-observability-hosting';

const inferenceDetails: InferenceDetails = {
  operationName: InferenceOperationType.CHAT,
  model: 'gpt-4o-mini',
  providerName: 'azure-openai',
};

const scope = ScopeUtils.populateInferenceScopeFromTurnContext(
  inferenceDetails,
  context,     // TurnContext
  authToken    // authentication token string
);

try {
  await scope.withActiveSpanAsync(async () => {
    const response = await callLLM();
    scope.recordOutputMessages([response.text]);
    scope.recordInputTokens(response.usage.inputTokens);
    scope.recordOutputTokens(response.usage.outputTokens);
  });
} finally {
  scope.dispose();
}

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

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

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

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

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

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

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

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

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

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

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

import { OutputScope, OutputResponse, SpanDetails } from '@microsoft/agents-a365-observability';

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

// Get the parent context from the originating scope
const parentContext = invokeScope.getSpanContext();

const response: OutputResponse = {
  messages: ['Here is your organized inbox with 15 urgent emails.'],
};

const scope = OutputScope.start(
  request,
  response,
  agentDetails,
  undefined, // userDetails
  { parentContext } as SpanDetails
);

// Output messages are recorded automatically from the response
scope.dispose();

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

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

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

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

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

Defina a variável de ambiente ENABLE_A365_OBSERVABILITY_EXPORTER como false. Essa configuração exporta spans (traces) para o console.

Defina a variável de ambiente ENABLE_A365_OBSERVABILITY_EXPORTER como false. Essa configuração exporta spans (traces) para o console.

Definir EnableAgent365Exporter como false em appsettings.json. Essa configuração exporta os spans (traces) para o console.

• Propriedades que você define usando a classe BaggageBuilder podem ser definidas ou sobrescrevidas pelas propriedades dos respectivos escopos.

• Defina as propriedades na tabela a seguir usando o método InvokeAgentScope.start.

  Dados	Descrição
  invoke_agent_details.details.agent_id	O identificador exclusivo para o agente de IA
  invoke_agent_details.details.agent_name	O nome legível pelo ser humano do agente de IA
  invoke_agent_details.details.agent_auid	O ID do usuário do agente (AUID)
  invoke_agent_details.details.agent_upn	O nome principal de usuário do agente (UPN)
  invoke_agent_details.details.agent_blueprint_id	O ID do blueprint/aplicativo do agente
  invoke_agent_details.details.tenant_id	O identificador do locatário para o agente
  invoke_agent_details.details.conversation_id	O identificador da conversa ou sessão
  invoke_agent_details.endpoint	O ponto de extremidade para a invocação do agente
  tenant_details.tenant_id	O identificador exclusivo para o locatário
  request.content	O conteúdo do payload enviado ao agente para invocação
  request.execution_type	Tipo de invocação indicando a origem da solicitação (por exemplo, HumanToAgent ou AgentToAgent)
  caller_details.caller_id	O identificador exclusivo para o chamador
  caller_details.caller_upn	O nome principal de usuário (UPN) do chamador
  caller_details.caller_user_id	A ID do usuário do chamador
  caller_details.tenant_id	A ID do locatário do chamador

• Defina as propriedades na tabela a seguir usando o método ExecuteToolScope.start.

  Dados	Descrição
  details.tool_name	O nome da ferramenta que está sendo executada
  details.arguments	Argumentos ou parâmetros de ferramentas
  details.tool_call_id	O identificador exclusivo para a chamada de ferramenta
  details.tool_type	O tipo da ferramenta que está sendo executada
  details.endpoint	Se uma chamada de ferramenta externa for feita
  agent_details.agent_id	O identificador exclusivo para o agente de IA
  agent_details.agent_name	O nome legível pelo ser humano do agente de IA
  agent_details.agent_auid	O ID de usuário do agente
  agent_details.agent_upn	O nome principal de usuário do agente (UPN)
  agent_details.agent_blueprint_id	O ID do blueprint ou aplicativo do agente
  agent_details.tenant_id	ID de locatário do agente.
  agent_details.conversation_id	A ID da conversa para a invocação do agente.
  tenant_details.tenant_id	ID de locatário do agente.

• Defina as propriedades na tabela a seguir usando o método InferenceScope.start.

  Dados	Descrição
  details.operationName	O nome ou tipo da operação para a inferência
  details.model	O nome ou identificador do modelo
  details.providerName	Nome do provedor
  agent_details.agent_id	O identificador exclusivo para o agente de IA
  agent_details.agent_name	O nome legível pelo ser humano do agente de IA
  agent_details.agent_auid	O ID do usuário do agente (AUID)
  agent_details.agent_upn	O nome principal de usuário do agente (UPN)
  agent_details.agent_blueprint_id	O ID do blueprint ou aplicativo do agente
  agent_details.tenant_id	O identificador exclusivo para o locatário
  agent_details.conversation_id	O identificador da conversa ou sessão
  tenant_details.tenant_id	O identificador exclusivo para o locatário
  request.content	O conteúdo enviado ao agente para inferência
  request.execution_type	Tipo de invocação indicando a origem da solicitação (por exemplo, HumanToAgent ou AgentToAgent)
  request.source_metadata	Represente as informações do canal

• Propriedades que você define usando a classe BaggageBuilder podem ser definidas ou sobrepostas pelas propriedades dos respectivos escopos.

• Defina as propriedades na tabela a seguir usando o método InvokeAgentScope.start.

  Dados	Descrição
  agentDetails.agentId	O identificador exclusivo para o agente de IA
  agentDetails.agentName	O nome legível pelo ser humano do agente de IA
  agentDetails.agentAuid	O ID do usuário do agente (AUID)
  agentDetails.agentEmail	O endereço de email do agente
  agentDetails.agentBlueprintId	O ID do blueprint/aplicativo do agente
  agentDetails.tenantId	O identificador do locatário para o agente
  scopeDetails.endpoint.host	O endereço de host do endpoint para invocar o agente
  scopeDetails.endpoint.port	O número da porta do ponto de extremidade para a invocação do agente
  request.content	O conteúdo da solicitação para a invocação do agente
  request.conversationId	O identificador da conversa ou sessão
  request.sessionId	O ID da sessão para a invocação do agente
  request.channel.name	Canalize informações como (msteams, email, e assim por diante)
  callerDetails.userDetails.userId	O identificador exclusivo para o chamador
  callerDetails.userDetails.userName	O nome de exibição do chamador
  callerDetails.userDetails.userEmail	O endereço de email do chamador

• Defina as propriedades na tabela a seguir usando o método ExecuteToolScope.start.

  Dados	Descrição
  details.toolName	O nome da ferramenta que está sendo executada
  details.arguments	Argumentos ou parâmetros de ferramentas
  details.toolCallId	O identificador exclusivo para a chamada de ferramenta
  details.toolType	O tipo da ferramenta que está sendo executada
  details.endpoint.host	O endereço host do endpoint para a execução da ferramenta. É obrigatório se for feita uma chamada externa
  details.endpoint.port	O número da porta do endpoint para a execução da ferramenta. É obrigatório se for feita uma chamada externa
  agentDetails.agentId	O identificador exclusivo para o agente de IA
  agentDetails.agentName	O nome legível pelo ser humano do agente de IA
  agentDetails.tenantId	O identificador do locatário para o agente
  request.conversationId	O identificador da conversa ou sessão

• Defina as propriedades na tabela a seguir usando o método InferenceScope.start.

  Dados	Descrição
  details.operationName	O nome ou tipo da operação para a inferência
  details.model	O nome ou identificador do modelo
  details.providerName	Nome do provedor
  agentDetails.agentId	O identificador exclusivo para o agente de IA
  agentDetails.agentName	O nome legível pelo ser humano do agente de IA
  agentDetails.tenantId	O identificador do locatário para o agente
  request.conversationId	O identificador da conversa ou sessão

• Propriedades que você define usando a classe BaggageBuilder podem ser definidas ou sobrepostas pelas propriedades dos respectivos escopos.

• Defina as propriedades na tabela a seguir usando o método InvokeAgentScope.Start.

  Dados	Descrição
  invokeAgentDetails.details.agentId	O identificador exclusivo do agente.
  invokeAgentDetails.details.agentName	Nome de exibição do agente.
  invokeAgentDetails.details.agentAUID	Azure AUID (ID de Usuário) para o agente.
  invokeAgentDetails.details.agentUPN	Nome de Usuário Principal (UPN) para o agente.
  invokeAgentDetails.details.agentBlueprintId	A ID do Blueprint/Aplicativo do agente.
  invokeAgentDetails.details.tenantId	ID de locatário do agente.
  invokeAgentDetails.endpoint	URI do ponto de extremidade do agente a ser invocado.
  tenantDetails.tenantId	O identificador do inquilino.
  request.content	O conteúdo da carga útil fornecido ao agente.
  request.executionType	Tipo de execução que descreve a solicitação.
  request.sourceMetadata.name	Nome legível para seres humanos da fonte. Nome do canal.
  conversationId	A ID da conversa para a invocação do agente.

• Defina as propriedades na tabela a seguir usando o método ExecuteToolScope.Start.

  Dados	Descrição
  details.toolName	Nome da ferramenta que está sendo invocada.
  details.arguments	Argumentos serializados eram passados para a ferramenta.
  details.toolCallId	Identificador para a invocação da ferramenta.
  details.toolType	Classificação de tipos para a ferramenta.
  details.endpoint	Endpoint necessário para execução remota de ferramentas.
  agentDetails.agentId	O identificador exclusivo do agente.
  agentDetails.agentName	Nome de exibição do agente.
  agentDetails.agentAUID	Azure AUID (ID de Usuário) para o agente.
  agentDetails.agentUPN	Nome de Usuário Principal (UPN) para o agente.
  agentDetails.agentBlueprintId	A ID do Blueprint/Aplicativo do agente.
  agentDetails.tenantId	ID de locatário do agente.
  tenantDetails.tenantId	O identificador do inquilino.

• Defina as propriedades na tabela a seguir usando o método InferenceScope.Start.

  Dados	Descrição
  details.operationName	Identificador de telemetria para a operação de inferência.
  details.model	Nome do modelo usado para satisfazer o pedido de inferência.
  details.providerName	O provedor responsável pela chamada de inferência.
  agentDetails.agentId	O identificador exclusivo do agente.
  agentDetails.agentName	Nome de exibição do agente.
  agentDetails.agentAUID	Azure AUID (ID de Usuário) para o agente.
  agentDetails.agentUPN	Nome de Usuário Principal (UPN) para o agente.
  agentDetails.agentBlueprintId	A ID do Blueprint/Aplicativo do agente.
  agentDetails.tenantId	ID de locatário do agente.
  tenantDetails.tenantId	O identificador do inquilino.
  parentId	Para gerenciamento explícito do escopo pai. Não é obrigatório na maioria dos casos.