3行まとめ
開発中の不具合確認に使い、本番の証跡とは分けて扱います。
trace、metrics、logsで処理経路、遅延、異常、コストの入口を作ります。
tool call、approval、external requestをつなぎ、誰が何を見て実行したかを残します。
run ID、thread/session ID、tool call ID、approval ID、external request IDで横断調査できるようにします。
うまく動いた記録ではなく、あとから説明できる記録として設計します。
- AIエージェントの実行ログは、debugログ、observabilityのtrace・metrics・logs、監査用のtool call・承認ログに分けて設計します。
- 事故調査で必要なのは、run ID、thread/session ID、tool call ID、approval ID、external request IDをつなぎ、「誰が、何を見て、何を実行したか」を遡れることです。
- OpenAI Agents SDK、LangSmith、Mastra、OpenTelemetryの公式情報を2026-06-14に確認し、本文ではX検索の需要シグナルを事実根拠にしていません。
AIエージェントは、動いた瞬間よりも、あとから説明できるかで本番導入の難しさが変わります。うまくいったrunだけを見るなら、traceの画面やconsole logで足りるかもしれません。けれど、顧客へ誤送信した、社内データを読ませすぎた、tool callが連鎖してコストが跳ねた、承認したはずのない操作が走った。こうした場面では、ログの量ではなく、証跡のつながりが必要です。
この記事では、AIエージェントの実行ログを事故調査、実行後レビュー、コスト確認に使える形へ分解します。OpenAI Agents SDKのtracing、guardrails、LangSmithとMastraのobservability、OpenTelemetryのtraces、logs、metricsを参照しつつ、特定vendorの導入手順ではなく、どの基盤でも最初に決めるべき設計項目に絞ります。
この記事でわかること
debug、observability、audit trailを目的と保存先で分けます。
run、thread、tool call、approval、external requestを同じ調査線で追えるようにします。
traceに残す属性と、hash、参照ID、要約へ寄せる情報を分けます。
tool callログを、外部世界への操作を説明する台帳として設計します。
承認者、表示内容、却下、編集、期限切れ、実行結果を調査できる形にします。
trace画面だけでなく、承認と外部実行まで含めた運用設計として見ます。
- AIエージェントのログをdebug、observability、audit trailに分ける理由
- run ID、thread/session ID、tool call ID、approval ID、external request IDのつなぎ方
- traceに残してよい情報と、hash、参照ID、要約へ寄せる情報の分け方
- tool callログを副作用の証跡台帳として設計する方法
- 承認ログに残すべき承認者、表示内容、却下、編集、期限切れ、実行結果
- metricsとlogsをコスト確認、異常検知、事故調査の入口にする考え方
- ZDRやPII、secret、private repo情報を含む業務で注意する保存先とアクセス権
すでにtrace、metric、logの一般的な計装設計を整理したい場合は、公開済みの<a href="https://ai-dev.blog.mo-gmo.com/codex-observability-instrumentation-trace-metric-log-alert-review/">Codexにobservability計装を任せる前に決めること</a>が近い入口です。この記事では、そこから一段絞って、AIエージェントのrun、tool call、approval、audit trailに焦点を当てます。
前提知識
ZDRが必要な業務では、OpenAI側のtraceに頼る前提ではなく、自社側の監査ログも設計します。
AIエージェントの実行ログを考えるとき、まず「ログ」という言葉を分けます。開発中に読むdebugログ、処理経路を追うtrace、傾向を見るmetrics、個別eventを残すlogs、監査のためのtool call台帳、承認ログは、目的も保存先も違います。
OpenAIのAgents guideでは、1回のモデル呼び出しとtool、アプリ側ロジックで足りるならResponses APIを使い、アプリ側がorchestration、tool execution、approvals、stateを持つ場合にAgents SDKのページを参照する整理になっています。つまり、SDKを使う時点で「アプリ側が何を保存し、どこで承認し、何を観測するか」を決める領域が増えます。
OpenAI Agents SDKのtracing docsでは、LLM generation、tool call、handoff、guardrail、custom eventなどがtrace対象として説明されています。tracingはデフォルトで有効ですが、Zero Data Retentionの組織では利用できないという注意もあります。ZDRが必要な業務では、OpenAI側のtraceに頼る前提ではなく、自社側の監査ログを別に設計します。
LangSmithはtraceをrunの集合として扱い、multi-turn conversationをthreadでつなぐ考え方を説明しています。Mastraはagent run、workflow step、tool call、model interactionをtrace、logs、metricsで見る考え方を説明し、metricsではduration、token usage、cost estimateを扱います。OpenTelemetryでは、trace、log、metricが別のsignalとして整理されています。
実行ログを3種類に分ける
最初に分けるのは、次の3種類です。
| 種類 | 目的 | 代表例 | 注意点 |
|---|---|---|---|
| debugログ | 開発中の不具合確認 | 一時的なconsole出力、例外stack | 本番の証跡にしない |
| observability | 処理経路、傾向、異常検知 | trace、span、logs、metrics | promptやpayloadを残しすぎない |
| audit trail | 実行責任と承認の説明 | tool call台帳、approval snapshot | 監査要件、保存期間、閲覧権限を決める |
評価基準
debugログは、開発者が一時的に読むためのものです。observabilityは、どこで遅いか、どこで失敗したか、どのtoolが多く呼ばれたかを見るためのものです。audit trailは、あとから「誰が何を見て、何を許可し、何が実行されたか」を説明するためのものです。
この3つを混ぜると、traceに顧客payloadを丸ごと入れたり、debugログだけで承認証跡を済ませたり、metricsだけで事故原因を説明しようとしたりします。設計の初期値としては、traceは道筋、tool callログは副作用、承認ログは責任の記録と考えると整理しやすくなります。
guardrailsと承認ログは別物
OpenAI Agents SDKのguardrails docsでは、入力や出力の検証、tripwireによる停止、blocking executionなどが説明されています。guardrailsは、危険な入力や不適切な出力を止める検査層として有効です。
注意点
ただし、guardrailsが止めたことと、人間が承認したことは別です。guardrailは「条件に合わないので止めた」を記録する材料になります。承認ログは「人間が何を見て、なぜ許可または却下したか」を残す材料です。どちらも必要ですが、同じテーブルに雑に押し込まない方が調査しやすくなります。
結果：最初に設計するのは5つのIDと3つのログ
- 1run ID
1回のagent実行を識別し、どの実行で起きたかを示します。
- 2thread/session ID
会話や作業の連続性を識別し、どの文脈から発生したかを追います。
- 3tool call ID
tool呼び出しを識別し、何を外部へ実行しようとしたかを残します。
- 4approval ID
承認判断を識別し、誰が何を見て許可または却下したかをつなぎます。
- 5external request ID
外部APIやDB更新を識別し、外部世界で何が実行済みかを確認します。
最小構成は、大きな監査基盤ではなく、IDの接続とログ種別の分離から始めます。
AIエージェントの実行ログ設計では、最初から大きな監査基盤を作る必要はありません。最小構成は、5つのIDをそろえ、3つのログを分けることです。
| 設計対象 | 最小で決めること | 事故調査で答える質問 |
|---|---|---|
run_id | 1回のagent実行を識別する | どの実行で起きたか |
thread_id / session_id | 会話や作業の連続性を識別する | どの文脈から発生したか |
tool_call_id | tool呼び出しを識別する | 何を外部へ実行したか |
approval_id | 承認判断を識別する | 誰が何を見て許可したか |
external_request_id | 外部APIやDB更新を識別する | 外部世界では何が実行済みか |
この5つがないと、trace、アプリDB、承認画面、外部APIログ、CI artifact、チケットの間を人間が手作業でつなぐことになります。時刻だけで追う運用は、timezone、retry、queue、並列tool callが入った瞬間につらくなります。
3つのログは、次のように分けます。
| ログ | 保存するもの | 保存しない初期値 |
|---|---|---|
| trace/logs | span名、tool名、status、latency、error type、cost estimate、参照ID | prompt全文、顧客payload全文、secret、内部URL |
| tool call audit | tool名、version、read/write、入力要約、payload hash、external ID、実行結果 | API key、cookie、private token、不要なraw response |
| approval log | 承認者、表示したsnapshot、判断、理由、期限、実行結果との紐づけ | 承認画面に出していない情報を後から混ぜた説明 |
ここまで決まれば、実装担当やCodexに依頼する単位がかなり具体的になります。「ログを足して」ではなく、「run_id、tool_call_id、approval_idを相関させ、tool inputはhashと要約だけ残し、raw payloadは保存しない」という依頼にできます。
traceはagent runからtool callまで一本の道筋で追う
- 1agent run
run ID、model、status、durationを持つ実行全体の入口です。
- 2model call
LLM generationの状態を残し、全文ではなく分類済み属性を中心に扱います。
- 3tool call
tool call ID、tool名、read/write区分、statusを残します。
- 4guardrailとapproval
blocked reasonやapproval stateを、実行経路の中で確認できるようにします。
- 5external call
external request ID、status、latencyを残し、外部API側の記録へつなげます。
spanは細かすぎても粗すぎても調査しにくいため、最初に粒度を決めます。
traceは、1回のagent runがどの順番で進んだかを見るための道筋です。OpenAI Agents SDKのtracingは、LLM generation、tool call、handoff、guardrailなどを追える設計になっています。MastraやLangSmithのobservabilityも、agent runやworkflow step、tool callを追う単位を持っています。
spanの粒度を先に決める
spanを細かくしすぎると、画面はにぎやかになりますが、事故調査では読みにくくなります。逆に粗すぎると、どのtoolで失敗したか、guardrailがどこで働いたか、retryが何回起きたかを追えません。
最初は次の粒度で十分です。
| spanまたはevent | 例 | 残す属性 |
|---|---|---|
| agent run | support_reply_agent.run | run_id、model、status、duration |
| tool call | tool.search_ticket | tool_call_id、tool名、read/write、status |
| guardrail | guardrail.input_check | rule名、result、blocked reason |
| approval | approval.requested | approval_id、approval state |
| external call | crm.update_ticket | external request ID、status、latency |
| error | agent.error | error type、retryable、step |
粒度の初期値
OpenTelemetryのtraceやspanの考え方に合わせるなら、1つのrunをroot traceとして扱い、その下にagent step、tool call、guardrail、approval待ち、外部APIをぶら下げます。vendor固有の実装は違っても、「何をspanにするか」を先に決める点は共通です。
prompt全文ではなく分類済み属性を残す
traceにpromptやtool argumentsを丸ごと残すと、デバッグは楽です。ただ、顧客情報、社内文書、private repo情報、API key、内部URL、未公開payloadがtrace基盤へ流れます。traceを見る権限を広くすると、二次的な情報漏えいの入口になります。
初期値は、全文保存ではなく分類済み属性です。
| 残す候補 | 例 |
|---|---|
| tool名 | update_ticket_status |
| 対象種別 | ticket、pull_request、customer_profile |
| 対象ID | 内部IDまたはマスク済みID |
| 入力要約 | 「statusをpendingからresolvedへ変更」 |
| payload hash | 後から同一性を確認するためのhash |
| error type | validation_error、timeout、permission_denied |
| cost estimate | run単位、model call単位の概算 |
保存範囲
raw payloadが必要な業務もあります。その場合も、traceへそのまま入れるのではなく、アクセス権が狭い保存先へ置き、traceには参照IDだけを残す方が扱いやすいです。
ZDRが必要な業務では代替ログを決める
OpenAI Agents SDKのtracing docsでは、Zero Data Retentionの組織ではtracingが利用できないと説明されています。ZDRが必要な業務で「Agents SDKのtrace dashboardを見ればよい」という設計にすると、導入前提が崩れます。
この場合は、自社側で次のeventを残します。
agent_run_event:
run_id: "run_20260614_001"
thread_id: "thread_sample"
actor_type: "user"
agent_name: "support_reply_agent"
event_type: "tool_call_requested"
tool_name: "update_ticket_status"
tool_call_id: "toolcall_001"
input_summary: "ticket status update"
input_hash: "sha256:dummy"
approval_id: "approval_001"
timestamp: "2026-06-14T09:24:00Z"
pii_mode: "redacted"この例は実データではありません。実務では、社内のセキュリティ、法務、監査担当と保存先、閲覧権限、保存期間を決めてから実装します。
tool callログは副作用の証跡台帳にする
input/outputは全文保存を初期値にせず、summary、hash、参照IDを基本にします。
tool callログは、便利な引数保存ではありません。AIエージェントが外部世界へ何を実行しようとしたか、何を実行したかを残す台帳です。read-only toolとwrite toolを同じ粒度で扱うと、危険な操作の証跡が薄くなります。
toolごとに副作用と権限を記録する
tool call台帳には、最低限この列を持たせます。
| 列 | 例 | 理由 |
|---|---|---|
| tool名とversion | crm.update_ticket@2026-06-14 | tool仕様の変化を追う |
| read/write区分 | read、draft、write | 承認要否を分ける |
| 実行主体 | user token、service account | 誰の権限で実行したかを追う |
| 対象resource | ticket、repo、invoice | 影響範囲を見る |
| input summary | 変更内容の要約 | 承認画面と調査で読む |
| input hash | sha256:... | rawを残さず同一性を確認する |
| approval ID | approval_001 | 人間判断と接続する |
| external ID | API request ID、issue number | 外部世界の実行結果と接続する |
| status | requested、approved、executed、failed | 現在地を追う |
確認項目
特にwrite系toolでは、idempotency keyとexternal IDを必ず検討します。メール送信、DB更新、決済、GitHub Issue作成、CRM更新は、二重実行が事故になりやすい領域です。workflow側でresumeできることと、外部操作を二重実行しないことは別の設計です。
input/outputは3段階で扱う
tool inputやoutputの保存範囲は、3段階に分けます。
| 保存レベル | 使う場面 | 注意点 |
|---|---|---|
| 全文保存 | 法的・監査上、原文保存が必要な限定領域 | 閲覧権限、削除、暗号化を厳しくする |
| マスク済み保存 | 調査で内容の傾向が必要な領域 | redaction漏れをreviewする |
| hash・参照IDのみ | 多くの業務の初期値 | 必要時に原本へ到達できる権限設計が必要 |
AIエージェントに渡したprompt、tool arguments、tool outputは、同じ感覚で保存しない方がよいです。promptにはユーザーの依頼や社内文脈が入り、tool argumentsには操作対象や変更内容が入り、tool outputには顧客情報や社内情報が返ることがあります。それぞれ機密度が違います。
read-onlyから始める
本番前のPoCでは、read-only toolから始める方が失敗を観察しやすくなります。write toolを入れる場合は、toolの説明、入力schema、実行前承認、実行ログ、ロール制御をセットで設計します。MCPやtool callingの権限境界を広く整理したい場合は、<a href="https://ai-dev.blog.mo-gmo.com/category/mcp/">MCPカテゴリ</a>の記事群も参考になります。
承認ログは誰が何を見て許可したかを残す
- 1依頼者
agent runを開始した人またはsystemを記録します。
- 2agent
tool callを提案した実行体として、提案内容と理由を残します。
- 3承認者
操作を許可、却下、編集、期限切れにした人と判断時刻を残します。
- 4実行者
backendやservice accountなど、実際にAPIを呼んだ主体を分けて記録します。
- 5approval snapshot
承認画面に表示したtool名、対象、差分、リスク、戻し方を保存します。
承認者と実行者を同じ言葉でまとめると、監査時に外部APIの責任境界が曖昧になります。
人間承認は、ボタンを押した事実だけでは足りません。事故調査で必要なのは、承認者が何を見て、どのリスクを理解し、どの操作を許可し、その後どのtool callが実行されたかです。
承認者と実行者を分ける
AIエージェントの承認では、少なくとも4つのactorが出ます。
| actor | 役割 |
|---|---|
| 依頼者 | agent runを開始した人またはsystem |
| agent | tool callを提案した実行体 |
| 承認者 | 操作を許可または却下した人 |
| 実行者 | backendやservice accountなど、実際にAPIを呼んだ主体 |
承認者と実行者を同じ言葉でまとめると、監査時に「誰の権限で外部APIが呼ばれたのか」が曖昧になります。人間が承認しても、実行はagentやbackendが行います。ログには両方を残します。
承認画面に表示した内容をsnapshotにする
承認ログには、承認画面に表示した内容のsnapshotを残します。後から最新DBを見ても、承認時点で人間が見た情報とは限りません。
| 保存する項目 | 例 |
|---|---|
| approval ID | approval_001 |
| tool call ID | toolcall_001 |
| 表示したtool名 | crm.update_ticket |
| 対象resource | ticket ID、repo、customer ID |
| 入力要約 | 「statusをresolvedへ変更」 |
| 差分 | 変更前後の要約 |
| リスク | 顧客通知あり、課金影響なし |
| 戻し方 | statusをpendingへ戻す |
| 承認者 | user IDまたはrole |
| 判断 | approved、rejected、edited、expired |
| 判断理由 | 任意の短いコメント |
評価基準
却下、編集、期限切れ、再承認もeventにします。approvedだけを残すと、止めた判断や差し戻した理由が消えます。事故調査では「実行した証跡」と同じくらい「止めた証跡」も重要です。
承認ログとworkflow stateを混同しない
承認付きworkflowの設計は、公開済みの<a href="https://ai-dev.blog.mo-gmo.com/langgraph-mastra-human-approval-workflow-state-resume/">LangGraphとMastraで承認付きワークフローを設計する</a>で扱っています。この記事の焦点は、workflowをどう止めるかではなく、止めた時に何を残すかです。
workflow engineのstateは、再開のために必要です。承認ログは、説明責任のために必要です。両方を同じ保存先に置く場合でも、列と閲覧権限は分けます。
metricsとlogsは事故調査とコスト確認の入口にする
agent runの増減を見て、急な利用増や停止を確認します。
tool連鎖や想定外の呼び出し増加を見ます。
外部APIやguardrail周辺の詰まりを検知します。
承認待ちによる滞留と再開処理の影響を確認します。
危険操作や誤提案が増えていないかを見ます。
duration、token usage、tool call、handoffの増加をコスト確認につなげます。
平均応答時間だけでは、AIエージェントの事故原因やコスト増は見えにくくなります。
metricsは傾向を見るための入口です。logsは個別eventの証拠です。traceはその間をつないで、1つのrunの道筋を追います。
Mastraのobservability docsでは、traces、logs、metricsが相関IDを共有し、metric spikeからtraceやlogsへ移動できる考え方が説明されています。OpenTelemetryでも、traces、logs、metricsは別のsignalとして整理されています。AIエージェントでも、この分離はそのまま有効です。
metricsで見るもの
AIエージェントでは、平均応答時間だけを見ても足りません。次のmetricsを候補にします。
| metric | 見たいこと |
|---|---|
| run count | agent runの増減 |
| run failure rate | 失敗率 |
| tool call count per run | tool連鎖や想定外の増加 |
| retry count | 外部APIやguardrail周辺の詰まり |
| approval wait time | 承認待ちによる滞留 |
| approval rejection rate | 危険操作や誤提案の増加 |
| guardrail trigger count | 入力・出力検査で止まる頻度 |
| token usage | context肥大やhandoff増加 |
| estimated cost | model callやtool連鎖による費用 |
コスト上振れは、モデル単価だけでは説明できません。tool再試行、長いcontext、handoff、承認待ち後の再開、失敗runが積み重なって増えます。費用を見るなら、run単位、team単位、tool単位で分けます。
logsで見るもの
logsは、あとから読むeventの証拠です。trace IDやrun IDを持たないlogは、事故調査で孤立します。
| log event | 必須に近い属性 |
|---|---|
agent.run.started | run ID、actor、agent名、entrypoint |
tool.call.requested | run ID、tool call ID、tool名、input summary |
approval.requested | approval ID、tool call ID、risk summary |
approval.decided | approval ID、decision、reviewer |
tool.call.executed | external request ID、status、latency |
guardrail.triggered | rule名、blocked reason |
agent.run.completed | status、duration、cost estimate |
agent.run.failed | error type、retryable、next action |
alertは、logsそのものではなく、metricsやeventの異常に置きます。想定外toolの試行、同一runでのtool call急増、guardrail発火の連続、承認却下率の上昇、cost上限接近は、早めに気づきたいシグナルです。
保存先とアクセス権を先に決める
ZDRだから何も残らないとは扱わず、OpenAI側、vendor側、自社側、通知先を分けて確認します。
実行ログ設計で一番危ないのは、「残しておけば安心」と考えることです。残すほど、保存先、閲覧権限、削除、保持期間、vendor転送の管理が増えます。
OpenAI側のtraceと自社側ログを分ける
OpenAI Agents SDKのtrace、LangSmithやMastraのobservability、自社DB、SIEM、CI artifact、Slack通知、チケットには、それぞれ別の保存先と閲覧者がいます。OpenAI側のdata controlsを確認しても、自社アプリ側のDBやログ基盤に残る情報は別管理です。
| 保存先 | 置くもの | 注意点 |
|---|---|---|
| OpenAI/SDK trace | model call、tool call、guardrailなどのtrace | ZDRやdata controlsを確認する |
| observability vendor | trace、logs、metrics、dashboard | promptやpayloadの転送範囲を見る |
| 自社DB | audit trail、approval snapshot、tool台帳 | role、retention、削除を設計する |
| CI artifact | 作業ログ、test結果、差分 | 公開repoや外部contributorに注意 |
| ticket/postmortem | timeline、impact、action items | 個人情報や内部URLを削る |
注意点
「ZDRだから何も残らない」と扱うのも危険です。OpenAI側の保存、vendor側の保存、自社側の保存、通知先、CI artifactは別です。どこに何が残るかを、ログ種別ごとに見ます。
PIIとsecretは保存前に分類する
保存前に分類する対象は、少なくとも次です。
- 顧客メール、氏名、電話番号、住所、決済情報
- 社内文書、private repo情報、未公開仕様
- API key、access token、cookie、private key
- 内部URL、管理画面URL、staging host
- raw prompt、raw tool arguments、raw tool output
- 外部APIのraw response
初期値は、redaction、hash、参照IDです。全文保存が必要な場合は、アクセス権を狭くし、削除方法と保持期間を明記します。
失敗点
顧客情報や社内文脈が入りやすく、traceの閲覧範囲がそのままリスクになります。
外部操作の対象やraw payloadが残り、必要以上の情報を広げる可能性があります。
承認者が何を見て、なぜ許可したのかをあとから説明できません。
異常の入口は見えても、個別eventやtool callの実行結果までは追えません。
trace、DB、Slack、ticket、CI artifactのアクセス権が揃わないと、管理が崩れます。
初期値は、分類済み属性、要約、hash、参照IDに寄せるほうが扱いやすくなります。
AIエージェントの実行ログでよくある失敗は、残しすぎと残さなすぎの両方です。
traceにpromptとtool引数を丸ごと残す
最初は便利です。何が起きたかすぐ分かります。しかし、promptには顧客情報や社内文脈が入り、tool引数には外部操作の対象やraw payloadが入ります。trace基盤の閲覧権限が広い場合、そこが機密情報の倉庫になります。
対策は、分類済み属性、要約、hash、参照IDを初期値にすることです。raw payloadが必要な業務だけ、別の保存先と閲覧権限で扱います。
承認ログにapprovedだけを残す
承認ボタンを押した事実だけでは、事故調査に耐えません。何を見たのか、どの差分だったのか、承認者は誰か、却下や編集はあったのか、承認後にどのtoolが実行されたのかが必要です。
approvedだけのログは、監査ログではなく操作履歴に近いものです。承認snapshot、decision reason、executed tool callをつなげます。
metricsだけで事故原因を見ようとする
metricsは入口です。失敗率やlatencyの上昇は、調査のきっかけにはなりますが、原因の説明には足りません。metric spikeからtrace、tool callログ、approval snapshotへ移動できるリンクが必要です。
保存先が増えたのにアクセス権を揃えない
OpenAI側trace、observability vendor、自社DB、CI artifact、Slack通知、チケットに情報が散ると、削除と最小権限が難しくなります。ログ設計では、保存先を増やすたびに閲覧roleとretentionを決めます。
実務で使うなら
保存期間は例では決めず、社内規定、契約、法務、監査要件に合わせます。
最小PoCでは、次の依頼packetを作ると始めやすいです。実装コードより先に、社内IssueやPR descriptionへ貼れる形にします。
| 項目 | 記入例 |
|---|---|
| 対象agent | support_reply_agent |
| 対象tool | search_ticket、draft_reply、update_ticket_status |
| 相関ID | run_id、thread_id、tool_call_id、approval_id、external_request_id |
| 保存するevent | run started、tool requested、approval decided、tool executed、run completed |
| 保存しないfield | raw prompt、raw customer payload、secret、internal URL |
| redaction | email、token、private repo URLをmask |
| tool input | summaryとhashのみ |
| approval snapshot | 表示したtool名、対象、差分、リスク、戻し方 |
| metrics | run count、failure rate、tool calls per run、approval wait、token usage、cost estimate |
| review query | run IDからtimelineを再構成できるか |
| retention | trace 30日、approval audit 1年など、社内規定に合わせる |
| owner | agent owner、security reviewer、on-call |
ここで書いたretentionは例です。実際の保存期間は、社内規定、契約、法務、監査要件に合わせます。
最初のレビュー観点
reviewでは、ログが多いか少ないかではなく、次を見ます。
- 1つのrun IDから、trace、tool call、approval、external APIまで追えるか
- tool input/outputにPIIやsecretが残っていないか
- 承認ログに、承認時点で表示した情報が残っているか
- ZDRやdata controlsが必要な業務で、OpenAI側traceに依存していないか
- metricsからtraceやtool callログへ移動できるか
- 削除要求や閲覧権限の変更に対応できるか
レビューで止める条件
事故後の調査手順を組み立てるなら、<a href="https://ai-dev.blog.mo-gmo.com/codex-log-investigation-packet-timestamp-redaction-evidence/">Codexにログ調査を頼む前に決めること</a>も合わせて読むと、timeline、evidence、next actionへつなげやすくなります。
セキュリティ・コスト注意
traceやlogへAPI key、cookie、private keyを入れないようにします。
raw prompt、raw tool arguments、raw tool outputを全文保存しない設計から始めます。
observability vendor、CI artifact、Slack通知、ticketへ何が出るかを確認します。
debug担当、on-call、security reviewer、audit reviewerで見られる範囲を変えます。
tool call、retry、handoff、context、承認待ち後の再開処理を確認します。
承認者がいる、traceがある、ZDRだから安全、という単純な見方は避けます。
AIエージェントの実行ログは、セキュリティとコストの両方に効きます。どちらも後回しにすると、運用後に直しにくくなります。
セキュリティ注意
- traceやlogへsecret、API key、cookie、private keyを入れない
- raw prompt、raw tool arguments、raw tool outputを初期値で全文保存しない
- approval snapshotには、承認に必要な最小情報だけを残す
- observability vendor、CI artifact、Slack通知、ticketへの転送範囲を確認する
- 閲覧権限を、debug担当、on-call、security reviewer、audit reviewerで分ける
- ZDRやdata controlsが必要な業務では、OpenAI側traceと自社側audit logを分ける
承認者がいるから安全、traceがあるから安全、ZDRだから安全、という単純な見方は避けます。安全性は、保存しない情報、残す情報、見られる人、削除できる範囲をセットで決めて初めて評価できます。
コスト注意
コストは、モデル呼び出しだけではありません。tool callが増える、retryが増える、handoffが増える、contextが長くなる、承認待ち後に再開処理が増える。これらが積み重なると、予算超過やrate limitに近づきます。
runごとのtoken usageとestimated costを持つだけでなく、tool calls per run、retry count、guardrail trigger count、approval rejection rateも見ると、無駄なrunを早く見つけやすくなります。運用予算の設計は、公開済みの<a href="https://ai-dev.blog.mo-gmo.com/codex-usage-budget-guardrails-runaway-tasks-alerts/">Codexの使いすぎを防ぐ前に決めること</a>ともつながります。
FAQ
run ID、tool call、approval、error、cost estimateを追える代替ログが必要です。
対象ID、入力要約、payload hash、external request ID、承認snapshotで調査できる範囲を確認します。
再開用のstate保存と、監査に耐える承認snapshotは別物として考えます。
observabilityの入口になっても、自社の承認、保存期間、閲覧権限は別に設計します。
OpenAI側traceに依存せず、自社側の監査ログと削除手順を先に決めます。
便利な観測基盤と、監査に必要な証跡は同じものとして扱わないようにします。
tracingを切っても運用できますか？
できます。ただし、run ID、tool call、approval、error、cost estimateを追える代替ログが必要です。ZDRが必要な業務では、OpenAI側tracingに依存しない自社側audit trailを用意します。
tool inputを全文保存しないと調査できませんか？
常に全文が必要とは限りません。多くの事故調査では、対象ID、入力要約、payload hash、external request ID、承認snapshotがあれば、何が起きたかを追えます。全文が必要な業務では、保存先と閲覧権限を狭くします。
承認ログはworkflow engineに任せればよいですか？
workflow engineのstate保存と、監査に耐える承認snapshotは別物として考えます。再開のためのstateには十分でも、承認者が見た内容、却下理由、実行結果との紐づけが足りないことがあります。
LangSmithやMastraを使えば監査ログは完成しますか？
いいえ。observability基盤は強力ですが、自社の監査要件、保存期間、閲覧権限、削除、承認者ロールまでは別に設計します。vendorのtraceやmetricsは、audit trailの一部として扱うのが安全です。
次に読むなら
AIエージェント、MCP、observability、承認付きworkflowの仕様更新を追いたい場合は、<a href="https://ai-dev.blog.mo-gmo.com/newsletter/">ニュースレター</a>で更新通知を受け取れます。チーム導入や監査ログ設計の相談は、<a href="https://ai-dev.blog.mo-gmo.com/contact/">お問い合わせ</a>から送れます。
参照した主な情報源
- https://developers.openai.com/api/docs/guides/agents
- https://openai.github.io/openai-agents-python/tracing/
- https://openai.github.io/openai-agents-python/guardrails/
- https://docs.langchain.com/langsmith/observability
- https://docs.langchain.com/langsmith/observability-concepts
- https://docs.langchain.com/langsmith/observability-quickstart
- https://mastra.ai/docs/observability/overview
- https://mastra.ai/docs/observability/tracing/overview
- https://mastra.ai/docs/workflows/overview
- https://opentelemetry.io/docs/concepts/signals/traces/
- https://opentelemetry.io/docs/concepts/signals/logs/
- https://opentelemetry.io/docs/concepts/signals/metrics/
更新履歴
- 2026-06-14
初版。OpenAI Agents guide、OpenAI Agents SDK tracing/guardrails、LangSmith、Mastra、OpenTelemetryの公式情報を確認して作成。
- 需要シグナル
X検索結果は需要シグナルとしてのみ扱い、本文根拠には使っていません。
ログやdata controlsの扱いは変わる可能性があるため、確認日を明示します。
| 日付 | 内容 |
|---|---|
| 2026-06-14 | 初版。OpenAI Agents guide、OpenAI Agents SDK tracing/guardrails、LangSmith、Mastra、OpenTelemetryの公式情報を確認して作成。X検索結果は需要シグナルとしてのみ扱い、本文根拠には使っていません。 |