Back to Details

parallel-agents

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Parallel Agent Orchestration

并行Agent编排

When launching multiple agents in parallel, follow this pattern to avoid context bloat.
在并行启动多个Agent时，请遵循此模式以避免上下文冗余。

Core Principles

核心原则

  1. No TaskOutput calls - TaskOutput returns full agent output, bloating context
  2. Run in background - Always use 
    run_in_background: true
  3. File-based confirmation - Agents write status to files, not return values
  4. Append, don't overwrite - Multiple agents can write to same status file
  1. 禁止调用TaskOutput - TaskOutput会返回完整的Agent输出，导致上下文冗余
  2. 后台运行 - 始终使用
    run_in_background: true
  3. 基于文件的确认 - Agent将状态写入文件，而非返回值
  4. 追加而非覆盖 - 多个Agent可写入同一状态文件

Output Patterns

输出模式

Simple Confirmation (parallel batch work)

简单确认（批量并行工作）

For tasks where agents just need to confirm completion:
bash
undefined
适用于仅需Agent确认完成的任务：
bash
undefined

Agent writes to shared status file

Agent写入共享状态文件

echo "COMPLETE: <task-name> - $(date)" >> .claude/cache/<batch-name>-status.txt

- Use `>>` to append (not `>` which overwrites)
- Include timestamp for ordering
- One line per agent completion
- Check with: `cat .claude/cache/<batch-name>-status.txt`
echo "COMPLETE: <task-name> - $(date)" >> .claude/cache/<batch-name>-status.txt

- 使用`>>`进行追加（而非`>`覆盖）
- 包含时间戳以记录顺序
- 每个Agent完成后写入一行
- 查看方式：`cat .claude/cache/<batch-name>-status.txt`

Detailed Output (research/exploration)

详细输出（研究/探索任务）

For tasks requiring detailed findings:
.claude/cache/agents/<task-type>/<agent-id>/
├── output.md      # Main findings
├── artifacts/     # Any generated files
└── status.txt     # Completion confirmation
  • Each agent gets own directory
  • Full output preserved for later reading
  • Status file still used for quick completion check
适用于需要详细结果的任务：
.claude/cache/agents/<task-type>/<agent-id>/
├── output.md      # 主要研究结果
├── artifacts/     # 生成的所有文件
└── status.txt     # 完成确认
  • 每个Agent拥有独立目录
  • 完整输出被保留以供后续查看
  • 仍使用状态文件进行快速完成检查

Task Prompt Template

任务提示模板

markdown
undefined
markdown
undefined

Task: <TASK_NAME>

Task: <TASK_NAME>

Your Mission

你的任务

<clear objective>
<明确目标>

Output

输出要求

When done, write confirmation: ```bash echo "COMPLETE: <identifier> - $(date)" >> .claude/cache/<batch>-status.txt ```
Do NOT return large output. Complete work silently.
undefined
完成后，写入确认信息： ```bash echo "COMPLETE: <identifier> - $(date)" >> .claude/cache/<batch>-status.txt ```
请勿返回大量输出。静默完成工作。
undefined

Launching Pattern

启动模式

typescript
// Launch all in single message block (parallel)
Task({
  description: "Task 1",
  prompt: "...",
  subagent_type: "general-purpose",
  run_in_background: true
})
Task({
  description: "Task 2",
  prompt: "...",
  subagent_type: "general-purpose",
  run_in_background: true
})
// ... up to 15 parallel agents
typescript
// 在单个消息块中启动所有任务（并行）
Task({
  description: "Task 1",
  prompt: "...",
  subagent_type: "general-purpose",
  run_in_background: true
})
Task({
  description: "Task 2",
  prompt: "...",
  subagent_type: "general-purpose",
  run_in_background: true
})
// ... 最多支持15个并行Agent

Monitoring

监控

bash
undefined
bash
undefined

Check completion status

检查完成状态

cat .claude/cache/<batch>-status.txt
cat .claude/cache/<batch>-status.txt

Count completions

统计完成数量

wc -l .claude/cache/<batch>-status.txt
wc -l .claude/cache/<batch>-status.txt

Watch for updates

实时监控更新

tail -f .claude/cache/<batch>-status.txt
undefined
tail -f .claude/cache/<batch>-status.txt
undefined

Batch Size

批量大小

  • Max 15 agents per parallel batch
  • Wait for batch to complete before launching next
  • Use status file to track which completed
  • 每个并行批次最多15个Agent
  • 等待当前批次完成后再启动下一批次
  • 使用状态文件跟踪已完成的任务

DO

需遵守的规则

  • Use 
    run_in_background: true
    always
  • Have agents write to status files
  • Use append (
    >>
    ) not overwrite (
    >
    )
  • Give each agent clear, self-contained instructions
  • Include all context in prompt (agents don't share memory)
  • 始终使用
    run_in_background: true
  • 让Agent写入状态文件
  • 使用追加（
    >>
    ）而非覆盖（
    >
    ）
  • 为每个Agent提供清晰、独立的指令
  • 将所有上下文包含在提示中（Agent不共享内存）

DON'T

禁止操作

  • Call TaskOutput (bloats context)
  • Return large outputs from agents
  • Launch more than 15 at once
  • Rely on agent return values for orchestration
  • 调用TaskOutput（会导致上下文冗余）
  • 让Agent返回大量输出
  • 一次启动超过15个Agent
  • 依赖Agent的返回值进行编排

Example: Provider Backfill

示例：供应商数据回填

bash
undefined
bash
undefined

Status file

状态文件

.claude/cache/provider-backfill-status.txt
.claude/cache/provider-backfill-status.txt

Each agent appends on completion

每个Agent完成后追加信息

echo "COMPLETE: anthropic - Thu Jan 2 12:34:56 2025" >> .claude/cache/provider-backfill-status.txt echo "COMPLETE: openai - Thu Jan 2 12:35:12 2025" >> .claude/cache/provider-backfill-status.txt

Check progress:
```bash
cat .claude/cache/provider-backfill-status.txt
echo "COMPLETE: anthropic - Thu Jan 2 12:34:56 2025" >> .claude/cache/provider-backfill-status.txt echo "COMPLETE: openai - Thu Jan 2 12:35:12 2025" >> .claude/cache/provider-backfill-status.txt

查看进度：
```bash
cat .claude/cache/provider-backfill-status.txt

COMPLETE: anthropic - Thu Jan 2 12:34:56 2025

COMPLETE: anthropic - Thu Jan 2 12:34:56 2025

COMPLETE: openai - Thu Jan 2 12:35:12 2025

COMPLETE: openai - Thu Jan 2 12:35:12 2025

undefined
undefined