AIエージェントのTracingとは？Tool Call・Handoffを追跡

AIエージェントが「最終結果は返したけれど、途中で何が起きたのか分からない」状態になると、原因調査が難しくなります。Tracingでは、1回のworkflowをTrace、その中のTool CallやHandoffなどをSpanとして追い、どの段階で挙動が変わったかを確認します。

まず確認：症状ごとに見るSpanを変える

症状	先に見る対象	確認ポイント
Tool結果が不正	Tool span	入力・出力・error
別Agentへ渡らない	Handoff span	遷移先・発火条件
回答が途中で止まる	Generation / Agent span	model応答・例外・guardrail
安全チェックで止まる	Guardrail span	tripwireや判定結果
全体が遅い	各Spanの時間	どのoperationが時間を使ったか

OpenAI Agents SDKのTracingは、LLM生成、Tool Call、Handoff、Guardrail、カスタムイベントなどを記録できます。まず「最終結果」だけでなく、どのoperationが原因候補かを絞ります。

TraceとSpanの違いを先に理解する

用語解説：Trace
1回のend-to-end workflowを表す単位です。会話1ターンや1つの業務処理など、全体をひとまとまりとして追います。

用語解説：Span
Traceの中にある個別operationです。Agent実行、LLM generation、Tool Callなどに開始・終了や親子関係を持たせて追跡します。

Traceが「注文処理全体」なら、Spanは「在庫確認」「決済」「通知」のような個別処理です。どのSpanで想定と違う値になったかを見ると、原因の範囲を狭められます。

Agents SDKではTracingが標準で記録される

OpenAI Agents SDKのPython実装ではTracingが既定で有効です。RunnerによるAgent実行がTraceで囲まれ、内部のGeneration、Tool、HandoffなどがSpanとして記録されます。Trace viewerを使うとworkflowを時系列で確認できます。

from agents import Agent, Runner

agent = Agent(
    name="Support Agent",
    instructions="問い合わせ内容を分類し、必要なToolを使って回答する"
)

result = Runner.run_sync(agent, "注文A-1041の状況を確認して")
print(result.final_output)

自分でworkflow名とmetadataを付ける

複数の処理を比較したい場合は、workflow名やmetadataを付けるとTraceを探しやすくなります。会話IDやrequest種別など、個人情報を避けた識別子を使うと運用しやすくなります。

from agents import trace

with trace(
    workflow_name="order_support",
    group_id="thread-1041",
    metadata={"flow": "status_check"}
):
    result = Runner.run_sync(agent, "注文状況を確認して")

metadataには原因切り分けに必要な情報だけを残します。秘密情報や不要な本文を観測性のためだけに複製しないことも重要です。