Aggiungere il tracciamento lato client agli agenti Foundry (anteprima)

• Python 3.10 o versione successiva.
• Pacchetto azure-ai-projects versione 2.0.0 o successiva.

• .NET 8.0 o versione successiva.
• Il pacchetto NuGet Azure.AI.Projects.

• Node.js 20 LTS o versioni successive.
• Il pacchetto @azure/ai-projects versione 2.4.0 o successiva.

Installare Microsoft Foundry SDK, OpenTelemetry e l'utilità di esportazione Monitoraggio di Azure:

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

Per l'esportazione limitata a console o OTLP (ad esempio Aspire Dashboard), installare l'utilità di esportazione OTLP:

pip install opentelemetry-exporter-otlp

Aggiungere i pacchetti NuGet necessari:

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

Per le applicazioni ASP.NET Core, Azure.Monitor.OpenTelemetry.AspNetCore è il pacchetto preferito. Il pacchetto Azure.Monitor.OpenTelemetry.Exporter illustrato di seguito funziona per tutti i tipi di applicazione .NET.

Installare Microsoft Foundry SDK, OpenTelemetry e l'utilità di esportazione Monitoraggio di Azure:

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

Per l'esportazione solo per la console, sono necessari anche i pacchetti dell'SDK OpenTelemetry:

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

Impostare la variabile di ambiente AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACINGtrue prima di chiamare AIProjectInstrumentor().instrument():

import os

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

from azure.ai.projects.telemetry import AIProjectInstrumentor

# Enable instrumentation
AIProjectInstrumentor().instrument()

Se la variabile non è impostata o non corrisponde a true (indipendentemente dalle maiuscole), la strumentazione di tracciamento non è abilitata e viene registrato un avviso.

Usare un interruttore AppContext o la stessa variabile di ambiente:

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

Quando si abilita , l'SDK abilita automaticamente il flag />

Se vengono impostati sia l'interruttore AppContext che la variabile di ambiente, l'interruttore AppContext ha la priorità.

Passa tracingOptions in experimental: true quando crei il AIProjectClient. A differenza degli SDK Python e C#, JavaScript/TypeScript SDK abilita la traccia per ogni istanza client anziché tramite una chiamata di strumentazione separata:

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

È anche possibile impostare la AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING variabile di ambiente su true anziché passare l'opzione . La tracingOptions proprietà ha la precedenza sulla variabile di ambiente. Per un esempio completo, vedere Esportare tracce in Monitoraggio di Azure.

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"]

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"):
        with project.get_openai_client() as openai:
            # Create an agent
            agent = project.agents.create_version(
                agent_name="MyAgent",
                definition=PromptAgentDefinition(
                    model=os.environ["FOUNDRY_MODEL_NAME"],
                    instructions="You are a helpful assistant.",
                ),
            )
            print(f"Agent created (id: {agent.id}, name: {agent.name})")

            # Create a conversation and get a response
            conversation = openai.conversations.create()
            response = openai.responses.create(
                conversation=conversation.id,
                extra_body={"agent_reference": {"name": agent.name, "id": agent.id, "type": "agent_reference"}},
                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)

Riferimento: AIProjectClient, DefaultAzureCredential, configure_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);
    }
}

Riferimento: AIProjectClient, DefaultAzureCredential, Sdk.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();

Riferimento: 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__)

È anche possibile usare Aspire Dashboard come visualizzatore locale compatibile con OTLP. Installare l'esportatore OTLP (pip install opentelemetry-exporter-otlp) e configurarlo come esportatore al posto di ConsoleSpanExporter.

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

Riferimento: classe AIProjectClient

Impostare la variabile di ambiente prima di instrumentare:

import os

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

Usare un'opzione o la variabile di ambiente AppContext:

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

In alternativa, impostare la OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT variabile di ambiente su true. Se vengono impostati sia l'interruttore AppContext che la variabile di ambiente, l'interruttore AppContext ha la priorità.

Imposta contentRecording: true in tracingOptions quando crei AIProjectClient:

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

È anche possibile impostare la OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT variabile di ambiente su true anziché passare l'opzione . La tracingOptions proprietà ha la precedenza sulla variabile di ambiente.

Creare un oggetto personalizzato SpanProcessor per inserire metadati come gli ID sessione in ogni intervallo:

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

Registrare il processore con il provider di traccia globale:

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

Creare un CustomAttributeProcessor.cs file con un processore che aggiunge attributi all'avvio di ogni attività:

using System.Diagnostics;
using OpenTelemetry;

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

Registrare il processore in Program.cs quando si crea il provider di traccia:

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

Informazioni di riferimento: BaseProcessor<T>