PydanticAI

OpenTelemetry を使用して Weave で PydanticAI のエージェントとツールの call をトレースする

OpenTelemetry (OTEL) を使用すると、Weave で PydanticAI のエージェントとツールの call をトレースできます。PydanticAI は、生成 AI を使った本番環境向けのアプリケーションを簡単かつ型安全に構築できるように、Pydantic チームが開発した Python のエージェントフレームワークです。すべてのエージェントとツールの call をトレースするために OTEL を使用します。

Weave における OTEL トレースの詳細については、Send OTEL Traces to Weave を参照してください。

このガイドでは、OTEL を使用して PydanticAI のエージェントとツールの call をトレースし、それらのトレースを Weave で可視化する方法を説明します。必要な依存関係をインストールし、Weave にデータを送信する OTEL トレーサーを設定し、PydanticAI のエージェントとツールを計装する方法を学びます。また、アプリケーション内のすべてのエージェントでデフォルトでトレースを有効にする方法も紹介します.

​

前提条件

始める前に、必要なOTELの依存関係をインストールしてください。

pip install opentelemetry-sdk OTELemetry-exporter-otlp-proto-http

次に、WeaveでOTELトレースを設定します。

​

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

PydanticAI から Weave にトレースを送信するには、TracerProvider と OTLPSpanExporter を使用して 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)

​

設定例

次のコード例では、PydanticAI アプリケーションから Weave に OTEL トレースを送信するために、OTLP span exporter と トレーサープロバイダー を設定する方法を示します。

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 entity/プロジェクト名 例: "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スパンエクスポーターを作成する
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 で PydanticAI Agents をトレースする

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 に送信されます。

​

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:
    """2つの数値を掛け合わせる。"""
    return a * b

# エージェントにツールを使用するよう指示する
result = agent.run_sync("What is 7 multiplied by 8?")
print(result.output)

エージェント 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 ドキュメントを参照してください。

​

さらに詳しく

• Weave ドキュメント: OTEL トレースを Weave に送信する
• OpenTelemetry 公式ドキュメント
• PydanticAI 公式ドキュメント
• PydanticAI GitHub リポジトリ