Adicionar rastreamento do lado do cliente a agentes do Foundry (versão prévia)

• Python 3.10 ou posterior.
• O azure-ai-projects pacote versão 2.0.0 ou posterior.

• .NET 8.0 ou posterior.
• O pacote NuGet Azure.AI.Projects.

• Node.js 20 LTS ou posterior.
• A versão 2.4.0 ou posterior do pacote @azure/ai-projects.

Instale o SDK do Microsoft Foundry, o OpenTelemetry e o exportador de Azure Monitor:

pip install azure-ai-projects opentelemetry-sdk azure-core-tracing-opentelemetry azure-monitor-opentelemetry

Para exportação somente de console ou OTLP (por exemplo, Aspire Dashboard), instale o exportador OTLP:

pip install opentelemetry-exporter-otlp

Adicione os pacotes NuGet necessários:

dotnet add package Azure.AI.Projects
dotnet add package Azure.AI.Projects.Agents
dotnet add package Azure.Identity
dotnet add package Azure.Monitor.OpenTelemetry.Exporter
dotnet add package OpenTelemetry.Exporter.Console

Para aplicativos ASP.NET Core, Azure.Monitor.OpenTelemetry.AspNetCore é o pacote preferencial. O pacote Azure.Monitor.OpenTelemetry.Exporter mostrado aqui funciona para todos os tipos de aplicativos .NET.

Instale o SDK do Microsoft Foundry, o OpenTelemetry e o exportador de Azure Monitor:

npm install @azure/ai-projects @azure/identity @azure/monitor-opentelemetry @opentelemetry/api dotenv

Para exportação somente de console, você também precisa dos pacotes do SDK do OpenTelemetry:

npm install @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base

Defina a variável de AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING ambiente para trueantes de chamar AIProjectInstrumentor().instrument():

import os

os.environ["AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING"] = "true"

from azure.ai.projects.telemetry import AIProjectInstrumentor

# Enable instrumentation
AIProjectInstrumentor().instrument()

Se a variável não estiver definida ou não for true (sem diferenciar maiúsculas de minúsculas), a instrumentação de rastreamento não será habilitada e um aviso será registrado.

Use um AppContext switch ou a mesma variável de ambiente:

// Enable GenAI tracing
AppContext.SetSwitch("Azure.Experimental.EnableGenAITracing", true);

Quando você habilita Azure.Experimental.EnableGenAITracing, o SDK habilita automaticamente o sinalizador Azure.Experimental.EnableActivitySource, que é necessário para que a instrumentação OpenTelemetry funcione.

Se a opção AppContext e a variável de ambiente estiverem definidas, a opção AppContext tem prioridade.

Passe tracingOptions em experimental: true ao criar o AIProjectClient. Ao contrário dos SDKs Python e C#, o SDK do JavaScript/TypeScript permite o rastreamento por instância do cliente em vez de por meio de uma chamada de instrumentação separada:

const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
  {
    tracingOptions: {
      experimental: true,
    },
  },
);

Você também pode definir a AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING variável de ambiente para true , em vez de passar a opção. A tracingOptions propriedade tem precedência sobre a variável de ambiente. Consulte Exportar rastreamentos para Azure Monitor para obter um exemplo completo.

import os

os.environ["AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING"] = "true"

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition
from azure.identity import DefaultAzureCredential
from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
AGENT_NAME = "MyAgent"

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project,
):
    # Get the Application Insights connection string from the project
    connection_string = project.telemetry.get_application_insights_connection_string()
    configure_azure_monitor(connection_string=connection_string)

    tracer = trace.get_tracer(__name__)

    with tracer.start_as_current_span("agent-tracing-scenario"):
        # Create an agent
        agent = project.agents.create_version(
            agent_name=AGENT_NAME,
            definition=PromptAgentDefinition(
                model=os.environ["FOUNDRY_MODEL_NAME"],
                instructions="You are a helpful assistant.",
            ),
        )
        print(f"Agent created (id: {agent.id}, name: {agent.name})")

        with project.get_openai_client(agent_name=agent.name) as openai:
            # Create a conversation and get a response
            conversation = openai.conversations.create()
            response = openai.responses.create(
                conversation=conversation.id,
                input="What is the largest city in France?",
            )
            print(f"Response: {response.output_text}")

            # Clean up
            openai.conversations.delete(conversation_id=conversation.id)

        project.agents.delete_version(agent_name=agent.name, agent_version=agent.version)

Referência: AIProjectClient, , DefaultAzureCredentialconfigure_azure_monitor

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
using Azure.Monitor.OpenTelemetry.Exporter;
using OpenTelemetry;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
using OpenAI.Responses;

