自主智能体调度

在部署多步骤 Agentic Workflows(例如大规模文档合成和长时间运行的研究)时,在实时模型上运行后台智能体可能会造成不必要的基础设施压力,并触发资源耗尽 (429) 错误。

Gemini Enterprise Agent Platform 提供延迟层级,这是一种专为可容忍延迟的工作负载设计的吞吐量优化调度器。调度器不会像处理实时聊天查询那样,以相同的紧急程度处理长时间运行的自主任务,而是会将复杂的多步骤 Agentic Workflows 排入队列,在非高峰时段执行,以实现高成功率和整体吞吐量。

当您使用延迟层级提交请求时,API 会异步接受任务并立即返回互动 ID。推迟层级具有以下特点:

  • 折扣费率:与标准请求相比,模型推理价格可享受 50% 的折扣,因此您可以在生产环境中管理代理费用。如需了解详情,请参阅价格。

  • 更高的吞吐量:延迟层级通过将繁重的异步工作负载移至非高峰时段,缓解了 429 错误(模型容量限制)和速率限制,从而释放标准层级配额,满足实时生产需求。

  • 完成超时:延迟层级旨在 24 小时内完成 95% 的任务。如果任务未在此时间段内完成,则会过期并转换为 failed 状态。在队列中花费的实际时间取决于当前的区域集群容量和需求。

使用场景

延迟层级非常适合可以容忍数小时周转时间的用例,例如以下示例:

  • 金融:每日或每周股权和市场研究。

  • 法律和合规:多文档监管以及并购尽职调查。

  • 策略:持续进行竞争情报分析和趋势综合。

  • 安全性:代码库漏洞扫描和修复。

支持的智能体

您可以为以下代理配置自主代理调度。选择一个代理以跳转到其设置说明:

如需直接在 Gemini 模型上运行自定义或第三方智能体循环,请参阅使用延迟层级。

安排 ADK 智能体

在 ADK 中,您可以在每次调用时在 RunConfig 上设置 service_tier 参数,而不是在智能体或模型上配置固定层级。设置 service_tier=ServiceTier.DEFERRED 会将每个模型调用排入非高峰期容量池,而默认的 ServiceTier.STANDARD 会同步运行。通过此单次运行设置,一个智能体定义可以同时处理交互式请求和离线批量工作流。

当您为 ADK 智能体发送延迟请求时,ADK 会自动为您执行后台提交、轮询和检索:

  1. ADK 在启用后台执行的情况下提交模型请求,后端返回一个状态为 queued 或 in_progress 的互动 ID。
  2. 当互动仍处于待处理状态时,ADK 会使用指数退避算法算法轮询后端。
  3. 当互动达到最终状态时,ADK 会将已完成的互动转换为标准模型回答事件,您可以通过运行程序接口使用这些事件。

本部分介绍了调度 ADK 代理的以下任务:

如需详细了解 ADK 中的 ServiceTier 配置,请参阅 ADK 文档中的延迟调度。

ADK 代理的限制

在延迟层级上安排 ADK 代理时,请考虑以下要求和限制:

  • 需要 Interactions API:服务层级仅适用于为 Interactions API 配置的模型,例如 Gemini(use_interactions_api=True)。标准内容生成模型和 ManagedAgent 会忽略 service_tier。
  • 与令牌流式传输不兼容:延迟执行无法与 RunConfig 中的 StreamingMode.SSE 结合使用。调用 /run_sse 时,请省略 streaming 或设置 "streaming": false。传递 "streaming": true 和 "service_tier": "deferred" 会返回 HTTP 422 Unprocessable Entity。
  • HTTP 连接限制:在 adk api_server、/run 和 /run_sse 上,在队列等待期间保持 HTTP 连接处于打开状态。如果代理或平台超时导致连接关闭(例如 Cloud Run 的 60 分钟限制),客户端轮询就会停止。后端交互仍会运行至完成并产生费用。
  • 每轮队列延迟时间:在多轮或工具调用工作流中,每个模型轮次都会提交单独的交互请求。每次轮到时,都会产生自己的非高峰期队列等待。
  • 重启后无法恢复正在进行的互动:ADK 不会在会话存储中持久保存正在进行的互动 ID,也不会重新连接到已断开连接的互动。停止客户端进程会放弃待处理的轮询循环,后续调用会启动新的交互。

在延迟层级上运行 ADK 智能体

