Gemini Managed Agentsの使い方｜バックグラウンド実行・Remote MCPをJavaScriptで実装

Gemini Managed Agentsで数分以上かかる調査や複数ツール処理を行うなら、リクエストをbackground: trueで開始し、interaction IDを保存して状態をポーリングします。Remote MCPやカスタム関数を使う場合は、エージェントがrequires_actionになったときだけ外部処理を実行し、結果を次のInteractionへ返します。

この記事はGemini Interactions API全体の入門ではなく、Googleが2026年7月7日に案内したManaged Agentsのバックグラウンド実行、Remote MCP、カスタム関数、認証情報の更新に焦点を当てます。

情報確認日：2026年7月27日（日本時間）

結論：interaction IDをジョブIDとして保存し、状態遷移ごとに処理を分ける

Gemini Managed Agentsとは

Managed Agentsは、Gemini APIのInteractions API上で、モデルの推論、ツール利用、状態をまたいだ処理を管理する仕組みです。アプリ側がすべての手順を1回の同期HTTPリクエストに押し込まず、処理の進行をInteractionとして追跡できます。

基本的なInteractions APIの開始方法は「Gemini Interactions APIの使い方」、MCPの役割は「MCPの基本」を先に読むと理解しやすくなります。

バックグラウンド実行が向く処理

• 多数の資料を横断する調査
• Remote MCP経由で複数サービスを参照する処理
• 段階的なコード生成と検証
• 人の承認や外部関数の結果を途中で待つ処理
• UIのリクエスト時間内に終わらないエージェント処理

短い質問や単発の生成までバックグラウンド化すると、ポーリング、保存、再試行の実装コストが増えます。処理時間とツール数を基準に同期・非同期を分けます。

JavaScriptでバックグラウンドInteractionを開始する

SDKの正確な型やメソッド名はバージョンで変わる可能性があります。次のコードは、公式案内のbackground: trueとinteraction IDの考え方を示す最小構成です。

import { GoogleGenAI } from "@google/genai";

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

const interaction = await ai.interactions.create({
  model: "gemini-2.5-pro",
  input: "公式資料を比較し、変更点と移行チェックリストを作成してください。",
  background: true,
});

console.log(interaction.id);
console.log(interaction.status);

APIキーは環境変数やシークレット管理から読み込みます。interaction IDはレスポンスを待つプロセスのメモリだけに置かず、ユーザー、依頼、作成時刻と結び付けて保存します。

状態をポーリングする

const terminalStatuses = new Set([
  "completed",
  "failed",
  "cancelled",
  "requires_action",
]);

let current;

do {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  current = await ai.interactions.get(interaction.id);
} while (!terminalStatuses.has(current.status));

if (current.status === "completed") {
  console.log(current.outputs);
} else if (current.status === "requires_action") {
  console.log(current.requiredAction);
} else {
  console.error(current.error ?? current.status);
}

実運用では固定2秒ではなく、Retry-Afterや公式のレート制限に従い、指数バックオフと最大待機時間を設定します。ブラウザから直接ポーリングさせるより、バックエンドのジョブが状態を更新し、フロントへ通知する構成が扱いやすいです。

Remote MCPを接続する設計

Remote MCPを使うと、エージェントがネットワーク越しのMCPサーバーで提供されるツールへ接続できます。便利な一方、外部データの読み取りや更新を伴うため、接続URLだけでなく許可ツールと認証境界を設計します。

const interaction = await ai.interactions.create({
  model: "gemini-2.5-pro",
  input: "社内ドキュメントからリリース手順だけを確認してください。",
  background: true,
  tools: [
    {
      type: "mcp",
      serverUrl: process.env.DOCS_MCP_URL,
      allowedTools: ["search_docs", "read_doc"],
    },
  ],
});

上のコードは構成例です。利用中のSDKでRemote MCPのフィールド名と認証方法を公式ドキュメントで確認してください。書き込みツールは、読み取り専用ツールと同じ認証で一括公開しない方が安全です。

カスタム関数とrequires_action

エージェントがアプリ固有の関数を必要とすると、Interactionがrequires_actionになり、アプリ側へ関数名と引数が返ります。アプリは引数を検証し、関数を実行し、その結果を次のInteractionへ返します。

1. 要求された関数が許可リストにあるか確認する
2. JSON Schemaなどで引数を検証する
3. ユーザーの権限と対象リソースを再確認する
4. 副作用がある操作は承認を挟む
5. 成功・失敗を構造化して返す

if (current.status === "requires_action") {
  const call = current.requiredAction.functionCall;

  if (call.name !== "lookup_release_status") {
    throw new Error("Unsupported function");
  }

  const result = await lookupReleaseStatus(call.args.projectId);

  await ai.interactions.create({
    previousInteractionId: current.id,
    input: {
      functionResponse: {
        name: call.name,
        result,
      },
    },
    background: true,
  });
}

認証情報を更新する

長時間タスクでは、Remote MCPや外部APIのアクセストークンが途中で期限切れになることがあります。Googleの案内ではInteractionをまたいだ認証情報の更新が扱えるため、再開時に新しい認証情報を安全な保管先から渡す設計にします。

本番運用のチェックリスト

• interaction IDにユーザーIDと処理目的を紐付けた
• 同じ依頼の二重実行を防ぐ冪等キーがある
• ポーリング間隔、最大待機時間、再試行上限がある
• requires_actionの関数名と引数を検証する
• 書き込み操作にはユーザー承認を挟む
• Remote MCPの接続先とツールを許可リスト化した
• トークン失効・更新・取り消しを処理できる
• SDKとAPIのバージョンを固定し、更新時にテストする

よくある質問

まとめ

Gemini Managed Agentsの長時間処理では、interaction IDをジョブIDとして保存し、状態遷移に応じて完了・失敗・外部アクションを分岐します。Remote MCPやカスタム関数を追加するほど、認証、引数検証、承認、監査ログが重要になります。まず読み取り専用の小さなツールから接続し、失敗時の再開経路を確認してから副作用のある処理へ広げてください。

公式情報

• Google：Expanding Managed Agents in the Gemini API
• Google AI for Developers：Interactions API