メインコンテンツへスキップ
OpenTelemetry (OTEL) を使用すると、Weave で PydanticAI のエージェントとツールの call をトレースできます。PydanticAI は、生成 AI を使った本番環境向けのアプリケーションを簡単かつ型安全に構築できるように、Pydantic チームが開発した Python のエージェントフレームワークです。すべてのエージェントとツールの call をトレースするために OTEL を使用します。
Weave における OTEL トレースの詳細については、Send OTEL Traces to Weave を参照してください。
このガイドは、Weave でエージェントとツールの実行状況を可視化したい、PydanticAI のエージェントを構築する開発者向けです。OTEL を使用して PydanticAI のエージェントとツールの call をトレースし、それらのトレースを Weave で可視化する方法を説明します。必要な依存関係をインストールし、Weave にデータを送信する OTEL トレーサーを設定し、PydanticAI のエージェントとツールを計装する方法を学びます。また、アプリケーション内のすべてのエージェントでデフォルトでトレースを有効にする方法も紹介します.

前提条件

Weaveにトレースを送信するには、まずOTELの依存関係をインストールし、OTELエクスポーターを設定する必要があります。必要なOTELの依存関係をインストールしてください。
pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
次に、WeaveでOTELトレースを設定します

Weave で OTEL トレースを設定する

PydanticAI から Weave にトレースを送信するには、TracerProviderOTLPSpanExporter を使用して OTEL を設定します。エクスポーターには、認証とプロジェクト識別に必要な正しいエンドポイントと HTTP ヘッダーを設定してください。 APIキーやプロジェクト情報などの機密性の高い環境変数は、環境ファイル (たとえば .env) に保存し、os.environ を使って読み込んでください。こうすることで、認証情報を安全に保ち、コードベースに含めずに済みます。

必須設定

  • エンドポイント: https://trace.wandb.ai/otel/v1/traces
  • ヘッダー:
    • Authorization: W&B APIキーを使用するBasic認証。
    • project_id: W&B の entity とプロジェクト名 (例: myteam/myproject)。

設定例

次のコードスニペットでは、OTLP span exporter と トレーサープロバイダー を設定して、PydanticAI アプリケーションから Weave に OTEL トレースを送信する方法を示します。
import base64
import os
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk import trace as trace_sdk
from opentelemetry.sdk.trace.export import SimpleSpanProcessor

# 環境変数から機密情報を読み込む
WANDB_BASE_URL = "https://trace.wandb.ai"
PROJECT_ID = os.environ.get("WANDB_PROJECT_ID")  # W&B のエンティティ/プロジェクト名(例: "myteam/myproject")
WANDB_API_KEY = os.environ.get("WANDB_API_KEY")  # W&B APIキー

OTEL_EXPORTER_OTLP_ENDPOINT = f"{WANDB_BASE_URL}/otel/v1/traces"
AUTH = base64.b64encode(f"api:{WANDB_API_KEY}".encode()).decode()

OTEL_EXPORTER_OTLP_HEADERS = {
    "Authorization": f"Basic {AUTH}",
    "project_id": PROJECT_ID,
}

# エンドポイントとヘッダーを指定して OTLP span エクスポーターを作成する
exporter = OTLPSpanExporter(
    endpoint=OTEL_EXPORTER_OTLP_ENDPOINT,
    headers=OTEL_EXPORTER_OTLP_HEADERS,
)

# トレーサープロバイダーを作成してエクスポーターを追加する
tracer_provider = trace_sdk.TracerProvider()
tracer_provider.add_span_processor(SimpleSpanProcessor(exporter))
これで、OTEL トレースを Weave にルーティングするために PydanticAI エージェントに渡せる tracer_provider を利用できます。

OTEL で PydanticAI エージェントをトレースする

PydanticAI エージェントをトレースし、トレースデータを Weave に送信するには、トレーサープロバイダーで設定した InstrumentationSettings オブジェクトを Agent コンストラクタに渡します。これにより、すべてのエージェントとツールの call が、OTEL の設定に従ってトレースされます。 次の例では、トレースを有効にした基本的なエージェントを作成する方法を示します。重要な step は、エージェントの初期化時に instrument 引数を設定することです。
from pydantic_ai import Agent
from pydantic_ai.models.instrumented import InstrumentationSettings

# OTEL トレースを有効にした PydanticAI エージェントを作成する
agent = Agent(
    "openai:gpt-4o",
    instrument=InstrumentationSettings(tracer_provider=tracer_provider),
)

result = agent.run_sync("What is the capital of France?")
print(result.output)
エージェントへのすべてのcallはトレースされ、Weave に送信されます。
基本的なPydanticAIエージェントのトレースの可視化

OTEL で PydanticAI のツールをトレースする

Weave では、エージェント と ツールの call を含む、OTEL でインストルメントされたあらゆる PydanticAI の operation をトレースできます。つまり、エージェント がツール (たとえば @agent.tool_plain でデコレートされた関数) を呼び出すと、ツールの inputs、outputs、そしてモデルの推論を含むやり取り全体が Weave でキャプチャされ、可視化されます。 次の例では、system prompt とツールを備えた エージェント を作成する方法を示します。トレースは エージェント とツールの両方で自動的に有効になります。
from pydantic_ai import Agent
from pydantic_ai.models.instrumented import InstrumentationSettings

# system prompt と OTEL トレースを備えた PydanticAI エージェントを作成する
agent = Agent(
    "openai:gpt-4o",
    system_prompt=(
        "You are a helpful assistant that can multiply numbers. "
        "When asked to multiply numbers, use the multiply tool."
    ),
    instrument=InstrumentationSettings(tracer_provider=tracer_provider),
)

# ツールを定義する
@agent.tool_plain
def multiply(a: int, b: int) -> int:
    """Multiply two numbers."""
    return a * b

# エージェントにツールを使用するよう指示する
result = agent.run_sync("What is 7 multiplied by 8?")
print(result.output)
ツールの call のトレース可視化
エージェント call と ツールの call はどちらも Weave でトレースされるため、アプリケーションの推論から実行までの全経路を確認できます.

デフォルトですべてのエージェントにインストルメンテーションを適用する

アプリケーション内のすべての PydanticAI エージェントに OTEL トレースを適用するには、Agent.instrument_all() method を使用します。これにより、instrument パラメーターを明示的に指定していないエージェントに対して、デフォルトの InstrumentationSettings インスタンスが設定されます。
from pydantic_ai import Agent
from pydantic_ai.models.instrumented import InstrumentationSettings

# すべてのエージェントにデフォルトのインストルメンテーションを設定する
Agent.instrument_all(InstrumentationSettings(tracer_provider=tracer_provider))

# 以降、新しいエージェントはデフォルトでこのインストルメンテーションを使用する
agent1 = Agent("openai:gpt-4o")
agent2 = Agent("openai:gpt-4o", system_prompt="Be helpful.")

result = agent1.run_sync("What is the capital of France?")
print(result.output)
これは、設定を繰り返し記述することなく、すべてのエージェントで一貫したトレースを実現したい大規模なアプリケーションで役立ちます。詳細については、PydanticAI OTEL ドキュメントを参照してください。

さらに詳しく