遅延ティアを使用する

遅延ティアを使用すると、Gemini Enterprise Agent Platform でカスタム エージェントの非同期マルチターン Gemini モデル呼び出しを割引料金で実行できます。Interactions API では、Agent Platform は、24 時間の目標内でバックグラウンド実行するために、遅延された各ターンをキューに入れ、7 日間状態を保持します。

遅延ティアは、次のような、ターンごとの制御が必要なレイテンシ許容型のエージェント ワークロードに適しています。

  • マルチステップのコーディング エージェントとセキュリティ エージェント: リポジトリの脆弱性スキャン、自動コード移行、回帰トリアージ。
  • ドキュメントと調査のパイプライン: 技術設計のレビュー、財務バックテスト、ツール呼び出しによるマルチドキュメントの合成。
  • オフライン エージェント評価: リアルタイムのレイテンシ制約なしで previous_interaction_id ターンをチェーンする大規模な品質ベンチマーク。

すべてのコンピューティング モデルを比較するには、使用オプションをご覧ください。Agent Development Kit(ADK)エージェントまたは Gemini Deep Research エージェントのマネージド実行をスケジュールするには、自律エージェントのスケジュール設定をご覧ください。

サポートされているモデルとロケーション

遅延ティアは、global エンドポイント(aiplatform.googleapis.com の locations/global)でのみサポートされています。service_tier="deferred" を含むリクエストをリージョン エンドポイント、または us または eu マルチリージョン エンドポイントに送信すると、HTTP 400("code": "invalid_request")が返されます。

次のメインライン Gemini モデルは、global エンドポイントで遅延ティアをサポートしています。

プロジェクトに Google Cloud アカウント チームを介した許可リストへのアクセス権がある場合は、次の Cyber モデルも使用できます。

始める前に

課金が有効になっている既存の Google Cloud プロジェクトで、次の前提条件の設定手順を完了します。

  1. Google アカウントにログインします。

    Google アカウントをまだお持ちでない場合は、新しいアカウントを登録します。

  2. Google Cloud CLI をインストールします。

  3. 外部 ID プロバイダ(IdP)を使用している場合は、まずフェデレーション ID を使用して gcloud CLI にログインする必要があります。

  4. gcloud CLI を初期化するには、次のコマンドを実行します。

    gcloud init
  5. このガイドを完了するために必要な権限があることを確認します。

  6. Agent Platform API が有効になっていない場合は、有効にします。

    API を有効にするために必要なロール

    API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール(roles/owner)を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール(roles/serviceusage.serviceUsageAdmin)を介してこの権限を取得できます。ロールを付与する方法を確認する。

    gcloud services enable aiplatform.googleapis.com
  7. ローカルシェルを使用している場合は、ユーザー アカウントのローカル認証情報を作成します。

    gcloud auth application-default login

    Cloud Shell を使用している場合は、この操作を行う必要はありません。

    認証エラーが返され、外部 ID プロバイダ(IdP)を使用している場合は、フェデレーション ID を使用して gcloud CLI にログインしていることを確認します。

  8. Google Cloud CLI をインストールします。

  9. 外部 ID プロバイダ(IdP)を使用している場合は、まずフェデレーション ID を使用して gcloud CLI にログインする必要があります。

  10. gcloud CLI を初期化するには、次のコマンドを実行します。

    gcloud init
  11. このガイドを完了するために必要な権限があることを確認します。

  12. Agent Platform API が有効になっていない場合は、有効にします。

    API を有効にするために必要なロール

    API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール(roles/owner)を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール(roles/serviceusage.serviceUsageAdmin)を介してこの権限を取得できます。ロールを付与する方法を確認する。

    gcloud services enable aiplatform.googleapis.com
  13. ローカルシェルを使用している場合は、ユーザー アカウントのローカル認証情報を作成します。

    gcloud auth application-default login

    Cloud Shell を使用している場合は、この操作を行う必要はありません。

    認証エラーが返され、外部 ID プロバイダ(IdP)を使用している場合は、フェデレーション ID を使用して gcloud CLI にログインしていることを確認します。

必要なロール

遅延モデル呼び出しの作成、モニタリング、キャンセルに必要な権限を取得するには、 Google Cloud プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

  • 遅延インタラクションの作成、ポーリング、キャンセル、削除: Agent Platform ユーザー(roles/aiplatform.user)
  • 遅延したインタラクションをモニタリングする(読み取り専用): Agent Platform 閲覧者(roles/aiplatform.viewer)
  • Cloud Storage からマルチモーダル入力ファイルを読み取る(省略可): Storage オブジェクト閲覧者(roles/storage.objectViewer)

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

