14 KiB
14 KiB
第03章：LLM 智能体详解
📌 本章目标
- 深入理解 LlmAgent 的工作原理
- 掌握 Agent 的指令设计（Instruction Design）
- 学习如何选择和配置不同的 LLM 模型
- 了解 output_key、before/after 回调等高级特性
- 使用 Google 内置工具（搜索、代码执行等）
3.1 LlmAgent 工作原理
3.1.1 执行流程
用户输入
│
▼
┌─────────────────────────────────────────────────┐
│ LlmAgent │
│ │
│ 1. 接收用户消息 │
│ ↓ │
│ 2. before_model_callback（模型调用前回调） │
│ ↓ │
│ 3. 构建上下文（系统指令 + 历史消息 + 工具定义） │
│ ↓ │
│ 4. 调用 LLM 获取响应 │
│ ↓ │
│ 5. after_model_callback（模型调用后回调） │
│ ↓ │
│ 6. 判断是否需要调用工具 │
│ ├── 是 → before_tool_callback → 执行工具 │
│ │ → after_tool_callback → 回到步骤3 │
│ └── 否 → 输出最终响应 │
│ ↓ │
│ 7. 保存输出到 State（如果设置了 output_key） │
│ ↓ │
│ 8. 返回响应给用户 │
└─────────────────────────────────────────────────┘
3.1.2 Agent 与 LlmAgent 的关系
# Agent 是 LlmAgent 的别名，两者完全等价
from google.adk.agents import Agent # Agent = LlmAgent 的别名
from google.adk.agents import LlmAgent # LlmAgent 是完整类名
# 以下两种写法效果完全相同：
agent1 = Agent(name="test", model="gemini-2.0-flash")
agent2 = LlmAgent(name="test", model="gemini-2.0-flash")
3.2 指令设计（Instruction Design）
3.2.1 好的指令设计原则
"""
Agent 指令设计示例
展示如何编写高质量的 Agent 系统指令
"""
from google.adk.agents import Agent
# ❌ 不好的指令设计：过于简单、缺乏约束
bad_agent = Agent(
name="bad_agent",
model="gemini-2.0-flash",
instruction="你是一个助手。", # 太模糊，Agent 不知道该做什么
)
# ✅ 好的指令设计：清晰、具体、有约束
good_agent = Agent(
name="good_agent",
model="gemini-2.0-flash",
instruction="""你是一个专业的旅行规划助手。
## 你的职责
- 帮助用户规划旅行行程
- 提供目的地推荐和旅行建议
- 使用工具查询天气、航班等信息
## 回答规范
1. 始终使用中文回答
2. 回答要简洁明了，使用列表格式
3. 如果信息不足，主动询问用户
4. 不要编造不存在的信息
## 工具使用规则
- 查询天气时，使用 get_weather 工具
- 查询航班时，使用 search_flights 工具
- 只有在需要实时数据时才使用工具
""",
)
3.2.2 指令模板
"""
常用指令模板
可以根据自己的需求修改使用
"""
# 模板一：数据分析助手
data_analyst_instruction = """你是一个数据分析专家。
## 核心能力
- 分析数据并生成洞察
- 创建数据可视化建议
- 解释统计指标的含义
## 工作流程
1. 理解用户的数据分析需求
2. 使用工具获取和处理数据
3. 生成分析报告，包含关键发现
4. 提供可操作的建议
## 输出格式
- 使用 Markdown 格式
- 包含数据表格和关键指标
- 提供结论和建议
"""
# 模板二：代码助手
code_assistant_instruction = """你是一个编程助手。
## 核心能力
- 编写和审查代码
- 调试和修复错误
- 代码重构和优化建议
## 规则
1. 代码注释使用中文
2. 遵循最佳实践和设计模式
3. 解释代码的工作原理
4. 提供测试建议
"""
# 模板三：客服助手
customer_service_instruction = """你是一个专业的客服代表。
## 核心职责
- 解答用户问题
- 处理投诉和反馈
- 引导用户完成操作
## 规则
1. 语气友好、专业
2. 先理解用户问题，再提供解决方案
3. 无法解决时，转交人工客服
4. 记录用户反馈
"""
3.3 模型选择与配置
3.3.1 Gemini 模型（默认）
"""
使用 Gemini 模型配置 Agent
Gemini 是 ADK 默认优化的模型
"""
from google.adk.agents import Agent
# 使用 Gemini 2.0 Flash（推荐，性价比高）
agent_flash = Agent(
name="flash_agent",
model="gemini-2.0-flash", # 快速、经济
instruction="你是一个高效的助手。",
)
# 使用 Gemini 2.5 Pro（更强推理能力）
agent_pro = Agent(
name="pro_agent",
model="gemini-2.5-pro-preview-05-06", # 更强的推理能力
instruction="你是一个需要深度推理的助手。",
)
# 使用 Gemini 3 Pro（最新版本）
agent_latest = Agent(
name="latest_agent",
model="gemini-3-pro-preview", # 最新版本
instruction="你是一个使用最新模型的助手。",
)
3.3.2 使用其他模型（LiteLLM）
"""
使用 LiteLLM 适配其他模型
LiteLLM 支持 100+ 种模型
"""
from google.adk.agents import Agent # 导入 Agent 类
from google.adk.models.lite_llm import LiteLlm # 导入 LiteLLM 适配器
# ========================================
# 使用 DeepSeek 模型
# ========================================
deepseek_agent = Agent(
name="deepseek_agent", # Agent 名称
model=LiteLlm( # 使用 LiteLLM 适配器
model="deepseek/deepseek-chat", # 格式：provider/model_name
api_key="你的_DEEPSEEK_API_KEY", # DeepSeek API Key
# api_base="https://api.deepseek.com", # 可选：自定义 API 地址
),
instruction="你是一个使用 DeepSeek 模型的助手。",
)
# ========================================
# 使用 OpenAI 模型
# ========================================
openai_agent = Agent(
name="openai_agent", # Agent 名称
model=LiteLlm( # 使用 LiteLLM 适配器
model="openai/gpt-4o", # OpenAI GPT-4o 模型
api_key="你的_OPENAI_API_KEY", # OpenAI API Key
),
instruction="你是一个使用 GPT-4o 模型的助手。",
)
# ========================================
# 使用 Claude 模型
# ========================================
claude_agent = Agent(
name="claude_agent", # Agent 名称
model=LiteLlm( # 使用 LiteLLM 适配器
model="anthropic/claude-3-5-sonnet-20241022", # Claude 模型
api_key="你的_ANTHROPIC_API_KEY", # Anthropic API Key
),
instruction="你是一个使用 Claude 模型的助手。",
)
3.3.3 模型选择指南
| 场景 | 推荐模型 | 原因 |
|---|---|---|
| 简单对话 | gemini-2.0-flash | 速度快、成本低 |
| 复杂推理 | gemini-2.5-pro | 推理能力强 |
| 代码生成 | gemini-2.5-pro / gpt-4o | 代码质量高 |
| 中文场景 | deepseek-chat | 中文能力强 |
| 长文本处理 | gemini-2.5-pro | 支持长上下文 |
3.4 使用 Google 内置工具
3.4.1 Google Search（网络搜索）
"""
使用 Google Search 工具
让 Agent 能够搜索互联网获取最新信息
"""
from google.adk.agents import Agent # 导入 Agent 类
from google.adk.tools import google_search # 导入 Google 搜索工具
# 创建带有搜索能力的 Agent
search_agent = Agent(
name="search_agent", # Agent 名称
model="gemini-2.0-flash", # 使用 Gemini 模型
instruction=( # 系统指令
"你是一个信息查询助手。\n"
"当用户提问时，使用 Google Search 工具搜索最新信息。\n"
"根据搜索结果提供准确、全面的回答。\n"
"如果搜索结果不够充分，可以多次搜索不同关键词。"
),
tools=[google_search], # 注册 Google 搜索工具
)
3.4.2 Code Execution（代码执行）
"""
使用 Code Execution 工具
让 Agent 能够执行 Python 代码进行计算和分析
"""
from google.adk.agents import Agent # 导入 Agent 类
from google.adk.tools import code_execution # 导入代码执行工具
# 创建带有代码执行能力的 Agent
code_agent = Agent(
name="code_agent", # Agent 名称
model="gemini-2.0-flash", # 使用 Gemini 模型
instruction=( # 系统指令
"你是一个数据分析助手。\n"
"当需要进行数学计算、数据分析或生成图表时，\n"
"使用 Code Execution 工具执行 Python 代码。\n"
"确保代码正确且高效。"
),
tools=[code_execution], # 注册代码执行工具
)
3.4.3 组合多个内置工具
"""
组合使用多个 Google 内置工具
创建功能更强大的 Agent
"""
from google.adk.agents import Agent # 导入 Agent 类
from google.adk.tools import google_search # 导入 Google 搜索工具
from google.adk.tools import code_execution # 导入代码执行工具
# 创建多功能 Agent
super_agent = Agent(
name="super_agent", # Agent 名称
model="gemini-2.0-flash", # 使用 Gemini 模型
instruction=( # 系统指令
"你是一个全能助手。\n"
"你可以搜索互联网获取最新信息。\n"
"你也可以执行代码来进行计算和分析。\n"
"根据用户的需求选择合适的工具。"
),
tools=[ # 注册多个工具
google_search, # 网络搜索
code_execution, # 代码执行
],
)
3.5 output_key — 输出到 State
"""
output_key 参数详解
将 Agent 的输出保存到会话状态（State）中
用于在多 Agent 系统中传递数据
"""
from google.adk.agents import Agent # 导入 Agent 类
# 创建一个将输出保存到 State 的 Agent
capital_agent = Agent(
name="capital_agent", # Agent 名称
model="gemini-2.0-flash", # 使用 Gemini 模型
instruction="回答用户关于国家首都的问题。只回答首都名称，不要多余内容。", # 指令
output_key="capital_city", # 🔑 关键参数：将输出保存到 state['capital_city']
)
# 当这个 Agent 运行后，它的最终响应文本会自动保存到 session.state['capital_city']
# 其他 Agent 可以通过 {capital_city} 在指令中引用这个值
3.6 Agent Transfer — 动态任务委派
"""
Agent Transfer 机制
LLM 可以根据用户需求动态地将任务委派给其他 Agent
"""
from google.adk.agents import LlmAgent # 导入 LlmAgent 类
# 定义专门的子 Agent
booking_agent = LlmAgent(
name="BookingAgent", # 预订 Agent
model="gemini-2.0-flash", # 使用 Gemini 模型
description="负责处理航班和酒店的预订请求。", # 描述：用于 LLM 路由决策
instruction="你是一个预订助手，帮助用户预订航班和酒店。", # 系统指令
)
info_agent = LlmAgent(
name="InfoAgent", # 信息查询 Agent
model="gemini-2.0-flash", # 使用 Gemini 模型
description="负责回答一般性问题和提供信息。", # 描述：用于 LLM 路由决策
instruction="你是一个信息助手，回答用户的各种问题。", # 系统指令
)
# 定义协调器 Agent（父 Agent）
coordinator = LlmAgent(
name="Coordinator", # 协调器 Agent
model="gemini-2.0-flash", # 使用 Gemini 模型
description="主协调器，负责将用户请求分配给合适的子 Agent。", # 描述
instruction=( # 系统指令
"你是一个协调器助手。\n"
"当用户需要预订航班或酒店时，将任务委派给 BookingAgent。\n"
"当用户询问一般性问题时，将任务委派给 InfoAgent。\n"
"使用 transfer_to_agent 工具来委派任务。"
),
sub_agents=[ # 🔑 注册子 Agent
booking_agent, # 预订 Agent
info_agent, # 信息 Agent
],
)
# 工作原理：
# 1. 用户发送消息给 Coordinator
# 2. Coordinator 的 LLM 分析消息，决定委派给哪个子 Agent
# 3. LLM 生成 transfer_to_agent(agent_name='BookingAgent') 调用
# 4. ADK 框架自动将执行切换到目标 Agent
# 5. 目标 Agent 处理请求并返回结果
3.7 完整代码示例
详见 code/llm_agent_demo.py — 包含完整的 LlmAgent 配置和运行示例。
📌 本章小结
- LlmAgent 是 ADK 最常用的智能体类型，以 LLM 为核心引擎
- 好的指令设计是 Agent 效果的关键
- ADK 默认优化 Gemini 模型，通过 LiteLLM 支持其他模型
- Google 内置工具（搜索、代码执行）可直接使用
output_key用于在多 Agent 系统中传递数据- Agent Transfer 实现动态任务委派
下一章：第04章 - 自定义工具开发 → 学习如何为 Agent 创建自定义工具。