OpenAI Agents SDK — traceで複数のRunを1つのトレースにまとめる
ChatGPTクローンを作ると、Runner.run を何度も呼ぶ場面が増えます。1回の質問ごとに1回実行、会話が続くほど Run も増える。
OpenAI Agents SDK では、デフォルトでは Run ごとにトレースが分かれます。デバッグや監視のとき、「このユーザーの一連の Run をまとめて見たい」という需要が出てきます。
今回は trace を使って、特定ユーザー（セッション）の 複数 Run を1つのトレースにグループ化 する方法を見ます。
デフォルト — Run ごとにトレースが分離
Runner.run を呼ぶたびに、Agents SDK は 個別のトレース を記録します。
result = await Runner.run(main_agent, "日本で一番熱い都市は？", session=session)
result = await Runner.run(main_agent, "韓国で一番熱い都市は？", session=session)
result = await Runner.run(main_agent, "中国で一番熱い都市は？", session=session)
このように3回実行すると、トレースダッシュボードには 3件の独立したトレース として表示されます。
| 状況 | トレースの数 |
|---|---|
Runner.run を3回 |
3件（Run ごとに分離） |
会話履歴を DB に残す SQLiteSession とは別の話です。Session は エージェントの記憶、trace は 実行ログのグループ化 です。
イメージは３回以上の複数回呼ばれている例
trace — 複数 Run を1つのトレースにまとめる
特定ユーザーの複数 Run を 1つのトレース名の下にまとめたい ときは、trace コンテキストマネージャを使います。
from agents import Agent, Runner, SQLiteSession, trace
session = SQLiteSession("user_1", "ai-memory.db")
with trace("user_yjyj"):
result = await Runner.run(
main_agent,
"日本で一番熱い都市は？",
session=session,
)
result = await Runner.run(
main_agent,
"韓国で一番熱い都市は？",
session=session,
)
result = await Runner.run(
main_agent,
"中国で一番熱い都市は？",
session=session,
)
with trace("user_yjyj"): ブロック内の すべての Run が、トレース名 user_yjyj の下にグループ化されます。
| 状況 | トレースの数 |
|---|---|
trace なしで3回 Run |
3件 |
with trace("user_yjyj"): 内で3回 Run |
1件（中に3 Task） |
トレース名 "user_yjyj" は任意の文字列です。ユーザー ID やセッション ID を渡すと、誰の一連の操作か をダッシュボードで追いやすくなります。
トレースダッシュボードで確認
Log画面を開くと、user_yjyj という名前の 1件のトレース に、複数 Run がまとまって表示されます。
一覧画面
-
Name:
user_yjyj -
Target:
Main Agent → Main Agent → Geaography Expert Agent → ...（Run ごとの実行パスが連結表示） -
Runs: 3 — ブロック内の
Runner.run回数
1行で「このユーザーが行った一連の操作」を把握できます。
詳細画面 — ツリービュー（Task ごとの実行構造）
トレースを開くと、Task 単位（= Runner.run 1回ごと）に実行構造がネスト表示されます。ここでは どの Agent が動いたか と handoff があったか がわかります。
user_yjyj
├── Task 1 (1,901 ms) ← 「日本で一番熱い都市は？」
│ └── Main Agent → turn → POST /v1/responses
│ ※ Handoff ノードなし
├── Task 2 (3,955 ms) ← 「韓国で一番熱い都市は？」
│ └── Main Agent
│ └── Handoff → Geaography Expert Agent
│ └── turn → POST /v1/responses
└── Task 3 (3,452 ms) ← 「中国で一番熱い都市は？」
└── Main Agent
└── Handoff → Geaography Expert Agent
└── turn → POST /v1/responses
詳細画面でTask 三つのツリーが表示されている
| Task | 質問 | 実行パス |
|---|---|---|
| Task 1 | 日本で一番熱い都市は？ | Main Agent のみ（handoff なし） |
| Task 2 | 韓国で一番熱い都市は？ | Main Agent → Handoff → Geography Expert Agent |
| Task 3 | 中国で一番熱い都市は？ | Main Agent → Handoff → Geography Expert Agent |
Task 3の詳細ログ
いつ trace を使うか
- 特定ユーザーの一連の操作 を1画面で追いたいとき
- handoff や tool 呼び出しを Run 横断で 分析したいとき
- 本番環境で レイテンシ・エラー率 をユーザー単位で確認したいとき
逆に、Run が1回だけなら trace は不要です。デフォルトのままで十分です。
まとめ
-
デフォルト —
Runner.runごとにトレースが 個別に 記録される -
with trace("名前"):— ブロック内の複数 Run を 1つのトレースにグループ化 -
SQLiteSessionは会話記憶、traceは実行ログ — 役割が異なる