Google Gen AI SDK をインストールする

クライアント ライブラリを使用する場合は、開発環境に Google Gen AI SDK(@google/genai >= 2.32.0 または google-genai >= 2.34.0)をインストールまたはアップグレードします。

Node.js

npm install @google/genai@latest

Python

pip install --upgrade "google-genai>=2.34.0"

遅延モデル呼び出しを作成して管理する

始める前にで設定した環境で、次の手順を実行します。REST サンプルは gcloud CLI 認証情報で認証され、Google Gen AI SDK サンプルはアプリケーションのデフォルト認証情報(ADC)を使用します。呼び出しでエラーが返された場合は、トラブルシューティングをご覧ください。

遅延モデル呼び出しを作成する

service_tier="deferred"、background=true、store=true を指定して interactions.create を呼び出し、非同期ターンを送信します。stream を省略するか、false に設定します。サンプルを実行する前に、PROJECT_ID を Google Cloud プロジェクト ID(my-agent-project など)に置き換えます。

REST

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: Google Cloud プロジェクト ID(my-agent-project など)。

HTTP メソッドと URL:

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions

リクエストの本文(JSON):

{
  "model": "gemini-4-argon",
  "input": "In two sentences, explain how a circuit breaker differs from exponential backoff in a distributed microservice architecture.",
  "service_tier": "deferred",
  "background": true,
  "store": true
}

リクエストを送信するには、次のいずれかのオプションを展開します。

レスポンスは、次のような JSON ペイロードを返します。

{
  "id": "v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0",
  "model": "gemini-4-argon",
  "status": "queued",
  "service_tier": "deferred",
  "steps": []
}

Node.js

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

async function createDeferredInteraction(projectId) {
  const ai = new GoogleGenAI({
    enterprise: true,
    project: projectId,
    location: "global",
  });

  const interaction = await ai.interactions.create({
    model: "gemini-4-argon",
    input:
      "In two sentences, explain how a circuit breaker differs from exponential backoff in a distributed microservice architecture.",
    service_tier: "deferred",
    background: true,
    store: true,
  });

  console.log(`Interaction ID: ${interaction.id}`);
  console.log(`Status: ${interaction.status}`);
  console.log(`Service tier: ${interaction.service_tier}`);
  return interaction.id ?? "";
}

await createDeferredInteraction("PROJECT_ID");

出力は次のようになります。

Interaction ID: v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0
Status: queued
Service tier: deferred

Python

from google import genai

def create_deferred_interaction(project_id: str) -> str:
    client = genai.Client(
        enterprise=True,
        project=project_id,
        location="global",
    )

    interaction = client.interactions.create(
        model="gemini-4-argon",
        input=(
            "In two sentences, explain how a circuit breaker differs from "
            "exponential backoff in a distributed microservice architecture."
        ),
        service_tier="deferred",
        background=True,
        store=True,
    )

    print(f"Interaction ID: {interaction.id}")
    print(f"Status: {interaction.status}")
    print(f"Service tier: {interaction.service_tier}")
    return interaction.id or ""

create_deferred_interaction("PROJECT_ID")

出力は次のようになります。

Interaction ID: v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0
Status: queued
Service tier: deferred

ステータスをポーリングしてトークンの使用状況を取得する

status が queued または in_progress の間、バックオフを使用して interactions.get をポーリングします。ターンが最終ステータスに達したら、output_text と usage を読み取ります。

遅延ティアは、クレジットに裏付けられたレイテンシ SLA なしで、24 時間以内に 95% のターンを完了することを目標としています。次の表に、Interaction リソースの status 値を示します。

ステータス 最終版 意味と次の手順
queued × 承認済みで、容量を待機しています。バックオフを使用して interactions.get をポーリングします。stream=true はまだリクエストしないでください。
in_progress × 実行中。interactions.get のポーリングを続けるか、stream=true で SSE ストリームをアタッチします。
requires_action ○ モデルが出力した function_call ステップでターンが終了しました。ツールを実行し、previous_interaction_id を使用して新しいターンを作成します。
requires_continuation ○ 長いデコードターンが、部分的な出力と continuation_token で停止しました。previous_interaction_id と continuation_token を再開し、input を省略して、max_output_tokens を引き上げます。
completed ○ ターンが終了しました。output_text と usage を読み取るか、次のターンで id を previous_interaction_id として渡します。
incomplete ○ ターンが max_output_tokens に達したときなど、早期に停止しました。部分的な steps と usage を確認します。
failed ○ ターンでランタイム エラーが発生したか、24 時間の完了期間を超過しました。API は expired ステータスを使用しません。error を確認してから、新しいリクエストを送信してください。
cancelled ○ interactions.cancel の呼び出しにより、ターンが完了する前に停止しました。

