マルチエージェントAgent SDK の見える化｜OpenTelemetry で記録
この記事の要点
- Agent SDK は中で Claude Code を動かしていて、その Claude Code が OpenTelemetry の記録を出す。設定は環境変数で渡す
- 記録は「数の集計・出来事・流れ」の3種類。どれも既定ではオフで、送り先の設定が要る
- 既定では、AI が読み書きした中身は記録されない。中身まで残す設定は、保存先の承認を取ってから
活用例：社内で動かす AI エージェントの操作を、利用者ごとに記録して監査できるようにする
- 部署
- 情報システム・内部監査
- 使うもの
- Claude Agent SDK・OpenTelemetry に対応した監視の仕組み
- AIに任せる
- 依頼された調査や資料づくり
- 人が決める
- 記録の送り先・中身まで残すかどうか・保存期間
AI エージェントを社内で本番として動かすと、「どの道具を使ったのか」「1回の依頼にどれだけ時間とお金がかかったのか」「どこで失敗したのか」 を、あとから確かめたくなります。
この記事では、公式ドキュメント「Observability with OpenTelemetry」（2026年11月11日確認）にもとづいて、Claude Agent SDK の動きを OpenTelemetry という共通の形式で記録し、監視の仕組みに送る方法を整理します。SDK を本番で動かす全体の考え方は Agent SDK の本番運用（ホスティング） で解説しています。
結論：記録を出すのは中の Claude Code。設定は環境変数で渡す
Agent SDK は、中で Claude Code を子どもの処理として動かしています。 記録を出すのはその Claude Code で、SDK 自身は記録を作りません。SDK は設定を Claude Code に渡し、Claude Code が記録を送り先に直接送ります。
設定は 環境変数 で渡します。渡し方は2つです。
| 渡し方 | 向いている場面 |
|---|---|
| アプリを動かす環境に入れる | 本番。コードを変えずに、すべての query() に効く（公式のおすすめ） |
| query() の env オプションに入れる | 同じアプリの中で、エージェントごとに設定を変えたい時 |
TypeScript 版で env を指定すると、元の環境変数が置き換わります。 元の値も一緒に入れます。Python 版では、元の環境変数の上に足されます。
記録は3種類
| 種類 | 中身 | 有効にする設定 |
|---|---|---|
| 数の集計（メトリクス） | トークン・費用・会話の数・書いた行数・道具の許可の判断 | OTEL_METRICS_EXPORTER |
| 出来事（ログ） | 依頼・API の呼び出し・エラー・道具の結果を1件ずつ | OTEL_LOGS_EXPORTER |
| 流れ（トレース） | 1回のやりとり・モデルへの依頼・道具の呼び出しを時間の帯で（ベータ） | OTEL_TRACES_EXPORTER と CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 |
どれも既定ではオフ です。CLAUDE_CODE_ENABLE_TELEMETRY=1 を入れ、少なくとも1つの送り先を選ぶと動き始めます。よくあるのは、3種類すべてを OTLP の HTTP で集める仕組み（コレクター）に送る形です。
動いているかの確かめ方と、2つの落とし穴
送ったあとは、集める仕組みの側に記録が届いているか で確かめます。
- 送り先の失敗は静かに捨てられる：送り先に届かなくてもエージェントは普通に動き、エラーも出ない。届いていない時は、送り先の側の記録を見る
- 画面に出す送り方（console）は使わない：SDK は標準出力をやりとりに使っているため、ぶつかってしまう。手元で見たい時は、手元に集める仕組みを立てて送る
短い処理で記録が抜ける時
記録はまとめて送られます。既定では 数の集計は60秒ごと、出来事と流れは5秒ごと です。処理がすぐ終わると、送り切る前に終わって記録が抜けることがあります。送る間隔を短くしておくと、抜けにくくなります。
流れ（トレース）で見えること
| 帯の名前 | 中身 |
|---|---|
| claude_code.interaction | 1回の依頼から返事までのやりとり全体 |
| claude_code.llm_request | Claude への依頼1回ごと（モデル名・かかった時間・トークン数） |
| claude_code.tool | 道具の呼び出し1回ごと（許可待ちの時間と、実行そのものに分かれる） |
| claude_code.hook | フックの実行1回ごと（詳しい記録の設定が別に要る） |
サブエージェントの動きは、呼び出した親の道具の帯の下に入るので、任せた流れが1本につながって見えます。 同じ会話で何度も query() を呼んだ時は、会話の番号（session.id）で絞ると1本の時系列で見られます。自分のアプリが記録の流れを出している時は、その中にエージェントの流れが自動で入ります。
利用者ごとに記録を分ける
1つのアプリで多くの人に使ってもらう場合、そのままでは 記録に残るのはアプリの認証の情報で、実際に頼んだ人ではありません。 query() を呼ぶたびに、頼んだ人の情報を記録の属性として足すと、利用者ごとの監査記録 になります。
監査で特に使うのは、道具の許可の判断と結果（tool_decision・tool_result）、外部の道具の接続（mcp_server_connection）、権限のモードの変更（permission_mode_changed）です。サービスの名前も既定の claude-code から変えられるので、エージェントが複数ある時は名前で分けておきます。
機密の扱い
既定の記録には、AI が読み書きした中身は入りません。 かかった時間・モデル名・道具の名前などの形だけです。次の設定を入れると、中身も記録に入ります。
| 設定 | 足されるもの |
|---|---|
| OTEL_LOG_USER_PROMPTS=1 | 依頼の文 |
| OTEL_LOG_TOOL_DETAILS=1 | 道具に渡した内容（ファイルの場所・コマンドなど） |
| OTEL_LOG_TOOL_CONTENT=1 | ファイルの中身やコマンドの結果など |
| OTEL_LOG_RAW_API_BODIES | API のやりとりの全文 |
公式ドキュメントでは、記録の保存先が、エージェントの扱うデータを保存してよいと承認されていない限り、入れないように とされています。
よくある質問
費用だけ知りたい時も、この仕組みが要りますか？
要りません。 使った量と費用は、SDK の返事の流れから直接読めます。Agent SDK の費用と使用量の記録 で解説しています。ふだんの Claude Code の監視の設定は Claude Code の利用状況の監視 でまとめています。
まとめ
- 記録を出すのは 中の Claude Code。設定は環境変数で渡す
- 記録は 数の集計・出来事・流れの3種類。どれも既定ではオフ
- 中身まで残す設定は、保存先の承認を取ってから 入れる
出典
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。
