可観測性とデバッグ: エージェントの一歩一歩を見る

このコースはエージェントが実際に何をしたのかを見ることを扱います。前のコース（このシリーズの 10 番目）は「通ったかどうか」に決着をつけました――最終状態の採点、検証器、評価セットです。しかし評価が渡してくれるのは合否だけです。ユーザーから「明らかにそこにある情報を見つけられない」と報告されたとき、あなたはまだ理由を言えません。検索クエリの言い回しが悪かったのか。ソースの選び方が悪かったのか。ツールが単にエラーを返しただけなのか。外から見れば、これらの原因は見分けがつきません。さらに悪いことに、エージェントは実行ごとに非決定的です。同じプロンプトが 2 回の実行で 2 つの異なる経路をたどるため、「再現してからブレークポイントを置く」という従来のデバッグの本能が効かなくなります。本コースは「言えない」を「調べられる」に変える方法を教えます。まず、生のトランスクリプト（ツール呼び出しとレスポンスの往復すべて）が一次証拠であり、エージェントの自己申告は証拠にならないことを確立します。次に、ハーネスに構造化ログとメトリクス（実行時間、呼び出し回数、トークン、エラー――今回は採点のためではなく、本番を見張るためです）を備え付けます。続いて、散らばった記録を相関 ID でトレースツリーにつなぎ、1 つのプロンプトが引き起こしたモデルリクエストとツール実行のすべてを 1 つのまとまりとして読めるようにします。さらに、フックを使ってループの要所にプローブを置き、非決定性のために組み立てられたデバッグのワークフローを歩きます。そして最後に、コース7 のハーネスに完全な可観測性レイヤーを配線し、「言えない」症状 1 つを、実際に間違ったステップまで追跡します。このシリーズの最初の 10 のコースを終えた読者向けです。特定の可観測性プラットフォームは扱わず（Datadog や Grafana などは引用が名指しする箇所でのみ登場します）、アラートのしきい値や SLO の設計も扱いません（一次資料に数値が存在しないためです）。コース10 の評価の手法も繰り返しません――向こうではメトリクスが採点し、ここでは同じメトリクスが診断します。

コース構成

学習目標

このコースを終えると、次のことができるようになります:

非決定性が「再現してからデバッグする」をどう壊すかを説明する: 同じプロンプトが 2 つの異なる、しかしどちらも正当な経路をたどり、1 つの症状の上に、外からは見分けのつかない複数の原因が乗っている
生のトランスクリプトを一次証拠として使う: ツール呼び出しとレスポンスの往復をすべて読み、エージェントの思考連鎖や自己申告が一度も触れなかった振る舞いを捕まえ、なぜ自己申告が信用できないのかを説明する
自分のハーネス向けに構造化ログとメトリクスを設計する: モデルリクエストごと、ツール呼び出しごとに記録を 1 本、実行時間、呼び出し回数、トークン、エラーをカバーする――そして公式の診断的な読み方を使って、メトリクスのパターンを具体的な修正に対応づける
散らばった記録を相関 ID でトレースツリーにつなぐ: 1 つのプロンプトが引き起こしたすべてが 1 つのまとまりとして読め、サブエージェントは親のトレースに入れ子になる――そしてテレメトリのパイプライン自身がどうあなたに嘘をつくか（沈黙する失敗、バッチの損失）を知る
ループのライフサイクルの要所にプローブを置く: セッションごと、ターンごと、ツール呼び出しごとの観測点を切り分け、PostToolUse で完全な呼び出し記録を取得し、prompt id で絞り込む → 最初の分岐点を見つける → 同一の入力で 1 ステップずつ再生する、というワークフローに沿って問題を切り分ける
コース7 のハーネスに完全な可観測性レイヤー（JSONL の構造化ログ + トレースツリーの出力 + メトリクスの集計）を配線し、デバッグのドリルを 1 周させる: 症状 → 絞り込み → 切り分け → 修正 → 再実行の比較（実際の実行は失敗地点から再開します）

前提知識

このシリーズの最初の 10 のコースを終えている、または同等の知識がある
stop_reason 駆動のハーネスループを手書きでき、tool_use / tool_result の対応づけを理解している（コース7）
評価トラックと、合格率にとどまらないメトリクスを知っている（コース10。本コースは同じメトリクスを採点から診断へ移します）
基本的な JavaScript / Node.js のコードを読み書きできる（レッスン6 では一緒に書き進めます）

想定学習時間

約 3〜4 時間（各レッスンのハンズオン演習を含む）。