長いデコードターンが requires_continuation として終了した場合は、previous_interaction_id、continuation_token、background=true、store=true、service_tier="deferred" を指定して interactions.create を呼び出し、再開します。input を省略し、max_output_tokens をこれまでに生成されたトークンよりも大きく設定します。各最終ステータスの課金方法については、料金と請求をご覧ください。

サンプルを実行する前に、次のように置き換えます。

  • PROJECT_ID: Google Cloud プロジェクト ID(my-agent-project など)。
  • INTERACTION_ID: 遅延モデル呼び出しの作成時に返されたインタラクション ID(v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0 など)。

REST

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: Google Cloud プロジェクト ID(my-agent-project など)。
  • INTERACTION_ID: 遅延モデル呼び出しの作成時に返されたインタラクション ID(v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0 など)。

HTTP メソッドと URL:

GET https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID

リクエストを送信するには、次のいずれかのオプションを展開します。

レスポンスは、次のような JSON ペイロードを返します。

{
  "id": "v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0",
  "model": "gemini-4-argon",
  "status": "completed",
  "service_tier": "deferred",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Exponential backoff increases the wait time between retries to give a struggling service time to recover. A circuit breaker stops sending requests once failures pass a threshold, failing fast until the downstream service is healthy again."
        }
      ]
    }
  ],
  "usage": {
    "total_input_tokens": 27,
    "total_output_tokens": 41,
    "total_tokens": 68
  }
}

Node.js

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

const PENDING_STATES = new Set(["queued", "in_progress"]);
const MAX_DELAY_MS = 30000;
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function waitForDeferredInteraction(projectId, interactionId) {
  const ai = new GoogleGenAI({
    enterprise: true,
    project: projectId,
    location: "global",
  });

  let delayMs = 5000;
  let current = await ai.interactions.get(interactionId);

  while (PENDING_STATES.has(current.status)) {
    await sleep(delayMs);
    delayMs = Math.min(delayMs * 2, MAX_DELAY_MS);
    current = await ai.interactions.get(interactionId);
  }

  console.log(`Status: ${current.status}`);
  if (current.status === "failed") {
    throw new Error(`Deferred turn failed: ${JSON.stringify(current.error)}`);
  }
  if (current.output_text) {
    console.log(current.output_text);
  }
  if (current.usage) {
    console.log(`Input tokens: ${current.usage.total_input_tokens}`);
    console.log(`Output tokens: ${current.usage.total_output_tokens}`);
    console.log(`Total tokens: ${current.usage.total_tokens}`);
  }
  return current.output_text ?? "";
}

await waitForDeferredInteraction(
  "PROJECT_ID",
  "INTERACTION_ID",
);

出力は次のようになります。

Status: completed
Exponential backoff increases the wait time between retries to give a struggling service time to recover. A circuit breaker stops sending requests once failures pass a threshold, failing fast until the downstream service is healthy again.
Input tokens: 27
Output tokens: 41
Total tokens: 68

Python

import time
from google import genai

PENDING_STATES = frozenset({"queued", "in_progress"})
MAX_DELAY_SECONDS = 30.0

def wait_for_deferred_interaction(
    project_id: str,
    interaction_id: str,
) -> str:
    client = genai.Client(
        enterprise=True,
        project=project_id,
        location="global",
    )

    delay_seconds = 5.0
    current = client.interactions.get(interaction_id)

    while current.status in PENDING_STATES:
        time.sleep(delay_seconds)
        delay_seconds = min(delay_seconds * 2.0, MAX_DELAY_SECONDS)
        current = client.interactions.get(interaction_id)

    print(f"Status: {current.status}")
    if current.status == "failed":
        raise RuntimeError(f"Deferred turn failed: {current.error}")
    if current.output_text:
        print(current.output_text)
    if current.usage:
        print(f"Input tokens: {current.usage.total_input_tokens}")
        print(f"Output tokens: {current.usage.total_output_tokens}")
        print(f"Total tokens: {current.usage.total_tokens}")
    return current.output_text or ""

