ADK 智能体的 Google Gemini 模型

Supported in ADKPython v0.1.0Typescript v0.2.0Go v0.1.0Java v0.2.0

ADK 支持 Google Gemini 系列生成式 AI 模型，这些模型提供了一套功能强大且用途广泛的能力。ADK 支持许多 Gemini 功能，包括代码执行（Code Execution）、Google 搜索、上下文缓存（Context caching）、计算机使用 (Computer Use) 和 交互(Interactions) API。

入门

以下代码示例展示了在你的智能体中使用 Gemini 模型的基本实现：

PythonTypeScriptGoJava

from google.adk.agents import LlmAgent

# --- 使用稳定的 Gemini Flash 模型的示例 ---
agent_gemini_flash = LlmAgent(
    # 使用最新的稳定 Flash 模型标识符
    model="gemini-2.5-flash",
    name="gemini_flash_agent",
    instruction="你是一个快速且得力的 Gemini 助手。",
    # ... 其他智能体参数
)

import {LlmAgent} from '@google/adk';

// --- 示例：定义一个基本的 Gemini Flash 智能体 ---
export const rootAgent = new LlmAgent({
  name: 'hello_time_agent',
  model: 'gemini-2.5-flash',
  description: 'Gemini flash agent',
  instruction: `你是一个快速且得力的 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)
}

// --- 示例：使用稳定的 Gemini Flash 模型 ---
LlmAgent agentGeminiFlash =
    LlmAgent.builder()
        // 使用最新的稳定 Flash 模型标识符
        .model("gemini-2.5-flash")
        .name("gemini_flash_agent")
        .instruction("你是一个快速且得力的 Gemini 助手。")
        // ... 其他智能体参数
        .build();

Gemini 模型身份验证

本节介绍如何通过 Google AI Studio 进行快速开发，或通过 Google Cloud Vertex AI 进行企业级应用来对 Google 的 Gemini 模型进行身份验证。这是在 ADK 中使用 Google 旗舰模型的最直接方式。

集成方法： 使用以下任一方法进行身份验证后，你可以将模型的标识符字符串直接传递给 LlmAgent 的 model 参数。

提示

ADK 内部用于 Gemini 模型的 google-genai 库可以通过 Google AI Studio 或 Vertex AI 进行连接。

语音/视频流的模型支持 为了在 ADK 中使用语音/视频流，你需要使用支持 Live API 的 Gemini 模型。你可以在文档中找到支持 Gemini Live API 的模型 ID：

• Google AI Studio: Gemini Live API
• Vertex AI: Gemini Live API

Google AI Studio

这是最简单的方法，建议用于快速入门。

• 身份验证方式： API 密钥

• 设置步骤：

  1. 获取 API 密钥： 从 Google AI Studio 获取你的密钥。

  2. 设置环境变量： 在项目的根目录中创建一个 .env 文件 (Python) 或 .properties 文件 (Java)，并添加以下内容。ADK 会自动加载此文件。

     export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
     export GOOGLE_GENAI_USE_VERTEXAI=FALSE
     

     (或者) 在模型初始化期间通过 Client 显式传递这些变量（请参见下面的示例）。

• 可用模型： 在 Google AI for Developers 网站上查看所有可用模型。

Google Cloud Vertex AI

对于可扩展和面向生产的用例，Vertex AI 是推荐的平台。Vertex AI 上的 Gemini 提供企业级功能、安全性和合规性控制。根据你的开发环境和用例，选择以下方法之一进行身份验证。

前置条件： 一个启用了 Vertex AI API 的 Google Cloud 项目。

方法 A: 用户凭据 (用于本地开发)

1. 安装 gcloud CLI： 遵循官方安装说明。
2. 使用 ADC 登录： 此命令会打开浏览器对你的个人账号进行身份验证，适用于本地开发。

   gcloud auth application-default login
   

3. 设置环境变量：

   export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
   export GOOGLE_CLOUD_LOCATION="YOUR_VERTEX_AI_LOCATION" # 例如，us-central1
   

   明确指示库使用 Vertex AI：

   export GOOGLE_GENAI_USE_VERTEXAI=TRUE
   

4. 可用模型： 在 Vertex AI 文档中查找可用的模型 ID。

方法 B: Vertex AI Express 模式

Vertex AI Express 模式提供了一种简化的、基于 API 密钥的设置，用于快速原型设计。

1. 注册 Express 模式以获取你的 API 密钥。
2. 设置环境变量：

   export GOOGLE_GENAI_API_KEY="PASTE_YOUR_EXPRESS_MODE_API_KEY_HERE"
   export GOOGLE_GENAI_USE_VERTEXAI=TRUE
   

方法 C: 服务账号 (用于生产环境和自动化)

对于已部署的任务应用程序，使用服务账号是标准方法。

1. 创建服务账号并为其授予 Vertex AI User 角色。
2. 为你的应用提供凭据：
   • 在 Google Cloud 上： 如果你在 Cloud Run、GKE、VM 或其他 Google Cloud 服务中运行智能体，环境会自动提供服务账号凭据。你无需创建密钥文件。
   • 在非 Google Cloud 环境： 创建一个服务账号密钥文件并使用环境变量指向它：

     export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"
     

     除了密钥文件，你还可以使用工作负载身份 (Workload Identity) 对服务账号进行身份验证，但这超出了本指南的范围。

保护你的凭据

服务账号凭据或 API 密钥是极其敏感的信息。切勿公开暴露它们。请使用密钥管理器（如 Google Cloud Secret Manager）在生产环境中安全地存储和访问它们。

Gemini 模型版本

请务必查阅 Gemini 官方文档以获取最新的模型名称，包括所需的特定预览版本。预览模型可能具有不同的可用性或配额限制。

故障排除

错误代码 429 - RESOURCE_EXHAUSTED

当你的请求数量超过了模型分配的处理容量时，通常会发生此错误。

要缓解此问题，你可以尝试以下操作：

1. 为你尝试使用的模型请求更高的配额限制。
2. 启用客户端重试。重试允许客户端在延迟后自动重新发送请求，如果配额问题是暂时的，这可能会有所帮助。

有两种方法可以设置重试选项：

选项 1：在 Agent 上设置重试选项（作为 generate_content_config 的一部分）。

如果你直接实例化智能体，可以使用此选项。

PythonJava

root_agent = Agent(
    model='gemini-2.5-flash',
    # ...
    generate_content_config=types.GenerateContentConfig(
        # ...
        http_options=types.HttpOptions(
            # ...
            retry_options=types.HttpRetryOptions(initial_delay=1, attempts=2),
            # ...
        ),
        # ...
    )
)

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-2.5-flash")
    // ...
    .generate_content_config(GenerateContentConfig.builder()
        // ...
        .http_options(HttpOptions.builder()
            // ...
            .retry_options(HttpRetryOptions.builder().initial_delay(1.0).attempts(2).build())
            // ...
            .build())
        // ...
        .build())
    .build();

选项 2：在模型适配器上设置重试选项。

如果你自己实例化适配器实例，可以使用此选项。

PythonJava

from google.genai import types

# ...

agent = Agent(
    model=Gemini(
        retry_options=types.HttpRetryOptions(initial_delay=1, attempts=2),
    )
)

import com.google.adk.agents.LlmAgent;
import com.google.adk.models.Gemini;
import com.google.genai.Client;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.HttpRetryOptions;

// ...

LlmAgent agent = LlmAgent.builder()
    .model(Gemini.builder()
        .model_name("gemini-2.5-flash")
        .api_client(Client.builder()
            .http_options(HttpOptions.builder()
                .retry_options(HttpRetryOptions.builder().initial_delay(1.0).attempts(2).build())
                .build())
            .build())
        .build())
    .build();

Gemini Interactions API

Supported in ADKPython v1.21.0

Gemini Interactions API 是 generateContent 推理 API 的替代方案，它提供了有状态的对话功能，允许你使用 previous_interaction_id 链接交互，而无需在每个请求中发送完整的对话历史记录。对于长对话，这种方式更为高效。

你可以通过在 Gemini 模型配置中设置 use_interactions_api=True 参数来启用 Interactions API，如以下代码片段所示：

PythonJava

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-2.5-flash",
        use_interactions_api=True,  # 启用 Interactions API
    ),
    name="interactions_test_agent",
    tools=[
        GoogleSearchTool(bypass_multi_tools_limit=True),  # 转换为函数工具
        get_current_weather,  # 自定义函数工具
    ],
)

import com.google.adk.agents.LlmAgent;
import com.google.adk.models.Gemini;
import com.google.adk.tools.GoogleSearchTool;

// 注意：Java ADK 对 Interactions API 的支持目前正在开发中。
LlmAgent rootAgent = LlmAgent.builder()
    .model(Gemini.builder()
        .model_name("gemini-2.5-flash")
        .build())
    .name("interactions_test_agent")
    .tools(
        GoogleSearchTool.INSTANCE, // 搜索工具
        getCurrentWeather // 自定义函数工具
    )
    .build();

有关完整的代码示例，请参阅 交互(Interactions) API 示例。

已知限制

交互(Interactions) API 不 支持在同一个智能体中混合使用自定义函数调用工具和内置工具（例如 Google 搜索工具）。你可以通过使用 bypass_multi_tools_limit 参数将内置工具配置为作为自定义工具运行，从而绕过此限制：

PythonJava

# 使用 bypass_multi_tools_limit=True 将 google_search 转换为函数工具
GoogleSearchTool(bypass_multi_tools_limit=True)

// 注意：bypassMultiToolsLimit 是 Python 特有的。
// 在 Java 中，只需直接使用工具实例即可。
GoogleSearchTool.INSTANCE;

在此示例中，该选项将内置的 google_search 转换为函数调用工具（通过 GoogleSearchAgentTool），从而使其可以与自定义函数工具一起使用。