sync execution

同步执行模式下，主 Agent 等待子 Agent 完成后再继续。

执行流程

1

主 Agent

调用子 Agent（阻塞）

2

子 Agent 执行

3

返回结果

4

主 Agent 继续

核心实现

async function executeSyncAgent(
  input: AgentInput,
  context: AgentContext
): Promise<ToolResult> {
  // 1. 准备消息
  const messages = [
    { role: 'user', content: input.prompt },
  ];
  
  // 2. 添加上下文文件
  if (input.contextFiles) {
    const contextContent = await loadContextFiles(input.contextFiles);
    messages[0].content += '\n\n' + contextContent;
  }
  
  // 3. 执行 Query Loop
  let finalResponse = '';
  
  for await (const event of query(messages, context.tools, {
    system: context.systemPrompt,
    model: context.model,
  })) {
    if (event.type === 'content') {
      finalResponse += event.content;
    }
  }
  
  // 4. 返回结果
  return {
    success: true,
    output: finalResponse,
  };
}

使用场景

1. 代码分析

// 主 Agent 需要分析结果才能继续
const analysis = await invokeSubAgent({
  name: 'context-gatherer',
  prompt: '分析项目结构',
});

// 基于分析结果继续工作
for (const file of analysis.files) {
  await processFile(file);
}

2. 决策支持

// 需要子 Agent 的建议
const recommendation = await invokeSubAgent({
  name: 'architecture-advisor',
  prompt: '这个重构方案是否合理？',
  contextFiles: [{ path: 'src/refactor-plan.md' }],
});

if (recommendation.approved) {
  await executeRefactoring();
}

3. 数据转换

// 子 Agent 处理数据转换
const transformed = await invokeSubAgent({
  name: 'data-transformer',
  prompt: '将 JSON 转换为 TypeScript 类型',
  contextFiles: [{ path: 'data.json' }],
});

await fsWrite({
  path: 'types.ts',
  text: transformed.output,
});

性能考量

执行时间

同步执行会阻塞主 Agent：

// 主 Agent 等待子 Agent
const start = Date.now();
const result = await invokeSubAgent({ ... });
const duration = Date.now() - start;

console.log(`Sub-agent took ${duration}ms`);

超时控制

async function executeSyncAgentWithTimeout(
  input: AgentInput,
  timeout: number
): Promise<ToolResult> {
  return Promise.race([
    executeSyncAgent(input, context),
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error('Timeout')), timeout)
    ),
  ]);
}

错误处理

子 Agent 失败

try {
  const result = await invokeSubAgent({ ... });
  
  if (!result.success) {
    // 子 Agent 失败，主 Agent 处理
    console.error('Sub-agent failed:', result.error);
    
    // 回退策略
    return await fallbackStrategy();
  }
} catch (error) {
  // 执行错误
  console.error('Sub-agent execution error:', error);
}

重试机制

async function invokeSubAgentWithRetry(
  input: AgentInput,
  maxRetries: number = 3
): Promise<ToolResult> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const result = await invokeSubAgent(input);
      
      if (result.success) {
        return result;
      }
      
      // 失败但可重试
      await sleep(1000 * (i + 1));
    } catch (error) {
      if (i === maxRetries - 1) {
        throw error;
      }
    }
  }
}

上下文传递

文件上下文

await invokeSubAgent({
  name: 'code-reviewer',
  prompt: 'Review this code',
  contextFiles: [
    { path: 'src/auth.ts' },
    { path: 'src/types.ts', startLine: 10, endLine: 50 },
  ],
});

状态上下文

// 传递当前状态
await invokeSubAgent({
  name: 'task-planner',
  prompt: 'Plan next steps',
  context: {
    completedTasks: state.completedTasks,
    currentGoal: state.currentGoal,
  },
});

下一步

• 了解 异步执行 的非阻塞模式

• 探索 Swarm 模式 的并行协作

• 查看 Worktree 隔离 的实现