wait_for_deferred_interaction(
    "PROJECT_ID",
    "INTERACTION_ID",
)

出力は次のようになります。

Status: completed
Exponential backoff increases the wait time between retries to give a struggling service time to recover. A circuit breaker stops sending requests once failures pass a threshold, failing fast until the downstream service is healthy again.
Input tokens: 27
Output tokens: 41
Total tokens: 68

省略可: 呼び出しの実行中に出力をストリーミングする

interactions.get が status="in_progress" を報告したら、stream=true を使用してサーバー送信イベント(SSE)ストリームをアタッチし、last_event_id を使用して切断された接続を再開できます。

REST

interactions.get URL に ?stream=true を追加します。再接続する場合は、&last_event_id=EVENT_ID も追加し、EVENT_ID を最後に受信したイベント ID に置き換えます。

Node.js

await ai.interactions.get(interactionId, { stream: true, last_event_id: lastEventId }) を反復処理し、event.event_id を記録して、step.delta イベントで event.delta?.text を読み取ります。

Python

client.interactions.get(interaction_id, stream=True, last_event_id=last_event_id) を反復処理し、event.event_id を記録して、step.delta イベントで event.delta.text を読み取ります。

SSE ストリーミングと再接続の詳細については、Interactions API デベロッパー ガイドをご覧ください。

マルチターン遅延ワークフローをチェーンする

マルチターン会話を続行するか、previous_interaction_id で completed または requires_action のインタラクションの id を渡して、ツールの実行結果を返します。tools、system_instruction、generation_config などのターン スコープのフィールドは自動的に引き継がれないため、必要なターンごとに渡します。チェーンされたターンは暗黙的なコンテキスト キャッシュの対象となりますが、キャッシュに保存されたプレフィックスは、数時間のキュー待機中に期限切れになる可能性があります。tool-result ステップのスキーマについては、Interactions API デベロッパー ガイドをご覧ください。

サンプルを実行する前に、次のように置き換えます。

  • PROJECT_ID: Google Cloud プロジェクト ID(my-agent-project など)。
  • PREVIOUS_INTERACTION_ID: 前の completed または requires_action ターンの ID(v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0 など)。

REST

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: Google Cloud プロジェクト ID(my-agent-project など)。
  • PREVIOUS_INTERACTION_ID: 前のターンの完了したインタラクション ID またはアクションが必要なインタラクション ID(v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0 など)。

HTTP メソッドと URL:

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions

リクエストの本文(JSON):

{
  "model": "gemini-4-argon",
  "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
  "input": "Draft a one-paragraph rollout checklist for adding a circuit breaker to a payment gateway client without causing false trips.",
  "service_tier": "deferred",
  "background": true,
  "store": true
}

リクエストを送信するには、次のいずれかのオプションを展開します。

レスポンスは、次のような JSON ペイロードを返します。

{
  "id": "v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0",
  "model": "gemini-4-argon",
  "previous_interaction_id": "v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0",
  "status": "queued",
  "service_tier": "deferred",
  "steps": []
}

Node.js

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

const ai = new GoogleGenAI({
  enterprise: true,
  project: "PROJECT_ID",
  location: "global",
});

const followUp = await ai.interactions.create({
  model: "gemini-4-argon",
  previous_interaction_id: "PREVIOUS_INTERACTION_ID",
  input:
    "Draft a one-paragraph rollout checklist for adding a circuit breaker to a payment gateway client without causing false trips.",
  service_tier: "deferred",
  background: true,
  store: true,
});

console.log(`Follow-up ID: ${followUp.id} (${followUp.status})`);

出力は次のようになります。

Follow-up ID: v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0 (queued)

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

follow_up = client.interactions.create(
    model="gemini-4-argon",
    previous_interaction_id="PREVIOUS_INTERACTION_ID",
    input=(
        "Draft a one-paragraph rollout checklist for adding a circuit "
        "breaker to a payment gateway client without causing false trips."
    ),
    service_tier="deferred",
    background=True,
    store=True,
)

print(f"Follow-up ID: {follow_up.id} ({follow_up.status})")

出力は次のようになります。

Follow-up ID: v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0 (queued)

遅延モデル呼び出しをキャンセルする

status が queued または in_progress の遅延インタラクションを停止するには、interactions.cancel を呼び出します。他のステータスのインタラクションで interactions.cancel を呼び出すと、HTTP 409("code": "aborted")が返されます。キャンセルが請求に与える影響については、料金と請求をご覧ください。

