Supervising Agents
Core Principle
The dispatcher IS the supervisor. When you dispatch a task, you own the outcome.
CODEBLOCK0
Part 1: The 5-Phase Workflow
CODEBLOCK1
Part 2: PREPARE Phase
Pre-Dispatch Checklist (MUST COMPLETE)
CODEBLOCK2
Decision: Should You Dispatch?
| Condition | Decision |
|---|
| Task is trivial (< 5 min) | Do it yourself |
| Task requires judgment you don't have |
Ask human first |
| Task has clear requirements and deliverables | ✓ Dispatch with supervision |
Part 3: DISPATCH Phase
Dispatch Prompt Template
CODEBLOCK3
After Dispatch: Record Agent ID
CODEBLOCK4
Part 4: MONITOR Phase (CRITICAL)
The #1 Mistake: Passive Waiting
CODEBLOCK5
Active Monitoring Techniques
Technique 1: Output File Watching
CODEBLOCK6
If no output after 1 check interval → INTERVENE NOW
Technique 2: SendMessage Probe
CODEBLOCK7
Technique 3: Timestamp Tracking
CODEBLOCK8
Monitoring Decision Matrix
| Check Result | What It Means | Your Action |
|---|
| Output files exist, have content | On track | Continue monitoring |
| No output files after 2 intervals |
Not started or stuck | SendMessage NOW |
| Output files empty | Fake work or error | SendMessage NOW |
| Subagent silent > 2x interval | May have abandoned | Escalate to human |
Real-Time Red Flags
| Signal | Probability | Immediate Action |
|---|
| No file changes in [interval] | 80% stuck | Check now |
| Subagent asks unrelated questions |
70% distracted | Redirect |
| Subagent says "almost done" but no files | 90% fake completion | Demand evidence |
| Time > 1.5x budget with no output | 95% failed | Intervene or take over |
Part 5: INTERVENE Phase
Intervention Protocol
CODEBLOCK9
Level 1: Probe (Mild Concern)
CODEBLOCK10
Level 2: Redirect (Clear Deviation)
CODEBLOCK11
Level 3: Takeover (Critical Failure)
CODEBLOCK12
Part 6: VERIFY Phase
The Verification Gate
NEVER accept "I'm done" without evidence.
CODEBLOCK13
Verification Commands
CODEBLOCK14
Common Verification Failures
| Claim | Reality | How to Catch |
|---|
| "Created the file" | File is empty | INLINECODE0 |
| "Tests pass" |
Tests don't exist | Run tests yourself |
| "Feature works" | Only happy path | Test edge cases |
| "All requirements done" | Some skipped | Check each one |
Part 7: REPORT Phase
Report Template
CODEBLOCK15
When to Escalate to Human
CODEBLOCK16
Part 8: Common Failure Patterns
Pattern 1: Confirmed but Never Started
What happens: Subagent confirms understanding, then does nothing.
Detection: No output files after 1 interval.
Fix:
CODEBLOCK17
Pattern 2: Silent Failure
What happens: Subagent encounters error, doesn't report, just stops.
Detection: No activity for 2+ intervals.
Fix:
CODEBLOCK18
Pattern 3: Fake Completion
What happens: Subagent claims done, output is empty/wrong.
Detection: Output files don't match requirements.
Fix:
CODEBLOCK19
Pattern 4: Scope Drift
What happens: Subagent works on something else, ignores original task.
Detection: Output unrelated to requirements.
Fix:
"Stop. You are working on [X] but task requires [Y].
Which part of the original task are you addressing?
If none, return to the original requirements immediately."
Part 9: Quick Reference
Time Estimates
| Task Type | Budget | Check Interval |
|---|
| Quick (< 10 lines) | 5 min | Check at end only |
| Simple function |
10 min | Every 3 min |
| Feature implementation | 30 min | Every 5 min |
| Complex multi-file | 60+ min | Every 10 min + milestones |
Red Flags Checklist
CODEBLOCK21
The Iron Rules
CODEBLOCK22
Implementation for openclaw
Setup
CODEBLOCK23
Usage Pattern
CODEBLOCK24
Summary
You dispatch → You own the outcome.
The subagent is a tool, not a trusted partner. Your job is to:
- 1. Define clearly
- Lock in commitment
- Actively monitor (not passive wait)
- Intervene early
- Verify with evidence
- Report with accountability
Most common failure: Passive waiting. Fix: Check output files early and often.
Research foundation: Persuasion techniques increase compliance 33% → 72% (Meincke et al., 2025, N=28,000).
监督代理
核心原则
调度者即监督者。 当你调度一项任务时,你需对结果负责。
你调度 → 你监控 → 你验证 → 你报告
如果子代理失败,你有责任发现它。
如果你不验证,你有责任承担错误输出。
第一部分:五阶段工作流
准备 ──► 调度 ──► 监控 ──► 验证 ──► 报告
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
明确定义 锁定 主动检查 证据 对人工
承诺 要求 负责
第二部分:准备阶段
调度前检查清单(必须完成)
□ 任务已定义
目标(一句话):_
要求(列出全部):_
交付物(具体文件):_
□ 时间已设定
预算:_ 分钟
检查间隔:_ 分钟(规则:预算/5,最少3分钟)
□ 验证计划已制定
如何检查输出是否存在:_
如何验证正确性:_
□ 红旗信号已定义
出问题的表现:_
决策:是否应调度?
| 条件 | 决策 |
|---|
| 任务简单(< 5分钟) | 自己完成 |
| 任务需要你不具备的判断力 |
先询问人工 |
| 任务有明确要求和交付物 | ✓ 调度并监督 |
第三部分:调度阶段
调度提示模板
任务:[一句话 - 成功的样子]
要求(全部完成):
- 1. [要求1]
- [要求2]
- [要求3]
交付物:
- - [文件1] - [预期内容]
- [文件2] - [预期内容]
时间:[X] 分钟
─── 开始前 ───
回复确认:
- 1. 目标是什么?(用你的话)
- 你将采取哪些步骤?
- 你如何知道已完成?
在确认之前不要开始。
调度后:记录代理ID
typescript
// 代理工具返回:agentId: abc123
// 保存此ID - 发送消息时需要
const agentId = abc123; // 跟踪此ID
第四部分:监控阶段(关键)
第一大错误:被动等待
❌ 错误:调度 → 等待 → 最后检查
✓ 正确:调度 → 主动监控 → 及早干预
主动监控技巧
技巧1:输出文件监控
bash
检查输出文件是否存在
ls -la [预期输出目录]
检查文件大小(应 > 0)
wc -l [预期文件]
检查修改时间
find . -name *.md -mmin -5 # 最近5分钟修改的文件
如果1个检查间隔后仍无输出 → 立即干预
技巧2:发送消息探测
typescript
// 使用SendMessage检查进度
SendMessage({
to: agentId,
message:
📊 进度检查
立即报告:
1. 你已完成什么?(具体文件/行数)
2. 你现在在做什么?
3. 有任何阻碍吗?
请在30秒内回复。
});
技巧3:时间戳跟踪
时间 0:00 - 调度
时间 3:00 - 第一次检查(输出文件是否存在?)
时间 6:00 - 第二次检查(进度可见?)
时间 9:00 - 第三次检查(接近完成?)
时间 12:00 - 最终验证
如果任何检查失败 → 立即干预
监控决策矩阵
| 检查结果 | 含义 | 你的行动 |
|---|
| 输出文件存在且有内容 | 正常进行 | 继续监控 |
| 2个间隔后仍无输出文件 |
未开始或卡住 | 立即发送消息 |
| 输出文件为空 | 虚假工作或错误 | 立即发送消息 |
| 子代理沉默 > 2倍间隔 | 可能已放弃 | 上报人工 |
实时红旗信号
| 信号 | 概率 | 立即行动 |
|---|
| [间隔]内无文件变化 | 80%卡住 | 立即检查 |
| 子代理问无关问题 |
70%分心 | 重新引导 |
| 子代理说快完成了但无文件 | 90%虚假完成 | 要求证据 |
| 时间 > 1.5倍预算且无输出 | 95%失败 | 干预或接管 |
第五部分:干预阶段
干预协议
┌─────────────────────────────────────────────────────────────┐
│ 干预决策 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 检查失败? │
│ │ │
│ ├── 完全无输出 ──────────────► 一级:探测 │
│ │ 你在做什么? │
│ │ │
│ ├── 方向错误 ───────────────► 二级:重新引导 │
│ │ 停止X,做Y │
│ │ │
│ ├── 对探测无响应 ──────────► 三级:接管 │
│ │ 我来处理 │
│ │ │
│ └── 反复失败 ─────────────► 上报人工 │
│ 此代理无法... │
│ │
└─────────────────────────────────────────────────────────────┘
一级:探测(轻度关注)
📊 状态检查
我还没有看到任何输出文件。
请在30秒内报告:
- 1. 你具体做了什么?(文件名,不是描述)
- 你现在在做什么?(具体行动)
- 我什么时候能看到输出?
请具体说明。正在处理不是答案。
二级:重新引导(明显偏离)
⚠️ 需要纠正
问题:[具体问题]
停止:[错误活动]
执行:[正确活动]
你有[X]分钟来展示进度。
不要解释。执行。
三级:接管(严重失败)
🔴 正在接管
此任务没有进展。
我将自己完成。
你:停止一切。提供你实际完成的内容列表(如果有的话)。
此操作已记录。
第六部分:验证阶段
验证关卡
没有证据,绝不接受我完成了。
□ 证据检查
- 给我看文件:[读取实际文件]
- 给我看测试输出:[运行测试]
- 给我看它工作:[演示功能]
□ 要求检查
| 要求 | 完成? | 证据 |
|------|--------|------|
| 1 | ✓/✗ | [证明]|
| 2 | ✓/✗ | [证明]|
| 3 | ✓/✗ | [证明]|
□ 质量检查
- 输出是否非空?
- 是否实际工作?
- 是否处理了边界情况?
验证命令
bash
文件是否存在且有内容?
ls -la [文件] && wc -l [文件]
代码是否有实际实现?
grep -E (function|class|def |export ) [文件]
测试是否通过?
npm test 2>&1 | tail -20
最近更改?
git status && git diff
常见验证失败
| 声称 | 现实 | 如何发现 |
|---|
| 已创建文件 | 文件为空 | wc -l 文件 |
| 测试通过 |
测试不存在 | 自己运行测试 |
| 功能正常 | 仅快乐路径 | 测试边界情况 |
| 所有要求已完成 | 部分跳过 | 逐项检查 |
第七部分:报告阶段
报告模板
markdown
📋 任务报告
任务:[名称]
状态: ✓ 完成 / ⚠ 问题 / ✗ 失败
时间:[实际] / [预算] 分钟
验证:
- - 输出存在:[是/否 + 证据]
- 测试通过:[是/否 + 输出]
- 所有要求满足:[是/否 + 检查清单]
证据:
- - 文件:[列表及大小]
- 关键内容:[粘贴相关部分]
问题:[如有]
下一步:[如需]
何时上报人工
🚨 上报条件:
- - 子代理在干预后完全失败
- 需要超出你权限的技术决策
- 尽管验证,输出质量仍不可接受
- 时间显著超预算且看不到尽头
- 子代理行为令人担忧(忽略所有指令)
第八部分:常见失败模式
模式1:确认但从未开始
现象: 子代理确认理解,然后什么都不做。