var projectEndpoint = Environment.GetEnvironmentVariable(
    "FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException(
        "FOUNDRY_PROJECT_ENDPOINT isn't set.");
var modelName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL_NAME")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL_NAME isn't set.");

// Enable GenAI tracing
AppContext.SetSwitch("Azure.Experimental.EnableGenAITracing", true);

AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

// Get the Application Insights connection string from the project
var connectionString = await projectClient.Telemetry
    .GetApplicationInsightsConnectionStringAsync();

// The Azure Monitor exporter reads this environment variable automatically
Environment.SetEnvironmentVariable(
    "APPLICATIONINSIGHTS_CONNECTION_STRING", connectionString);

// Configure OpenTelemetry with Azure Monitor exporter
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("Azure.AI.Projects.*")
    .SetResourceBuilder(
        ResourceBuilder.CreateDefault().AddService("AgentTracingSample"))
    .AddAzureMonitorTraceExporter()
    .Build();

using (tracerProvider)
{
    // Create an agent
    DeclarativeAgentDefinition agentDefinition = new(model: modelName)
    {
        Instructions = "You are a helpful assistant."
    };
    ProjectsAgentVersion agent = await projectClient.AgentAdministrationClient
        .CreateAgentVersionAsync(
            agentName: $"agent-tracing-{Guid.NewGuid():N}",
            options: new(agentDefinition));
    try
    {
        Console.WriteLine(
            $"Agent created (id: {agent.Id}, name: {agent.Name})");

        // Call the agent to emit GenAI spans
        ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient
            .GetProjectResponsesClientForAgent(agent.Name);
#pragma warning disable OPENAI001
        ResponseItem request = ResponseItem.CreateUserMessageItem(
            "What is the largest city in France?");
        ResponseResult response = await responseClient.CreateResponseAsync(
            [request]);
#pragma warning restore OPENAI001
        Console.WriteLine($"Response: {response.GetOutputText()}");
    }
    finally
    {
        await projectClient.AgentAdministrationClient.DeleteAgentVersionAsync(
            agentName: agent.Name,
            agentVersion: agent.Version);
    }
}

Referência: AIProjectClient, , DefaultAzureCredentialSdk.CreateTracerProviderBuilder

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import {
  useAzureMonitor,
  shutdownAzureMonitor,
} from "@azure/monitor-opentelemetry";
import { context, trace } from "@opentelemetry/api";
import "dotenv/config";

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "";
const modelName = process.env["FOUNDRY_MODEL_NAME"] || "";

// Enable tracing when you create the client. To capture prompt and
// completion content, set contentRecording to true (off by default).
const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
  {
    tracingOptions: { contentRecording: false, experimental: true },
  },
);
const openAIClient = project.getOpenAIClient();

// Get the Application Insights connection string from the project
const connectionString =
  await project.telemetry.getApplicationInsightsConnectionString();

// Configure Azure Monitor tracing
useAzureMonitor({
  azureMonitorExporterOptions: { connectionString },
});

const tracer = trace.getTracer("AgentTracingSample");
const span = tracer.startSpan("agent-tracing-scenario");
const ctx = trace.setSpan(context.active(), span);