サンプルを実行する前に、次のように置き換えます。

  • PROJECT_ID: Google Cloud プロジェクト ID(my-agent-project など)。
  • INTERACTION_ID: queued または in_progress インタラクションの ID(v1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ など)。

REST

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: Google Cloud プロジェクト ID(my-agent-project など)。
  • INTERACTION_ID: キャンセルするキューに格納されたインタラクションまたは進行中のインタラクションの ID(例: v1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ)。

HTTP メソッドと URL:

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID/cancel

リクエストを送信するには、次のいずれかのオプションを展開します。

レスポンスは、次のような JSON ペイロードを返します。

{
  "id": "v1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ",
  "model": "gemini-4-argon",
  "status": "cancelled",
  "service_tier": "deferred"
}

Node.js

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

const ai = new GoogleGenAI({
  enterprise: true,
  project: "PROJECT_ID",
  location: "global",
});

const cancelled = await ai.interactions.cancel("INTERACTION_ID");
console.log(`Status: ${cancelled.status}`);

次のような出力が表示されます。

Status: cancelled

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

cancelled = client.interactions.cancel("INTERACTION_ID")
print(f"Status: {cancelled.status}")

次のような出力が表示されます。

Status: cancelled

料金、割り当て、セキュリティ管理

Deferred ティアで本番環境ワークロードを実行する前に、課金ルール、割り当て、ペイロードの上限、セキュリティ管理を確認してください。

料金と課金

遅延モデル呼び出しは、入力トークン、出力トークン、思考トークンの標準の従量課金制料金と比較して 50% 割引で課金されます。請求には次のルールが適用されます。

  • 割引の併用: 遅延割引は、契約割引と暗黙的なコンテキスト キャッシュ トークン割引と併用され、キャッシュされたレートに適用されます。
  • 標準料金へのフォールバックなし: 遅延リクエストが Standard PayGo にスピルオーバーまたはダウングレードされることはないため、割引なしのオンデマンド料金で請求されることはありません。
  • モデル呼び出しごとの課金: ターンで行われるモデル呼び出しごとに課金されます。completed、incomplete、requires_action、requires_continuation で終了するターンは、遅延レートで課金されます。
  • キャンセルされたターン: queued の間にキャンセルしたターンは課金されません。in_progress の状態でターンをキャンセルすると、すでに開始されているモデル呼び出し(生成中に中断された呼び出しを含む)が課金されます。
  • 失敗したターン: failed で終了する単一呼び出しターン(24 時間の完了ウィンドウを超えるターンを含む)は課金されません。マルチステップのサーバーサイド ツールループでは、失敗前に完了したモデル呼び出しは課金されますが、失敗した呼び出しは課金されません。
  • チェーンターン: previous_interaction_id チェーンの各ターンは個別に課金されます。後のターンをキャンセルしたり、後のターンが失敗したりしても、前のターンの料金は変更されません。

モデルごとのトークンレートについては、Agent Platform の料金ページをご覧ください。

割り当て、ペイロードの上限、保持

