OpenAI Agent SDKとW&B WeaveでAIエージェントをトレースしてみた

はじめに

はじめまして！株式会社NTTデータグループ 技術革新統括本部 AI技術部の大木郁登と申します。

先日、社内で「OpenAI Agents SDK × W&B Weave」についてのハンズオンに参加しました。近年、エージェントやLLMのオブザーバビリティが重要視されていますが、オブザーバビリティツールとして素晴らしい内容を学ぶことができたためご紹介します。
なお、ハンズオンの様子については後日、別記事で掲載しようと思います。

本記事では、その内容をもとにシングルエージェントをWeaveでトレースする最小例を紹介します。記事を読めば、実装→実行→トレース確認→CSVエクスポートまで一通り体験することができます。

想定読者

• OpenAI Agents SDKでAIエージェントを実装し、挙動（ツール呼び出し、プロンプト、出力）を追跡したい人
• W&B Weaveでエージェントのトレースを始めたい人
• OpenAI Agents SDKについての理解がある程度ある人（一度触ったことがあればOK）

記事の構成

記事の構成は以下の通りです。

1. OpenAI Agents SDKとは
2. W&B Weaveとは
3. 環境構築
4. 実装・動作確認の方針
5. エージェントの実装及び動作確認
6. エージェントのトレース
7. 最後に

1. OpenAI Agents SDKとは

OpenAI Agents SDKは、エージェント型AIアプリケーションを構築するための軽量で使いやすいツールキットです。このSDKは、Pythonをベースに設計されており、複雑な抽象化を最小限に抑えつつ、実際のアプリケーション開発に必要な機能を提供します。
主なコンポーネントとして、以下が含まれます。

• エージェント: 指示やツールを備えたLLM（大規模言語モデル）。
• ハンドオフ: 特定のタスクを他のエージェントに委任する機能。
• ガードレール: エージェントへの入力を検証し、不正なデータを防ぐ仕組み。
• セッション管理: エージェント間の会話履歴を自動的に保持。
• トレーシング: ワークフローの可視化やデバッグ、評価を可能にする機能。
  ※Bing Copilot Searchにより生成
  ※参考1:https://openai.github.io/openai-agents-python/

2. W&B Weaveとは

W&B Weave（ウィーブ）は、LLMアプリやAI機能を“観察・評価・改善”するためのツールキットです。開発中や本番運用中の「モデル呼び出しやアプリの処理の流れ」を記録（トレーシング）し、結果を比較・評価して、次の改善につなげやすくしてくれます。
主なコンポーネントとして、以下が含まれます。

• トレーシング（実行記録）：LLMの呼び出しや関数の入出力を時系列で可視化。どこで何が起きたかを後から追えるので、デバッグや運用監視が楽になります。
• 評価（Evaluation）：スコアラーやジャッジを使って、モデルやプロンプトの良し悪しを定量比較。実験結果を並べて差分を確認できます。
• 反復改善・実験：プロンプトやモデル設定を変えて試し、結果を蓄積・比較して最適化。Playgroundやレジストリ（W&B Models）とも連携できます。
  ※ChatGPTにより生成
  ※参考2:https://wandb.ai/site/weave/
  ※参考3:https://weave-docs.wandb.ai/

3. 環境構築

前提

• OSはWindows 11で動作確認済み
• Python 3.12.10で動作確認済み
• OpenAI Agents SDK（Pythonのパッケージ名はopenai-agents）0.3.0で動作確認済み
• W&B Weave（Pythonのパッケージ名はweave）0.52.7で動作確認済み
• OpenAI APIキーが発行済み
• W&B APIキーが発行済み

環境構築手順

こちらのリポジトリからコードをクローンしREADMEに従って環境構築を実施してください。

4. 実装・動作確認の方針

今回はWeaveのメリットを明らかにするために、エージェント実装においてWeave「あり」と「なし」それぞれのコードを用意し実行結果を比較します。そのため最もシンプルなエージェントとして_3_agents_sdk.pyを利用します。
_3_agents_sdk.pyでは、シングルエージェントに"What is 2 + 2?"の回答を出力させるものとなっています。

5. エージェントの実装及び動作確認

