AI エージェントは、もうブラックボックスではない
エージェントをデプロイしたあと、必ずこう思います。「なぜこの回答になったのか?」
プロンプトは正しかったはずなのに結果がおかしい、ツール呼び出しが想定外の場所で失敗する、トークン消費が突然跳ね上がる。ログを追っても reasoning の過程は見えず、tool call の順序も残っていない。事実上、目を閉じてデバッグしているような状態でした。
Vercel はこの問題に正面から取り組みました。オープンソースのエージェントフレームワーク eve を Vercel にデプロイすると、実行トレースが自動的に Agent Runs として取り込まれ、MCP ツールと Vercel CLI から参照できるようになりました。
ポイントは次の3つです。
- エージェント実行履歴をプロジェクト単位で検索
- 各 run の reasoning / tool call / トークン使用量をすべて取得
- MCP を持たないコーディングエージェントでも CLI 経由で自身の run をデバッグ可能
本記事は Vercel 公式チェンジログを根拠資料として整理したものです(末尾リンク参照)。
MCP ツール4種 + CLI コマンド4種、これがすべて
MCP ツール
エージェントが MCP に対応していれば、以下の4ツールがそのまま使えます。
| ツール | 役割 |
|---|---|
list_agent_run_projects | チーム内で Agent Runs 活動のあるプロジェクトを検索 |
list_agent_runs | 特定プロジェクトの直近 run 一覧を取得 |
get_agent_run | メタデータ、ライフサイクルイベント、使用量、サブエージェント情報を取得 |
get_agent_run_trace | turn / message / reasoning / tool call / トークン使用量 / tool 入出力を含む全トレースを取得 |
CLI コマンド
# MCP のインストール
npx add-mcp https://mcp.vercel.com
# または CLI を最新版にアップグレード
npm i -g vercel@latest
# Agent Runs 関連コマンド
vercel agent-runs projects # run が存在するプロジェクト一覧
vercel agent-runs list # 直近 run 一覧
vercel agent-runs inspect # 特定 run の詳細
vercel agent-runs trace # run の全トレースを取得
実務でそのまま使える Tips
すべての CLI サブコマンドが --json フラグをサポートしています。マシンリーダブルな出力が必要なときに便利です。
# JSON でパースして他のツールに渡す
vercel agent-runs list --json | jq '.[] | {id, status, tokens}'
# パイプに渡すとトレースが markdown でレンダリングされる
vercel agent-runs trace <run-id> | less
特に最後の点が興味深いところです。MCP にアクセスできないコーディングエージェントでも、CLI を直接呼び出して自身の run を自己デバッグできるという意味になります。たとえば Claude Code に対して次のように指示できます。
「自分のプロジェクトの最新プロダクション Agent Runs を見せて」 「直近の run を基にスキルを更新して」
エージェントが自身の実行ログを読み、自己改善するループが CLI ひとつで開いたわけです。
朗報だが、単なる「ログビューア」ではない
良い点
- 自動収集: Vercel にデプロイするだけでトレースが自動 ingest されます。SDK 連携や追加設定は不要です。
- reasoning まで露出: 単なる入出力ログではなく、モデルがどのような思考過程を経たかまで残ります。ハルシネーションの原因追跡に特に有効です。
- トークン使用量の追跡: run 単位でトークン消費を確認でき、コスト最適化の出発点になります。
- エージェントの自己デバッグ: CLI + markdown パイプの組み合わせは、MCP のない環境で特に強力です。
注意点
- Vercel への依存: Agent Runs は Vercel デプロイ環境で自動 ingest される仕組みです。他のクラウドやオンプレミスで動かすエージェントはこの恩恵を受けられません。
- eve フレームワーク前提: 現時点の説明は eve エージェントフレームワーク基準です。LangChain や CrewAI など他フレームワークを使う場合は別途連携が必要になる可能性があります。
- トレースデータ量: reasoning と tool 入出力まで全て保存すると、データ量はかなり大きくなります。長期保管ポリシーとコストは事前に確認しておきましょう。
- 機密情報の露出リスク: tool の入出力がそのままトレースに残るため、API キーや個人情報が tool の引数に入るとそのまま記録されます。マスキングポリシーは必ず点検してください。
日本国内の開発現場での適用文脈
日本ではまだ Vercel をメインのデプロイ先にしているチームは多くありませんが、AI エージェントの PoC を高速で回しているチームであれば話は別です。特に社内ネットワークが制限され MCP サーバーを立てられない環境でも、CLI だけでトレースを取得できるという点は実用的です。閉域網で動くコーディングエージェントに vercel agent-runs trace --json を実行させる、といった使い方が可能です。
ただし、日本の SI/金融系のようにデータの外部持ち出しに敏感な組織では、トレースに reasoning と tool 入出力が丸ごと残る事実を事前に共有しておく必要があります。「エージェントが何をしたか全部見える」というのは諸刃の剣です。
まとめ
Vercel Agent Runs は、**「エージェントを作ったのに、なぜこう動くのか分からない」**という開発者長年の不満に正面から応える機能です。MCP ツール4種と CLI コマンド4種、そして --json / markdown パイプの組み合わせだけ覚えれば十分です。
次のステップ学習の方向性
- eve フレームワークのテンプレートから始める — テンプレートを1つ選んでデプロイし、最初の run からトレースを読み解きましょう。
- MCP ツールをコーディングエージェントに接続 —
npx add-mcp https://mcp.vercel.comの一行で完了します。 - CLI 自己デバッグループの実験 — エージェントに自身の run を分析させ、スキルを改善するワークフローを組んでみてください。
- トークン使用量のダッシュボード化 —
--json出力を集約して run 単位のコストを追跡すると、最適化ポイントが見えてきます。
あわせて読みたい記事
- AI 時代、「できますか?」ではなく「どれくらいできますか?」を問うべき理由 — 確率論的システムを扱う視点から、エージェントデバッグを捉え直せます。
- Python 3.14.3 リリース! 押さえておくべき主な変更点と実務への影響 — エージェントのバックエンドを Python で組むなら、あわせてチェックしておきましょう。