Google ADK

🏗️ 核心架构

Google 官方 Agent Development Kit，深度绑定 Gemini 生态。采用 LlmAgent(BaseAgent) 单继承树，所有 LLM 行为由 LlmAgent 统一处理，非 LLM 编排由 SequentialAgent、LoopAgent、ParallelAgent 等子类负责。

核心设计：Processor Pipeline 架构。请求和响应经过有序的 processor 链处理，每个 processor 负责一个关注点（指令注入、上下文缓存、规划、代码执行、输出 schema），实现了高度模块化的中间件模式。

类继承体系

BaseAgent (abstract)
  ├── LlmAgent        → 所有 LLM 驱动的智能体
  ├── SequentialAgent → 顺序编排（非 LLM）
  ├── LoopAgent       → 循环编排
  ├── ParallelAgent   → 并行编排
  └── LangGraphAgent  → LangGraph 集成桥接

Flow 架构

BaseLlmFlow (abstract)
  ├── SingleFlow → 单 Agent + 工具调用（无子 Agent 转移）
  └── AutoFlow   → SingleFlow + Agent Transfer（多 Agent 协作）

♻️ 主循环

由 SingleFlow（或 AutoFlow）驱动，采用 Request/Response Processor Pipeline：

LlmAgent._run_async_impl()
  → self._llm_flow.run_async(ctx)     # SingleFlow 或 AutoFlow
    → Request Processors (有序执行):
      1. basic.request_processor       → 基础设置
      2. auth_preprocessor             → 认证预处理
      3. request_confirmation          → 工具确认拦截
      4. instructions.request_processor → 构建 system instruction
      5. identity.request_processor    → Agent 身份注入
      6. compaction.request_processor  → 长上下文压缩
      7. contents.request_processor    → 对话历史注入
      8. context_cache_processor       → 上下文缓存配置
      9. interactions_processor        → 交互 ID 管理
     10. _nl_planning.request_processor → NL 规划
     11. _code_execution.request_processor → 代码执行优化
     12. _output_schema_processor      → 结构化输出 schema
    → LLM 调用
    → Response Processors:
      1. _nl_planning.response_processor
      2. _code_execution.response_processor
    → (如果有 tool_call → 执行工具 → 重新进入请求处理)*

📝 提示词工程（源码级分析）

ADK 的提示词系统设计精巧，分为三层：

1. Instruction 层次

• global_instruction — 根 Agent 定义，影响整棵 Agent 树（已废弃，迁移到 GlobalInstructionPlugin）
• static_instruction — 静态内容，不变，支持 Context Caching 优化
• instruction — 动态指令，支持 {variable} 模板 + InstructionProvider 函数

2. static_instruction + instruction 互斥逻辑

# instructions.py 源码逻辑：
if agent.instruction and not agent.static_instruction:
    # 无 static_instruction → instruction 作为 system_instruction
    llm_request.append_instructions([si])
elif agent.instruction and agent.static_instruction:
    # 有 static_instruction → instruction 移到 user content
    dynamic_content = types.Content(role='user', parts=[types.Part(text=si)])
    llm_request.contents.append(dynamic_content)

这种设计实现了上下文缓存优化：静态部分作为 system instruction 可被 Gemini 隐式/显式缓存，动态部分放在 user content 中每轮更新。

3. Agent Transfer 提示词（AutoFlow 自动注入）

# _build_transfer_instruction_body 源码：
You have a list of other agents to transfer to:

Agent name: {target_agent.name}
Agent description: {target_agent.description}

If you are the best to answer the question according to your
description, you can answer it.

If another agent is better for answering the question according to its
description, call `transfer_to_agent` function to transfer the question
to that agent.

**NOTE**: the only available agents for `transfer_to_agent` function are
`{formatted_agent_names}`.

加上 transfer_to_agent 工具定义，LLM 通过 function call 实现跨 Agent 路由。

🔧 工具系统

工具声明采用 Union 类型统一处理：

ToolUnion = Union[Callable, BaseTool, BaseToolset]

• Callable → 自动包装为 FunctionTool
• BaseTool → 直接使用
• BaseToolset → 调用 get_tools_with_prefix(ctx) 解析

特殊处理：当 GoogleSearchTool 或 VertexAiSearchTool 与其他工具共存时，自动包装为 GoogleSearchAgentTool / DiscoveryEngineSearchTool（绕过 Gemini 内置工具不能与其他工具并用的限制）。

Callback 钩子系统

6 个生命周期回调，每个都支持列表（按序执行，首个非 None 返回值短路）：

• before_model_callback → 可跳过 LLM 调用
• after_model_callback → 可替换 LLM 响应
• on_model_error_callback → 错误恢复
• before_tool_callback → 可跳过工具执行
• after_tool_callback → 可替换工具结果
• on_tool_error_callback → 工具错误恢复

🧠 记忆与状态

Session State 通过 {variable_name} 模板注入到 instruction 中。instructions_utils.inject_session_state() 负责变量替换。

output_key 机制：Agent 输出自动写入 session state，供下游 Agent 或工具读取，实现 Agent 间数据传递。

compaction processor 负责长对话压缩，在请求处理链中先于 contents processor 执行。

🔗 多 Agent 协作

Agent 树结构：通过 sub_agents 嵌套组成树，parent_agent 反向引用。

转移方向控制：

• disallow_transfer_to_parent — 禁止向父 Agent 转移（同时也禁止"继续回复"，防止用户卡在某个 Agent）
• disallow_transfer_to_peers — 禁止向兄弟 Agent 转移

恢复机制：Agent 可被暂停（长时工具调用）和恢复，通过 agent_state 事件追踪。

🆕 独特特性

• Live API — 支持实时流式交互（语音/视频），_run_live_impl() 独立于文本模式
• A2A 协议 — 内置 Agent-to-Agent 互操作协议（实验性）
• Context Caching — 静态+动态指令分离，支持 Gemini 隐式和显式缓存
• Planner — 内置规划器，支持 BuiltInPlanner（利用 Gemini thinking）
• Code Executor — 可选代码执行器，支持 BuiltInCodeExecutor
• Config 文件驱动 — 支持 YAML agent 配置，工具/回调通过全限定名引用
• output_schema + tools 共存 — 在思考循环中暴露工具，仅在最终输出时强制结构化

🔑 核心类

📂 关键文件

• src/google/adk/agents/llm_agent.py — 核心智能体类
• src/google/adk/agents/base_agent.py — 基类，状态管理
• src/google/adk/flows/llm_flows/single_flow.py — 单 Agent 流程
• src/google/adk/flows/llm_flows/auto_flow.py — 多 Agent 流程
• src/google/adk/flows/llm_flows/instructions.py — 提示词构建
• src/google/adk/flows/llm_flows/agent_transfer.py — Agent 转移逻辑
• src/google/adk/flows/llm_flows/contents.py — 上下文管理
• src/google/adk/flows/llm_flows/compaction.py — 长对话压缩
• src/google/adk/flows/llm_flows/context_cache_processor.py — 缓存处理
• src/google/adk/tools/function_tool.py — 函数工具封装
• src/google/adk/a2a/ — A2A 协议实现