await context.with(ctx, async () => {
  // Create an agent
  const agent = await project.agents.createVersion("MyAgent", {
    kind: "prompt",
    model: modelName,
    instructions: "You are a helpful assistant.",
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name})`);

  // Create a conversation and get a response
  const conversation = await openAIClient.conversations.create({});
  const response = await openAIClient.responses.create(
    {
      conversation: conversation.id,
      input: "What is the largest city in France?",
    },
    {
      body: {
        agent_reference: { name: agent.name, type: "agent_reference" },
      },
    },
  );
  console.log(`Response: ${response.output_text}`);

  // Clean up
  await openAIClient.conversations.delete(conversation.id);
  await project.agents.deleteVersion(agent.name, agent.version);
});

span.end();

// Shut down Azure Monitor to flush all pending traces before exit
await shutdownAzureMonitor();

Referência: classe AIProjectClient, telemetry.getApplicationInsightsConnectionString

import os

os.environ["AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING"] = "true"

from azure.ai.projects.telemetry import AIProjectInstrumentor
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor

# Set up console tracing
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(
    SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(tracer_provider)

# Enable instrumentation
AIProjectInstrumentor().instrument()

tracer = trace.get_tracer(__name__)

Você também pode usar o Aspire Dashboard como um visualizador compatível com OTLP local. Instale o exportador OTLP (pip install opentelemetry-exporter-otlp) e configure-o como exportador em vez de ConsoleSpanExporter.

Referência: AIProjectInstrumentor, ConsoleSpanExporter

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
using OpenTelemetry;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
using OpenAI.Responses;

var projectEndpoint = Environment.GetEnvironmentVariable(
    "FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException(
        "FOUNDRY_PROJECT_ENDPOINT isn't set.");
var modelName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL_NAME")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL_NAME isn't set.");

// Enable GenAI tracing
AppContext.SetSwitch("Azure.Experimental.EnableGenAITracing", true);

AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

// Configure OpenTelemetry with console exporter
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("Azure.AI.Projects.*")
    .SetResourceBuilder(
        ResourceBuilder.CreateDefault().AddService("AgentTracingSample"))
    .AddConsoleExporter()
    .Build();

using (tracerProvider)
{
    DeclarativeAgentDefinition agentDefinition = new(model: modelName)
    {
        Instructions = "You are a helpful assistant."
    };
    ProjectsAgentVersion agent = await projectClient.AgentAdministrationClient
        .CreateAgentVersionAsync(
            agentName: $"agent-tracing-{Guid.NewGuid():N}",
            options: new(agentDefinition));
    try
    {
        ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient
            .GetProjectResponsesClientForAgent(agent.Name);
#pragma warning disable OPENAI001
        ResponseItem request = ResponseItem.CreateUserMessageItem(
            "What is the largest city in France?");
        ResponseResult response = await responseClient.CreateResponseAsync(
            [request]);
#pragma warning restore OPENAI001
        Console.WriteLine($"Response: {response.GetOutputText()}");
    }
    finally
    {
        await projectClient.AgentAdministrationClient.DeleteAgentVersionAsync(
            agentName: agent.Name,
            agentVersion: agent.Version);
    }
}

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import { context, trace } from "@opentelemetry/api";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import {
  ConsoleSpanExporter,
  SimpleSpanProcessor,
} from "@opentelemetry/sdk-trace-base";
import "dotenv/config";

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "";
const modelName = process.env["FOUNDRY_MODEL_NAME"] || "";

// Set up console tracing
const provider = new NodeTracerProvider({
  spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())],
});
provider.register();

const tracer = trace.getTracer("AgentTracingConsoleSample");

// Enable tracing when you create the client
const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
  {
    tracingOptions: { contentRecording: false, experimental: true },
  },
);
const openAIClient = project.getOpenAIClient();

const span = tracer.startSpan("agent-tracing-console-scenario");
const ctx = trace.setSpan(context.active(), span);

await context.with(ctx, async () => {
  // Agent operations emit traces to the console
  const agent = await project.agents.createVersion("MyAgent", {
    kind: "prompt",
    model: modelName,
    instructions: "You are a helpful assistant.",
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name})`);
  await project.agents.deleteVersion(agent.name, agent.version);
});

span.end();
await provider.shutdown();

Referência: classe AIProjectClient

Defina a variável de ambiente antes da instrumentação:

import os

os.environ["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "true"

Use um AppContext interruptor ou a variável de ambiente:

// Enable content recording
AppContext.SetSwitch("Azure.Experimental.TraceGenAIMessageContent", true);

Ou defina a variável de OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT ambiente como true. Se a opção AppContext e a variável de ambiente estiverem definidas, a opção AppContext tem prioridade.

Defina contentRecording: true em tracingOptions ao criar o AIProjectClient:

const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
  {
    tracingOptions: { contentRecording: true, experimental: true },
  },
);

Você também pode definir a OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT variável de ambiente para true , em vez de passar a opção. A tracingOptions propriedade tem precedência sobre a variável de ambiente.

Crie um SpanProcessor personalizado para injetar metadados, como IDs de sessão, em cada span:

from opentelemetry.sdk.trace import SpanProcessor, ReadableSpan
from opentelemetry.trace import Span

class CustomAttributeSpanProcessor(SpanProcessor):
    def on_start(self, span: Span, parent_context=None):
        span.set_attribute("session.id", "user-session-abc")

    def on_end(self, span: ReadableSpan):
        pass

Registre o processador com o provedor de rastreamento global:

from typing import cast
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider

provider = cast(TracerProvider, trace.get_tracer_provider())
provider.add_span_processor(CustomAttributeSpanProcessor())

Crie um CustomAttributeProcessor.cs arquivo com um processador que adiciona atributos quando cada atividade é iniciada:

using System.Diagnostics;
using OpenTelemetry;

sealed class CustomAttributeProcessor : BaseProcessor<Activity>
{
    public override void OnStart(Activity activity)
    {
        activity.SetTag("session.id", "user-session-abc");
    }
}

Registre o processador em Program.cs ao criar o provedor de rastreador:

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("Azure.AI.Projects.*")
    .AddProcessor(new CustomAttributeProcessor())
    .AddConsoleExporter()
    .Build();

Referência: BaseProcessor<T>