Google ADK 实战：用代码优先的方式构建 AI Agent

来源：google.github.io/adk-docs · google/adk-python · google/adk-java | 整理时间：2026-04-07

什么是 Google ADK？

Google Agent Development Kit（ADK）是 Google 推出的开源、代码优先的 Agent 开发框架。它的设计哲学是：用纯代码定义 Agent 的行为、工具和工作流，而不是依赖可视化拖拽或声明式配置。

关键数据

• 开源时间：2025 年 4 月首次发布
• 支持语言：Python、Java、Go、TypeScript（其中 Python 和 Java 已达 v1.0.0 稳定版）
• 许可证：Apache 2.0
• 模型支持：Gemini（深度优化）、Claude、Vertex AI、Ollama、vLLM、LiteLLM

与其他框架的定位差异

核心概念

四大支柱

Agent 类型

ADK 提供四种 Agent 类型，覆盖从简单到复杂的所有场景：

此外，你可以通过继承 BaseAgent 创建自定义 Agent。

安装

Python

pip install google-adk

Java（Maven）

<dependency>
    <groupId>com.google.adk</groupId>
    <artifactId>google-adk</artifactId>
    <version>1.0.0</version>
</dependency>

Java（Gradle）

implementation 'com.google.adk:google-adk:1.0.0'

Go

go get google.golang.org/adk

第一个 Agent（Python）

最简单的 Agent：城市时间查询

from google.adk.agents.llm_agent import Agent

def get_current_time(city: str) -> dict:
    """返回指定城市的当前时间。"""
    from datetime import datetime
    import zoneinfo

    timezone_map = {
        "北京": "Asia/Shanghai",
        "东京": "Asia/Tokyo",
        "纽约": "America/New_York",
        "伦敦": "Europe/London",
    }

    tz = timezone_map.get(city, "UTC")
    now = datetime.now(zoneinfo.ZoneInfo(tz))
    return {
        "status": "success",
        "city": city,
        "time": now.strftime("%Y-%m-%d %H:%M:%S"),
        "timezone": tz,
    }

root_agent = Agent(
    model="gemini-2.5-flash",
    name="time_agent",
    description="查询全球城市的当前时间。",
    instruction="""你是一个时间查询助手。
当用户询问某个城市的时间时，使用 get_current_time 工具查询。
用中文回答用户。""",
    tools=[get_current_time],
)

用 Runner 运行 Agent

from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService

# 创建会话服务
session_service = InMemorySessionService()

# 创建 Runner
runner = Runner(
    agent=root_agent,
    session_service=session_service,
    app_name="time_app",
)

# 创建会话
session = await session_service.create_session(
    user_id="user_1",
    app_name="time_app",
)

# 运行 Agent
from google.genai import types

user_message = types.Content(
    role="user",
    parts=[types.Part(text="现在北京几点了？")],
)

async for event in runner.run_async(
    user_id=session.user_id,
    session_id=session.id,
    new_message=user_message,
):
    if event.is_final_response():
        print(event.content.parts[0].text)

工具系统

内置工具

ADK 提供了多种开箱即用的工具：

搜索 Agent 示例

from google.adk.agents import Agent
from google.adk.tools import google_search

search_agent = Agent(
    name="search_assistant",
    model="gemini-2.5-flash",
    instruction="""你是一个搜索助手。
使用 Google 搜索来回答用户的问题。
优先引用搜索结果中的信息，并注明来源。""",
    description="一个可以搜索互联网的助手。",
    tools=[google_search],
)

自定义工具

任何 Python 函数都可以作为工具，ADK 会自动从函数签名和 docstring 中提取参数描述：