まずはWeaveなしでエージェントの挙動を確認するため、_3_agents_sdk.pyのコードからWeaveに関する箇所を削除し実行します。
※コード内のコメントはChatGPTで生成しています。

import asyncio
from agents import Agent, Runner, function_tool

# @function_tool によって、この関数はエージェントが利用できる「ツール」として登録される。
@function_tool
def add(a: int, b: int) -> int:
    return a + b

# ここでエージェントを定義
agent = Agent(
    name="Calculator",
    instructions="You are a calculator. You can add two numbers together.",
    tools=[add],
)

async def run_sdk(input):
    # Runner.run(agent, input) でエージェントを実行し応答を受け取る。
    response = await Runner.run(agent, input)
    print(response.final_output)
    return response.final_output

if __name__ == "__main__":
    asyncio.run(run_sdk(input="What is 2 + 2?"))

_3_agents_sdk.pyの実行及び出力の確認

python _3_agents_sdk.py
2 + 2 is 4.

6. エージェントのトレース

先程動作確認したコードにWeaveによるトレース用のコードを加え、シングルエージェントの挙動を確認してみます。
※コード内のコメントはChatGPTで生成しています。

import config
import asyncio
import weave
from agents import Agent, Runner, function_tool, set_trace_processors
from weave.integrations.openai_agents.openai_agents import WeaveTracingProcessor

# Weave のログ・トレースを特定のプロジェクトに紐付ける。 
+weave.init(project_name=config.WEAVE_PROJECT)
# set_trace_processors: トレース処理を Weave 側で受け取る設定。
+set_trace_processors([WeaveTracingProcessor()])

# @function_tool によって、この関数はエージェントが利用できる「ツール」として登録される。
@function_tool
def add(a: int, b: int) -> int:
    return a + b

# ここでエージェントを定義
agent = Agent(
    name="Calculator",
    instructions="You are a calculator. You can add two numbers together.",
    tools=[add],
)

# @weave.op() によって Weave 側でこの処理も追跡できるようになる。
[e-mail]()
async def run_sdk(input):
    # Runner.run(agent, input) でエージェントを実行し応答を受け取る。
    response = await Runner.run(agent, input)
    print(response.final_output)
    return response.final_output

if __name__ == "__main__":
    asyncio.run(run_sdk(input="What is 2 + 2?"))

_3_agents_sdk.pyの実行結果を確認すると、Weaveの利用によりエージェントの出力結果だけでなく、正常にログインできたことやトレース結果を確認できるURLが表示されています。

python .\_3_agents_sdk.py
weave: Logged in as Weights & Biases user: <ユーザ名>.
weave: View Weave data at https://<テナント名>/<ユーザ名>/agents-course-live/weave
weave: 🍩 https://<テナント名>/<ユーザ名>/agents-course-live/r/call/XXXXXXX
2 + 2 = 4

※実際には<テナント名>、<ユーザ名>、XXXXXXXには適切な値が記載されています。

Weaveによる取得情報の確認

ターミナルに出力されるトレース用リンクにアクセスすると以下のような画面でトレース一覧結果のリストが表示されています。（赤枠部分が今回実行した結果）
取得可能な主な項目は以下。

• Status（正常終了の有無）
• input（エージェントへの入力で引数名をinputとしているもの）
• prompt（エージェントへの入力で引数名をpromptとしているもの※上記inputとは名前の付け方が異なるだけ）
• output（エージェントからの出力）
• User（ユーザ）
• Tokens（実行に使用したトークン数）
• Cost（実行に要したコスト）
• Latency（run_sdk関数の実行時間）
  

エージェントのワークフローを確認することができる

「export」ボタンから、CSV等の形式で出力することもできます。

API使用料推移・入出力トークン数・レイテンシをグラフで確認することもできます。

7. 最後に

本記事では、OpenAI Agents SDKのシングルエージェントをW&B Weaveでトレースする手順を紹介しました。プロンプト・入出力・トークン・コスト・レイテンシをUIで横断的に可視化でき、CSVエクスポートで実験管理もしやすくなります。次回はマルチエージェントのトレースや、評価機能を使った定量比較も取り上げていきたいと思います。