クライアント側トレースを Foundry エージェントに追加する (プレビュー)

• Python 3.10 以降。
• azure-ai-projects パッケージ バージョン 2.0.0 以降。

• .NET 8.0 以降。
• Azure.AI.Projects NuGet パッケージ。

• Node.js 20 LTS 以降。
• @azure/ai-projects パッケージ バージョン 2.4.0 以降。

Microsoft Foundry SDK、OpenTelemetry、および Azure Monitor エクスポーターをインストールします。

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

コンソール専用または OTLP エクスポート ( たとえば、アスパイア ダッシュボード) の場合は、OTLP エクスポーターをインストールします。

pip install opentelemetry-exporter-otlp

必要な NuGet パッケージを追加します。

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

ASP.NET Core アプリケーションの場合、Azure.Monitor.OpenTelemetry.AspNetCore が推奨パッケージです。 ここで示す Azure.Monitor.OpenTelemetry.Exporter パッケージは、すべての.NETアプリケーションの種類に対して機能します。

Microsoft Foundry SDK、OpenTelemetry、および Azure Monitor エクスポーターをインストールします。

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

コンソールのみのエクスポートには、OpenTelemetry SDK パッケージも必要です。

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

AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACINGを呼び出すtrueに、環境変数を AIProjectInstrumentor().instrument() に設定します。

import os

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

from azure.ai.projects.telemetry import AIProjectInstrumentor

# Enable instrumentation
AIProjectInstrumentor().instrument()

変数が設定されていない場合、または true されていない場合 (大文字と小文字は区別されません)、トレース インストルメンテーションは有効ではなく、警告がログに記録されます。

AppContext スイッチまたは同じ環境変数を使用します。

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

Azure.Experimental.EnableGenAITracing を有効にすると、OPENTelemetry インストルメンテーションが機能するために必要な Azure.Experimental.EnableActivitySource フラグが SDK によって自動的に有効になります。

AppContext スイッチと環境変数の両方が設定されている場合、AppContext スイッチが優先されます。

AIProjectClientを作成するときに、tracingOptionsにexperimental: trueを渡します。 Pythonおよび C# SDK とは異なり、JavaScript/TypeScript SDK では、個別のインストルメンテーション呼び出しではなく、クライアント インスタンスごとにトレースを有効にします。

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

オプションを渡す代わりに、 AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING 環境変数を true に設定することもできます。 tracingOptions プロパティは、環境変数よりも優先されます。 完全な例については、「トレースをAzure Monitorにエクスポートする」を参照してください。

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)

リファレンス: 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);
    }
}

リファレンス: 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();

リファレンス: 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__)

また、ローカル OTLP 互換ビューアーとして 、アスパイア ダッシュボード を使用することもできます。 OTLP エクスポーター (pip install opentelemetry-exporter-otlp) をインストールし、 ConsoleSpanExporterではなくエクスポーターとして構成します。

リファレンス: 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();

リファレンス: AIProjectClient クラス

インストルメント化する前に環境変数を設定します。

import os

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

AppContext スイッチまたは環境変数を使用します。

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

または、 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT 環境変数を true に設定します。 AppContext スイッチと環境変数の両方が設定されている場合、AppContext スイッチが優先されます。

contentRecording: trueを作成するときに、tracingOptionsでAIProjectClientを設定します。

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

オプションを渡す代わりに、 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT 環境変数を true に設定することもできます。 tracingOptions プロパティは、環境変数よりも優先されます。

セッション ID などのメタデータをすべてのスパンに挿入するカスタム SpanProcessor を作成します。

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

グローバル トレーサー プロバイダーにプロセッサを登録します。

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

各アクティビティの開始時に属性を追加するプロセッサを含む CustomAttributeProcessor.cs ファイルを作成します。

using System.Diagnostics;
using OpenTelemetry;

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

トレーサー プロバイダーをビルドするときに、プロセッサを Program.cs に登録します。

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

BaseProcessor<T> を参照してください。