ADK 智能体的 LiteLLM 模型连接器¶

Supported in ADKPython v0.1.0

ADK Python 安全公告：LiteLLM 供应链漏洞

2026 年 3 月 24 日，在 PyPI 上的 LiteLLM 1.82.7 和 1.82.8 版本中发现了未经授权的代码。如果你在使用 ADK Python 时包含了 eval 或 extensions 额外依赖项，请立即更新到 ADK Python 的最新版本。如果你在此期间安装或升级了 LiteLLM，请更换所有密钥和凭据。有关详细信息和所需操作，请参阅 ADK 安全公告和 LiteLLM 安全更新：疑似供应链事件。

LiteLLM 是一个 Python 库，作为模型和模型托管服务的翻译层，为 100 多种 LLM 提供标准化的、兼容 OpenAI 的接口。ADK 通过 LiteLLM 库提供集成，允许你访问来自 OpenAI、Anthropic、Ollama、Mistral、DeepSeek 和 Cohere 等提供商的大量 LLM。你可以在本地运行开源模型或自行托管它们，并使用 LiteLLM 进行集成，以实现运营控制、成本节约、隐私保护或离线使用场景。

你可以使用 LiteLLM 库访问远程或本地托管的 AI 模型：

远程模型托管： 使用 LiteLlm 包装类并将其设置为 LlmAgent 的 model 参数。
本地模型托管： 使用配置为指向你本地模型服务器的 LiteLlm 包装类。有关本地模型托管协议的示例，请参阅 Ollama 或 vLLM 文档。

Windows 下使用 LiteLLM 的编码问题

在 Windows 上将 ADK 智能体与 LiteLLM 一起使用时，你可能会遇到 UnicodeDecodeError。发生此错误是因为 LiteLLM 可能会尝试使用默认的 Windows 编码 (cp1252) 而不是 UTF-8 来读取缓存文件。通过将 PYTHONUTF8 环境变量设置为 1 可防止此错误。这会强制 Python 对所有文件 I/O 使用 UTF-8。

示例 (PowerShell):

# 为当前会话设置
$env:PYTHONUTF8 = "1"

# 为用户持久设置
[System.Environment]::SetEnvironmentVariable('PYTHONUTF8', '1', [System.EnvironmentVariableTarget]::User)

设置¶

安装 LiteLLM:
```
pip install litellm
```
设置提供商 API 密钥： 将 API 密钥配置为你打算使用的特定提供商的环境变量。
- OpenAI 示例：
```
export OPENAI_API_KEY="你的_OPENAI_API_KEY"
```
- Anthropic（非 Agent Platform）示例：
```
export ANTHROPIC_API_KEY="你的_ANTHROPIC_API_KEY"
```
- 有关其他提供商的正确环境变量名称，请参阅 LiteLLM 提供商文档。

示例实现¶

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

# --- 使用 OpenAI GPT-4o 的示例智能体 ---
# (需要配置 OPENAI_API_KEY)
agent_openai = LlmAgent(
    model=LiteLlm(model="openai/gpt-4o"), # LiteLLM 模型字符串格式
    name="openai_agent",
    instruction="你是一个由 GPT-4o 驱动的得力助手。",
    # ... 其他智能体参数
)

# --- 使用 Anthropic Claude Haiku (非 Vertex) 的示例智能体 ---
# (需要配置 ANTHROPIC_API_KEY)
agent_claude_direct = LlmAgent(
    model=LiteLlm(model="anthropic/claude-3-haiku-20240307"),
    name="claude_direct_agent",
    instruction="你是一个由 Claude Haiku 驱动的助手。",
    # ... 其他智能体参数
)

Anthropic 思考块¶

Supported in ADKPython v1.28.0

当你通过 LiteLlm 连接器使用 Anthropic Claude 模型（如 Claude 3.7 Sonnet）时，ADK 支持 Anthropic 的结构化推理功能，称为"思考块"。ADK 会自动提取 thinking_blocks 及其签名。

Anthropic 要求在多轮对话中将这些签名发送回去，否则会在第一轮之后静默丢弃思考内容。ADK 在每个出站请求中都会重建带有签名的 thinking_blocks，因此 Claude 的推理会在工具调用和多轮交互中得到保留，无需你进行任何自定义状态管理。