docs(skill): document blocking and background sub-agent modes
This commit is contained in:
parent
21d1a14fea
commit
494edc53e9
@ -81,27 +81,115 @@ sub_agent_results/refactor_auth/ # 按功能组织
|
||||
- ❌ 使用绝对路径（必须是相对于项目根目录的相对路径）
|
||||
- ❌ 使用通用名称如 "output" "result"（多个子智能体会冲突）
|
||||
|
||||
## 执行模式：阻塞 vs 后台
|
||||
|
||||
子智能体有两种执行模式，通过 `run_in_background` 参数控制：
|
||||
|
||||
### 阻塞模式（run_in_background=false，默认）
|
||||
|
||||
**行为：**
|
||||
- 创建子智能体后，你会**停止输出**，等待它完成
|
||||
- 完成后结果直接在工具返回中给出，继续你的工作
|
||||
- 不会有额外的系统通知消息
|
||||
|
||||
**何时使用：**
|
||||
- ✅ 快速任务（预计 < 1 分钟）
|
||||
- ✅ 需要立即使用结果的任务
|
||||
- ✅ 单个子智能体，没有其他并行工作
|
||||
|
||||
**示例：**
|
||||
```python
|
||||
# 快速信息搜集，立即需要结果
|
||||
create_sub_agent(
|
||||
agent_id=1,
|
||||
summary="搜索 Python 3.12 新特性",
|
||||
task="搜索并整理 Python 3.12 的主要新特性，生成 python312.md",
|
||||
deliverables_dir="research/python312",
|
||||
run_in_background=false, # 阻塞等待
|
||||
timeout_seconds=300
|
||||
)
|
||||
# 工具返回后，你可以立即读取 research/python312/python312.md
|
||||
```
|
||||
|
||||
### 后台模式（run_in_background=true）
|
||||
|
||||
**行为：**
|
||||
- 创建子智能体后，工具**立即返回**，你可以继续做其他事情
|
||||
- 子智能体在后台运行，完成后系统会**自动插入一条 user 消息**通知你
|
||||
- 你会在对话中看到类似："这是一句系统自动发送的user消息，用于通知你子智能体已经运行完成..."
|
||||
|
||||
**何时使用：**
|
||||
- ✅ 耗时任务（预计 > 1 分钟）
|
||||
- ✅ 多个并行任务
|
||||
- ✅ 你有其他工作可以先做（回答用户问题、处理其他任务）
|
||||
|
||||
**后台模式下你应该做什么：**
|
||||
|
||||
**情况 A：运行子智能体期间需要做别的事情**
|
||||
```python
|
||||
# 创建多个后台任务
|
||||
create_sub_agent(agent_id=1, task="...", run_in_background=true, ...)
|
||||
create_sub_agent(agent_id=2, task="...", run_in_background=true, ...)
|
||||
|
||||
# 立即告诉用户并继续其他工作
|
||||
"我已经启动了2个子智能体在后台并行工作，预计需要10-15分钟。在等待期间，我可以先帮你处理其他事情。"
|
||||
|
||||
# 然后你可以：
|
||||
# - 回答用户的其他问题
|
||||
# - 处理其他任务
|
||||
# - 阅读代码、分析问题
|
||||
# - 运行其他工具
|
||||
# 子智能体完成时会自动插入一条 system 消息通知你
|
||||
```
|
||||
|
||||
**情况 B：运行子智能体期间不需要做别的事情**
|
||||
```python
|
||||
create_sub_agent(agent_id=1, task="大规模日志分析", run_in_background=true, timeout_seconds=1800)
|
||||
|
||||
# 告诉用户预计时间
|
||||
"我已启动子智能体进行日志分析，这个任务比较耗时，预计需要20-30分钟。系统会在完成后自动通知我，届时我会立即处理结果并回复你。"
|
||||
|
||||
# 然后停止工作和输出，等待系统通知
|
||||
# 子智能体运行完成后，系统会自动发送一条 user 消息通知你
|
||||
```
|
||||
|
||||
**重要提示：**
|
||||
- 系统会自动处理通知，你只需要在收到通知消息后处理结果即可
|
||||
- 如果你正在执行工具调用，系统会延迟通知，避免打断你的工作流
|
||||
- 通知类型取决于你是否继续工作：继续工作时收到 system 消息，停止输出时收到 user 消息
|
||||
|
||||
### 模式选择决策树
|
||||
|
||||
```
|
||||
任务预计耗时 < 1 分钟？
|
||||
├─ 是 → 使用阻塞模式（run_in_background=false）
|
||||
└─ 否 → 有多个并行任务？
|
||||
├─ 是 → 使用后台模式（run_in_background=true）
|
||||
└─ 否 → 有其他工作可以先做？
|
||||
├─ 是 → 使用后台模式
|
||||
└─ 否 → 使用阻塞模式
|
||||
```
|
||||
|
||||
## 并行执行模式
|
||||
|
||||
创建多个子智能体时，确保它们的任务**完全独立**：
|
||||
|
||||
```python
|
||||
# ✅ 好的并行：各自独立
|
||||
create_sub_agent(agent_id=1, task="生成模块 A 的文档", deliverables_dir="docs/module_a", ...)
|
||||
create_sub_agent(agent_id=2, task="生成模块 B 的文档", deliverables_dir="docs/module_b", ...)
|
||||
# ✅ 好的并行：各自独立，使用后台模式
|
||||
create_sub_agent(agent_id=1, task="生成模块 A 的文档", deliverables_dir="docs/module_a", run_in_background=true, ...)
|
||||
create_sub_agent(agent_id=2, task="生成模块 B 的文档", deliverables_dir="docs/module_b", run_in_background=true, ...)
|
||||
# 告诉用户："已启动2个子智能体并行生成文档，预计10分钟完成。系统会在完成后自动通知我。"
|
||||
# 然后你可以继续做其他事情，或者停止输出等待通知
|
||||
|
||||
# ✅ 好的并行：信息搜集
|
||||
create_sub_agent(agent_id=1, task="搜索并整理 Claude 最新模型信息", deliverables_dir="research/claude", ...)
|
||||
create_sub_agent(agent_id=2, task="搜索并整理 ChatGPT 最新模型信息", deliverables_dir="research/chatgpt", ...)
|
||||
# 等两个都完成后，你再对比整合
|
||||
create_sub_agent(agent_id=1, task="搜索并整理 Claude 最新模型信息", deliverables_dir="research/claude", run_in_background=true, ...)
|
||||
create_sub_agent(agent_id=2, task="搜索并整理 ChatGPT 最新模型信息", deliverables_dir="research/chatgpt", run_in_background=true, ...)
|
||||
# 等系统自动通知两个都完成后，你再对比整合
|
||||
|
||||
# ✅ 好的并行：系统调研
|
||||
create_sub_agent(agent_id=1, task="分析前端认证实现", deliverables_dir="analysis/frontend_auth", ...)
|
||||
create_sub_agent(agent_id=2, task="分析后端鉴权实现", deliverables_dir="analysis/backend_auth", ...)
|
||||
|
||||
# 等待所有完成
|
||||
wait_sub_agent(agent_id=1)
|
||||
wait_sub_agent(agent_id=2)
|
||||
create_sub_agent(agent_id=1, task="分析前端认证实现", deliverables_dir="analysis/frontend_auth", run_in_background=true, ...)
|
||||
create_sub_agent(agent_id=2, task="分析后端鉴权实现", deliverables_dir="analysis/backend_auth", run_in_background=true, ...)
|
||||
# 系统会在每个完成时发送通知，你可以逐个处理或等全部完成
|
||||
```
|
||||
|
||||
```python
|
||||
@ -167,10 +255,12 @@ create_sub_agent(agent_id=1, ...) # 失败了
|
||||
|
||||
## 检查结果
|
||||
|
||||
子智能体完成后，检查 `success` 字段和 `deliverables_dir`：
|
||||
### 阻塞模式下
|
||||
|
||||
工具返回中直接包含结果：
|
||||
|
||||
```python
|
||||
result = wait_sub_agent(agent_id=1)
|
||||
result = create_sub_agent(agent_id=1, run_in_background=false, ...)
|
||||
|
||||
if result["success"]:
|
||||
# 读取交付目录中的文件
|
||||
@ -182,9 +272,45 @@ else:
|
||||
# 考虑增加 timeout_seconds 重试
|
||||
else:
|
||||
# 查看 result["message"] 了解失败原因
|
||||
# 检查交付目录中是否有部分结果
|
||||
```
|
||||
|
||||
### 后台模式下
|
||||
|
||||
等待系统自动插入的通知消息：
|
||||
|
||||
**如果你继续工作**，会收到 system 消息：
|
||||
```
|
||||
✅ 子智能体1 任务摘要：搜索 Python 3.12 新特性 已完成。
|
||||
|
||||
调用了15次
|
||||
阅读了8次文件
|
||||
编辑了2次文件
|
||||
搜索了3次内容
|
||||
查看了5个网页
|
||||
运行了2个指令
|
||||
|
||||
运行了245秒
|
||||
|
||||
已搜索并整理 Python 3.12 的主要新特性...
|
||||
|
||||
交付目录：research/python312
|
||||
```
|
||||
|
||||
**如果你停止输出**，会收到 user 消息：
|
||||
```
|
||||
这是一句系统自动发送的user消息，用于通知你子智能体已经运行完成
|
||||
|
||||
子智能体1 (搜索 Python 3.12 新特性) 已完成任务。
|
||||
|
||||
已搜索并整理 Python 3.12 的主要新特性...
|
||||
|
||||
运行了245秒
|
||||
|
||||
交付目录：research/python312
|
||||
```
|
||||
|
||||
收到通知后，读取交付目录中的文件并处理结果。
|
||||
|
||||
## thinking_mode 选择
|
||||
|
||||
- `fast`：常规任务（文档生成、信息搜集、数据分析）
|
||||
@ -194,4 +320,12 @@ else:
|
||||
|
||||
## 总结
|
||||
|
||||
子智能体的本质是**并行执行完全独立的任务**。如果你发现自己在设计子智能体之间的协作流程，那可能不应该使用子智能体，而应该自己顺序执行这些步骤。
|
||||
子智能体的本质是**并行执行完全独立的任务**。
|
||||
|
||||
**关键要点：**
|
||||
1. **执行模式选择**：快速任务用阻塞模式，耗时任务或并行任务用后台模式
|
||||
2. **后台模式下**：创建后继续工作或停止输出，系统会自动通知完成
|
||||
3. **任务独立性**：子智能体之间无法通信，确保任务完全独立
|
||||
4. **任务描述**：子智能体看不到对话历史，task 参数必须包含所有信息
|
||||
|
||||
如果你发现自己在设计子智能体之间的协作流程，那可能不应该使用子智能体，而应该自己顺序执行这些步骤。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user