Agent 的可觀測性：一次任務該記錄哪些欄位

Agent 的執行是非決定性的，同樣輸入可能走不同路徑。沒有完整軌跡，事後除錯幾乎不可能。

任務層級

• trace_id、user_id、開始與結束時間。
• 原始使用者輸入（必要時遮蔽個資）。
• 最終結果與結束原因：完成、步數上限、預算上限、錯誤中止。
• 總步數、總 token、總費用。

步驟層級

• step 序號、模型名稱與版本、提示版本。
• 工具名稱、參數（敏感欄位遮蔽）、耗時、成功與否。
• 工具回傳的長度與是否被截斷。
• 該步的 token 用量。

log.info('agent_step', extra={
    'trace_id': trace_id, 'step': step,
    'tool': call.name,
    'args': redact(call.arguments),
    'latency_ms': int((time.time() - t0) * 1000),
    'ok': result.get('ok', True),
    'truncated': truncated,
    'in_tok': usage.input_tokens, 'out_tok': usage.output_tokens,
})

三個最有用的衍生指標

1. 平均步數：突然上升代表任務變難或工具開始失敗。
2. 工具錯誤率（依工具分組）：直接指出是哪個外部系統出問題。
3. 截斷比例：偏高代表工具回傳設計需要調整。