init
This commit is contained in:
Nelson
434
ADKLearning/google-adk-tutorial/03-llm-agent-in-depth.md
Normal file
434
ADKLearning/google-adk-tutorial/03-llm-agent-in-depth.md
Normal file
@@ -0,0 +1,434 @@
|
||||
# 第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 的关系
|
||||
|
||||
```python
|
||||
# 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 好的指令设计原则
|
||||
|
||||
```python
|
||||
"""
|
||||
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 指令模板
|
||||
|
||||
```python
|
||||
"""
|
||||
常用指令模板
|
||||
可以根据自己的需求修改使用
|
||||
"""
|
||||
|
||||
# 模板一：数据分析助手
|
||||
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 模型（默认）
|
||||
|
||||
```python
|
||||
"""
|
||||
使用 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）
|
||||
|
||||
```python
|
||||
"""
|
||||
使用 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（网络搜索）
|
||||
|
||||
```python
|
||||
"""
|
||||
使用 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（代码执行）
|
||||
|
||||
```python
|
||||
"""
|
||||
使用 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 组合多个内置工具
|
||||
|
||||
```python
|
||||
"""
|
||||
组合使用多个 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
|
||||
|
||||
```python
|
||||
"""
|
||||
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 — 动态任务委派
|
||||
|
||||
```python
|
||||
"""
|
||||
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章 - 自定义工具开发](./04-custom-tools.md) → 学习如何为 Agent 创建自定义工具。
|
||||
Reference in New Issue
Block a user