AIエージェントが止まっても気づけないので、Failed / Stuck監視を入れてみた

1. なぜAIエージェントに監視が必要なのか

• AI Agentは「起動した」だけでは安心できない
• APIエラーや例外でFailedになる
• 無限待ちや外部API待ちでStuckすることがある
• 本番では、失敗そのものより「失敗に気づけない」ことが問題
• 今回は高度なトレースではなく、まず死活監視だけ入れる

2. 今回監視したい状態

• Running
• Success
• Failed
• Stuck

3. 監視方法をどうするか

• 自前でDB・timeout判定・通知まで作ることも可能
• LangSmith/LangfuseのようなObservability製品もある
• ただ今回は「Agentが動いたか、失敗したかだけ知りたい」
• そこでシンプルな監視としてRunveraを使う

4. RunveraでAgentを作成する

• Runveraに登録
• Agentを1つ作成
• Monitor Tokenを取得
• timeoutを設定
• SDKに渡す
  

5. Node.js Agentに監視を追加する

• SDKをインストール
• Tokenを環境変数に置く
• 既存Agentをmonitor()で囲むだけ

import { GoogleGenAI } from "@google/genai";
import { Runvera } from "@runvera/sdk";

const ai = new GoogleGenAI({
  apiKey: process.env.GEMINI_API_KEY,
});

const runvera = new Runvera({
  token: process.env.RUNVERA_TOKEN!,
});

async function myAgent() {
  const response = await ai.models.generateContent({
    model: "gemini-3.8-flash",
    contents: `
今週のニュースの中から、あなたが最も面白いと思うニュースを1つ選んでください。

以下の形式で日本語で答えてください。

タイトル:
概要:
なぜ面白いのか:
`,
  });

  console.log(response.text);

  return response.text;
}

await runvera.monitor(() => myAgent());

6. 正常終了させてみる

• Agentを普通に実行
• DashboardにRunningが出る
• 終了するとSuccessになる
• Durationも確認できる

7. わざとFailedさせてみる

• Agent内で例外を投げる
• Failedとして記録される
• エラーメッセージを確認
• メール通知も届く(素晴らしい！)
  例

async function myAgent() {
  throw new Error("API request failed");
}

8. 次にStuckさせてみる

• Agentを意図的に長時間待機させる
• timeoutを超える
• Runvera側でStuck判定
• 「例外すら出ない停止」を検知できる

例えば、「永遠に終わらない処理」を使ってテストできます。

async function myAgent() {
  await new Promise(() => {});
}

9. 実際に使ってみて良かったところ

• 導入コードが少ない
• FailedだけでなくStuckも分かる
• Agentごとに履歴を見られる
• 複雑なTracing設定が不要
• 小規模なAgentなら十分実用的
• 失敗だけメールで通知がくるので便利

10. まとめ

• AI Agentは「失敗する」だけでなく「止まる」
• Stuckはログを見ないと気づきにくい
• 最低限でも Running / Success / Failed / Stuck が見えると安心
• 高度なObservabilityが不要なら、シンプルな死活監視でも十分価値がある

今回使ったRunveraはこちら