在部署多步骤 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 会自动为您执行后台提交、轮询和检索:
- ADK 在启用后台执行的情况下提交模型请求,后端返回一个状态为
queued或in_progress的互动 ID。 - 当互动仍处于待处理状态时,ADK 会使用指数退避算法算法轮询后端。
- 当互动达到最终状态时,ADK 会将已完成的互动转换为标准模型回答事件,您可以通过运行程序接口使用这些事件。
本部分介绍了调度 ADK 代理的以下任务:
- 在启用延迟层级之前,请查看要求和限制。
- 使用
RunConfig(service_tier=ServiceTier.DEFERRED)在延迟层级上运行 ADK 智能体。 - 在 Agent Runtime、Cloud Run 或 Google Kubernetes Engine (GKE) 上部署延迟 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"会返回 HTTP422 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会返回 HTTP422 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}"
)
后续步骤
探索有关异步模型调用、有状态互动和代管式研究智能体的相关指南:
- 在使用延迟层级中,为自定义和第三方智能体运行异步模型调用。
- 在 Interactions API 概览中查看核心会话、工具和状态概念。
- 在使用 Gemini Deep Research 智能体中规划和整合多步研究工作流。