# 通过 LiteLlm 连接器把 Google ADK 的 Agent 接到 Router One

> https://router.one/zh/integrations/google-adk 的 Markdown 镜像，供 AI 助手与爬虫使用。Router One 是 OpenAI 兼容的统一 LLM API 网关。
> 最后更新：2026-09-15

Google 的 Agent Development Kit（ADK）是用来构建、评估和部署 Agent 的开源框架；在 Python 里，一个 LlmAgent 带着 name、instruction、tools 和 model，由 adk run 或 adk web 驱动循环。它的原生路径把 gemini-… 这类模型字符串解析到 Google 自己的 API；这条路径之外的模型通过 LiteLlm 连接器接入，Router One 就配在这里：LiteLlm 带上 openai/… 形式的 model、api_base 和 api_key 之后，每次模型调用都变成 POST /v1/chat/completions，一把 Key 覆盖目录里的所有聊天模型，每次调用在 Dashboard → Logs 都有成本和延迟 Trace，而工具、session 和 Agent 循环仍在你的进程里运行。本指南覆盖安装、LiteLlm 的三个字段、模型字符串规则，以及怎样给一次运行设预算。

## 安装 google-adk 与 litellm，并设置凭证

使用 Python 3.10 或更新版本，安装 google-adk 和 litellm：LiteLlm 连接器页写明 ADK 要求 litellm>=1.84，而且该连接器只标注支持 ADK Python，所以本指南不适用于 TypeScript、Go、Java 或 Kotlin 版 ADK。adk create my_agent 会生成 adk run 需要的目录：含 root_agent 定义的 agent.py、__init__.py 和一个 .env 文件。快速入门把 API Key 放在这个 .env 里再运行两条命令；adk run 会加载它（设置 ADK_DISABLE_LOAD_DOTENV 可关闭），shell 里已导出的变量优先于文件里的值，所以下面的 macOS/Linux shell 示例和 .env 文件两种写法都可以。运行前替换两个占位符：一把 Router One Key，以及当前目录中支持 Chat Completions 的精确模型 ID。ROUTER_ONE_* 是本示例自己定义并显式读取的变量名；Key 直接传给 LiteLlm，所以不需要设置 OPENAI_API_KEY。

`terminal`

```bash
python -m pip install google-adk
python -m pip install "litellm>=1.84"
export ROUTER_ONE_API_KEY="sk-your-router-one-key"
export ROUTER_ONE_MODEL_ID="<exact-model-id-from-/models>"
```

## 把 Google ADK 配置到 Router One base URL

保存为 my_agent/agent.py，保留 adk create 生成的 __init__.py，然后在上一级目录运行 adk run my_agent。LiteLlm 是 ADK 对 litellm 库的包装：除 model 以外的关键字参数都会被保存下来，原样传给 litellm 的 completion 调用，api_base 和 api_key 就是这样到达 LiteLLM 的。model 必须以 openai/ 开头：LiteLLM 文档把这个前缀定义为「调用 OpenAI /chat/completions 端点」的指令，而 LiteLLM 只在第一个斜杠处切分一次，openai/ 之后的内容会原样作为请求里的 model 字段发出。示例用 ROUTER_ONE_MODEL_ID 拼出它，所以 openai/gpt-5.5 这样的 GPT 系列 ID 写成 openai/openai/gpt-5.5。api_base 填带 /v1 的 base URL，后面不加任何路径；LiteLLM 底层用 OpenAI Python 客户端发请求，会自己补上 /chat/completions。api_key 填 Router One Key，在这里传入后就不需要 OPENAI_API_KEY 和 OPENAI_API_BASE。root_agent 是 Agent 目录唯一必需的元素；name、instruction 和这个 model 对象就是 LiteLLM 连接器页示例用到的 LlmAgent 字段。在同一个上级目录运行 adk web --port 8000，可在 http://localhost:8000 打开开发界面：

`my_agent/agent.py`

```python
import os

from google.adk.agents import LlmAgent
from google.adk.models.lite_llm import LiteLlm

# openai/ makes LiteLLM call an OpenAI /chat/completions endpoint; the rest of
# the string is sent unchanged as the model field (openai/openai/gpt-5.5 for a GPT ID).
model = LiteLlm(
    model="openai/" + os.environ["ROUTER_ONE_MODEL_ID"],
    api_base="https://api.router.one/v1",  # ends in /v1, nothing after it
    api_key=os.environ["ROUTER_ONE_API_KEY"],
)

# root_agent is the only required element of the agent folder.
root_agent = LlmAgent(
    name="router_one_agent",
    model=model,
    instruction="Answer in one short sentence.",
)

# From the parent folder:  adk run my_agent     (or: adk web --port 8000)
```

## 每个值填在哪里，怎么验证

Router One 需要的东西都在 LiteLlm 对象里，Agent 的其余部分不变。下表列出每个字段、要填的值和能证明它生效的检查，最后是本指南不配置的两条路径：

