适用于 ADK 智能体的 Google Gemma 模型¶
Supported in ADKPython v0.1.0
ADK 智能体可以使用具备广泛能力的 Google Gemma 系列生成式 AI 模型。ADK 支持许多 Gemma 特性，包括工具调用 (Tool Calling) 和结构化输出 (Structured Output)。
你可以通过 Gemini API 使用 Gemma 4，或使用 Google Cloud 上的多种自托管选项： Agent Platform、 Google Kubernetes Engine、 Cloud Run。
Gemma 3 needs a different model class than the Gemma 4 examples below. It has
no native function calling or system instruction support, so ADK supplies
workarounds in dedicated classes: use Gemma(model="gemma-3-27b-it") for the
Gemini API and Gemma3Ollama() for Ollama, both from google.adk.models.
Gemma3Ollama is only defined when LiteLLM is
installed (litellm>=1.84).
Gemini API Example¶
在 Google AI Studio 中创建一个 API 密钥。
# 将 GEMINI_API_KEY 环境变量设置为你的 API 密钥
# export GEMINI_API_KEY="YOUR_API_KEY"
from google.adk.agents import LlmAgent
from google.adk.models import Gemini
# 待测试的简单工具
def get_weather(location: str) -> str:
return f"地点: {location}。天气: 晴朗，华氏 76 度，风速 8 英里/小时。"
root_agent = LlmAgent(
model=Gemini(model="gemma-4-31b-it"),
name="weather_agent",
instruction="你是一个可以提供实时天气信息的得力助手。",
tools=[get_weather]
)
// 将 GEMINI_API_KEY 环境变量设置为你的 API 密钥
// export GEMINI_API_KEY="YOUR_API_KEY"
import com.google.adk.agents.LlmAgent;
import com.google.adk.tools.Annotations.Schema;
import com.google.adk.tools.FunctionTool;
LlmAgent weatherAgent = LlmAgent.builder()
.model("gemma-4-31b-it")
.name("weather_agent")
.instruction("""
你是一个可以提供实时天气信息的得力助手。
""")
.tools(FunctionTool.create(this, "getWeather"))
.build();
@Schema(name = "getWeather",
description = "获取给定地点的天气预报")
public Map<String, String> getWeather(
@Schema(name = "location",
description = "天气预报的地点")
String location) {
return Map.of("forecast", "地点: " + location
+ "。天气: 晴朗，华氏 76 度，风速 8 英里/小时。");
}
vLLM 示例¶
如需在这些服务中访问 Gemma 4 端点，你可以通过 Python 的 LiteLLM 库，以及 Java 的 LangChain4j 使用 vLLM 模型。
以下示例展示了如何在 ADK 智能体中使用 Gemma 4 vLLM 端点。
设置¶
- 部署模型： 使用 Agent Platform、Google Kubernetes Engine 或 Cloud Run 部署你选择的模型，并使用其兼容 OpenAI 的 API 端点。请注意，API 基础 URL 包含
/v1（例如https://your-vllm-endpoint.run.app/v1）。- 对 ADK 工具的重要说明： 部署时，确保服务工具支持并启用了兼容的工具/函数调用和推理解析器。
- 身份验证： 确定你的端点如何处理身份验证（例如 API 密钥、Bearer 令牌）。
代码¶
import subprocess
from google.adk.agents import LlmAgent
from google.adk.models.lite_llm import LiteLlm
# --- 使用托管在 vLLM 端点上的模型的智能体示例 ---
# 由模型部署提供的端点 URL
api_base_url = "https://your-vllm-endpoint.run.app/v1"
# *你的* vLLM 端点配置所识别的模型名称
model_name_at_endpoint = "openai/google/gemma-4-31B-it"
# 待测试的简单工具
def get_weather(location: str) -> str:
return f"地点: {location}。天气: 晴朗，华氏 76 度，风速 8 英里/小时。"
# 身份验证（示例：为 Cloud Run 部署使用 gcloud 身份令牌）
# 请根据你的端点安全性进行调整
try:
gcloud_token = subprocess.check_output(
["gcloud", "auth", "print-identity-token", "-q"]
).decode().strip()
auth_headers = {"Authorization": f"Bearer {gcloud_token}"}
except Exception as e:
print(f"警告: 无法获取 gcloud 令牌 - {e}。")
auth_headers = None # 或进行适当的错误处理
root_agent = LlmAgent(
model=LiteLlm(
model=model_name_at_endpoint,
api_base=api_base_url,
# Pass authentication headers if needed
extra_headers=auth_headers,
# Alternatively, if endpoint uses an API key:
# api_key="YOUR_ENDPOINT_API_KEY",
extra_body={
"chat_template_kwargs": {
"enable_thinking": True # 启用思考
},
"skip_special_tokens": False # 应设置为 False
},
),
name="weather_agent",
instruction="你是一个可以提供实时天气信息的得力助手。",
tools=[get_weather] # 工具！
)
要使用托管在 vLLM 上的 Gemma，必须使用兼容 OpenAI 的库。LangChain4j 提供了一个 OpenAI 依赖项，你可以将其添加到 pom.xml 中：
<!-- LangChain4j 到 ADK 的桥接 -->
<dependency>
<groupId>com.google.adk</groupId>
<artifactId>google-adk-langchain4j</artifactId>
<version>${adk.version}</version>
</dependency>
<!-- Core LangChain4j 库 -->
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-core</artifactId>
<version>${langchain4j.version}</version>
</dependency>
<!-- OpenAI 兼容模型 -->
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-open-ai</artifactId>
<version>${langchain4j.version}</version>
</dependency>
创建一个 OpenAI 兼容的聊天模型（流式或非流式），使用 LangChain4j 包装器进行包装，然后将其传递给 LlmAgent：
import com.google.adk.agents.LlmAgent;
import com.google.adk.tools.Annotations.Schema;
import com.google.adk.tools.FunctionTool;
import dev.langchain4j.model.chat.StreamingChatModel;
import dev.langchain4j.model.openai.OpenAiStreamingChatModel;
// 由模型部署提供的端点 URL
String apiBaseUrl = "https://your-vllm-endpoint.run.app/v1";
// *你的* vLLM 端点配置所识别的模型名称
String gemmaModelName = "gg-hf-gg/gemma-4-31b-it";
// 首先，使用 LangChain4j 定义一个兼容 OpenAI 的聊天模型
StreamingChatModel model =
OpenAiStreamingChatModel.builder()
.modelName(gemmaModelName)
// 如果你的端点需要 API 密钥
// .apiKey("YOUR_ENDPOINT_API_KEY")
.baseUrl(apiBaseUrl)
.customParameters(
Map.of(
"skip_special_tokens", false,
"chat_template_kwargs", Map.of("enable_thinking", true)
)
)
.build();
// 使用 LangChain4j 包装器模型配置智能体
LlmAgent weatherAgent = LlmAgent.builder()
.model(new LangChain4j(model))
.name("weather_agent")
.instruction("""
你是一个可以提供实时天气信息的得力助手。
""")
.tools(FunctionTool.create(this, "getWeather"))
.build();
@Schema(name = "getWeather",
description = "获取给定地点的天气预报")
public Map<String, String> getWeather(
@Schema(name = "location",
description = "天气预报的地点")
String location) {
return Map.of("forecast", "地点: " + location
+ "。天气: 晴朗，华氏 76 度，风速 8 英里/小时。");
}
使用 Gemma 4、ADK 和 Google Maps MCP 构建美食之旅智能体¶
本示例展示了如何使用 Gemma 4、ADK 和 Google Maps MCP 服务器构建个性化的美食之旅智能体。该智能体接收用户提供的菜品照片或文本描述、地点以及可选预算，然后推荐用餐地点并将其组织成步行路线。
先决条件¶
- 在 Google AI Studio 中获取 API 密钥。将
GEMINI_API_KEY环境变量设置为你的 Gemini API 密钥。 - 在 Google Cloud 控制台上启用 Google Maps API。
- 创建一个 Google Maps 平台 API 密钥。将
MAPS_API_KEY环境变量设置为你的 API 密钥。 - 安装 ADK 并在 Python 环境中进行配置，或在 Java 项目中配置 Java 依赖项。
项目结构¶
agent.py
import os
import dotenv
from google.adk.agents import LlmAgent
from google.adk.models import Gemini
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
dotenv.load_dotenv()
system_instruction = """
你是一位专业的个性化美食导游。
你的目标是根据输入内容构建美食之旅：菜品照片（或文字描述）、地点和预算。
请遵循以下 4 个严格步骤：
1. **识别菜系/菜品：** 分析用户提供的描述或图片 URL 以确定主要的菜系或特定菜品。
2. **寻找最佳地点：** 使用 `search_places` 工具查找在用户指定位置供应该菜系/菜品的高评分餐厅、摊位或咖啡馆。
**地点的关键规则：** `search_places` 返回 AI 生成的地点数据摘要以及每个地点的 `place_id`、纬度/经度坐标和地图链接，但可能缺少直接、显式的名称字段。你必须仔细地将每个描述的地点与其提供的 `place_id` 或 `lat_lng` 关联起来。
3. **构建路线：** 使用 `compute_routes` 工具在所选地点之间构建优化的步行路线。
**关键路由规则：** 为了避免幻觉，你必须使用 `search_places` 返回的确切 `place_id` 字符串或 `lat_lng` 对象来提供 `origin` 和 `destination`。如果你不知道确切名称，请不要猜测或虚构 `address` 或 `place_id`。
4. **内部贴士：** 为旅程中的每个地点提供具体的“必点项，雷区点”等内部贴士。
清晰、简洁地组织你的回复。如果用户提供了预算，请确保你的建议与之匹配。
"""
MAPS_MCP_URL = "https://mapstools.googleapis.com/mcp"
def get_maps_mcp_toolset():
dotenv.load_dotenv()
maps_api_key = os.getenv("MAPS_API_KEY")
if not maps_api_key:
print("警告: 未找到 MAPS_API_KEY 环境变量。")
maps_api_key = "no_api_found"
tools = McpToolset(
connection_params=StreamableHTTPConnectionParams(
url=MAPS_MCP_URL,
headers={
"X-Goog-Api-Key": maps_api_key
}
)
)
print("Google Maps MCP 工具集已配置。")
return tools
maps_toolset = get_maps_mcp_toolset()
root_agent = LlmAgent(
model=Gemini(model="gemma-4-31b-it"),
name="food_tour_agent",
instruction=system_instruction,
tools=[maps_toolset],
)
环境变量¶
在运行智能体之前设置所需的环境变量。
示例用法¶
要测试美食之旅智能体的能力，请尝试将以下提示词之一粘贴到聊天框中：
- “我想在多伦多进行一次拉面之旅。我当天的预算是 60 美元。请给我一条包含前三个地点的步行路线，并告诉我每个地点应该点什么。”
- “我有这张深盘披萨的照片 [插入图片 URL]。我想在芝加哥海军码头 (Navy Pier) 附近寻找最棒的店。请规划一次步行游览，并告诉我每站必尝的是哪一种。”
- “我在奥斯汀市中心寻找正宗的烧烤之旅。预算控制在 100 美元以内。请在 3 个高评分地点之间构建一条步行路线，并给出关于购买最佳肉块的内部建议。”
智能体会：
- 推断可能的菜系或菜品风格
- 使用 Google Maps MCP 工具搜索相关地点
- 计算所选站点之间的步行路线
- 返回结构化的美食之旅建议和内部贴士