Agent 团队协作

多 Agent 架构

在实际项目中，单个 Agent 往往难以胜任所有任务。ThePopeBot 支持多 Agent 架构，让你可以组建一个各有专长的 Agent 团队。

架构模式

ThePopeBot 提供三种多 Agent 协作模式：

1. 层级模式（Hierarchical）
   主管 Agent → 分配任务 → 专家 Agent → 汇报结果

2. 对等模式（Peer-to-Peer）
   Agent A ⇄ Agent B ⇄ Agent C（平等协作）

3. 流水线模式（Pipeline）
   Agent A → Agent B → Agent C（串行处理）

定义 Agent 团队

import { defineTeam } from '@thepopebot/core';

export const devTeam = defineTeam({
  name: 'development-team',
  mode: 'hierarchical',
  coordinator: 'tech-lead',
  agents: [
    {
      id: 'tech-lead',
      role: 'coordinator',
      agent: techLeadAgent,
      capabilities: ['task-planning', 'code-review', 'decision-making'],
    },
    {
      id: 'frontend-dev',
      role: 'specialist',
      agent: frontendAgent,
      capabilities: ['react', 'css', 'ui-design', 'accessibility'],
    },
    {
      id: 'backend-dev',
      role: 'specialist',
      agent: backendAgent,
      capabilities: ['api', 'database', 'authentication', 'performance'],
    },
    {
      id: 'qa-engineer',
      role: 'validator',
      agent: qaAgent,
      capabilities: ['testing', 'bug-detection', 'quality-assurance'],
    },
  ],
});

角色分工

每个 Agent 在团队中扮演特定角色。良好的角色分工能让团队高效运转。

协调者（Coordinator）

协调者负责接收任务、分析需求并将子任务分配给合适的专家。

const techLeadAgent = defineAgent({
  name: 'tech-lead',
  systemPrompt: `你是开发团队的技术负责人。你的职责是：
    1. 分析收到的任务需求
    2. 将任务拆解为可并行的子任务
    3. 根据专长将子任务分配给团队成员
    4. 审查团队成员的输出质量
    5. 汇总结果并形成最终交付物

    团队成员及其专长：
    - frontend-dev: React、CSS、UI 设计
    - backend-dev: API、数据库、认证
    - qa-engineer: 测试、质量保证`,
  tools: ['task-manager', 'team-communication'],
});

专家（Specialist）

专家 Agent 专注于特定领域的任务执行：

const frontendAgent = defineAgent({
  name: 'frontend-dev',
  systemPrompt: `你是一位资深前端开发工程师，精通：
    - React/TypeScript 开发
    - CSS/Tailwind 样式
    - 响应式设计
    - Web 可访问性标准
    你只处理前端相关的任务，其他任务请转交给合适的团队成员。`,
  tools: ['filesystem', 'shell', 'browser-preview'],
});

验证者（Validator）

验证者负责检查其他 Agent 的输出质量：

const qaAgent = defineAgent({
  name: 'qa-engineer',
  systemPrompt: `你是质量保证工程师，负责：
    - 审查代码质量和规范
    - 编写和运行测试用例
    - 检测潜在的 Bug 和安全问题
    - 验证功能是否符合需求`,
  tools: ['codeAnalysis', 'testRunner', 'securityScanner'],
});

任务委派模式

当协调者收到一个复杂任务时，它会自动进行任务拆解和委派。

// 任务委派流程示例
const taskDelegation = {
  originalTask: '开发一个用户注册功能',

  decomposition: [
    {
      subtask: '设计注册 API 端点',
      assignTo: 'backend-dev',
      priority: 'high',
      dependencies: [],
    },
    {
      subtask: '创建注册表单 UI',
      assignTo: 'frontend-dev',
      priority: 'high',
      dependencies: [],
    },
    {
      subtask: '实现表单验证和 API 对接',
      assignTo: 'frontend-dev',
      priority: 'medium',
      dependencies: ['设计注册 API 端点'],
    },
    {
      subtask: '编写端到端测试',
      assignTo: 'qa-engineer',
      priority: 'medium',
      dependencies: ['创建注册表单 UI', '设计注册 API 端点'],
    },
  ],
};

委派策略

ThePopeBot 支持多种委派策略：

策略	说明	适用场景
capability-match	根据能力匹配	通用场景
load-balance	负载均衡	任务量大时
priority-first	优先级驱动	紧急任务
round-robin	轮询分配	均匀分配

Agent 间通信

Agent 之间通过消息总线进行通信，支持同步和异步两种方式。

直接通信

// Agent A 向 Agent B 发送消息
await teamBus.send({
  from: 'frontend-dev',
  to: 'backend-dev',
  type: 'query',
  content: '注册 API 的请求格式是什么？',
});

// Agent B 接收并响应
teamBus.on('message', async (msg) => {
  if (msg.to === 'backend-dev' && msg.type === 'query') {
    const response = await backendAgent.process(msg.content);
    await teamBus.reply(msg.id, response);
  }
});

广播通信

// 协调者向所有成员广播
await teamBus.broadcast({
  from: 'tech-lead',
  type: 'announcement',
  content: '需求已变更，请暂停当前任务等待新指令。',
});

事件驱动通信

// 当后端任务完成时，自动通知前端
teamBus.on('task-completed', async (event) => {
  if (event.agentId === 'backend-dev' && event.task.type === 'api-design') {
    await teamBus.send({
      from: 'system',
      to: 'frontend-dev',
      type: 'dependency-ready',
      content: `API 设计完成，接口文档：${event.result.apiSpec}`,
    });
  }
});

示例：代码审查流水线

让我们构建一个完整的代码审查流水线，展示多 Agent 协作的强大能力：

import { definePipeline } from '@thepopebot/core';

export const codeReviewPipeline = definePipeline({
  name: 'code-review',
  trigger: 'pull_request.opened',

  stages: [
    {
      name: 'static-analysis',
      agent: 'code-assistant',
      task: async (pr) => ({
        type: 'static-analysis',
        files: pr.changedFiles,
        checks: ['complexity', 'duplication', 'naming'],
      }),
    },
    {
      name: 'security-review',
      agent: 'security-agent',
      task: async (pr, prevResults) => ({
        type: 'security-scan',
        files: pr.changedFiles,
        severity: 'medium',
        context: prevResults['static-analysis'],
      }),
    },
    {
      name: 'test-coverage',
      agent: 'qa-engineer',
      task: async (pr) => ({
        type: 'coverage-check',
        minCoverage: 80,
        newFiles: pr.addedFiles,
      }),
    },
    {
      name: 'final-review',
      agent: 'tech-lead',
      task: async (pr, prevResults) => ({
        type: 'comprehensive-review',
        allResults: prevResults,
        action: 'generate-review-comment',
      }),
    },
  ],

  onComplete: async (results) => {
    // 在 PR 上发布综合审查评论
    await github.createReviewComment(results.prNumber, results.summary);
  },
});

流水线执行流程

PR 创建 → 静态分析 → 安全审查 → 测试覆盖率检查 → 综合评审 → 发布评论

每个阶段的输出会作为下一阶段的输入，形成完整的信息链条。最终由技术负责人 Agent 汇总所有结果，生成一份全面的审查报告。

小结

今天你学习了 ThePopeBot 多 Agent 协作的核心概念，包括团队定义、角色分工、任务委派和 Agent 间通信。你还构建了一个完整的代码审查流水线。明天我们将深入高级配置与定制化开发。