AIエージェントに調査、修正、PR作成、ログ分析を任せると、成果物は早く返ってきます。けれど、レビュー担当が本当に困るのは「何を見れば受け入れてよいか」が毎回違うことです。本文の要約はある。PR もある。ビルド結果もある。ただし、どの主張がどの根拠に支えられていて、どこが未確認なのかが一目で追えない。
この記事では、AIエージェントの evidence packet を扱います。組織全体の利用ルールは AIコーディングツールの社内ガイドライン、実行後に何を監査ログとして残すかは AIエージェント監査ログ設計ガイド、成果物や証拠をどの期間保存するかは AIエージェント artifact retention 設計ガイド、最終報告の形式は AIエージェント出力契約設計ガイド、Codex 差分の受け入れ判断は Codex レビュー完了ゲート設計ガイド に分けています。
今回の論点は、レビュー直前に 主張、根拠、検証、不足、次の判断 を小さな packet として束ねることです。
先に結論: evidence packet はログの要約ではない
evidence packet は、長い作業ログを短くしたものではありません。レビュー担当が判断できるように、agent の主張と根拠を対応付けた小さな資料です。
私なら、最小構成を次の 6 項目にします。
| 項目 | 入れるもの | レビューで見ること |
|---|---|---|
claim | agent が正しいと言っていること | 何を受け入れる判断なのか |
source | docs、コード、ログ、issue、tool result | 根拠が現行で信頼できるか |
freshness | 確認日、対象 version、取得範囲 | 古い情報で判断していないか |
verification | test、build、再現手順、手動確認 | claim を実際に確認したか |
gap | 未確認、反証候補、対象外 | 人間が追加で見るべき点 |
decision | accept、revise、escalate、hold | 次に何をするか |
この 6 項目が揃っていれば、レビュー担当は会話履歴を掘らずに判断できます。逆に、どれだけ長い final answer でも、claim と source がつながっていなければ弱いです。
なぜ evidence packet が必要なのか
AIエージェント運用では、証拠があちこちに散ります。
- PR diff
- shell command の stdout / stderr
- browser screenshot
- MCP tool result
- OpenAI Agents SDK の trace
- CI の build log
- 外部 docs の該当ページ
- GitHub issue や社内 ticket のコメント
- agent の最終回答
これらを全部レビュー担当へ投げると、判断はできますが遅くなります。逆に agent の要約だけを信じると、前提違いに気付けません。
OpenAI Agents SDK の tracing は、agent run の LLM generation、tool call、handoff、guardrail などを trace / span として扱えます。OpenTelemetry の GenAI observability も、モデル呼び出し、token、tool call、tool result を観測対象として整理しています。つまり、根拠となる raw signal は増えています。
ただし、raw signal が増えるほど、レビュー前に束ねる単位が必要になります。evidence packet は、観測ログそのものではなく、判断に必要な証拠だけを取り出した review surface です。
audit log、artifact、output contract と分ける
evidence packet が曖昧になる原因は、近い概念を混ぜることです。
| 近い概念 | 主な目的 | evidence packet との違い |
|---|---|---|
| audit log | 後から何が起きたかを説明する | すべての操作証跡ではなく、判断に使う根拠だけを束ねる |
| artifact retention | 何をどの期間保存するかを決める | 保存方針ではなく、レビュー時点の提示単位を決める |
| output contract | 最終回答の形を固定する | final answer 全体ではなく、claim と evidence の対応を固定する |
| review gate | 受け入れるか落とすかを見る | gate に渡す入力として evidence packet を用意する |
この分担を決めると、記事や実装 PR のレビューがかなり楽になります。audit log には run_id と tool_call_id を残す。artifact store には検証結果や screenshot を置く。final answer には要約を書く。そのうえで、review gate へ渡す evidence packet には、判断に必要な claim だけを載せます。
claim を先に分解する
evidence packet で最初にやるべきことは、根拠集めではありません。agent の主張を分解することです。
悪い例はこうです。
実装しました。公式 docs に沿っています。build も通っています。これでは、どの主張がどの根拠に支えられているのか分かりません。
良い packet は、主張を小さくします。
evidence_packet:
subject: "billing webhook retry fix"
claims:
- id: "claim-1"
statement: "retry count が 0 のときだけ webhook が再送されない"
sources:
- type: "failing_test"
path: "tests/billing/webhook-retry.test.ts"
line_hint: "retry_count_zero"
verification:
- command: "pnpm test tests/billing/webhook-retry.test.ts"
result: "passed"
gap: "production queue metrics は未確認"
decision: "accept_with_monitoring"ここで重要なのは、claim を「作業完了」ではなく「レビュー可能な単位」にすることです。
source には種類と信頼度を持たせる
source は URL や file path の羅列では足りません。最低限、種類と信頼度を分けます。
| source type | 例 | 扱い |
|---|---|---|
| primary_doc | 公式 docs、仕様、リリースノート | 仕様判断の優先根拠にする |
| repo_evidence | 既存コード、test、設定、AGENTS.md | この repo での挙動判断に使う |
| runtime_log | CI、build、production log、trace | 実際に起きたことの根拠にする |
| community_note | issue、discussion、ブログ | 補助情報に留める |
| model_summary | agent の要約 | source ではなく pointer として扱う |
特に AIエージェント運用では、model summary を source にしない方が安全です。要約は便利ですが、根拠ではありません。要約の背後にある file、log、trace、docs を packet に入れます。
外部情報を使う場合は、freshness も一緒に置きます。
source:
type: "primary_doc"
url: "https://openai.github.io/openai-agents-python/tracing/"
checked_at: "2026-08-18"
target: "Agents SDK tracing"
used_for: "tool call, handoff, guardrail を trace に含める前提"
limitation: "自社の PR evidence 保存方針までは定義しない"「公式 docs を見た」だけでは弱いです。いつ、どの対象に、何の判断で使ったのかを残します。
verification は claim ごとに置く
検証結果を最後にまとめて書くと、レビュー担当はどの主張を検証したのか分からなくなります。
verification:
- command: "pnpm run build"
result: "passed"これだけでは、build が通ったことは分かります。しかし、今回の claim が security boundary、MCP scope、外部 API の idempotency なら、build だけでは検証になりません。
私なら、claim ごとに verification を置きます。
| claim | verification |
|---|---|
| route guard が効く | 認可 test、手動 403 確認 |
| docs の仕様に合う | 公式 docs の対象 version、該当 section |
| MCP tool result が schema に合う | outputSchema validation、negative case |
| secret が出力されない | redaction test、artifact 確認 |
| UI が崩れていない | screenshot、主要 viewport、console error |
OpenAI Agents SDK の guardrails は、tool 入力や出力の検査、tripwire による停止を扱えます。ただし guardrail があることと、今回の claim が検証済みであることは別です。evidence packet では、guardrail の存在を source にし、実際に通った検証を verification に分けます。
gap を隠さない
AIエージェントの完了報告で一番危ないのは、未確認事項が消えることです。
良い evidence packet は、弱い点を隠しません。
gaps:
- id: "gap-1"
type: "runtime_unverified"
detail: "production webhook queue の実データでは未確認"
impact: "edge case が残る可能性"
next_action: "deploy 前に dashboard で 24h error rate を確認"gap は失敗ではありません。レビュー判断に必要な残り作業です。
OWASP の AI Agent Security Cheat Sheet は、agent の判断、tool call、結果、監査証跡、承認、policy version などを構造化して残すことを推奨しています。実務では、この「残す」を evidence packet へそのまま詰めるのではなく、レビューで見る gap に変換する方が使いやすいです。
handoff と escalation では packet を短くする
agent 間の handoff や人間エスカレーションでは、packet を大きくしすぎると逆効果です。
OpenAI Agents SDK の handoff は、専門 agent へ処理を渡す仕組みで、handoff input に reason や priority のような小さな metadata を持たせられます。ここに全文ログを載せるより、次の agent が判断する claim だけ渡した方が安全です。
私なら、handoff 用 packet は次の 5 つまでに絞ります。
handoff_evidence_packet:
task: "investigate failing checkout test"
current_claim: "failure is isolated to tax rounding"
strongest_source: "tests/checkout/tax.test.ts"
verification_done:
- "pnpm test tests/checkout/tax.test.ts failed before fix"
- "pnpm test tests/checkout/tax.test.ts passed after fix"
unresolved_gap: "EU VAT fixture は未確認"handoff は百科事典ではありません。次の agent や人間が最初に見るべき根拠だけを渡します。
実務テンプレート
最初は、次のテンプレートで十分です。
evidence_packet:
run_id: "agent-run-20260818-001"
owner: "platform-ai"
subject: "PR review for billing retry fix"
data_class: "internal"
claims:
- id: "claim-1"
statement: "retry count 0 の webhook が再送されるようになった"
sources:
- type: "repo_evidence"
ref: "tests/billing/webhook-retry.test.ts"
checked_at: "2026-08-18"
used_for: "failure reproduction and regression check"
verification:
- type: "test"
command: "pnpm test tests/billing/webhook-retry.test.ts"
result: "passed"
gaps:
- "production queue metrics は未確認"
decision_hint: "accept_after_runtime_dashboard_check"
packet_status: "ready_for_review"これを毎回巨大な JSON schema にする必要はありません。PR 本文、ticket comment、artifact store の metadata、agent final answer の一部、どこに置いてもかまいません。重要なのは、claim と source と verification が離れないことです。
よくある失敗
1. source を agent の final answer にする
final answer は source ではありません。source は docs、code、log、trace、tool result です。final answer は、それらを人間へ渡す表示面です。
2. freshness を書かない
AI ツールや MCP 仕様は更新が早いです。公式 docs でも確認日と対象 version を入れないと、数週間後に同じ判断を再利用してよいか分かりません。
3. build 成功を万能の検証にする
build は必要ですが、security、権限、データ境界、MCP scope、外部副作用の検証にはなりません。claim に対して適切な verification を置きます。
4. gap を「注意点」に丸める
注意点ではなく、次の判断に使える gap にします。誰が、何を見れば、accept / revise / hold に進めるのかを書く方がよいです。
5. packet を保存方針にしてしまう
evidence packet はレビュー入力です。保存期間、削除条件、incident hold は artifact retention 側で決めます。
導入手順
まず全 agent に完璧な packet を義務化する必要はありません。壊れやすい作業から始めます。
- PR 作成、外部 write、MCP write、security fix だけを対象にする。GitHub 上での通常レビュー導線は Codex code review 実践ガイド や Claude Code code review 実践ガイド と分け、evidence packet 自体はその前段の判断材料に留める
- final answer に
claims / sources / verification / gaps / decision_hintを必須にする source.typeをprimary_doc / repo_evidence / runtime_log / community_noteに分ける- build や test を claim ごとの verification に移す
- gap がある場合は
ready_for_reviewではなくneeds_human_decisionにする - 1か月後に、レビュー差し戻し理由を packet template へ戻す
この順番なら、運用負荷を増やしすぎずに始められます。
まとめ
AIエージェント evidence packet は、ログ保存でも、最終報告テンプレでもありません。レビュー前に、agent の主張、参照元、freshness、検証、未確認事項、次の判断を束ねるための小さな運用単位です。
私なら、まず PR 作成や MCP write のような高リスク作業だけに導入します。final answer を「やりました」で終わらせず、claim と source と verification を対応付ける。gap を隠さず、review gate へ渡す。ここまでできると、AIエージェントの成果物は「速いが怖いもの」ではなく、レビュー可能な作業単位になります。