如需在延迟层级上安排 ADK 智能体,请使用 use_interactions_api=True 配置 Gemini 模型,并在调用运行程序时传递 RunConfig(service_tier=ServiceTier.DEFERRED):

import asyncio

from google.adk.agents import LlmAgent
from google.adk.agents import RunConfig
from google.adk.apps import App
from google.adk.models import ServiceTier
from google.adk.models.google_llm import Gemini
from google.adk.runners import InMemoryRunner
from google.genai import types

root_agent = LlmAgent(
    name="batch_agent",
    model=Gemini(
        model="gemini-3.5-flash",
        use_interactions_api=True,
        client_kwargs={
            "enterprise": True,
            "project": "PROJECT_ID",
            "location": "global",
        },
    ),
    instruction="Process input documents and produce summaries.",
)

app = App(
    name="batch_app",
    root_agent=root_agent,
)

runner = InMemoryRunner(app=app)


async def main() -> None:
  session = await runner.session_service.create_session(
      app_name=app.name,
      user_id="user_123",
      session_id="session_456",
  )

  run_config = RunConfig(service_tier=ServiceTier.DEFERRED)

  async for event in runner.run_async(
      user_id="user_123",
      session_id=session.id,
      new_message=types.Content(
          role="user",
          parts=[
              types.Part.from_text(
                  text="Summarize quarterly performance metrics."
              )
          ],
      ),
      run_config=run_config,
  ):
    if event.content and event.content.parts:
      for part in event.content.parts:
        if part.text:
          print(part.text)


asyncio.run(main())

请将 PROJECT_ID 替换为您的 Google Cloud 项目 ID。

当互动状态为 queued 或 in_progress 时,runner.run_async() 在互动完成之前不会产生任何事件。通过在应用日志中检查以下消息,验证延迟层级是否处于活跃状态:

  • 在 INFO 级别,互动传输会记录 Interaction INTERACTION_ID is queued; waiting for the result. 和 Interaction INTERACTION_ID reached status completed.。启用调试日志记录后,请求处理器还会记录 Using service_tier from run_config: ServiceTier.DEFERRED。
  • 如果模型未设置 use_interactions_api=True,ADK 会忽略 service_tier,继续进行标准生成,并记录一条警告,指出模型未使用 Interactions API。

部署延迟的 ADK 代理

您需要针对每个请求配置 service_tier,而不是在智能体定义中进行配置,因此一个 ADK 智能体软件包 (use_interactions_api=True) 可以同时处理实时和延迟工作负载。您可以将此软件包部署到 Agent Runtime、Cloud Run 或 GKE。

下表比较了延迟 ADK 工作负载的部署选项:

部署选项 何时使用 执行模型 最长超时时间 如何申请延期层级
Agent Runtime 异步后台作业,其中 Agent Platform 管理会话、在不保持 HTTP 连接打开的情况下运行,并将结果直接写入 Cloud Storage 托管式后台作业 (run_query_job) 168 小时(7 天;每个模型轮次 24 小时) input 内的 "run_config": {"service_tier": "deferred"}
Cloud Run 服务 无服务器 HTTPS 端点,可处理交互式请求和在 60 分钟内完成的延迟工作负载 无服务器 HTTP 或 SSE (adk deploy cloud_run) 60 分钟(3,600 秒) /run 或 /run_sse(带有 "streaming": false)请求正文中的 "service_tier": "deferred"
Cloud Run 作业 没有 HTTP 连接的无服务器批处理工作负载,可能需要等待超过 60 分钟(每个模型轮次最多 24 小时) 无服务器批处理容器 (gcloud run jobs) 168 小时(7 天) RunConfig(service_tier=ServiceTier.DEFERRED)
GKE 需要自定义网络、Pod 生命周期控制或无服务器请求超时限制的 Kubernetes 工作负载 Kubernetes Pod (adk deploy gke) 无限制(已配置 Pod 和入站流量) /run 或 /run_sse(带有 "streaming": false)请求正文中的 "service_tier": "deferred"

如果您的模型使用 global 端点,而您的部署在区域端点(例如 us-central1)中运行,请将 client_kwargs={"location": "global"} 传递给 Gemini(...)。确保您的运行时服务账号在您的项目中具有 Agent Platform User (roles/aiplatform.user) 角色。

选择部署目标以查看配置说明:

Agent Runtime