遅延ティアには、独自のモデル呼び出し割り当てはありません。遅延呼び出しは、Flex 従量課金制の割り当て(flex_requests_per_minute_per_project_per_base_model、3,000 RPM)を共有します。この割り当ては、interactions.create が queued を返した後の各モデル呼び出しで確認されます。主なプロジェクトの割り当てとシステム上限は次のとおりです。

  • 作成と同時実行の割り当て: 作成時に stateful_genai_interaction_creations の場合は最大 100 RPM または無制限。割り当てティアに応じて最大 500 concurrent_interaction_generations。
  • 1 日あたりのステートフル スループット(固定): プロジェクトごとに 1 日あたり 240 GiB の書き込みと 480 GiB の読み取り。
  • ペイロードと保持の上限: interactions.create 呼び出しあたり最大 9.75 MiB の非圧縮 HTTP 本文、7 日間の状態保持。チェーンは、最大 100 個の異なる Cloud Storage(gs://)URI をサポートします。

割り当てテーブルとコンソールの手順の詳細については、遅延ティアの割り当てと上限をご覧ください。

セキュリティとコンプライアンスの管理

遅延階層は global エンドポイントで状態をキューに格納して保持するため、サポートされているガバナンス管理がコンプライアンス要件に一致していることを確認します。

  • サポートされているコントロール: VPC Service Controls(VPC-SC。境界内では外部の mcp_server ツールは許可されません)、アクセスの透明性(AXT)、Cloud Audit Logs、FedRAMP High。
  • サポートされていないコントロール: ステートレス ゼロデータの保持(store=false と constraints/vertexai.disableAPIStorage の適用はどちらも "code": "invalid_request" で HTTP 400 を返します)、顧客管理の暗号鍵(CMEK)、データ所在地、DoD IL5、ITAR。

機能の一覧については、生成 AI のセキュリティ管理をご覧ください。

トラブルシューティング

次の表に、遅延ティアの一般的なエラーとその解決方法を示します。

エラーまたはステータス 一般的な原因 解決策
400(error.code: "invalid_request"、エンドポイント、フラグ、モデル) global 以外のエンドポイント、サポートされていないモデル、または interactions.create の無効な background、store、stream フラグ。 サポートされているモデルで locations/global をターゲットに設定し、background=true と store=true を設定して、stream=true を省略します。
400(error.code: "invalid_request"、ペイロード、URI、ツール) 非圧縮の本文が 9.75 MiB を超えている、チェーンが 100 個の gs:// URI を超えている、または VPC-SC 内の外部 mcp_server ツール。 サイズの大きいファイルを gs:// URI として渡し(チェーンあたり最大 100 個)、VPC-SC 内の外部 mcp_server ツールを省略します。
400(interactions.create: error.code: "invalid_request"、interactions.delete: status: "FAILED_PRECONDITION")
  • constraints/vertexai.disableAPIStorage ポリシーが適用されます。
  • interactions.create は queued または in_progress のターンにチェーンするか、requires_continuation に input を設定します。
  • interactions.delete は queued または in_progress のターンをターゲットにします。
  • API 状態の永続化を許可するプロジェクトを使用します。
  • 最後のターンにのみチェーンします。requires_continuation で、continuation_token を渡し、input を省略します。
  • 有効なターンを削除する前にキャンセルしてください。
401(status: "UNAUTHENTICATED" または error.code: "authentication") gcloud CLI 認証情報(REST サンプル)または ADC(Google Gen AI SDK サンプル)がないか、期限切れになっています。 REST サンプルの場合は、gcloud auth login を実行します。Google Gen AI SDK のサンプルの場合は、gcloud auth application-default login を実行します。その後、リクエストを再試行します。
403(status: "PERMISSION_DENIED" または error.code: "permission_denied")
  • 呼び出し元に roles/aiplatform.user がない。
  • 呼び出し元に gs:// 入力に対する storage.objects.get がありません。
roles/aiplatform.user を付与します。Cloud Storage 入力の場合は、roles/storage.objectViewer も付与します。
404(error.code: "not_found"、interactions.deleteにstatus: "NOT_FOUND") インタラクションまたは previous_interaction_id が存在しないか、削除されています。また、global 以外のエンドポイントに属しているか、7 日間の保持期間を過ぎている可能性があります。 global エンドポイントでインタラクション ID を確認します。親ターンが期限切れになった場合は、previous_interaction_id なしで新しいチェーンを開始します。
409(error.code: "aborted") interactions.cancel は、すでに最終ステータス(requires_action、requires_continuation、completed、incomplete、failed、cancelled)になっているインタラクションをターゲットにしています。 まず、interactions.get で status を確認します。キャンセルできるのは、queued と in_progress のインタラクションのみです。
429(error.code: "too_many_requests") プロジェクトが、インタラクション作成率、同時インタラクション生成数、1 日のステートフル スループットなど、プロジェクトごとの割り当てを超えています。
  • Retry-After ヘッダーの遅延後に、バックオフとジッターを使用して再試行します。
  • 遅延ティアの割り当てと上限で、調整可能な割り当ての増加をリクエストします。1 日あたりのスループットの上限は固定されています。
status="failed"
  • アップストリーム モデルまたはツールの障害が発生したか、ターンが 24 時間の完了ウィンドウを超えました。
  • リクエストで *-cyber* モデルが使用されているが、プロジェクトに許可リストへのアクセス権がない。
  • interactions.get が返す error フィールドを調べて、新しい interactions.create リクエストを送信します。
  • Cyber モデルの場合は、 Google Cloud アカウント チームに許可リストへのアクセス権を確認してください。

次のステップ

非同期およびステートフルな Gemini ワークロードに関連するガイドとリファレンス ドキュメントを確認する。