Antigravity の AI エージェントを Langfuse で観測する — 本番投入前にやっておきたい可視化設計

Antigravity で一気に組み上げた AI エージェントを、いざ本番に出す直前になって「このエージェント、内部で何回 LLM を呼んでいるんだろう？」と急に不安になった経験はないでしょうか。私自身、デモでは気持ちよく動いていたエージェントが、実ユーザーを相手にした途端に 1 リクエストで 30 回もモデルを叩いていたことに気づき、慌ててログを追いかけたことがあります。

観測の話は地味で、すぐに売上に効く種類の仕事ではありません。ただ、エージェントが複雑になるほど、観測なしで改善することは現実的に不可能になっていきます。Antigravity で開発した AI エージェントに Langfuse を組み込み、トレース・トークン消費・コストを「最低限これだけ見ていればつらい思いをしない」という線まで可視化するための、実践的な設計を順番にご紹介します。

なぜ AI エージェントの可観測性はいつも後回しになるのか

OpenTelemetry や Prometheus でアプリケーション全体を計測することについては、Antigravity の OpenTelemetry 可観測性パイプラインのような記事で整理してきました。ただ、AI エージェントに限って言うと、汎用の可観測性スタックだけではどうしても足りない部分が残ります。

汎用ツールが得意なのは HTTP リクエスト数や CPU 使用率などの「インフラ的な数字」です。一方で、AI エージェントの開発者が本当に知りたいのは「どのプロンプトが何トークン使い、どのツール呼び出しが何ミリ秒で帰ってきて、最終出力がどれくらいユーザーにとって満足できるものだったか」という、もう一段だけ内側の情報です。ここを後から足そうとすると、ログのフォーマットからやり直す羽目になります。

Langfuse は、この「AI 特有の観測」に特化した OSS のトレーシング基盤です。セルフホストもクラウドも選べるため、個人開発から企業利用まで同じコードを使い回せるのが好きで、私は Antigravity プロジェクトのデフォルトにするようになりました。

Langfuse を選ぶ理由をもう少し正直に

AI 観測ツールは今、かなり選択肢が多い状況です。LangSmith・Helicone・Arize・Phoenix など、それぞれに尖った強みがあります。その中で Langfuse を選ぶ理由を、私が現場で感じているメリット順に挙げておきます。

セルフホスト可能で、クラウド版と同じ API: 個人の試作ではクラウド版、仕事の案件ではセルフホスト、という使い分けができます。
Python / TypeScript の SDK が素直: Antigravity の Agent で自動生成させても、ほぼそのまま動くコードが出てきます。
「トレース」「世代（Generation）」「スコア」の 3 概念だけで理解できる: 最初の学習コストが低く、チームに展開しやすいのが地味に効きます。
評価（Eval）機能との統合: 本番のトレースをそのまま評価データセットに昇格できるため、「観測 → 評価 → 改善」が 1 つのツールで完結します。

逆に、インフラ全体の監視や SLO 管理までやりたい場合は、Prometheus + Grafana 監視ガイドの構成と併用した方が素直です。Langfuse は「AI の中身に特化した観測」、Prometheus は「アプリ全体の健全性」と役割を分けて考えると、両方入れても管理が破綻しません。

Antigravity 上で Langfuse を 15 分で導入する

Langfuse は langfuse パッケージを入れて、環境変数を 3 つ設定するだけで動き始めます。Antigravity の Agent に「Google Gen AI SDK と Langfuse を組み合わせた最小サンプルを Python で書いて」と投げると、おおむね次のようなコードが出てきます。

# app/observed_agent.py — Gen AI SDK の呼び出しを Langfuse に記録する最小例
import os
from google import genai
from langfuse.decorators import observe, langfuse_context
 
# 環境変数: LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY / LANGFUSE_HOST
client = genai.Client(api_key=os.environ["GOOGLE_API_KEY"])
 