将智能体部署到 Agent Runtime 时,请设置 agent_framework="google-adk" 并在 requirements 中添加 google-adk>=2.10.0。向推理引擎服务代理 (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.) 授予输出存储桶的 Storage Object Creator (roles/storage.objectCreator) 角色。

如需提交异步延迟长时间运行的查询作业,请调用 client.runtimes.run_query_job() 并在 input 中传递 "run_config": {"service_tier": "deferred"}:

import json
import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
)

job = client.runtimes.run_query_job(
    name=(
        "projects/PROJECT_ID"
        "/locations/LOCATION"
        "/reasoningEngines/RESOURCE_ID"
    ),
    config={
        "query": json.dumps({
            "class_method": "async_stream_query",
            "input": {
                "user_id": "USER_ID",
                "session_id": "SESSION_ID",
                "message": "Summarize quarterly performance metrics.",
                "run_config": {"service_tier": "deferred"},
            },
        }),
        "output_gcs_uri": (
            "gs://BUCKET_NAME"
            "/OUTPUT_FILE.jsonl"
        ),
    },
)

替换以下内容:

  • PROJECT_ID:您的 Google Cloud 项目 ID。
  • LOCATION:部署代理的受支持区域,例如 us-central1。
  • RESOURCE_ID:已部署的 reasoningEngine 资源的数字 ID。
  • USER_ID 和 SESSION_ID:调用的用户和会话标识符。
  • BUCKET_NAME 和 OUTPUT_FILE:Cloud Storage 存储桶和对象前缀,Agent Runtime 会将流式事件作为以换行符分隔的 JSON(application/x-ndjson,每行一个 JSON 对象)写入其中。

Cloud Run

根据预期队列时长配置 Cloud Run 服务或 Cloud Run 作业:

  • Cloud Run 服务 (adk deploy cloud_run):在 HTTPS 端点(/run 和 /run_sse)后部署 adk api_server。在部署时传递 -- --timeout=3600,以便 Cloud Run 在默认的 5 分钟超时后不会关闭 HTTP 连接:

    adk deploy cloud_run \
      --project=PROJECT_ID \
      --region=LOCATION \
      --service_name=SERVICE_NAME \
      AGENT_DIR \
      -- --no-allow-unauthenticated --timeout=3600
    

    替换以下内容:

    • PROJECT_ID:您的 Google Cloud 项目 ID。
    • LOCATION:Cloud Run 区域,例如 us-central1。
    • SERVICE_NAME:您的 Cloud Run 服务名称。
    • AGENT_DIR:智能体源目录的路径。

    在调用 /run 或 /run_sse 之前,请使用 POST /apps/APP_NAME/users/USER_ID/sessions 创建会话,其中 APP_NAME 默认为您的智能体目录名称。如需请求延迟执行,请在 JSON 请求正文中添加 "service_tier": "deferred" 作为顶级字段。调用 /run_sse 时,省略 streaming 或设置 "streaming": false(传递 "streaming": true 会返回 HTTP 422 Unprocessable Entity):

    {
      "app_name": "batch_app",
      "user_id": "user_123",
      "session_id": "session_456",
      "new_message": {
        "role": "user",
        "parts": [{"text": "Summarize batch results."}]
      },
      "service_tier": "deferred",
      "streaming": false
    }
    
  • Cloud Run 作业 (gcloud run jobs deploy):运行容器直至完成,无需 HTTP 请求生命周期,并支持 --task-timeout 最长 168 小时(7 天)。在作业入口点中将 RunConfig(service_tier=ServiceTier.DEFERRED) 传递给 runner.run_async(),并使用 --task-timeout=86400s(24 小时)进行部署。

GKE

使用 adk deploy gke 打包 ADK 智能体并将其部署到 GKE 集群:

adk deploy gke \
  --project=PROJECT_ID \
  --region=LOCATION \
  --cluster_name=CLUSTER_NAME \
  --service_name=SERVICE_NAME \
  AGENT_DIR

替换以下内容:

  • PROJECT_ID:您的 Google Cloud 项目 ID。
  • LOCATION:区域级 GKE 集群所在的区域,例如 us-central1。
  • CLUSTER_NAME:GKE 集群的名称。
  • SERVICE_NAME:代理的 Kubernetes 服务名称。
  • AGENT_DIR:智能体源目录的路径。