| Google ADK 字段 | 填什么 | 怎么验证 |
| --- | --- | --- |
| LiteLlm(model=…) | openai/ 加上精确的目录 ID：openai/anthropic/claude-sonnet-5、openai/deepseek-v4.1-flash，GPT 系列 ID 写成 openai/openai/gpt-5.5 | Logs 里每条 Trace 的模型就是去掉开头 openai/ 的 ID；LiteLLM 只在第一个斜杠处切分，其余部分（包括属于 ID 本身的前缀）原样保留 |
| LiteLlm(api_base=…) | https://api.router.one/v1 | 以 /v1 结尾，后面什么都不加；LiteLLM 文档把 Not Found 错误归因于缺少 /v1 后缀，并提醒不要在 base URL 后追加任何路径 |
| LiteLlm(api_key=…) | 为这个 Agent 单独创建、设了 maxSpend 的 Router One Key，从 ROUTER_ONE_API_KEY 读取 | 第一条 Trace 出现在 Dashboard → Logs 里这把 Key 名下；这个参数优先于 OPENAI_API_KEY，环境变量不会覆盖它 |
| LlmAgent(model=…) | LiteLlm 对象，不是字符串 | 字符串会交给 ADK 的注册表解析：gemini-… 字符串走 Google 自己的 API 和 GOOGLE_API_KEY，不会到达网关；ADK 关于「通过 LiteLLM 使用 Gemini」的警告只针对 gemini/ 和 vertex_ai/ 开头的字符串，不影响 openai/google/… 这类 ID |
| LlmAgent(tools=[…]) | 普通 Python 函数；ADK 会把每个函数包装成 FunctionTool，并根据函数签名和 docstring 生成 schema | 模型详情页的工具调用能力；函数在你的进程里执行，每个工具结果都会作为又一次 Chat Completions 请求送回模型 |
| RunConfig(streaming_mode=…) | 默认 StreamingMode.NONE，向 runner.run_async 传入 StreamingMode.SSE 才开启流式 | 模型详情页的流式支持；adk run 不传 RunConfig，所以用的是非流式调用 |
| 本指南不配置的路径 | gemini-… 模型字符串和原生 Gemini 模型类；ADK Go 的实验性 openaimodel 包 | Go 的这个包面向 OpenAI Responses API，网关只对当前上架的 GPT 系列和 DeepSeek ID 原生提供该端点 |

## 给一个 Agent 定预算，并逐次核对模型调用

一个用户回合可能产生多次模型请求：连接器对运行中的每次 LLM 调用发起一次 LiteLLM 调用，每个函数工具的结果又会作为一次新的 Chat Completions 请求送回模型。RunConfig.max_llm_calls 限制一次运行里的 LLM 调用次数——不传值也不设 ADK_MAX_LLM_CALLS 时为 500，设为 0 或更小则不限制；它数的是次数，不是钱。重试也是独立请求：请求带 http_options.retry_options 时，ADK 会把 attempts 作为 LiteLLM 的 num_retries 传入，每一次到达网关的尝试都是独立请求，有各自的 request_id、Trace 和费用。给每个 Agent 单独建一把设了 maxSpend 的 Router One Key；运行触到上限后，下一次调用返回 HTTP 402，钱包和其他 Key 不受影响。adk web 的事件历史显示一次运行的事件，adk run --save_session 会把它们写进 JSON 文件；两者都不显示账单。每次调用的费用就是 Dashboard → Logs 里的 Trace——模型、输入输出 tokens、费用、延迟、状态和 request_id——按 Key、时间、精确模型和 request_id 对账，报障时保留 request_id。Router One 只服务模型请求并记录 Trace；session、状态、工具执行和 Agent 循环都留在你的进程里。

## Google ADK 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 Google ADK 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个工具单独建 API Key，并设置 maxSpend 消费上限。

## Google ADK 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

## 在 trace 里验证 Google ADK 的调用

先在 Google ADK 发出一次简单文本请求，再到 Dashboard → Logs 按时间、模型和 request_id 核对 trace：tokens、花费、延迟和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

## 常见问题

### LiteLLM 报 BadRequestError: LLM Provider NOT provided，或者请求根本没有发到 Router One，模型字符串错在哪里？

