Skip to content

实时智能体支持的模型

Supported in ADKPython v0.1.0

实时智能体需要一个能够维持双向连接的模型；标准的 Gemini 模型无法做到。关于 ADK 在实时智能体之外支持的模型，以及非 Gemini 提供商，请参阅智能体模型。

实时模型

实时智能体运行在能够端到端接收音频输入并产生音频输出的模型上，中间没有文本转语音的阶段。这正是它们能够以自然韵律产生类人语音的原因，也是标准 Gemini 模型在双向连接上无法做到的。

同一个模型在每个后端上有不同的 ID：

模型 AI Studio Agent Platform
Gemini 2.5 Flash Live gemini-2.5-flash-native-audio-preview-12-2025 gemini-live-2.5-flash-native-audio

gemini-live-2.5-flash-native-audio 是 ADK 的 LlmAgent.DEFAULT_LIVE_MODEL，也是本节示例中使用的模型。

选择后端

实时模型通过两个后端之一来访问。ADK 使用相同的代码与两个后端通信；你通过环境变量进行切换，因此可以在一个后端上开发，在另一个后端上部署。

AI Studio Agent Platform
全称 Google AI Studio Gemini Enterprise Agent Platform
最适合 原型开发、开发测试 生产环境、企业级
认证 API key (GOOGLE_API_KEY) 云凭据 (GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION)
设置 仅需 API key 云项目设置
限制 会话时长和并发数 会话时长和并发数

通过 GOOGLE_GENAI_USE_ENTERPRISE 环境变量进行切换（FALSE 表示 AI Studio，TRUE 表示 Agent Platform）；无需修改代码。请参阅快速开始进行设置。

Agent Platform：确认位置可用性

Agent Platform 上实时模型的可用性因位置而异。在部署之前，请检查你的 GOOGLE_CLOUD_LOCATION 是否在 Agent Platform 位置 的端点位置表中；使用 us-central1、us-east1 或 asia-northeast1 等区域端点是安全的默认选择。

这些模型直接生成音频，具有自然韵律，并且能够自动检测对话语言。你在此基础上配置的内容——语音、转录、轮次检测——在配置中有描述。

有一个属性在模型级别固定：实时模型仅生成音频。它们不支持 TEXT 响应模态，因此要在语音的同时获取文本，你需要使用音频转录。

各模型的功能支持

一些 RunConfig 设置取决于你运行的是哪个模型：

功能 gemini-live-2.5-flash-native-audio
主动性和情感对话 通过 RunConfig 可选启用
工具上的 response_scheduling 支持

平台限制和配额

两个后端都对连接和会话的运行时长以及同时运行的会话数量进行了限制。这些数字会变化，因此请以官方文档为准，并在生产环境中依赖某个限制之前进行验证。

限制 AI Studio Agent Platform
会话时长，仅音频 15 分钟 15 分钟
会话时长，音频 + 视频 2 分钟 2 分钟
连接生命周期 约 10 分钟 约 10 分钟
并发会话数 参见速率限制 按量付费每个项目最多 1,000 个；使用 Provisioned Throughput 无限制

Agent Platform 默认还将对话会话限制在 10 分钟，这与上述仅音频的限制是分开的。

启用上下文窗口压缩可以让会话时长超过限制。在 Agent Platform 上，可以通过 Cloud Console 配额页面 中的 "Bidi generate content concurrent requests" 请求增加并发会话数。请根据 AI Studio、Gemini API 速率限制 和 Agent Platform 的文档验证当前的数字。

如何处理模型名称

从环境变量读取模型名称，而不是硬编码。同一个模型在 AI Studio 和 Agent Platform 上有不同的 ID，因此 .env 变量可以让一个代码库同时支持两个后端，并且可以隔离模型弃用的影响。

推荐模式：

import os
from google.adk.agents import Agent

# 使用环境变量，并设置合理的默认值作为回退
agent = Agent(
    name="my_agent",
    model=os.getenv("DEMO_AGENT_MODEL", "gemini-live-2.5-flash-native-audio"),
    tools=[...],
    instruction="..."
)

为什么使用环境变量：

  • 后端特定的 ID：同一个模型在 AI Studio 和 Agent Platform 上的名称不同，因此在它们之间切换意味着要更改模型 ID。使用环境变量可以将此信息从代码中剥离
  • 模型可用性变化：模型会定期发布和弃用。一年前编写的实时智能体不应在代码中绑定到一个已经不存在的模型
  • 环境特定的配置：为开发、预发布和生产环境使用不同的模型

在 .env 文件中配置：

# AI Studio
DEMO_AGENT_MODEL=gemini-2.5-flash-native-audio-preview-12-2025

# Agent Platform
# DEMO_AGENT_MODEL=gemini-live-2.5-flash-native-audio

环境变量加载顺序

使用 python-dotenv 的 .env 文件时，你必须在导入任何读取环境变量的模块之前调用 load_dotenv()。否则，os.getenv() 将返回 None 并回退到默认值，忽略你的 .env 配置。

main.py 中的正确顺序：

from dotenv import load_dotenv
from pathlib import Path

# 在导入智能体之前加载 .env 文件
load_dotenv(Path(__file__).parent / ".env")

# 现在可以安全地导入使用环境变量的模块
from google_search_agent.agent import agent

错误顺序（不会生效）：

from dotenv import load_dotenv
from google_search_agent.agent import agent  # 智能体在此处读取环境变量

# 太晚了！智能体已经使用默认模型初始化
load_dotenv(Path(__file__).parent / ".env")

这是 Python 的导入行为：当你导入一个模块时，其顶层代码会立即执行。如果你的智能体模块在导入时调用了 os.getenv("DEMO_AGENT_MODEL")，那么 .env 文件必须已经加载。

选择合适的模型：

  1. 选择后端：AI Studio 用于原型开发，Agent Platform 用于生产环境。这决定了上表中的 ID 列
  2. 检查当前可用性：参考上方的模型表格和官方文档
  3. 配置环境变量：在 .env 文件中设置模型名称，并在构建智能体时从中读取

模型兼容性和可用性

有关模型兼容性和可用性的最新信息：

在部署到生产环境之前，请务必在官方文档中验证模型可用性和功能支持情况。