在调用 /run 或 /run_sse 之前,请使用 POST /apps/APP_NAME/users/USER_ID/sessions 创建会话,其中 APP_NAME 默认为您的智能体目录名称。如需请求延迟执行,请在 JSON 请求正文中添加 "service_tier": "deferred" 作为顶级字段。调用 /run_sse 时,省略 streaming 或设置 "streaming": false(传递 "streaming": true 会返回 HTTP 422 Unprocessable Entity):

{
  "app_name": "batch_app",
  "user_id": "user_123",
  "session_id": "session_456",
  "new_message": {
    "role": "user",
    "parts": [{"text": "Summarize batch results."}]
  },
  "service_tier": "deferred",
  "streaming": false
}

在队列等待和模型执行期间,对 /run 和 /run_sse 的请求会使 HTTP 连接保持打开状态。增加 GKE Ingress 和负载均衡器后端超时,以适应预期的队列延迟。如果客户端连接关闭或超时,服务器会取消本地轮询。后端互动仍会运行并产生费用,但不会返回输出。

强制执行客户端截止期限

ADK 不会对队列等待应用客户端超时,而是依赖于后端的 24 小时完成超时。如需限制应用中的总等待时间,请将 runner.run_async() 封装在 asyncio.timeout() 中:

import asyncio
import logging

from google.adk.agents import RunConfig
from google.adk.models import ServiceTier
from google.genai import types

logger = logging.getLogger(__name__)


# Continues from the earlier example using existing runner and session objects:
async def run_with_deadline(runner, session) -> None:
  message = types.Content(
      role="user",
      parts=[
          types.Part.from_text(text="Generate quarterly financial summary.")
      ],
  )
  run_config = RunConfig(service_tier=ServiceTier.DEFERRED)

  try:
    async with asyncio.timeout(300):
      async for event in runner.run_async(
          user_id="user_123",
          session_id=session.id,
          new_message=message,
          run_config=run_config,
      ):
        if event.content and event.content.parts:
          for part in event.content.parts:
            if part.text:
              print(part.text)
  except TimeoutError:
    logger.error(
        "Client timeout exceeded after 300 seconds. The deferred interaction"
        " continues to run and incur billing on the backend, so its output"
        " cannot be retrieved."
    )

强制执行客户端超时会在下一个休眠间隔停止客户端轮询循环,但不会取消后端上的工作。即使在客户端超时后,互动也会继续运行,直到完成并在服务器上产生费用。

安排 Gemini Deep Research 智能体

使用 Interactions API 创建、监控、取消延迟的 Deep Research 任务,以及检索其结果。

创建延迟任务

以下示例展示了如何使用 client.interactions.create() 通过延迟层级启动 Deep Research 任务:

import time
from google import genai

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

PROMPT = "Analyze the latest market trends in renewable energy storage."
DEEP_RESEARCH_AGENT = "deep-research-preview-04-2026"

interaction = client.interactions.create(
    input=PROMPT,
    agent=DEEP_RESEARCH_AGENT,  # Agent identifier
    service_tier="deferred",  # Run on deferred tier for off-peak scheduling
    background=True,  # Return immediately instead of waiting for the answer
    store=True,  # Persist interaction state to poll or stream later
    stream=False,  # `stream` must be set to False during task creation
)

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

请将 PROJECT_ID 替换为您的 Google Cloud 项目 ID。

该方法会立即返回 status="queued" 或 status="in_progress" 以及 service_tier="deferred"。

监控任务进度

在等待非高峰期容量并主动运行时,互动 status 为 queued 或 in_progress。随着智能体执行规划、搜索和分析步骤,新项会附加到 steps 列表中。

您可以通过定期轮询互动或流式传输更新,以编程方式跟踪任务状态。

投票

定期(例如每 15-30 秒)轮询互动,直到互动达到以下任一最终状态:completed、failed、cancelled 或 incomplete。

TERMINAL_STATES = ("completed", "failed", "cancelled", "incomplete")
POLL_INTERVAL_SECONDS = 15
TIMEOUT_MINUTES = 60

started = time.time()
deadline = started + TIMEOUT_MINUTES * 60

while True:
  current = client.interactions.get(interaction.id)
  elapsed = int(time.time() - started)
  steps = getattr(current, "steps", None) or []
  print(f"[{elapsed:>4}s] status={current.status} steps={len(steps)}")

  if current.status in TERMINAL_STATES:
    break
  if time.time() >= deadline:
    raise TimeoutError(
        f"Still {current.status} after {TIMEOUT_MINUTES} min. The interaction "
        "continues running server-side; re-run the check to resume polling."
    )
  time.sleep(POLL_INTERVAL_SECONDS)

