Google ADK搭建基于Kimi K3的智能体详细教程

从实践来看，要在国内环境中用上Google ADK这样的框架，并顺利把它和自己熟悉的国产模型对接起来，并不是一件特别顺滑的事。Google在2025年4月对外开源了Agent Development Kit（ADK），这是一个以代码为核心的框架，专门用来构建、评估和部署复杂的AI智能体以及多智能体系统。理想很丰满，现实是，由于某些众所周知的原因，直接调用外网的大语言模型并不方便。好在国内模型生态其实早已百花齐放。经过一番资料检索和反复测试，最终成功通过Google ADK连接上了Kimi K3模型。过程虽然曲折，但结果值得记录。通过同样的思路，也可以搭建基于其他模型的智能体。下面就把整个过程拆解开来，一步步走通。

一、安装Google ADK库

这一步最简单，直接使用pip命令：

pip install google-adk

二、创建项目的目录层次结构

首先，需要搭建一个干净的项目目录。结构如下：

multi_tool_agent |-
|- .env
|- __init__.py
|- agent.py

1.1 定义.env

.env文件用来存放环境变量，这是连接外部API的关键。既然要访问Kimi K3模型，就需要在官网申请好API密钥，然后在文件中配置：

# 设置kimi官方开放平台申请API密钥
MOONSHOT_API_KEY="你的kimi-k3模型的API密钥"
# 设置访问的模型的基址
MOONSHOT_API_BASE="https://api.moonshot.cn/v1"

1.2 __init__.py

这个文件用于将agent模块导入包中，内容很简单：

from . import agent

二、在agent.py文件中调用kimi-k3模型

核心代码都集中在agent.py中，这里需要分几个步骤来配置。

2.1 配置LiteLlm

LiteLlm是Google ADK连接不同模型后端的桥梁，需要提前做一些网络和成本方面的配置，避免潜在的连接问题：

import os
import litellm
# LiteLLM 配置
# 禁用远程成本映射获取（避免网络问题）
litellm.local_model_cost_map = True
# 禁用远程成本映射获取（避免网络问题）
os.environ["LITELLM_LOCAL_MODEL_COST_MAP"] = "True"
# 设置 LiteLLM 日志级别为 ERROR（避免过多日志输出）
os.environ["LITELLM_LOG"] = "ERROR"
# 设置 LiteLLM 请求超时时间为 60 秒（避免网络问题）
os.environ["LITELLM_REQUEST_TIMEOUT"] = "60"
# 为 LiteLLM 添加一个“非官方/自定义”kimi-k3模型的配置
# 注册 kimi-k3 模型成本
litellm.model_cost = litellm.model_cost or {}
litellm.model_cost["moonshot/kimi-k3"] = {
    "input_cost_per_token": 0.000001,
    "output_cost_per_token": 0.000002,
    "litellm_provider": "openai",
    "mode": "chat",
    "supports_system_messages": True,
    "supports_function_calls": True,
}
print("自定义LiteLLM 配置完成")

这里需要格外留意的是，必须手动注册Kimi K3模型的成本信息，否则后续调用时会报错。另外，禁用远程成本映射和设置超时时间，是为了避免网络波动导致的问题，非常实用。

2.2 导入Google ADK库和配置环境变量

接下来，需要用dotenv加载环境变量，并导入ADK的核心库：

# 利用load_dotenv加载当前目录的.env文件的环境变量 
from dotenv import load_dotenv
load_dotenv()
# 导入google adk的相关库
from google.adk.models.lite_llm import LiteLlm
from google.adk.tools import FunctionTool
from google.adk.agents import Agent  

2.3 定义函数工具

用@FunctionTool装饰器来定义一个工具函数，这是智能体执行具体操作的能力单位。这里用一个模拟的天气查询工具来演示：

@FunctionTool
def get_weather(city: str) -> dict:
    """
    获取指定城市的天气信息.
    Args:
        city (str): 城市名称.
    Returns:
        dict: 状态和结果或错误的信息.
    """
    if city == "南昌":
        return {
            "status": "success",
            "report": (
                "今天南昌的天气是晴朗，最高气温为35摄氏度。"
                " 天气炎热，请注意防暑降温。"
            ),
        }
    else:
        return {
            "status": "error",
            "error_message": f"没有找到 '{city}' 的天气信息。",
        }

很可爱也很实用的一点是，工具函数可以返回标准化的状态和结果，智能体可以根据这些信息进行后续决策。当然，这只是模拟，真实场景中可以对接真实的天气API。

2.4 创建智能体

万事俱备，最后一步就是创建智能体对象。这里需要指定模型、指令和工具：

# 创建LiteLlm模型对象
model = LiteLlm(
        model="moonshot/kimi-k3",
        temperature=1,
        max_tokens=2048,
        extra_params={
            "api_base": os.getenv("MOONSHOT_API_BASE"),
            "api_key": os.getenv("MOONSHOT_API_KEY"),
        }
    )
# 创建智能体
root_agent = Agent(  
    name="weather_assistant",  
    model=model,  
    instruction="你是一个有帮助的助手。需要时使用get_weather工具获取天气信息。",  
    description="一个获取天气信息的助手。",  
    tools=[get_weather]  
)

注意，在创建LiteLlm对象时，通过extra_params传入了API基址和密钥，这是连接自定义模型的关键。

三、利用adk web在网页中测试连接是否成功

代码写完了，需要验证一下整个流程是否跑通。先在终端中进入项目目录的上级目录。下图展示了当前目录结构，方便确认文件位置是否正确：

图1 显示当前目录的所有下级目录

然后，运行启动命令：

adk web

这个命令会启动一个本地Web服务，默认在http://127.0.0.1:8000上提供智能体的交互界面。运行结果如下：

图2 调用adk web

之后，打开浏览器，输入http://127.0.0.1:8000，就能看到智能体的对话界面：

图3 启动成功

现在，分别在消息输入框中输入“南昌的天气”和“南京的天气”，看看kimi-k3模型如何调用get_weather工具并返回结果。运行结果清晰显示，智能体成功识别了工具调用，并返回了针对不同城市的响应：

图4 运行结果

从结果来看，连接链路是通的。这个思路完全可以复用，如果想换成其他国内模型，只需要修改.env中的API密钥和基址，并在LiteLlm配置中注册对应的模型名称和成本信息即可。

参考文献

• "Agent Development Kit: Making it easy to build multi agent applications" https://developers.googleblog.com/en/agent-development-kit-easy-to-build-multi-agent-applications [EB/OL]
• "DeepWiki google/adk-python Overview"
• https://deepwiki.com/google/adk-python/1-overview[EB/OL]