def calculate_mortgage(
    principal: float,
    annual_rate: float,
    years: int,
) -> dict:
    """计算房贷月供。

    Args:
        principal: 贷款总额（元）
        annual_rate: 年利率（百分比，如 3.5 表示 3.5%）
        years: 贷款年限

    Returns:
        包含月供和总利息的字典
    """
    monthly_rate = annual_rate / 100 / 12
    months = years * 12
    if monthly_rate == 0:
        monthly_payment = principal / months
    else:
        monthly_payment = principal * (
            monthly_rate * (1 + monthly_rate) ** months
        ) / ((1 + monthly_rate) ** months - 1)

    total_payment = monthly_payment * months
    total_interest = total_payment - principal

    return {
        "monthly_payment": round(monthly_payment, 2),
        "total_payment": round(total_payment, 2),
        "total_interest": round(total_interest, 2),
    }

finance_agent = Agent(
    name="finance_agent",
    model="gemini-2.5-flash",
    instruction="你是一个金融助手，帮助用户计算房贷。",
    tools=[calculate_mortgage],
)

MCP 工具

ADK 支持 Model Context Protocol（MCP），可以直接接入 MCP 服务器提供的工具：

from google.adk.tools.mcp_tool import MCPToolset
from mcp import StdioServerParameters

# 连接到 MCP 文件系统服务器
file_tools = MCPToolset(
    connection_params=StdioServerParameters(
        command="npx",
        args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    )
)

file_agent = Agent(
    name="file_agent",
    model="gemini-2.5-flash",
    instruction="你可以读写 /tmp 目录下的文件。",
    tools=[file_tools],
)

多 Agent 编排

层级式编排（子 Agent）

通过 sub_agents 将多个 Agent 组合成层级结构：

from google.adk.agents import LlmAgent, SequentialAgent

# 专家 Agent
greeter = LlmAgent(
    name="greeter",
    model="gemini-2.5-flash",
    instruction="你负责热情地问候用户，用中文打招呼。",
)

task_executor = LlmAgent(
    name="task_executor",
    model="gemini-2.5-flash",
    instruction="你负责执行用户的具体任务请求。",
)

# 协调者 Agent
coordinator = LlmAgent(
    name="coordinator",
    model="gemini-2.5-flash",
    instruction="""你是协调者，根据用户的请求分配给合适的子 Agent。
- 简单打招呼交给 greeter
- 具体任务交给 task_executor""",
    description="协调多个专家 Agent 为用户服务。",
    sub_agents=[greeter, task_executor],
)

顺序执行

from google.adk.agents import SequentialAgent

pipeline = SequentialAgent(
    name="research_pipeline",
    sub_agents=[
        research_agent,   # 步骤 1：研究
        writer_agent,     # 步骤 2：写作
        reviewer_agent,   # 步骤 3：审查
    ],
)

并行执行

from google.adk.agents import ParallelAgent

parallel_analysis = ParallelAgent(
    name="parallel_analysis",
    sub_agents=[
        sentiment_agent,  # 同时分析情感
        summary_agent,    # 同时生成摘要
        keyword_agent,    # 同时提取关键词
    ],
)

循环执行

from google.adk.agents import LoopAgent

refinement_loop = LoopAgent(
    name="refinement_loop",
    max_iterations=3,
    sub_agents=[
        writer_agent,     # 写一版
        reviewer_agent,   # 审查并给出修改建议
    ],
)

复杂编排示例

将多种编排模式组合使用：

# 完整的研究-写作-审查流水线
research_pipeline = SequentialAgent(
    name="research_pipeline",
    sub_agents=[
        # 先并行收集多方面信息
        ParallelAgent(
            name="info_gathering",
            sub_agents=[
                web_search_agent,    # 网络搜索
                database_agent,      # 数据库查询
            ],
        ),
        # 然后循环写作和审查
        LoopAgent(
            name="write_review_loop",
            max_iterations=3,
            sub_agents=[
                writer_agent,
                reviewer_agent,
            ],
        ),
    ],
)

Java 版本示例

ADK 的 Java API 与 Python 保持一致的设计风格：

import com.google.adk.agents.LlmAgent;
import com.google.adk.tools.FunctionTool;

// 定义工具方法
public class HelloTimeAgent {

    public static ToolOutput getCurrentTime(ToolContext ctx, String city) {
        String time = java.time.LocalTime.now().toString();
        return ToolOutput.success(
            "Current time in " + city + " is " + time
        );
    }

