ADK 智能体的 Google Gemini 模型¶
ADK 支持 Google Gemini 系列生成式 AI 模型，这些模型提供了一系列功能强大的模型，具有广泛的功能。ADK 支持许多 Gemini 功能，包括代码执行、Google 搜索、上下文缓存、Computer USE以及 Interactions API。
入门¶
以下代码示例展示了在你的智能体中使用 Gemini 模型的基本实现：
import (
"google.golang.org/adk/agent/llmagent"
"google.golang.org/adk/model/gemini"
"google.golang.org/genai"
)
// --- Example using a stable Gemini Flash model ---
modelFlash, err := gemini.NewModel(ctx, "gemini-2.0-flash", &genai.ClientConfig{})
if err != nil {
log.Fatalf("failed to create model: %v", err)
}
agentGeminiFlash, err := llmagent.New(llmagent.Config{
// Use the latest stable Flash model identifier
Model: modelFlash,
Name: "gemini_flash_agent",
Instruction: "You are a fast and helpful Gemini assistant.",
// ... other agent parameters
})
if err != nil {
log.Fatalf("failed to create agent: %v", err)
}
import com.google.adk.kt.agents.Instruction
import com.google.adk.kt.agents.LlmAgent
import com.google.adk.kt.models.Gemini
// --- 示例：使用稳定的 Gemini Flash 模型 ---
val agentGeminiFlash = LlmAgent(
// 使用最新的稳定 Flash 模型标识符
name = "gemini_flash_agent",
model = Gemini(name = "gemini-flash-latest"),
instruction = Instruction("你是一个快速且得力的 Gemini 助手。"),
// ... 其他智能体参数
)
注意：Gemini 模型选择器 gemini-flash-latest
ADK 文档中的大多数代码示例使用 gemini-flash-latest 来选择最新可用的 Gemini Flash 版本。但是，如果你是从区域端点（如 us-central1）访问 Gemini，此选择字符串可能无法生效。在这种情况下，请使用 Gemini 模型页面或 Google Cloud Gemini 模型列表中的特定模型版本字符串。
本节介绍如何通过 Google AI Studio 进行快速开发，或通过 Google Cloud Vertex AI 进行企业级应用来对 Google 的 Gemini 模型进行身份验证。这是在 ADK 中使用 Google 旗舰模型的最直接方式。
本节介绍如何对 Google 的 Gemini 模型进行身份验证，可以通过 Google AI Studio 进行快速开发，也可以通过 Google Cloud Agent Platform 进行企业级应用。这是在 ADK 中使用 Google 旗舰模型的最直接方式。
提示
ADK 内部用于 Gemini 模型的 google-genai 库可以通过 Google AI Studio 或 Vertex AI 进行连接。
语音/视频流式处理的模型支持
为了在 ADK 中使用语音/视频流式处理，你需要使用支持 Live API 的 Gemini 模型。你可以在文档中找到支持 Gemini Live API 的模型 ID：
Google AI Studio¶
这是最简单的方法，建议用于快速入门。
- 身份验证方式： API 密钥
-
设置步骤：
- 获取 API 密钥： 从 Google AI Studio 获取你的密钥。
-
设置环境变量： 在项目的根目录中创建一个
.env文件 (Python) 或.properties文件 (Java)，并添加以下内容。ADK 会自动加载此文件。(或者) 在模型初始化期间通过
Client显式传递这些变量（请参见下面的示例）。
-
可用模型： 在 Google AI for Developers 网站上查看所有可用模型。
Google Cloud Vertex AI¶
Google Cloud Agent Platform¶
对于可扩展和生产场景，Agent Platform 是推荐的平台。Agent Platform 上的 Gemini 支持企业级功能、安全性和合规控制。根据你的开发环境和用例，选择以下身份验证方法之一。
前置条件： 一个已启用 Agent Platform 的 Google Cloud 项目。
- 安装 gcloud CLI： 遵循官方安装说明。
- 使用 ADC 登录： 此命令会打开浏览器对你的个人账号进行身份验证，适用于本地开发。
-
设置环境变量：
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" export GOOGLE_CLOUD_LOCATION="YOUR_VERTEX_AI_LOCATION" # 例如，us-central1明确告诉库使用 Agent Platform：
-
模型： 在 Agent Platform 文档 中查找可用的模型 ID。
方法 B: Agent Platform Express 模式¶
Agent Platform Express 模式提供了一种简化的、基于 API 密钥的设置，用于快速原型设计。
- 注册 Express 模式以获取你的 API 密钥。
- 设置环境变量：
方法 C: 服务账号 (用于生产环境和自动化)¶
对于已部署的任务应用程序，使用服务账号是标准方法。
- 创建服务账号 并授予其
Agent Platform User角色。 - 为应用程序提供凭据：
- 在 Google Cloud 上： 如果你在 Cloud Run、GKE、VM 或其他 Google Cloud 服务中运行智能体，环境可以自动提供服务账号凭据。你无需创建密钥文件。
- 在其他地方： 创建一个服务账号密钥文件 并使用环境变量指向它： 除了密钥文件，你还可以使用工作负载身份 (Workload Identity) 对服务账号进行身份验证，但这超出了本指南的范围。
保护你的凭据
服务账号凭据或 API 密钥是极其敏感的信息。切勿公开暴露它们。请使用密钥管理器（如 Google Cloud Secret Manager）在生产环境中安全地存储和访问它们。
Gemini 模型版本
请务必查阅 Gemini 官方文档以获取最新的模型名称，包括所需的特定预览版本。预览模型可能具有不同的可用性或配额限制。
故障排除¶
错误代码 429 - RESOURCE_EXHAUSTED¶
当你的请求数量超过了模型分配的处理容量时，通常会发生此错误。
要缓解此问题，你可以尝试以下操作：
- 为你尝试使用的模型请求更高的配额限制。
- 启用客户端重试。重试允许客户端在延迟后自动重新发送请求，如果配额问题是暂时的，这可能会有所帮助。
有两种方法可以设置重试选项：
选项 1：在智能体上设置重试选项（作为 generate_content_config 的一部分）。
如果你是自行实例化此模型适配器，则应使用此选项。
=== "Python"
```python
root_agent = Agent(
model='gemini-flash-latest',
# ...
generate_content_config=types.GenerateContentConfig(
# ...
http_options=types.HttpOptions(
# ...
retry_options=types.HttpRetryOptions(initial_delay=1, attempts=2),
# ...
),
# ...
)
)
```
=== "Java"
```java
import com.google.adk.agents.LlmAgent;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.HttpRetryOptions;
// ...
LlmAgent rootAgent = LlmAgent.builder()
.model("gemini-flash-latest")
// ...
.generateContentConfig(GenerateContentConfig.builder()
// ...
.httpOptions(HttpOptions.builder()
// ...
.retryOptions(HttpRetryOptions.builder().initialDelay(1.0).attempts(2).build())
// ...
.build())
// ...
.build())
.build();
```
```
**选项 2：在此模型适配器上设置重试选项。**
如果你是自行实例化适配器实例，则应使用此选项。
=== "Python"
```python
from google.genai import types
root_agent = Agent(
model='gemini-flash-latest',
# ...
generate_content_config=types.GenerateContentConfig(
# ...
http_options=types.HttpOptions(
# ...
retry_options=types.HttpRetryOptions(initial_delay=1, attempts=2),
# ...
),
# ...
)
)
```
=== "Java"
```java
import com.google.adk.agents.LlmAgent;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.HttpRetryOptions;
LlmAgent agent = LlmAgent.builder()
.model(Gemini.builder()
.modelName("gemini-flash-latest")
.apiClient(Client.builder()
.httpOptions(HttpOptions.builder()
.retryOptions(HttpRetryOptions.builder().initialDelay(1.0).attempts(2).build())
.build())
.build())
.build())
.build();
```
=== "Kotlin"
在 Kotlin 中，你可以通过自己创建 `Client` 实例并将其传递给 `Gemini` 构造函数来实现这一点。
```kotlin
import com.google.adk.kt.agents.LlmAgent
import com.google.adk.kt.models.Gemini
import com.google.genai.Client
import com.google.genai.types.HttpOptions
import com.google.genai.types.HttpRetryOptions
val client = Client.builder()
.apiKey("YOUR_API_KEY")
.httpOptions(HttpOptions.builder()
.retryOptions(HttpRetryOptions.builder().initialDelay(1.0).attempts(2).build())
.build())
.build()
val model = Gemini(client = client, name = "gemini-flash-latest")
val agent = LlmAgent(
name = "my_agent",
model = model
// ...
)
```
Gemini Interactions API¶
Gemini Interactions API 是 generateContent 推理 API 的替代方案，它提供了有状态的对话功能，允许你使用 previous_interaction_id 链接交互，而无需在每个请求中发送完整的对话历史记录。对于长对话，这种方式更为高效。
你可以通过在 Gemini 模型配置中设置 use_interactions_api=True 参数来启用 Interactions API，如以下代码片段所示：
from google.adk.agents.llm_agent import Agent
from google.adk.models.google_llm import Gemini
from google.adk.tools.google_search_tool import GoogleSearchTool
root_agent = Agent(
model=Gemini(
model="gemini-flash-latest",
use_interactions_api=True, # 启用 Interactions API
),
name="interactions_test_agent",
tools=[
GoogleSearchTool(bypass_multi_tools_limit=True), # 转换为函数工具
get_current_weather, # 自定义函数工具
],
)
有关完整的代码示例，请参见 Interactions API 示例。
已知限制¶
Interactions API 不支持在同一智能体内混合使用自定义函数调用工具与内置工具（例如 Google 搜索 工具）。你可以通过配置内置工具使用 bypass_multi_tools_limit 参数将其作为自定义工具来绕过此限制：
在此示例中，此选项将内置的 google_search 转换为函数调用工具（通过 GoogleSearchAgentTool），使其能够与自定义函数工具一起工作。