@observe(as_type="generation")
def answer_question(question: str) -> str:
    """ユーザーの質問に Gemini で回答する関数。@observe で自動的にトレースされる。"""
    model = "gemini-2.5-flash"
 
    # Langfuse に「どのモデルを呼んだか」を明示する
    langfuse_context.update_current_observation(
        model=model,
        input={"question": question},
    )
 
    response = client.models.generate_content(model=model, contents=question)
    output_text = response.text
 
    # 使用トークン数と出力を Langfuse に渡す
    langfuse_context.update_current_observation(
        output={"answer": output_text},
        usage={
            "input": response.usage_metadata.prompt_token_count,
            "output": response.usage_metadata.candidates_token_count,
            "unit": "TOKENS",
        },
    )
    return output_text
 
if __name__ == "__main__":
    print(answer_question("Antigravity の特徴を 3 行で教えてください。"))

このコードを実行すると、Langfuse のダッシュボードに「どのプロンプトで」「何トークン使い」「何秒かかったか」が 1 行ずつ積まれていきます。実行する前にプロジェクトの API キーをダッシュボードから発行し、.env に書いておくだけで十分です。

上のサンプルに、Antigravity Python API を本番で落とさないためのリトライ設計で紹介している tenacity ベースのリトライを重ねると、そのままステージング投入できるレベルになります。

トレース設計で迷わないための 3 つの観点

SDK を入れれば記録は始まりますが、後から見返して本当に役立つトレースにするには、ちょっとした設計が必要です。私が Antigravity のプロジェクトで必ず守っているルールは 3 つだけです。

1 ユーザーリクエスト = 1 トレース: 複数のツール呼び出しや LLM 呼び出しを、必ず同じ trace_id の下にぶら下げる。これだけで「あのユーザーのあのリクエストが何をやっていたか」を 1 画面で追えるようになります。
ツール呼び出しは span に分ける: DB アクセス・外部 API・LLM 呼び出しをそれぞれ span として記録しておくと、ボトルネックが一目で分かります。Langfuse の UI はガントチャート表示がしっかりしているので、この設計と相性が良いです。
ユーザー ID・セッション ID を必ずタグに入れる: 後で「プレミアムユーザーだけコスト分析したい」「このセッションだけ再現したい」と思ったとき、タグがないと何もできません。個人情報を直接入れる必要はなく、ハッシュ化した ID で十分です。

この 3 つを最初から守っておけば、プロジェクトが大きくなって Agent の種類が増えても、ダッシュボードが荒れていきません。

ダッシュボードから本当に読み取るべきサイン

Langfuse のダッシュボードには数字と折れ線がたくさん並びますが、Antigravity で開発した個人プロジェクトの文脈で私が毎日見ているのは、実は 3 つだけです。

1 トレースあたりの平均トークン数: 直近 1 週間で上がり始めたら、プロンプトか Retrieval の設計がどこか太り始めたサインです。Agent のコスト最適化ガイドと合わせて、まずここから削っていきます。
レイテンシの p95: p50 が良くても p95 が悪ければ、一部のユーザーだけ著しく遅い状態になっています。体感品質を決めるのはほぼ p95 です。
失敗率（error rate）: Langfuse では observation レベルで失敗を記録できます。ゼロであることは期待しない方がよく、「どれくらいを許容するか」を先に決めておくと、アラート疲れしにくくなります。

逆に、最初からすべての指標を見に行こうとすると疲れてしまい、結局ダッシュボードを開かなくなります。「この 3 つだけは毎朝見る」という運用に絞ると、観測が続きます。

今日できる最初の一歩

観測の整備は、一気にやろうとすると必ず途中で力尽きます。おすすめは、いま一番よく使っている Antigravity のエージェントスクリプトを 1 つだけ選び、@observe デコレータを付けて 10 分だけダッシュボードを眺めてみることです。自分のエージェントが「思っていたより静かだ」あるいは「思っていたより騒がしい」と感じる瞬間があれば、それがまさに観測を続ける価値が生まれた合図です。

そこまでくれば、あとはプロジェクトが成長するのに合わせて、トレース粒度や評価スコアを少しずつ足していけば十分です。完璧な計装より、毎朝 1 分だけ見返す習慣の方が、エージェントの品質には強く効いてきます。