AI - Agent 到底怎么“接模型”？怎么认证？公司网关/本地模型怎么接？

Agent 到底怎么"接模型"？怎么认证？公司网关/本地模型怎么接？

[ADK 中的 "Model" 是什么概念？](#ADK 中的 “Model” 是什么概念？)
[一、ADK 接入模型的两种机制](#一、ADK 接入模型的两种机制)
- [1. Direct String / Registry（直接字符串 / 注册表解析）](#1. Direct String / Registry（直接字符串 / 注册表解析）)
- [2. Wrapper Classes（包装类）](#2. Wrapper Classes（包装类）)
[二、Gemini 模型：ADK "一等公民"的用法与能力点](#二、Gemini 模型：ADK “一等公民”的用法与能力点)
- [1. Gemini Interactions API：长对话更省带宽/更高效](#1. Gemini Interactions API：长对话更省带宽/更高效)
- - [1.1 如何启用](#1.1 如何启用)
  - [1.2 限制](#1.2 限制)
[三、Gemini model authentication（Gemini 模型认证）](#三、Gemini model authentication（Gemini 模型认证）)
- [3.1 语音/视频 streaming 的模型要求（Live API）](#3.1 语音/视频 streaming 的模型要求（Live API）)
- [3.2 Google AI Studio（最简单的方式）](#3.2 Google AI Studio（最简单的方式）)
- [3.3 Google Cloud Vertex AI（生产推荐平台）](#3.3 Google Cloud Vertex AI（生产推荐平台）)
- - [Method A：User Credentials（本地开发）](#Method A：User Credentials（本地开发）)
  - [Method B：Vertex AI Express Mode（快速原型）](#Method B：Vertex AI Express Mode（快速原型）)
  - [Method C：Service Account（生产/自动化）](#Method C：Service Account（生产/自动化）)
- [3.5 常见错误与治理：429 RESOURCE_EXHAUSTED（配额/限流）](#3.5 常见错误与治理：429 RESOURCE_EXHAUSTED（配额/限流）)
[四、Using Anthropic models（使用 Anthropic 模型）](#四、Using Anthropic models（使用 Anthropic 模型）)
[五、Using Apigee gateway for AI models（用 Apigee 作为 AI 网关）](#五、Using Apigee gateway for AI models（用 Apigee 作为 AI 网关）)
[六、Using Cloud & Proprietary Models via LiteLLM（用 LiteLLM 接云上/闭源模型）](#六、Using Cloud & Proprietary Models via LiteLLM（用 LiteLLM 接云上/闭源模型）)
[七、本地模型：Ollama + LiteLLM（离线/隐私/省钱）](#七、本地模型：Ollama + LiteLLM（离线/隐私/省钱）)
- [7.1 Ollama Integration](#7.1 Ollama Integration)
- [7.2 要用 ollama_chat provider，不要用 ollama](#7.2 要用 ollama_chat provider，不要用 ollama)
- [7.3 Using openai provider（把本地 Ollama 当 OpenAI 兼容接口用）](#7.3 Using openai provider（把本地 Ollama 当 OpenAI 兼容接口用）)
- [7.4 Debugging（调试 Ollama/LiteLLM 请求）](#7.4 Debugging（调试 Ollama/LiteLLM 请求）)
- [7.5 自建推理服务：vLLM 这类 OpenAI-Compatible Endpoint](#7.5 自建推理服务：vLLM 这类 OpenAI-Compatible Endpoint)
[八、Using Hosted & Tuned Models on Vertex AI（使用 Vertex AI Endpoints 上的托管/微调模型）](#八、Using Hosted & Tuned Models on Vertex AI（使用 Vertex AI Endpoints 上的托管/微调模型）)
- [8.1 Model Garden Deployments](#8.1 Model Garden Deployments)
- [8.2 Fine-tuned Model Endpoints](#8.2 Fine-tuned Model Endpoints)
- [8.3 Third-Party Models on Vertex AI（例如 Anthropic Claude）](#8.3 Third-Party Models on Vertex AI（例如 Anthropic Claude）)

随着生成式 AI 的快速发展，AI Agent（智能代理）成为了构建自动化智能系统的重要组成部分。Google 推出的 Agent Development Kit（ADK）是一个开源框架，旨在让开发者更简单、更灵活地构建、测试和部署 AI Agents。它不仅支持多种语言（如 Python、TypeScript、Go 和 Java），还提供了便于与不同语言模型（LLMs）集成的机制。

本篇帮助你理解如何在 ADK 中使用不同的语言模型，并安全地进行身份认证配置。更多 AI 系列文章，请参考《AI 入门》

ADK 中的 "Model" 是什么概念？

在 ADK 里，Model 并不是一个 Agent，而是：

LlmAgent 用来做推理 / 生成的底层大模型配置。

你可以理解为：

Agent = 行为 + 规则 + 工具 + 工作流
Model = Agent 用来"思考和说话"的大脑

ADK 把"Agent 的逻辑"和"底层模型的选择"解耦开来，这一点非常重要：

同一个 Agent 逻辑，可以随时换模型，而不需要改业务代码。

一、ADK 接入模型的两种机制

ADK 的核心设计之一是模型无关性（model-agnostic） ------这意味着你可以使用 Google 自家的 Gemini 模型（ADK 的一等公民，最推荐，最完整 ），也可以接入第三方或本地部署的 LLM（可以接，但能力完整度不保证 ）。

ADK 主要用两种机制集成模型：

1. Direct String / Registry（直接字符串 / 注册表解析）

适用范围：

与 Google 生态深度集成的模型（例如：通过 Google AI Studio 或 Vertex AI 访问的 Gemini）
部署在 Vertex AI Endpoints 上的模型（用 endpoint 资源字符串）

做法：把模型名或 endpoint resource string 直接传给 LlmAgent(model=...)；ADK 内部 registry 会把该字符串解析到正确的后端 client，并调用对应的推理接口，通常会利用 google-genai。

python 复制代码

agent = LlmAgent(model="gemini-2.0-flash", ...)
# 或者：agent = LlmAgent(model="projects/.../locations/.../endpoints/...", ...)

⚡️ 这个方式非常适合快速开始，因为你不需要手动配置低层的客户端。

2. Wrapper Classes（包装类）

适用范围：

Google 体系外的模型（OpenAI / Anthropic / Cohere...）
你需要特殊客户端配置/企业治理（比如 Apigee 网关）
你要接本地模型（Ollama）或自建推理服务（vLLM）

做法：实例化 wrapper（如 ApigeeLlm / LiteLlm），把对象传给 LlmAgent(model=...)

python 复制代码

agent = LlmAgent(model=ApigeeLlm(...), ...)
agent = LlmAgent(model=LiteLlm(...), ...)

二、Gemini 模型：ADK "一等公民"的用法与能力点

ADK 对 Gemini 家族模型有比较完整的能力支持，比如 Code Execution、Google Search、Context caching、Computer use，以及一个很关键的 Interactions API。

1. Gemini Interactions API：长对话更省带宽/更高效

Interactions API 是 generateContent 推理 API 的替代方案，提供有状态对话：你可以用 previous_interaction_id 串联对话，而不必每次请求都携带完整历史；长对话更高效。

1.1 如何启用

在 Gemini 模型配置里设置 use_interactions_api=True。

python 复制代码

model=Gemini(model="gemini-2.5-flash", use_interactions_api=True)

tools 同时包含：

GoogleSearchTool(bypass_multi_tools_limit=True)（将内置搜索"转换为函数工具"）

示例：

python 复制代码

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,  # Enable Interactions API
    ),
    name="interactions_test_agent",
    tools=[
        GoogleSearchTool(bypass_multi_tools_limit=True),  # Converted to function tool
        get_current_weather,  # Custom function tool
    ],
)

1.2 限制

不能把"内置工具"和"自定义函数工具"混用：

Interactions API 不支持在同一个 agent 里混用「自定义 function-calling 工具」和「内置工具（例如 Google Search）」

解决方案：把内置工具"改造成自定义工具形态"，方式是给 GoogleSearchTool 配置 bypass_multi_tools_limit=True：

python 复制代码

GoogleSearchTool(bypass_multi_tools_limit=True)

这个选项会把内置 google_search 转为函数调用工具（via GoogleSearchAgentTool），从而能和自定义函数工具共存。

Interactions API 这条链路里，"工具体系"需要统一成函数调用风格，避免混搭。

三、Gemini model authentication（Gemini 模型认证）

Gemini 的认证分成两大块：

Google AI Studio：适合快速开始
Google Cloud Vertex AI：适合生产、规模化与企业治理

通过认证并使用 Gemini；这是在 ADK 里使用 Google 旗舰模型最直接的方式, 认证完成后：你就可以把模型标识符字符串直接传给 LlmAgent 的 model 参数（即 "Direct String / Registry" 路径）。
Tip：ADK 内部用于 Gemini 的 google-genai，既可连 AI Studio，也可连 Vertex AI。

3.1 语音/视频 streaming 的模型要求（Live API）

要在 ADK 里使用 voice/video streaming，需要使用支持 Live API 的 Gemini 模型；具体支持的 model ID 需要到官方 Live API 文档查（Google AI Studio / Vertex AI 各有页面）。

3.2 Google AI Studio（最简单的方式）

这是最简单、推荐快速上手的方法。

Authentication Method：API Key
Setup：
- 从 Google AI Studio 获取 API key
- 在项目根目录创建 .env（Python）或 .properties（Java），ADK 会自动加载
- 配置环境变量：
  GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
  GOOGLE_GENAI_USE_VERTEXAI=FALSE
Models：所有可用模型在 "Google AI for Developers site" 查询

3.3 Google Cloud Vertex AI（生产推荐平台）

Vertex AI 更适合可扩展、生产导向场景，并提供企业级特性、安全与合规控制；你需要根据开发环境/用例选择认证方式。前置条件：启用 Vertex AI 的 GCP Project。

Method A：User Credentials（本地开发）

步骤：

安装 gcloud CLI（按官方安装说明）
使用 ADC 登录（会打开浏览器认证）：gcloud auth application-default login
设置环境变量：

GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"

GOOGLE_CLOUD_LOCATION="YOUR_VERTEX_AI_LOCATION"（例如：us-central1）

并显式指定使用 Vertex：GOOGLE_GENAI_USE_VERTEXAI=TRUE
模型 ID 去 Vertex AI 文档查

Method B：Vertex AI Express Mode（快速原型）

Express Mode 提供基于 API key 的简化配置，适合快速原型。步骤：

注册 Express Mode 获取 API key
设置：
GOOGLE_API_KEY="PASTE_YOUR_EXPRESS_MODE_API_KEY_HERE"
GOOGLE_GENAI_USE_VERTEXAI=TRUE

Method C：Service Account（生产/自动化）

部署应用通常用服务账号。步骤：

创建 Service Account，并赋予 Vertex AI User 角色
提供凭证：
- 在 Google Cloud 环境（Cloud Run / GKE / VM 等），环境可自动提供服务账号凭证，不一定需要 key file
- 在其他环境，创建服务账号 key file，并设置环境变量：
  - GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"
也可以用 Workload Identity 替代 key file，但超出本文档范围

示例：

python 复制代码

from google.adk.agents import LlmAgent

# --- Example using a stable Gemini Flash model ---
agent_gemini_flash = LlmAgent(
    # Use the latest stable Flash model identifier
    model="gemini-2.0-flash",
    name="gemini_flash_agent",
    instruction="You are a fast and helpful Gemini assistant.",
    # ... other agent parameters
)

# --- Example using a powerful Gemini Pro model ---
# Note: Always check the official Gemini documentation for the latest model names,
# including specific preview versions if needed. Preview models might have
# different availability or quota limitations.
agent_gemini_pro = LlmAgent(
    # Use the latest generally available Pro model identifier
    model="gemini-2.5-pro-preview-03-25",
    name="gemini_pro_agent",
    instruction="You are a powerful and knowledgeable Gemini assistant.",
    # ... other agent parameters
)

核心表达：

示例包含 "stable Gemini Flash" 的创建（例如 model="gemini-2.0-flash"）
也包含 "Gemini Pro" 示例，并提醒：要以官方 Gemini 文档为准，注意 preview model 的名称、可用性和 quota 限制

3.5 常见错误与治理：429 RESOURCE_EXHAUSTED（配额/限流）

429 通常是请求数超过了分配容量。缓解方式：

为目标模型申请更高 quota
启用客户端重试（client-side retries）

两种配置 retry 的方式：

Option 1：在 Agent 的 generate_content_config 里设置（http_options.retry_options），示例使用
types.HttpRetryOptions(initial_delay=1, attempts=2)

python 复制代码

root_agent = Agent(
    model='gemini-2.0-flash',
    ...
    generate_content_config=types.GenerateContentConfig(
        ...
        http_options=types.HttpOptions(
            ...
            retry_options=types.HttpRetryOptions(initial_delay=1, attempts=2),
            ...
        ),
        ...
    )

Option 2：在模型 adapter 上设置 retry（当你自己实例化 adapter 时），示例是 Gemini(retry_options=...)

python 复制代码

from google.genai import types

# ...

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

四、Using Anthropic models（使用 Anthropic 模型）

Anthropic 目前的模型主线叫 Claude，和 Gemini / GPT 类似，也是多模态大模型家族，特点是强调安全性、对齐和长上下文。

在 Java ADK 中使用 Claude wrapper class，既可以直连 Anthropic API key，也可以通过 Vertex AI backend（Vertex 相关见后面的 "Third-Party Models on Vertex AI"）。

Prerequisites：

Dependencies：Java ADK 的 Claude wrapper 依赖 Anthropic 官方 Java SDK 的类，通常作为传递依赖（transitive）存在
Anthropic API Key：从 Anthropic 获取，并用 secret manager 管理

Integration步骤：

实例化 com.google.adk.models.Claude，提供模型名
用 AnthropicOkHttpClient 配置 API key
把 Claude 实例传给 LlmAgent

完整 Java 示例代码（DirectAnthropicAgent）。

java 复制代码

import com.anthropic.client.AnthropicClient;
import com.google.adk.agents.LlmAgent;
import com.google.adk.models.Claude;
import com.anthropic.client.okhttp.AnthropicOkHttpClient; // From Anthropic's SDK

public class DirectAnthropicAgent {

  private static final String CLAUDE_MODEL_ID = "claude-3-7-sonnet-latest"; // Or your preferred Claude model

  public static LlmAgent createAgent() {

    // It's recommended to load sensitive keys from a secure config
    AnthropicClient anthropicClient = AnthropicOkHttpClient.builder()
        .apiKey("ANTHROPIC_API_KEY")
        .build();

    Claude claudeModel = new Claude(
        CLAUDE_MODEL_ID,
        anthropicClient
    );

    return LlmAgent.builder()
        .name("claude_direct_agent")
        .model(claudeModel)
        .instruction("You are a helpful AI assistant powered by Anthropic Claude.")
        // ... other LlmAgent configurations
        .build();
  }

  public static void main(String[] args) {
    try {
      LlmAgent agent = createAgent();
      System.out.println("Successfully created direct Anthropic agent: " + agent.name());
    } catch (IllegalStateException e) {
      System.err.println("Error creating agent: " + e.getMessage());
    }
  }
}

五、Using Apigee gateway for AI models（用 Apigee 作为 AI 网关）

Apigee 是 Google Cloud 提供的一个 API 管理平台，用来统一管理、保护和监控对外/对内开放的接口

可以把"Apigee 作为 AI 网关"理解成：

在"你的应用 ↔ 各种大模型服务（Gemini、Claude、OpenAI 等）"之间，再加一层统一的 API 门面和治理层。

Apigee 作为 AI Gateway，把你的模型 endpoint（例如 Vertex AI 或 Gemini API）暴露在 Apigee proxy 后面，可获得企业级能力：

Model Safety：例如 Model Armor 的威胁防护
Traffic Governance：Rate Limiting、Token Limiting（成本与滥用控制）
Performance：Semantic Caching、模型路由
Monitoring & Visibility：对 AI 请求做监控/分析/审计

NOTE：ApigeeLLM wrapper 当前主要面向 Vertex AI 与 Gemini API（generateContent），后续会扩展支持。

示例：核心是先创建 ApigeeLlm，再把它传给 LlmAgent

python 复制代码

from google.adk.agents import LlmAgent
from google.adk.models.apigee_llm import ApigeeLlm

# Instantiate the ApigeeLlm wrapper
model = ApigeeLlm(
    # Specify the Apigee route to your model. For more info, check out the ApigeeLlm documentation (https://github.com/google/adk-python/tree/main/contributing/samples/hello_world_apigeellm).
    model="apigee/gemini-2.5-flash",
    # The proxy URL of your deployed Apigee proxy including the base path
    proxy_url=f"https://{APIGEE_PROXY_URL}",
    # Pass necessary authentication/authorization headers (like an API key)
    custom_headers={"foo": "bar"}
)

# Pass the configured model wrapper to your LlmAgent
agent = LlmAgent(
    model=model,
    name="my_governed_agent",
    instruction="You are a helpful assistant powered by Gemini and governed by Apigee.",
    # ... other agent parameters
)

这样配置后，每次 agent 的 API 调用都会先经过 Apigee，执行安全、限流、日志等策略，再转发到实际模型 endpoint。并提供 "Hello World Apigee LLM" 完整示例链接。

六、Using Cloud & Proprietary Models via LiteLLM（用 LiteLLM 接云上/闭源模型）

LiteLLM 是"统一适配层"

不同云上 / 闭源模型（Gemini、Claude、OpenAI、Azure OpenAI...）各有自己的 REST API、鉴权方式、参数格式。
LiteLLM 做的事情就是：把这些差异都"吃掉"，对外暴露一个统一的调用接口（类似 "OpenAI 风格的 /v1/chat/completions"）。
你的应用只需要会说 "LiteLLM 的语言"，不需要针对每家云单独写一套 SDK / Client。

通过 LiteLLM 接入 OpenAI、Anthropic（非 Vertex）、Cohere 等众多 provider。集成方式：实例化 LiteLlm wrapper，传给 LlmAgent(model=...)。

LiteLLM 的定位：translation layer，提供标准化的、OpenAI 兼容接口，覆盖 100+ LLM。

Setup：

安装：pip install litellm
配置 provider API keys 到环境变量（示例给了 OPENAI_API_KEY、ANTHROPIC_API_KEY；其他 provider 变量名去 LiteLLM Providers 文档查）

示例：

OpenAI GPT-4o：LiteLlm(model="openai/gpt-4o")
Anthropic Claude Haiku（非 Vertex）：LiteLlm(model="anthropic/claude-3-haiku-20240307")

python 复制代码

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

# --- Example Agent using OpenAI's GPT-4o ---
# (Requires OPENAI_API_KEY)
agent_openai = LlmAgent(
    model=LiteLlm(model="openai/gpt-4o"), # LiteLLM model string format
    name="openai_agent",
    instruction="You are a helpful assistant powered by GPT-4o.",
    # ... other agent parameters
)

# --- Example Agent using Anthropic's Claude Haiku (non-Vertex) ---
# (Requires ANTHROPIC_API_KEY)
agent_claude_direct = LlmAgent(
    model=LiteLlm(model="anthropic/claude-3-haiku-20240307"),
    name="claude_direct_agent",
    instruction="You are an assistant powered by Claude Haiku.",
    # ... other agent parameters
)

Windows Encoding Note：

在 Windows 上可能遇到 UnicodeDecodeError，原因是 LiteLLM 可能用默认编码 cp1252 读取缓存而非 UTF-8；建议设置 PYTHONUTF8=1（PowerShell 给了临时与持久两种设置示例）。

bash 复制代码

# Set for the current session
$env:PYTHONUTF8 = "1"

# Set persistently for the user
[System.Environment]::SetEnvironmentVariable('PYTHONUTF8', '1', [System.EnvironmentVariableTarget]::User)

七、本地模型：Ollama + LiteLLM（离线/隐私/省钱）

为了最大控制、节约成本、隐私或离线用途，你可以本地运行开源模型或自建推理服务；用 LiteLLM 指向本地模型 server 即可。

7.1 Ollama Integration

Ollama：用于在本地运行开源模型。

Ollama = 在你本机/服务器上跑大模型的"本地推理服务"（如 Llama 3、Qwen 等）。

它暴露一个本地 HTTP 接口（默认 http://localhost:11434），你用 REST 或 SDK 调它。

模型选择

如果 agent 依赖 tools，需要选支持 tool 的模型；建议选"体量合适且支持 tool"的模型。

检查方式：用 ollama show ...，并确认 Capabilities 下面有 tools。

bash 复制代码

ollama show mistral-small3.1
  Model
    architecture        mistral3
    parameters          24.0B
    context length      131072
    embedding length    5120
    quantization        Q4_K_M

  Capabilities
    completion
    vision
    tools

模板（template）与"无限工具循环"风险

某些模型的默认 template 会"强暗示模型一直输出函数调用 JSON"，从而导致无限循环。

建议你导出 modelfile、修改模板提示词、更换为更合理的"是否需要调用工具"的判断逻辑，再 ollama create 生成新模型。

7.2 要用 ollama_chat provider，不要用 ollama

LiteLLM wrapper 可用于创建 Ollama 模型 agent；示例用 LiteLlm(model="ollama_chat/mistral-small3.1")，并挂载 roll_die、check_prime 两个工具。
关键强调：必须用 ollama_chat provider，而不是 ollama。否则可能出现无限工具循环、忽略历史上下文等异常行为。

环境变量建议：尽管生成时可在 LiteLLM 里传 api_base，在完成后调用其他 API 时依赖环境变量；因此建议设置：

OLLAMA_API_BASE="http://localhost:11434"

然后运行 adk web。

python 复制代码

root_agent = Agent(
    model=LiteLlm(model="ollama_chat/mistral-small3.1"),
    name="dice_agent",
    description=(
        "hello world agent that can roll a dice of 8 sides and check prime"
        " numbers."
    ),
    instruction="""
      You roll dice and answer questions about the outcome of the dice rolls.
    """,
    tools=[
        roll_die,
        check_prime,
    ],
)

7.3 Using openai provider（把本地 Ollama 当 OpenAI 兼容接口用）

替代方案：把 Ollama 当成 OpenAI 兼容服务来连（provider 用 openai），但需要改用环境变量：

OPENAI_API_BASE=http://localhost:11434/v1（注意末尾必须有 /v1）
OPENAI_API_KEY=anything
并给了对应 LiteLlm(model="openai/mistral-small3.1") 的示例和 adk web 运行方式。

python 复制代码

root_agent = Agent(
    model=LiteLlm(model="openai/mistral-small3.1"),
    name="dice_agent",
    description=(
        "hello world agent that can roll a dice of 8 sides and check prime"
        " numbers."
    ),
    instruction="""
      You roll dice and answer questions about the outcome of the dice rolls.
    """,
    tools=[
        roll_die,
        check_prime,
    ],
)

7.4 Debugging（调试 Ollama/LiteLLM 请求）

在 agent 代码 imports 后加入：

python 复制代码

import litellm
litellm._turn_on_debug()

然后在日志里找 "Request Sent from LiteLLM:" 以及对应 curl 请求示例。

bash 复制代码

Request Sent from LiteLLM:
curl -X POST \
http://localhost:11434/api/chat \
-d '{'model': 'mistral-small3.1', 'messages': [{'role': 'system', 'content': ...

7.5 自建推理服务：vLLM 这类 OpenAI-Compatible Endpoint

vLLM 等工具可高效托管模型，并经常暴露 OpenAI-compatible API endpoint。

vLLM 可以理解成一个高性能大模型推理/服务引擎，主要用来在自己的服务器/GPU 上高效部署和托管 LLM。

vLLM 是一个专门为"大模型在线推理"做性能优化的开源引擎，用来在你自己的算力上高效地跑和服务 LLM。

步骤：

部署模型并记录 API base（示例：https://.../v1）
- Important for ADK Tools：要用 ADK tools，需要 serving 端支持并启用 OpenAI-compatible tool/function calling；vLLM 可能需要类似
  --enable-auto-tool-choice、以及可能的 --tool-call-parser（与模型相关），参考 vLLM Tool Use 文档。
确定 endpoint 的认证方式（API key / bearer token 等）

示例：

LiteLlm(model=..., api_base=..., extra_headers=...)
示例里通过 gcloud auth print-identity-token -q 获取 Cloud Run 的 identity token，用作 Authorization: Bearer ...；获取失败则打印 warning 并把 headers 设为 None。

python 复制代码

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

# --- Example Agent using a model hosted on a vLLM endpoint ---

# Endpoint URL provided by your vLLM deployment
api_base_url = "https://your-vllm-endpoint.run.app/v1"

# Model name as recognized by *your* vLLM endpoint configuration
model_name_at_endpoint = "hosted_vllm/google/gemma-3-4b-it" # Example from vllm_test.py

# Authentication (Example: using gcloud identity token for a Cloud Run deployment)
# Adapt this based on your endpoint's security
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"Warning: Could not get gcloud token - {e}. Endpoint might be unsecured or require different auth.")
    auth_headers = None # Or handle error appropriately

agent_vllm = 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"
    ),
    name="vllm_agent",
    instruction="You are a helpful assistant running on a self-hosted vLLM endpoint.",
    # ... other agent parameters
)

八、Using Hosted & Tuned Models on Vertex AI（使用 Vertex AI Endpoints 上的托管/微调模型）

为了企业级可扩展性、可靠性和与 Google Cloud MLOps 的集成，可以使用部署到 Vertex AI Endpoints 的模型（包括 Model Garden 模型与自建微调模型）。

集成方式（Direct String）：把 endpoint 资源字符串直接传给 LlmAgent(model=...)：

projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID。

Vertex AI Setup（Consolidated）：

Application Default Credentials (ADC)：

gcloud auth application-default login
环境变量：

GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"

GOOGLE_CLOUD_LOCATION="YOUR_VERTEX_AI_LOCATION"
启用 Vertex 后端：

GOOGLE_GENAI_USE_VERTEXAI=TRUE

8.1 Model Garden Deployments

你可以从 Vertex AI Model Garden 部署多种开源或闭源模型到 endpoint。

示例：

一个 Llama 3 endpoint 字符串
LlmAgent(model=llama3_endpoint, ...)
并示例使用 types.GenerateContentConfig(max_output_tokens=2048)。

python 复制代码

from google.adk.agents import LlmAgent
from google.genai import types # For config objects

# --- Example Agent using a Llama 3 model deployed from Model Garden ---

# Replace with your actual Vertex AI Endpoint resource name
llama3_endpoint = "projects/YOUR_PROJECT_ID/locations/us-central1/endpoints/YOUR_LLAMA3_ENDPOINT_ID"

agent_llama3_vertex = LlmAgent(
    model=llama3_endpoint,
    name="llama3_vertex_agent",
    instruction="You are a helpful assistant based on Llama 3, hosted on Vertex AI.",
    generate_content_config=types.GenerateContentConfig(max_output_tokens=2048),
    # ... other agent parameters
)

8.2 Fine-tuned Model Endpoints

把你微调的模型（基于 Gemini 或 Vertex 支持的其他架构）部署后会得到 endpoint，可直接使用。示例展示了一个 fine-tuned Gemini endpoint 字符串并传给 LlmAgent(model=...)。

python 复制代码

from google.adk.agents import LlmAgent

# --- Example Agent using a fine-tuned Gemini model endpoint ---

# Replace with your fine-tuned model's endpoint resource name
finetuned_gemini_endpoint = "projects/YOUR_PROJECT_ID/locations/us-central1/endpoints/YOUR_FINETUNED_ENDPOINT_ID"

agent_finetuned_gemini = LlmAgent(
    model=finetuned_gemini_endpoint,
    name="finetuned_gemini_agent",
    instruction="You are a specialized assistant trained on specific data.",
    # ... other agent parameters
)

8.3 Third-Party Models on Vertex AI（例如 Anthropic Claude）

一些供应商（如 Anthropic）也允许通过 Vertex AI 直接使用其模型。

Python：direct model string + 需要手动注册

Integration Method：使用类似 "claude-3-sonnet@20240229" 的直接模型字符串，但必须在 ADK 中手动注册。

Why Registration：

ADK registry 会自动识别 gemini-* 和标准 Vertex endpoint 字符串，并通过 google-genai 路由
对于其他"通过 Vertex 但用直连模型字符串"的类型（如 Claude），你必须告诉 ADK registry 哪个 wrapper class（此处是 Claude）能处理该标识符。

Setup：

完成 consolidated Vertex AI setup（ADC + env vars + GOOGLE_GENAI_USE_VERTEXAI=TRUE）
安装 provider library：pip install "anthropic $vertex$ "
应用启动时注册：

python 复制代码

	# Required for using Claude model strings directly via Vertex AI with LlmAgent
	from google.adk.models.anthropic_llm import Claude
	from google.adk.models.registry import LLMRegistry
	LLMRegistry.register(Claude)

示例：

python 复制代码

from google.adk.agents import LlmAgent
from google.adk.models.anthropic_llm import Claude # Import needed for registration
from google.adk.models.registry import LLMRegistry # Import needed for registration
from google.genai import types

# --- Register Claude class (do this once at startup) ---
LLMRegistry.register(Claude)

# --- Example Agent using Claude 3 Sonnet on Vertex AI ---

# Standard model name for Claude 3 Sonnet on Vertex AI
claude_model_vertexai = "claude-3-sonnet@20240229"

agent_claude_vertexai = LlmAgent(
    model=claude_model_vertexai, # Pass the direct string after registration
    name="claude_vertexai_agent",
    instruction="You are an assistant powered by Claude 3 Sonnet on Vertex AI.",
    generate_content_config=types.GenerateContentConfig(max_output_tokens=4096),
    # ... other agent parameters
)