Skip to content

ADK 智能体的 Google Gemini 模型

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

ADK 支持 Google Gemini 系列生成式 AI 模型,这些模型提供了一套功能强大且功能广泛的模型。ADK 支持许多 Gemini 功能,包括 代码执行、Google 搜索、上下文缓存、Computer Use 和 Interactions API。

入门

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

from google.adk.agents import LlmAgent

# --- 使用稳定的 Gemini Flash 模型的示例 ---
agent_gemini_flash = LlmAgent(
    # 使用最新的稳定 Flash 模型标识符
    model="gemini-2.5-flash",
    name="gemini_flash_agent",
    instruction="You are a fast and helpful Gemini assistant.",
    # ... 其他智能体参数
)

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

// --- 示例 #2: 在模型中使用 API 密钥的强大 Gemini Pro 模型 ---
export const rootAgent = new LlmAgent({
  name: 'hello_time_agent',
  model: 'gemini-2.5-flash',
  description: 'Gemini flash agent',
  instruction: `You are a fast and helpful Gemini assistant.`,
});

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)
}

// --- 示例 #1: 使用带有环境变量的稳定 Gemini Flash 模型 ---
LlmAgent agentGeminiFlash =
    LlmAgent.builder()
        // 使用最新的稳定 Flash 模型标识符
        .model("gemini-2.5-flash") // 设置环境变量以使用此模型
        .name("gemini_flash_agent")
        .instruction("You are a fast and helpful Gemini assistant.")
        // ... 其他智能体参数
        .build();

Gemini 模型身份验证

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

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

Tip

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

语音/视频流的模型支持

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

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 的 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_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 服务中运行智能体,环境可以自动提供服务帐户凭据。你不必创建密钥文件。
    • 在其他地方: 创建一个 服务帐户密钥文件 并使用环境变量指向它: 
      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 的一部分。

    如果你自己实例化此模型适配器,则可以使用此选项。

    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),
            ...
        ),
        ...
    )

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

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

    from google.genai import types

# ...

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

Gemini Interactions API

Supported in ADKPython v1.21.0

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-2.5-flash",
        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 参数将内置工具配置为作为自定义工具运行来解决此限制:

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

在此示例中,此选项将内置的 google_search 转换为函数调用工具(通过 GoogleSearchAgentTool),这使其可以与自定义函数工具一起使用。