agent_management/QUICKSTART.md

蜂群模式快速开始

一句话方案

将蜂群的去中心化任务分发、动态角色分配和自组织协作机制，通过在agent-manager中引入任务广播队列、agent能力注册表和竞价响应机制来实现，让agents像蜂群一样根据自身能力主动认领任务而非被动分配。

实现方式

传统方式：Claude Code在本地启动子agent 新方案：Claude Code调用agent-manager API，在K8s上动态创建多个specialized agents协作编码

快速测试

1. 启动服务

conda activate data && python app.py

2. 创建蜂群

curl -X POST http://localhost:8000/api/swarm/create \
  -H "Content-Type: application/json" \
  -d '{
    "task_description": "实现简单的TODO API",
    "agents": [
      {"role": "architect", "template": "a2a_litellm_agent", "replicas": 1},
      {"role": "coder", "template": "code_manager_agent", "replicas": 2},
      {"role": "reviewer", "template": "a2a_litellm_agent", "replicas": 1}
    ],
    "orchestration": {"strategy": "sequential"}
  }'

3. 查询状态

curl http://localhost:8000/api/swarm/{swarm_id}/status

4. 监听结果（SSE）

curl -N http://localhost:8000/api/swarm/{swarm_id}/results

5. 运行测试脚本

python test_swarm_api.py

核心组件

数据库模型

• Swarm: 蜂群主表
• SwarmAgent: Agent实例
• SwarmMessage: 通信消息

API端点

• POST /api/swarm/create - 创建蜂群
• GET /api/swarm/{id}/status - 查询状态
• GET /api/swarm/{id}/results - SSE流式结果
• POST /api/swarm/{id}/stop - 停止蜂群
• GET /api/swarm/{id}/logs - 获取日志

编排策略

• Sequential: architect → coder → reviewer（顺序执行）
• Parallel: 所有agents并行工作
• Hybrid: 混合模式

架构特点

1. K8s原生: 每个agent独立namespace和pod
2. A2A通信: 基于HTTP的agent间通信协议
3. 实时追踪: SSE流式推送进度和结果
4. 灵活编排: 支持多种协作策略
5. 资源隔离: 独立的K8s资源和配额管理

下一步集成

Claude Code MCP工具

{
  "name": "create_code_swarm",
  "description": "在K8s上创建Agent蜂群协作编码",
  "inputSchema": {
    "type": "object",
    "properties": {
      "task": {"type": "string"},
      "agents": {"type": "array"}
    }
  }
}

使用示例

# Claude Code调用
result = await mcp.call_tool("create_code_swarm", {
    "task": "实现用户认证模块",
    "agents": [
        {"role": "architect", "model": "gpt-4"},
        {"role": "coder", "model": "gpt-4", "replicas": 2}
    ]
})

# 监听结果
async for event in mcp.stream_results(result["swarm_id"]):
    if event["type"] == "code_diff":
        apply_diff(event["diff"])

技术债务和改进

当前限制

1. Agent Pods实际部署需要K8s集群（当前为模拟）
2. 后台任务使用FastAPI BackgroundTasks（生产建议Celery）
3. 无认证授权机制
4. 无自动资源清理TTL

建议改进

1. 实现真实的K8s pod部署和监控
2. 添加认证和授权机制
3. 实现自动资源清理和TTL
4. 添加更多编排策略（如基于依赖的DAG执行）
5. 实现agent能力注册和任务竞价机制

文档

详细文档请参考：

• SWARM_README.md - 完整文档
• test_swarm_api.py - API测试示例

Git提交

git log --oneline feature/swarm-mode
# b4b20f0 feat: implement swarm mode for multi-agent collaboration
# 2657ef2 docs: add swarm mode documentation and test script

---

实现完成！ 🎉

核心功能已就绪，可以开始集成到Claude Code或进行进一步的测试和优化。