Antigravity エージェントのオブザーバビリティ設計図
AI エージェントが本番環境で動き始めると、最初に直面するのは『何が起きているのか分からない』という壁です。従来の Web アプリケーションなら、リクエストのレイテンシとエラー率を見れば大体の状況が掴めました。ところが AI エージェントは違います。レスポンスは200で返ってきているのに『答えが間違っている』『余計なツールを呼んでいる』『高額な API を無駄遣いしている』といった問題が静かに進行します。
私自身、Antigravity でエージェントを本番投入し始めた頃、まさにこの問題に直面しました。ここではその経験から組み上げた『AI エージェント向けオブザーバビリティ』の設計手法を、すぐに実装に落とせる形でお伝えします。
なぜ AI エージェントのオブザーバビリティは特殊なのか
従来のオブザーバビリティ（観測可能性）は、Three Pillars と呼ばれる三本柱で語られてきました。メトリクス、ログ、トレースの三つです。これらを組み合わせれば、システムの状態を再現できる、というのが基本思想です。
AI エージェントの世界では、この三本柱だけでは足りません。エージェント特有の『観測したいもの』が三つあります。
第一に『思考』です。エージェントが次の行動を決定する前に、どんな推論を行ったか。これは LLM の出力テキスト（チェーン・オブ・ソート）として現れます。第二に『行動』です。どのツールを、どんな引数で呼び出したか。これが副作用を生む唯一のレイヤーです。第三に『成果』です。エージェントが最終的に達成したタスクが、ユーザーの意図に合致していたか。これは多くの場合、人間のフィードバックや A/B テストで測ります。
これらを区別せずに一緒くたにログに出すと、後から問題を分析する時に手詰まりになります。Antigravity 環境では特に、複数のエージェントが協調動作するため、観測の粒度を最初から正しく設計しておく点が肝心です。
第一の柱：構造化トレースで思考を再現する
エージェントの動作を後から追えるようにするには、構造化されたトレース（実行履歴）が不可欠です。OpenTelemetry のスパン構造を借りて、エージェントの実行を以下のように分解します。
// トレース構造の例
{
spanName: "agent.run",
attributes: { agent_id: "support-bot-v3", session_id: "..." },
children: [
{
spanName: "agent.thought",
attributes: { reasoning: "ユーザーは返金を求めている..." },
children: [
{
spanName: "tool.call",
attributes: { tool: "lookup_order", args: { orderId: "..." } },
duration_ms: 245,
},
{
spanName: "tool.call",
attributes: { tool: "issue_refund", args: { amount: 1500 } },
duration_ms: 1820,
},
],
},
{
spanName: "agent.response",
attributes: { tokens: 312, model: "claude-sonnet-4-6" },
},
],
}このような階層構造で記録しておくと、後から『なぜこのエージェントは返金を発行したのか』を再現できます。重要なのは、思考（reasoning）と行動（tool.call）を別スパンに分離することです。これにより、思考が誤っていたのか、ツール呼び出しが誤っていたのかを切り分けられます。
Antigravity では、@trace.span() のようなデコレータを使って、エージェントのコードに最小限の修正でトレースを仕込めます。本番投入の最初の週は、サンプリング率を100%にして全実行をトレースし、典型的な動作パターンを把握することをお勧めします。
第二の柱：行動メトリクスで異常を早期検知する
トレースは詳細を追うのに優れていますが、傾向を捉えるのには向きません。傾向を捉えるにはメトリクス（数値の集約値）が必要です。
AI エージェント特有のメトリクスとして、私が必須だと考えているのは以下の五つです。
# エージェント別メトリクス
agent_invocations_total:
type: counter
labels: [agent_id, outcome] # outcome: success, partial, error
agent_tool_calls_total:
type: counter
labels: [agent_id, tool_name, status]
agent_tokens_consumed:
type: histogram
labels: [agent_id, model, direction] # direction: input, output
agent_response_latency_seconds:
type: histogram
labels: [agent_id, model]
agent_cost_usd:
type: counter
labels: [agent_id, model]特に agent_cost_usd は、軽視されがちですが本番運用では生命線になります。エージェントが想定外のツール呼び出しを連発し始めると、コストが急増します。Antigravity の実行履歴から逆算すれば、リアルタイムでコストを集計できます。
これらのメトリクスを Prometheus + Grafana のような時系列基盤で可視化し、以下のアラートを最低限仕掛けておきます。エージェントごとのエラー率が前週比で2倍を超えたら通知。1セッションあたりのトークン消費量が中央値の3倍を超えたら通知。1時間あたりのコストが予算上限を超えたら自動的にエージェントを停止する仕組みも有効です。
第三の柱：成果ログで品質を継続改善する
最後の柱は『成果ログ』です。これは従来のアプリログとは別物として設計します。
エージェントの一連の動作が完了した後、その『成果』を記録します。以下のフィールドを含めます。
- セッション ID（トレースとの紐付けに使用）
- ユーザーの当初の要求（最初のメッセージ）
- エージェントが返した最終応答
- ユーザーのフィードバック（明示的な評価、または『その後の行動』からの推定）
- 自動評価スコア（別の LLM による評価、ルーブリックベースの採点など）
このログは、後から品質改善のためのデータセットとして使います。低スコアの成果ログを集めて分析することで、エージェントの弱点が浮き彫りになります。プロンプトの改善、ツールの追加、ファインチューニングのデータ収集、すべての出発点になります。
統合ダッシュボードの設計
ここまでで集めた情報を、運用担当者が一望できるダッシュボードに集約します。Antigravity 環境で私が実際に運用しているダッシュボードのレイアウトをご紹介します。
最上段には『健康指標』を3〜4枚のスコアカードで配置します。直近1時間の総セッション数、エラー率、平均レイテンシ、累積コスト。一目でシステム全体の状態が分かるようにします。
中段には『時系列グラフ』を配置します。エージェントごとの呼び出し数、ツールごとの成功率、モデルごとのトークン消費量。これらを縦に並べることで、異常の発生時刻を相互に関連付けて分析できます。
下段には『最近の異常セッション』のリストを配置します。エラーで終了したセッション、レイテンシが異常に長かったセッション、コストが高かったセッションへのリンクを並べます。クリックするとトレース詳細にドリルダウンできるようにしておきます。
このレイアウトの肝は、トップダウンに情報を見られることです。最初に全体の健康状態を確認し、異常があれば時系列で原因の時間帯を特定し、最後に個別のセッションに飛んでトレースを精査します。この流れが自然にできるダッシュボードが、運用負荷を大きく下げます。
サンプリング戦略：全部記録するのは現実的ではない
ここまで『全部記録しよう』と書いてきましたが、本番規模では現実的ではありません。トレースのストレージコストだけで月数万円かかることもあります。実用的なサンプリング戦略を紹介します。
エージェント本番投入の最初の2週間は、全実行を記録します。データが少ない時期は、欠損があると後から原因究明できなくなるためです。
定常運用に入ったら、以下の方針で間引きます。エラーで終了したセッションは100%記録（少ないが価値が高い）。コストが上位5%のセッションは100%記録（コスト最適化に直結）。それ以外は10〜20%のサンプリング。これに加えて、新しいバージョンをリリースした直後の48時間は100%記録に戻すローリング戦略を組み合わせます。
実装の段階的ロードマップ
このフレームワークを実装するなら、以下の順序が現実的です。
最初の1週間は、構造化トレースの導入だけに集中します。これだけで運用の見通しが劇的に改善します。次の1週間で、基本的なメトリクス（呼び出し数、エラー率、レイテンシ、コスト）を収集します。
その後の1ヶ月で、成果ログの自動評価パイプラインを構築します。これが最も時間のかかる作業ですが、長期的なリターンも最大です。最後に統合ダッシュボードとアラート整備を行います。
各段階で『目に見える改善』があるため、組織全体の理解を得やすい順序になっています。
次の一歩
このガイドを読み終えた今、まず取り組むべきは現在運用中のエージェントに『構造化トレース』を入れることです。一つのエージェントだけでも構いません。1週間トレースを取り続けて、それを眺めることで多くの気づきがあります。
『このエージェントは思ったより同じツールを何度も呼んでいる』『この処理はほぼ常に失敗している』『このユーザーセッションだけ異常に長い』。データが手元にあって初めて、改善のアイデアが生まれます。オブザーバビリティは投資ですが、その効果は確実に現れます。