print(f"\nFinished in {int(time.time() - started)}s with status={current.status}.")

流式传输

您可以通过使用 stream=True 调用 client.interactions.get() 来订阅实时更新。互动进入 in_progress 状态后,数据流会在事件发生时推送事件,例如中间思考、文本增量和状态更新。

如果连接在任务仍处于 queued 或 in_progress 状态时断开,请使用 client.interactions.get() 和 stream=True 重新连接到数据流,并将上次收到的事件 ID 传递给 last_event_id。如果您省略 last_event_id,则 API 会从头开始重放每个事件。

INTERACTION_ID = interaction.id  # from the create step
MAX_RECONNECTS = 5
STREAM_TIMEOUT = 300  # seconds

print(
    f"streaming interaction: {INTERACTION_ID} (status={interaction.status})\n"
)

def render(event):
  """Prints one SSE event. Returns True once the interaction has finished."""
  if event.event_type == "step.delta":
    delta = event.delta
    if delta.type == "text":
      print(delta.text, end="", flush=True)
    elif delta.type == "thought_summary":
      summary = (getattr(delta.content, "text", "") or "").strip()
      if summary:
        print(f"\n[thinking] {summary[:200]}", flush=True)
    elif delta.type.endswith("_call"):
      queries = getattr(getattr(delta, "arguments", None), "queries", None)
      print(
          f"\n[{delta.type}] {', '.join(queries) if queries else ''}",
          flush=True,
      )
  elif event.event_type == "interaction.status_update":
    print(f"[status] {event.status}", flush=True)
  elif event.event_type == "interaction.completed":
    print(f"\n\n[status] {event.interaction.status}", flush=True)
    return True
  elif event.event_type == "error":
    print(f"\n[error] {event.error.message}", flush=True)
    return True
  return False

last_event_id = None
finished = False

for attempt in range(MAX_RECONNECTS):
  try:
    # stream=True turns the GET into a live subscription. last_event_id=None on
    # the first pass, so the server starts from the beginning of the run.
    for event in client.interactions.get(
        INTERACTION_ID,
        stream=True,
        last_event_id=last_event_id,
        timeout=STREAM_TIMEOUT,
    ):
      last_event_id = event.event_id or last_event_id
      finished = render(event) or finished
  except Exception as e:  # pylint: disable=broad-except
    # A dropped connection loses nothing: the run continues server-side and the
    # next iteration reattaches from last_event_id.
    print(f"\n[stream dropped: {type(e).__name__}] reattaching...", flush=True)

  if finished:
    break
  # The server also closes the stream when the run ends, without an error.
  if client.interactions.get(
      INTERACTION_ID, timeout=STREAM_TIMEOUT
  ).status not in ("queued", "in_progress"):
    break
else:
  print(f"\n[gave up after {MAX_RECONNECTS} reconnects]")

print(f"\n\nStreamed interaction: {INTERACTION_ID}")

取消任务

您可以在任务状态为 queued、in_progress 或 requires_action 时取消任务。取消任务后,其状态会转换为 cancelled。

如需取消任务,请使用 client.interactions.cancel():

client.interactions.cancel(interaction.id)

检索最终输出和 token 用量

当互动达到 completed 状态时,steps 列表中会显示完整转写内容。最终回答是最后一个 model_output 步骤的文本内容。

由于互动已存储 (store=True),因此您可以使用任何会话中的互动 ID 随时提取结果:

def get_final_text(completed_interaction):
  """Returns the text of the last model_output step."""
  for step in reversed(getattr(completed_interaction, "steps", None) or []):
    if getattr(step, "type", None) != "model_output":
      continue
    text = "".join(
        part.text
        for part in (getattr(step, "content", None) or [])
        if getattr(part, "text", None)
    )
    if text:
      return text
  return ""


final = client.interactions.get(interaction.id)
print(f"Status: {final.status}\n")
print(get_final_text(final) or "(No text output)")

if final.usage:
  print(
      f"\nToken usage:\n"
      f"  Input tokens:  {final.usage.total_input_tokens}\n"
      f"  Output tokens: {final.usage.total_output_tokens}\n"
      f"  Total tokens:  {final.usage.total_tokens}"
  )

后续步骤

探索有关异步模型调用、有状态互动和代管式研究智能体的相关指南: