openserv-multi-agent-workflows

OpenServ 上的多 Agent 工作流

构建多个 AI Agent 协作完成复杂任务的工作流。

参考文件：

• reference.md - 工作流模式、声明式同步、触发器、监控
• troubleshooting.md - 常见问题及解决方案
• examples/ - 完整的流水线示例（blog、youtube-to-blog 等）

---

快速入门

完整的可运行示例请参阅 examples/：

• blog-pipeline.md - 简单的双 Agent 工作流（研究 → 写作）
• content-creation-pipeline.md - 三 Agent 工作流（研究 → 写作 → 图片）
• life-coaching-pipeline.md - 复杂的六 Agent 工作流，包含全面的输入架构

推荐使用 workflows.sync() 模式：

1. 使用 client.authenticate() 进行身份验证
2. 使用 client.agents.listMarketplace() 查找 Agent
3. 使用 client.workflows.create() 创建工作流，其中包括：
   • 触发器
   • 任务
   • 边（⚠️ 至关重要 - 用于连接触发器和任务）

⚠️ 至关重要： 创建工作流时，务必定义边。设置任务的 dependencies 并不足够——你必须创建工作流边，才能实际连接触发器与任务，以及各个任务之间。

---

工作流名称与目标

创建工作流时（通过 workflows.create() 或 provision()），有两个关键属性：

• name（字符串）- 这将成为 ERC-8004 中的 Agent 名称。名称应精炼、有力且令人印象深刻——这是用户看到的对外品牌名称。要像在为产品发布命名，而不是给变量命名。示例：'Instant Blog Machine'、'AI Video Studio'、'Polymarket Intelligence'。
• goal（字符串，必填）- 对工作流所实现目标的详细描述。必须具体而全面——目标过于简短或含糊会导致 API 调用失败。至少写一个完整的句子，说明工作流端到端的用途。

---

核心概念

工作流

工作流（工作区）是一个容器，用于容纳多个 Agent 及其任务。

任务依赖关系

• 每个任务都会分配给特定的 Agent
• 任务可以依赖其他任务：dependencies: [taskId1, taskId2]
• 只有当所有依赖任务均处于 done 状态时，任务才会启动
• 依赖任务的输出会传递给依赖它们的任务

工作流图

• 节点：触发器和任务
• 边：节点之间的连接
• 任务 A 完成后，其输出会通过边流向依赖它的任务

Agent 发现

// Search marketplace for agents by name/capability (semantic search)
const result = await client.agents.listMarketplace({ search: 'research' })
const agents = result.items // Array of marketplace agents

// Get agent details
const agent = await client.agents.get({ id: 123 })
console.log(agent.capabilities_description)

// Note: client.agents.searchOwned() only searches YOUR OWN agents
// Use listMarketplace() to find public agents for multi-agent workflows

常见 Agent 类型：研究（Grok、Perplexity）、内容撰写、数据分析、社交媒体（Nano Banana Pro）、视频／音频创作。

---

边的设计最佳实践

至关重要：仔细设计工作流边，避免创建错综复杂的“意大利面条式”图。

设计良好的工作流具有清晰且明确的数据流。常见错误会导致工作流难以维护。

错误模式 - 所有节点都相互连接

         ┌──────────────────────────────────┐
         │           ┌─────────┐            │
         │     ┌─────┤ Agent A ├─────┐      │
         │     │     └────┬────┘     │      │
         │     │          │          │      │
Trigger ─┼─────┼──────────┼──────────┼──────┤
         │     │          │          │      │
         │     │     ┌────┴────┐     │      │
         │     └─────┤ Agent B ├─────┘      │
         │           └─────────┘            │
         └──────────────────────────────────┘
              (Spaghetti - avoid this!)

这会导致：

• 执行顺序不明确
• 难以调试
• Agent 收到重复或冲突的输入
• 难以理解任务之间的依赖关系

良好模式

顺序流水线：

Trigger → Research → Content → Enhancement → Output

分阶段扇出：

                    ┌─ Task A ─┐
Trigger → Research ─┼─ Task B ─┼─→ Combiner → Output
                    └─ Task C ─┘

条件分支（v1.1.3+）：

                    ┌─[approved]─→ Process
Trigger → Review ──┤
                    └─[rejected]─→ Reject Handler

在任务上使用 outputOptions，并在边上使用 sourcePort 进行分支。

保持工作流整洁的指南

1. 通常线性结构最佳：从简单的链式结构开始，只有在确有需要时才增加复杂度
2. 每个任务都应有明确用途：如果你无法解释任务 A 为什么连接到任务 B，就移除这条边
3. 尽量减少交叉连接：避免将每个 Agent 都连接到其他所有 Agent
4. 仅在并行工作时使用扇出：一个来源连接多个任务没有问题；但不要让所有节点彼此相连
5. 在末尾设置一个汇总任务：如果需要合并输出，就设置一个最终任务，使其依赖所有并行分支

添加边之前，请先思考：

• 任务 B 是否确实需要任务 A 的输出？
• 没有这条连接，任务 B 是否也能正常运行？
• 我是不是在“以防万一”的情况下添加这条边？（不要这样做！）

---

更新此技能

此技能可能已过时。OpenServ 团队会定期发布更新，但在你更新之前，此处不会反映新功能、API 变更和错误修复。如果某些功能未按预期运行，或者你想确保获取最新信息，请先更新此技能，再继续操作。

# Check if updates are available
npx skills check

# Update all installed skills to latest versions
npx skills update

或者直接重新安装 OpenServ 技能：

npx skills add openserv-labs/skills

---

相关技能

• openserv-agent-sdk - 构建单个 Agent 的能力
• openserv-client - 完整的平台客户端 API 参考
• openserv-launch - 在 Base 区块链上发布代币
• openserv-ideaboard-api - 在 Ideaboard 上寻找创意并发布 Agent 服务