    // 定义 Agent
    public static final LlmAgent ROOT_AGENT = LlmAgent.builder()
        .name("hello-time-agent")
        .description("查询城市当前时间")
        .instruction("""
            你是一个时间查询助手。
            使用 'getCurrentTime' 工具查询城市时间。
            """)
        .model("gemini-2.5-flash")
        .tools(FunctionTool.create(HelloTimeAgent.class, "getCurrentTime"))
        .build();
}

运行 Java Agent：

import com.google.adk.runner.Runner;
import com.google.adk.runner.InMemoryRunner;
import com.google.adk.session.Session;
import com.google.genai.types.Content;
import com.google.genai.types.Part;

InMemoryRunner runner = new InMemoryRunner(HelloTimeAgent.ROOT_AGENT);

Session session = runner.sessionService()
    .createSession(runner.appName(), "user1234")
    .blockingGet();

Content userMsg = Content.fromParts(Part.fromText("现在东京几点了？"));

runner.runAsync(
    session.userId(),
    session.id(),
    userMsg,
    RunConfig.builder().build()
)
.subscribe(event -> {
    if (event.isFinalResponse()) {
        System.out.println(event.content().parts().get(0).text());
    }
});

模型无关设计

ADK 虽然对 Gemini 做了深度优化，但设计上支持多种模型后端：

使用非 Gemini 模型的示例：

from google.adk.agents import Agent
from google.genai import types

# 通过 LiteLLM 接入 Claude
agent = Agent(
    name="claude_agent",
    model="litellm:anthropic/claude-sonnet-4-6",
    instruction="你是一个助手。",
    tools=[my_tool],
)

# 通过 Ollama 接入本地模型
agent = Agent(
    name="local_agent",
    model="ollama:qwen3:14b",
    instruction="你是一个本地运行的助手。",
)

开发者工具

内置 Dev UI

ADK 提供了 Web 界面用于交互式调试：

# 启动开发服务器
adk web

在浏览器中打开后，可以：

• 与 Agent 实时对话
• 查看工具调用过程
• 检查中间状态和事件流

评估工具

# 运行评估
adk eval --config eval_config.json

支持定义测试用例和预期输出，自动评估 Agent 的表现。

部署选项

与其他框架的互操作

ADK 提供了与其他流行框架的桥接工具：

• LangchainTool：将 LangChain 工具包装为 ADK 工具
• CrewaiTool：将 CrewAI 工具包装为 ADK 工具
• MCP 协议：直接连接 MCP 服务器，复用现有工具生态

from google.adk.tools import LangchainTool
from langchain_community.tools import WikipediaQueryRun

# 将 LangChain 工具转为 ADK 工具
wiki_tool = LangchainTool(WikipediaQueryRun())

agent = Agent(
    name="wiki_agent",
    model="gemini-2.5-flash",
    instruction="使用维基百科回答问题。",
    tools=[wiki_tool],
)

A2A 协议

ADK 支持 Agent-to-Agent（A2A）协议，允许不同框架、不同服务上的 Agent 之间相互通信：

┌─────────────┐     A2A Protocol     ┌──────────────┐
│  ADK Agent  │ ◄──────────────────► │ CrewAI Agent │
│  (Python)   │                      │  (Python)    │
└─────────────┘                      └──────────────┘
       ▲                                    ▲
       │ A2A                                │ A2A
       ▼                                    ▼
┌─────────────┐                      ┌──────────────┐
│ LangGraph   │                      │  Remote API  │
│  Agent      │                      │  Agent       │
└─────────────┘                      └──────────────┘

相关链接

• Agent 框架全景
• 核心模式详解
• ADK 官方文档：https://google.github.io/adk-docs/
• ADK Python 仓库：https://github.com/google/adk-python
• ADK Java 仓库：https://github.com/google/adk-java
• ADK 快速入门：https://google.github.io/adk-docs/get-started/quickstart/