連載: AIに仕事を奪われる不安から始めるハーネス作成入門
第13回 ← 前回（第12回）: モデルルーターの設計
はじめに：AIエージェントの「暴走」が怖い方へ
AIエージェントを業務で使い始めようとすると、「おかしな処理をしてしまったらどうするのか」「失敗したときに原因を特定できるのか」という不安が浮かびます。これは自然な懸念です。
しかし、SE経験者であれば、この問題に対する答えを既に知っています。それがログ設計です。業務システムでも、問題発生時にログがなければ原因調査はできません。AIエージェントも同じです。
本記事では、AIハーネスにログ設計が必要な理由を整理し、「何を記録すべきか」のログ項目表を作成します。
従来システムとAIエージェントのログの違い
従来の業務システムのログとAIエージェントのログを比較すると、重要な違いが見えてきます。
| 観点 | 従来システム | AIエージェント |
|---|---|---|
| 処理内容 | 事前に定義済み | 実行時に動的に決定 |
| 出力の予測可能性 | 高い（同じ入力→同じ出力） | 低い（同じ入力でも異なる出力） |
| エラーの性質 | 明示的（例外・エラーコード） | 潜在的（一見正しいが不正確） |
| コスト | 固定（サーバー資源） | 変動（トークン消費量に依存） |
| 追跡性 | スタックトレース | プロンプト→応答の履歴 |
この違いからわかるように、AIエージェントのログは従来システムのログとは記録すべき内容が異なるということです。
なぜAIハーネスにログが必要なのか：4つの目的
目的1: 障害切り分け（トリアージ）
AIエージェントが予期しない結果を返したとき、原因が「プロンプトの設計」なのか「モデルの応答」なのか「外部ツールの動作」なのかを切り分ける必要があります。ログがなければ、この切り分けは不可能です。
目的2: コストの可視化
LLMのAPI呼び出しにはトークン単位のコストが発生します。「どの処理にどれだけコストがかかったか」を記録しておかないと、予算超過の問題を事前に検知できません。
目的3: 品質の継続的改善
ログを蓄積することで、「どのプロンプトパターンで品質が下がりやすいか」「どのモデルがどのタスクに強いか」といったデータが得られます。これは従来システムのパフォーマンスログ分析と同じ考え方です。
目的4: 監査・コンプライアンス対応
業務でAIを使う以上、「いつ、何を、どのように処理したか」の記録が求められる場面があります。監査ログは、従来システムでも必須であり、SE経験者には馴染みのある領域です。
AIハーネスのログ項目表（成果物）
以下が、AIハーネスで記録すべきログ項目の一覧です。
基本項目（必須）
| カテゴリ | ログ項目 | 説明 | SE業務での対応 |
|---|---|---|---|
| 識別 | 実行ID | エージェント実行の一意識別子 | トランザクションID |
| 識別 | タイムスタンプ | 実行開始・終了時刻 | アクセスログのタイムスタンプ |
| 入力 | プロンプト | LLMに送信したプロンプト全文 | リクエストボディ |
| 入力 | コンテキスト | RAGで取得したコンテキスト | 参照データ |
| 出力 | モデル応答 | LLMの応答全文 | レスポンスボディ |
| 出力 | ツール呼び出し | MCPツールの呼び出し内容 | API呼び出しログ |
| コスト | トークン数 | 入力・出力のトークン数 | リソース使用量 |
| 結果 | ステータス | 成功/失敗/タイムアウト | HTTPステータスコード |
拡張項目（推奨）
| カテゴリ | ログ項目 | 説明 | 導入判断基準 |
|---|---|---|---|
| 品質 | 人間評価スコア | 応答品質の人間評価 | 品質改善が目的の場合 |
| 品質 | フィードバック | ユーザーからのフィードバック | ユーザー対徬機能がある場合 |
| デバッグ | リトライ回数 | エラー時の自動リトライ回数 | 自動リトライ機能がある場合 |
| デバッグ | モデルバージョン | 使用したLLMモデルのバージョン | 複数モデルを併用する場合 |
| セキュリティ | マスク処理フラグ | 機密情報のマスク処理が行われたか | 機密情報を扱う場合 |
| 監査 | 承認者 | 実行を承認した人物 | Human-in-the-loopがある場合 |
ログ設計で5W1Hを押さえる
ログ設計を考えるにあたって、お馴染みの5W1Hフレームワークがそのまま使えます。
| 5W1H | ログでの対応 | 具体例 |
|---|---|---|
| Who | 実行者/承認者 | user_id, approver_id |
| What | 処理内容 | prompt, tool_calls |
| When | タイムスタンプ | start_at, end_at |
| Where | 実行環境 | model_name, environment |
| Why | 実行トリガー | trigger_type, parent_task |
| How | 処理結果 | status, output, cost |
ログレベルの設計
従来システムのログレベル（DEBUG, INFO, WARN, ERROR）をAIエージェント向けにマッピングすると、以下のようになります。
| レベル | 従来システム | AIエージェントでの例 |
|---|---|---|
| DEBUG | デバッグ用詳細情報 | プロンプト全文、モデル応答全文 |
| INFO | 通常処理の記録 | タスク開始・完了、ツール呼び出し |
| WARN | 注意が必要な状態 | トークン消費が閾値超過、リトライ発生 |
| ERROR | エラー発生 | モデルAPIエラー、ツール実行失敗 |
ログ保存形式の検討
AIエージェントのログをどの形式で保存するかは、運用目的によって判断します。
| 保存形式 | メリット | デメリット | 適用場面 |
|---|---|---|---|
| JSON | プログラムで処理しやすい | 人が直接読みにくい | 自動分析・集計 |
| Markdown | 人が読みやすい | プログラムでの解析が手間 | 手動レビュー・共有 |
| 両方併用 | 用途別に最適化 | 保存容量が増加 | 本格運用 |
本連載では、次回（第14回）でMarkdownとJSONの両方を併用する実装アプローチを紹介します。
ログ設計のアンチパターン
AIエージェントのログ設計で避けたいパターンも整理しておきます。
| アンチパターン | 問題点 | 対策 |
|---|---|---|
| ログなし | 原因調査不能 | 最低限の基本項目を必ず記録 |
| 全部記録 | ストレージ圧迫、機密情報漏洩 | ログレベルで制御 |
| 非構造化ログ | 検索・分析が困難 | JSONなど構造化形式を併用 |
| タイムスタンプなし | 時系列分析不能 | ISO 8601形式で必ず記録 |
SE経験からのマッピング
SE経験者が既に持っているログ設計のスキルとAIハーネスへのマッピングを整理します。
| SEのログ設計経験 | AIハーネスでの活用 |
|---|---|
| アクセスログ設計 | プロンプト・レスポンスの履歴記録 |
| パフォーマンスログ | トークン消費・レイテンシの記録 |
| 監査ログ | 承認者・実行トリガーの記録 |
| エラーログ | モデルAPIエラー・ツール失敗の記録 |
| ログローテーション | トークンコストを考慮した保存期間設計 |
まとめ
- AIエージェントのログは従来システムとは異なる設計が必要
- ログの目的は、障害切り分け・コスト可視化・品質改善・監査対応の4つ
- SEのログ設計経験は、AIハーネスのログ設計に直接活かせる
- まずは基本項目から始め、運用しながら拡張項目を追加する
次回予告：AIエージェント実行ログをMarkdownとJSONで残す
第14回では、今回設計したログ項目表を実際にMarkdownテンプレートとJSONスキーマに落とし込みます。
具体的には以下の内容を扱います。
- 人がレビューするためのMarkdownログテンプレート
- プログラムで集計・分析するためのJSONスキーマ
- MarkdownとJSONの併用パターンの実装例
- Pythonでのログ出力コード例
「ログ項目は決めたけど、実際にどうファイルに書き出すの？」という疑問に答える実装回です。ぜひお楽しみに。
連載: AIに仕事を奪われる不安から始めるハーネス作成入門
次回（第14回）: AIエージェント実行ログをMarkdownとJSONで残す