ADK 智能体的 Google Gemini 模型

ADK 中支持Python v0.1.0Typescript v0.2.0Go v0.1.0Java v0.2.0

ADK supports the Google Gemini family of generative AI models that provide a powerful set of models with a wide range of features. ADK provides support for many Gemini features, including Code Execution, Google Search, Context caching, Computer use and the Interactions API.

入门指南

The following code examples show a basic implementation for using Gemini models in your agents:

PythonTypeScriptGoJava

from google.adk.agents import LlmAgent

# --- 使用稳定的 Gemini Flash 模型的示例 ---
agent_gemini_flash = LlmAgent(
    # Use the latest stable Flash model identifier
    model="gemini-2.5-flash",
    name="gemini_flash_agent",
    instruction="You are a fast and helpful Gemini assistant.",
    # ... other agent parameters
)

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

// --- 示例 #2: 使用强大的 Gemini Pro 模型,在模型中使用 API Key ---
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: 使用带有 ENV 变量的稳定 Gemini Flash 模型 ---
LlmAgent agentGeminiFlash =
    LlmAgent.builder()
        // Use the latest stable Flash model identifier
        .model("gemini-2.5-flash") // Set ENV variables to use this model
        .name("gemini_flash_agent")
        .instruction("You are a fast and helpful Gemini assistant.")
        // ... other agent parameters
        .build();

Gemini 模型身份验证

This section covers authenticating with Google's Gemini models, either through Google AI Studio for rapid development or Google Cloud Vertex AI for enterprise applications. This is the most direct way to use Google's flagship models within ADK.

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

Tip

The google-genai library, used internally by ADK for Gemini models, can connect through either Google AI Studio or Vertex AI.

语音/视频流式传输的模型支持

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

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

Google AI Studio

This is the simplest method and is recommended for getting started quickly.

• 身份验证方法: API Key

• 设置:

  1. 获取 API key: 从 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

For scalable and production-oriented use cases, Vertex AI is the recommended platform. Gemini on Vertex AI supports enterprise-grade features, security, and compliance controls. Based on your development environment and usecase, 选择以下方法之一进行身份验证。

先决条件: 具有启用 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" # e.g., us-central1
   

   明确告知库使用 Vertex AI:

   export GOOGLE_GENAI_USE_VERTEXAI=TRUE
   

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

方法 B: Vertex AI Express 模式

Vertex AI Express 模式 为快速原型设计提供简化的基于 API Key 的设置。

1. 注册 Express 模式 以获取您的 API key。
2. 设置环境变量:

   export GOOGLE_API_KEY="PASTE_YOUR_EXPRESS_MODE_API_KEY_HERE"
   export GOOGLE_GENAI_USE_VERTEXAI=TRUE
   

方法 C: 服务帐户 (用于生产和自动化)

For deployed applications, a service account is the standard method.

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 key 是强大的凭据。绝不要公开它们。使用Google Cloud Secret Manager 等密钥管理器 在生产环境中安全地存储和访问它们。

Gemini 模型版本

始终查看官方 Gemini 文档以获取最新的模型名称, 包括需要时的特定预览版本。预览模型可能有不同的可用性或配额限制。

故障排除

错误代码 429 - RESOURCE_EXHAUSTED

This error usually happens if the number of your requests exceeds the capacity allocated to process requests.

To mitigate this, you can do one of the following:

1. 请求更高的配额限制用于您尝试使用的模型。

2. 启用客户端重试。重试允许客户端在延迟后自动重试请求,如果配额问题是临时的,这会有所帮助。

   有两种设置重试选项的方法:

   选项 1: 在智能体上将重试选项设置为 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

ADK 中支持Python 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,  # 自定义函数工具
    ],
)

For a complete code sample, see the Interactions API sample.

已知限制

Interactions API 不支持在同一智能体内将自定义函数调用工具与 内置工具 (如 Google Search 工具) 混合使用。您可以通过使用 bypass_multi_tools_limit 参数将内置工具配置为自定义工具来解决此限制:

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

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