模型字符串的第一段就是 LiteLLM 的 provider 开关，只有 openai/ 会选中把请求发到 api_base 的 OpenAI Chat Completions 处理器。不带它时，LiteLLM 在自己的各家模型列表里都对不上的不带前缀的目录 ID 会以 BadRequestError 结束，消息为 LLM Provider NOT provided. Pass in the LLM provider you are trying to call；而 LiteLLM 能识别为其他 provider 模型的 ID，或者第一段恰好是 LiteLLM provider 名称的 ID（例如 anthropic/claude-sonnet-5），会被交给那家 provider 自己的处理器，于是没有任何 Chat Completions 请求到达网关。所有系列都把 openai/ 放在第一段：LiteLLM 只去掉这一个前缀，其余部分作为 model 字段发出，所以 GPT 系列 ID 写成 openai/openai/gpt-5.5。再核对 LiteLLM 文档和源码给出的两点：api_base 必须以 /v1 结尾且不追加任何路径，因为 LiteLLM 内部的 OpenAI 客户端会自己补 /chat/completions，缺 /v1 会表现为 Not Found 错误；api_key 和 api_base 参数优先于 OPENAI_API_KEY、OPENAI_BASE_URL 和 OPENAI_API_BASE，环境里残留的值不会把 agent.py 里的这两个值改到别处。

### 流式输出和工具调用能通过 LiteLlm 连接器使用吗？

两者都由连接器处理，也都取决于模型。流式是按每次运行决定的，不是按模型对象：RunConfig.streaming_mode 默认为 StreamingMode.NONE，只有设为 StreamingMode.SSE 时流程才会给连接器传 stream=True；adk run 调用 runner 时不传 RunConfig，所以用的是非流式调用。开启 SSE 后，连接器会在 LiteLLM 调用上加 stream=True 和带 include_usage 的 stream_options，逐块读取并按 index 重组工具调用；如果某个工具调用的参数在解析成 JSON 之前就被截断，会返回错误。工具以工具定义的形式放在同一个 Chat Completions 请求里：ADK 根据函数签名和 docstring 生成每个定义，在你的进程里执行函数，再把结果送回模型。ADK 的 vLLM 页写明服务端必须支持 OpenAI 兼容的工具调用，所以加工具前先在模型详情页确认工具调用能力，并按普通回复、流式、单次工具调用的顺序分别测试，在 Logs 里各自对应一条请求。连接器对 Anthropic thinking block 的处理只在 anthropic/ 这条 LiteLLM 路径上有文档说明，不适用于本指南使用的 openai/ 路径。

### Google ADK 能通过网关用哪些模型？

选用当前目录中同时支持 Google ADK 所用端点和所需功能的模型。精确 ID、当前单价与能力以 /models 及模型详情为准；不要仅按 GPT、Claude 等系列名判断兼容性。客户端能列出模型，只证明模型发现成功，仍需验证实际调用。

### 能列出模型，但调用报 400 或 404，怎么办？

先记录实际请求路径和错误消息，再核对精确模型 ID。400 可能是参数、工具类型或模型与端点不匹配；404 可能是请求路径或资源不存在，不能直接判定模型下线。若错误提示 must be called via，按它指明的端点调整客户端 provider，或换用支持当前端点的模型。不要在所有工具里统一增删 /v1 或 /chat/completions。

### 中国大陆能直连吗？

能。网关在大陆可直连、无需 VPN，配置与全球环境完全一致。

### 报 401/402/403/429 怎么排查？

先到 Dashboard → Logs 核对请求及错误消息。401 查 Key 是否传入和有效；402 查钱包余额与 maxSpend；403 查 Key 权限和访问限制；429 查请求频率、token 限额及上游限流，按错误来源处理。保留 request_id，再按错误码速查页逐项排查。

## 相关页面

- 全部接入指南：https://router.one/zh/integrations
- Google ADK 的 API 错误排查：https://router.one/zh/llm-api-error-codes
- API 兼容性：端点与功能对照：https://router.one/zh/facts/api-compatibility.md
- Responses API 配置与限制：https://router.one/zh/codex-responses-api
- smolagents 接入：https://router.one/zh/integrations/smolagents
- Goose 接入：https://router.one/zh/integrations/goose
- OpenAI Python SDK 接入：https://router.one/zh/integrations/openai-sdk
- 工具调用的 API 要求：https://router.one/zh/llm-tool-calling
- 连接与 /v1 路径排查：https://router.one/zh/api-connection-troubleshooting
- Google ADK 官方文档：LiteLLM 模型连接器：https://adk.dev/agents/models/litellm/
- Google ADK 官方文档：vLLM 模型托管（api_base 示例）：https://adk.dev/agents/models/vllm/
- LiteLLM 官方文档：OpenAI 兼容端点：https://docs.litellm.ai/docs/providers/openai_compatible
- 网关层负责什么：https://router.one/zh/llm-api-gateway
- OpenAI 兼容 API：https://router.one/zh/openai-compatible-api
- API 文档：https://router.one/zh/docs
- 本页规范地址：https://router.one/zh/integrations/google-adk
- 模型与每模型 token 价格：https://router.one/zh/models （markdown：https://router.one/zh/models.md ）
- 定价：https://router.one/zh/pricing
- API 文档（markdown）：https://router.one/zh/docs.md
- 公司事实（markdown）：https://router.one/zh/facts/company.md