OpenAI Agents SDK : トレース

by

OpenAI Agents SDK のトレースについて、スパンやデフォルトのトレースについての説明です。

OpenAI Agents SDK : トレース

作成 : クラスキャット・セールスインフォメーション
作成日時 : 03/25/2025

* 本記事は openai.github.io/openai-agents-python の以下のページを独自に翻訳した上でまとめ直し、補足説明を加えています :

* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。
* ご自由にリンクを張って頂いてかまいませんが、sales-info@classcat.com までご一報いただけると嬉しいです。

 

クラスキャット 人工知能 研究開発支援サービス ⭐️ リニューアルしました 😉

◆ クラスキャット は人工知能に関する各種サービスを提供しています。お気軽にご相談ください :

  • 人工知能導入個別相談会(無償)実施中！ [詳細]

  • 人工知能研究開発支援 [詳細]
    1. 自社特有情報を含むチャットボット構築支援
    2. 画像認識 (医療系含む) / 画像生成

  • PoC(概念実証)を失敗させないための支援 [詳細]

◆ お問合せ : 下記までお願いします。

  • クラスキャット セールス・インフォメーション
  • sales-info@classcat.com
  • ClassCatJP

 

 

OpenAI Agents SDK : トレース

Agents SDK は組み込みのトレースを含み、エージェント実行中のイベントの包括的な記録を収集します : LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、そして発生するカスタムイベントさえも。トレース・ダッシュボード を使用して、開発中そして実運用中にワークフローをデバッグ、視覚化、そして監視することができます。

Note : トレースはデフォルトで有効にされています。トレースを無効にする 2 つの方法があります :

  1. 環境変数 OPENAI_AGENTS_DISABLE_TRACING=1 を設定することで、トレースをグローバルに無効にできます。

  2. agents.run.RunConfig.tracing_disabled を True に設定することで単一の実行のトレースを無効にできます。

For organizations operating under a Zero Data Retention (ZDR) policy using OpenAI’s APIs, tracing is unavailable.

 

トレースとスパン

  • トレース は「ワークフロー」の単一の end-to-end な操作を表します。それらはスパン (Spans) で構成されています。トレースは以下のプロパティを持ちます :
    • workflow_name: これは論理ワークフローかアプリケーションです。例えば、”Code generation” や “Customer service” です。

    • trace_id: トレースの一意な ID です。渡さない場合は自動的に生成されます。形式 trace_<32_alphanumeric> が必須です。

    • group_id: 同じ会話から複数のトレースをリンクするためのオプションのグループ ID です。例えば、チャット・スレッド ID を使用しても良いでしょう。

    • disabled: True の場合、トレースは記録されません。

    • metadata: トレースのオプションのメタデータ。

  • スパン は開始時刻と終了時刻を持つ操作を表します。スパンは以下を持ちます :
    • started_at と ended_at タイムスタンプ。

    • trace_id, それらが属するトレースを表します。

    • parent_id, これは (もしあれば) このスパンの親スパンを指します。

    • span_data, これはスパンについての情報です。例えば、AgentSpanData はエージェントについての情報を含み、GenerationSpanData は LLM 生成についての情報を含みます、等々。

 

デフォルトのトレース

デフォルトでは、SDK は以下をトレースします :

  • Runner.{run, run_sync, run_streamed}() 全体が trace() でラップされます。

  • エージェントが実行されるたび、agent_span() でラップされます。

  • LLM 生成は generation_span() でラップされます。

  • 関数ツール呼び出しはそれぞれ function_span() でラップされます。

  • ガードレールは guardrail_span() でラップされます。

  • ハンドオフは handoff_span() でラップされます。

  • 音声入力 (音声-to-テキスト) は transcription_span() でラップされます。

  • 音声出力 (テキスト-to-音声) は speech_span() でラップされます。

  • 関連する音声スパンは speech_group_span() の下に親として配置して良いです。

デフォルトでは、トレースは “Agent trace” と命名されます。トレースを使用する場合、この名前を設定できます、あるいは、RunConfig で名前とその他のプロパティを構成できます。

更に、カスタム・トレース・プロセッサ をセットアップして (代替、またはセカンダリ destinations として) トレースを他の destinations にプッシュすることもできます。

 

より高位なトレース

run() の複数の呼び出しを単一のトレースの一部にしたい場合があります。コード全体を trace() でラップすることでこれを行なうことができます。

from agents import Agent, Runner, trace

async def main():
    agent = Agent(name="Joke generator", instructions="Tell funny jokes.")

    with trace("Joke workflow"): 
        first_result = await Runner.run(agent, "Tell me a joke")
        second_result = await Runner.run(agent, f"Rate this joke: {first_result.final_output}")
        print(f"Joke: {first_result.final_output}")
        print(f"Rating: {second_result.final_output}")

 

トレースの作成

trace() 関数をトレースを作成するために使用できます。トレースは開始して終了する必要があります。それを行なう 2 つのオプションがあります :

  1. 推奨 : trace をコンテキスト・マネージャとして使用します、i.e. “with trace(…) as my_trace”. これは適切なタイミングでトレースを自動的に開始して終了します。

  2. trace.start() と trace.finish() を手動で呼び出すこともできます。

現在のトレースは Python contextvar を使用して追跡されます。つまり、自動的に平行処理 (concurrency) されます。手動でトレースを開始/終了する場合は、現在のトレースを更新するために mark_as_current と reset_current を start()/end() に渡す必要があります。

 

スパンの作成

様々な *_span() メソッドを使用してスパンを作成することができます。通常は、手動でスパンを作成する必要はありません。カスタム・スパンの情報を追跡するために custom_span() 関数が利用可能です。

スパンは自動絵的に現在のトレースの一部となり、Python contextvar で追跡される、最も近い現在のスパンの下でネストされます、

 

機密データ

特定のスパンは潜在的に機密データを捕捉する可能性があります。generation_span() は LLM 生成の入力/出力をストアし、function_span() は関数呼び出しの入力/出力をストアします。これらは機密データを含む可能性があるので、RunConfig.trace_include_sensitive_data を使用してそのデータを捕捉することを無効にできます。

同様に、音声スパンはデフォルトで入力と出力音声用の base64-encoded PCM データを含みます。VoicePipelineConfig.trace_include_sensitive_audio_data を構成することで、音声データの捕捉を無効にできます。

 

カスタム・トレース・プロセッサ

トレースの高位アーキテクチャは :

  • 初期化時、グローバルな TraceProvider を作成します、これはトレースの作成を担います。

  • トレース/スパンをバッチで BackendSpanExporter に送信する BatchTraceProcessor を使用して TraceProvider を構成します。BackendSpanExporter はスパンとトレースを OpenAI バックエンドにバッチでエクスポートします。

このデフォルトのセットアップをカスタマイズして、トレースを代替や追加のバックエンドに送信したり、exporter の動作を変更するには、2 つのオプションがあります :

  1. add_trace_processor() は、準備ができればトレースとスパンを受信する、追加の トレース・プロセッサを追加することを可能にします。これはトレースを OpenAI のバックエンドに送信することに加えて、独自の処理を行なうことを可能にします。

  2. set_trace_processors() はデフォルトのプロセッサを独自のトレースプロセッサと 置き換える ことを可能にします。つまり、トレースは、それを行なう TracingProcessor を含めない限り、OpenAI バックエンドに送信されません。

 

外部トレース・プロセッサのリスト

 

以上