Swarm 多智能体工作流
本教程演示如何使用 Shannon 的 SwarmWorkflow 部署持久化协作智能体,它们并行工作,支持智能体间消息传递和共享工作区。你将学到
- 如何通过 API 和 Python SDK 提交 Swarm 任务
- 智能体如何分解、执行和综合结果
- 如何通过 SSE 流式传输监控智能体进度
- 如何配置 Swarm 参数
- 实际用例与最佳实践
前置条件
- 已运行的 Shannon 堆栈(Docker Compose)
- Gateway 可通过
http://localhost:8080访问 config/features.yaml中已启用 Swarm(默认启用)- 鉴权默认:
- Docker Compose:默认关闭鉴权(
GATEWAY_SKIP_AUTH=1)。 - 本地构建:默认开启鉴权。可设置
GATEWAY_SKIP_AUTH=1关闭;或在请求中加入 API key 头-H "X-API-Key: $API_KEY"。
- Docker Compose:默认关闭鉴权(
快速开始
curl -X POST http://localhost:8080/api/v1/tasks \
-H "Content-Type: application/json" \
-d '{
"query": "Compare AI chip markets across US, Japan, and South Korea",
"session_id": "swarm-demo-001",
"context": {
"force_swarm": true
}
}'
{
"task_id": "task-abc123...",
"status": "STATUS_CODE_OK",
"message": "Task submitted successfully",
"created_at": "2025-11-10T10:00:00Z"
}
data: {"type":"WORKFLOW_STARTED","agent_id":"swarm-supervisor","message":"Assigning a team of agents"}
data: {"type":"PROGRESS","agent_id":"swarm-supervisor","message":"Planning approach"}
data: {"type":"PROGRESS","agent_id":"swarm-supervisor","message":"Assigning 3 agents"}
data: {"type":"AGENT_STARTED","agent_id":"takao","message":"Agent takao started"}
data: {"type":"AGENT_STARTED","agent_id":"mitaka","message":"Agent mitaka started"}
data: {"type":"AGENT_STARTED","agent_id":"kichijoji","message":"Agent kichijoji started"}
data: {"type":"PROGRESS","agent_id":"takao","message":"Agent takao progress: iteration 1/25, action: tool_call"}
data: {"type":"AGENT_COMPLETED","agent_id":"takao","message":"Agent takao completed"}
data: {"type":"AGENT_COMPLETED","agent_id":"mitaka","message":"Agent mitaka completed"}
data: {"type":"AGENT_COMPLETED","agent_id":"kichijoji","message":"Agent kichijoji completed"}
data: {"type":"PROGRESS","agent_id":"swarm-supervisor","message":"Combining findings from 3 agents"}
data: {"type":"WORKFLOW_COMPLETED","agent_id":"swarm-supervisor","message":"All done"}
{
"task_id": "task-abc123...",
"status": "TASK_STATUS_COMPLETED",
"result": "## AI Chip Market Comparison\n\n### United States\nThe US market is dominated by NVIDIA...\n\n### Japan\nJapan focuses on edge AI...\n\n### South Korea\nSouth Korea leverages Samsung...",
"metadata": {
"workflow_type": "swarm",
"total_agents": 3,
"agents": [
{"agent_id": "takao", "iterations": 8, "tokens": 12400, "success": true, "model": "gpt-5-mini-2025-08-07"},
{"agent_id": "mitaka", "iterations": 6, "tokens": 9800, "success": true, "model": "gpt-5-mini-2025-08-07"},
{"agent_id": "kichijoji", "iterations": 7, "tokens": 11200, "success": true, "model": "gpt-5-mini-2025-08-07"}
]
}
}
一步提交 + 流式传输
对于前端应用,使用合并的提交+流式传输端点:Python SDK
基本用法
带流式传输
自定义上下文
智能体协作方式
团队名册
每个智能体都会收到团队名册,显示所有智能体及其任务分配。这使智能体知道就特定信息联系谁:发布发现
智能体通过共享工作区分享发现。这些内容会出现在每个智能体的提示上下文中:发送直接消息
智能体可以向特定队友发送直接消息:请求帮助
当智能体需要额外支持时,可以向监督者请求帮助:配置
features.yaml
配置参数
| 参数 | 默认值 | 范围 | 描述 |
|---|---|---|---|
enabled | true | true/false | 启用或禁用 Swarm 工作流 |
max_agents | 10 | 1-50 | 智能体总数上限(含动态生成) |
max_iterations_per_agent | 25 | 1-100 | 每个智能体的最大推理-行动循环次数 |
agent_timeout_seconds | 600 | 60-3600 | 每个智能体的超时时间 |
max_messages_per_agent | 20 | 1-100 | 每个智能体可发送的 P2P 消息上限 |
workspace_snippet_chars | 800 | 100-4000 | 智能体提示中工作区条目的截断限制 |
workspace_max_entries | 5 | 1-20 | 每个主题显示的最近工作区条目数 |
实际用例
市场研究
分配智能体并行研究不同市场或竞争对手,然后综合为统一报告。
技术对比
每个智能体评估不同的框架、库或架构,在发现过程中实时分享。
多区域分析
智能体同时研究不同地理区域,发现交叉传播。
文献综述
智能体探索研究课题的不同方面,通过工作区分享来源和关键发现。
示例:技术框架对比
示例:综合行业分析
理解响应元数据
Swarm 工作流返回包含每个智能体详情的元数据:| 字段 | 描述 |
|---|---|
workflow_type | Swarm 工作流始终为 "swarm" |
total_agents | 参与的智能体总数 |
agents[].agent_id | 唯一智能体名称 |
agents[].iterations | 完成的推理-行动循环次数 |
agents[].tokens | 该智能体消耗的总 Token 数 |
agents[].success | 智能体是否成功完成 |
agents[].model | 智能体使用的 LLM 模型 |
提示与最佳实践
- 入门
- 性能
- 不适用场景
- 设置
context.force_swarm: true路由到 SwarmWorkflow - 从默认配置开始,根据结果进行调整
- 通过 SSE 事件监控智能体行为
- 使用会话(
session_id)进行多轮 Swarm 对话
故障排除
回退行为
如果 Swarm 工作流失败(分解错误、所有智能体失败等),Shannon 会自动回退到标准 DAG/Supervisor 工作流路由。force_swarm 标志会从上下文中移除以防止递归失败。