build-agent-broker-project

⚠️ 严格输出约定 — 适用于此技能中的每一轮助手回复

每轮面向用户的文本不得超过 4 行，除非你要输出已确认项目的编号列表（资产列表、验证结果、资产 → 节点分配）——此时列表本身就是输出，不要添加前言。

禁止使用以下开头。 绝不要以以下任一短语或其同义表达开始一轮回复。如果发现自己正在输入其中之一，请将其删除：

• “我现在要……” / “现在我来……” / “接下来，我……” / “让我……”
• “首先，……” / “开始之前，……” / “在我……之前”
• “根据……” / “鉴于……” / “既然……”
• “太好了！” / “完美！” / “明白了！” / “了解！” / “当然！”
• “我将……” / “我计划……” / “我的方法是……”
• “让我想想……” / “让我分析一下……” / “让我检查一下……”
• “我正在做的是……” / “我的计划是……” / “下面是摘要……”
• “接下来……” / “既然我们已经……” / “现在我们将……”
• 任何描述你接下来要做什么的句子。直接去做。

禁止包含以下内容。 一轮回复中绝不要包含：

• 重述用户刚才说过的内容。用户记得。
• 预先解释本轮之后会发生什么。等到那时再说。
• 重述当前阶段的目标。阶段标题已说明。
• 逐步叙述推理过程。用户只看结论。
• 在正文中提及阶段编号或步骤编号（“第 4 步说明……” / “在第 2 阶段……”）。模型用这些内容导航；用户看不到。

普通回复的必需格式：

<one action OR one question OR one bulleted list>
<optional: one short follow-up sentence, only if strictly needed>
<stop>

阶段结束确认的格式：

<bulleted list of what was captured, ≤ 6 bullets>
Anything missing?

验证结果的格式：

✅ PASS    (or)    ❌ FAIL — <N> issue(s)
- <issue 1>
- <issue 2>

如果某个阶段需要多项操作，请通过工具调用完成，不要在操作之间进行叙述。只在需要决策或确认时输出面向用户的文本。

---

MuleSoft Agent Broker Builder

将多 Agent 工作流的自然语言描述转换为完整、经过验证且可部署的 Agent Network V2（GA，A2A v1.0）项目。提供 6 阶段引导体验，并支持发布和部署。

该技能从头到尾均以 CLI 为主。 验证、发布和部署使用 Anypoint CLI Agent Fabric 插件（mulesoft-anypoint-cli-agent-fabric-plugin）。Exchange 资产搜索使用 Anypoint CLI v4（anypoint-cli-v4 exchange asset list）。两者都可用于 Claude Code、Cursor、Codex 和 Vibes，且与 CI/CD 流程一致。有 MCP 工具（mcp__mulesoft__*）时可作为备用方案，但不依赖 MCP。

适用场景

• 适用于：构建新的 Agent Broker；添加或替换节点、Agent、MCP 工具或 LLM；调整指令；更改路由；运行验证、发布或部署。
• 不适用于：V1 → V2 转换（使用 translate-agent-broker-old-to-new-project）；独立 Mule 应用、DataWeave 或 API。

如果 YAML 中包含 schemaVersion: 1.0.0，则这是 V1 — 停止操作并转交给转换器。V2 标记为 agentNetwork: 2.0.0（不加引号，位于文件顶部）。

参考资料（按需阅读）

• references/canonical-example.md — 完整且可运行的 Agent Network V2（GA，A2A v1.0）项目。结构模板 — 如有疑问，请照此复制。
• references/gotchas.md — GA 语法规则、编译错误规则、RULE-ASSET-MODE（内联与 Exchange）、子 Agent 与协调器的选择、认证大小写规则、CLI 与 MCP 工具集成，以及优雅降级。

MuleSoft Agent Network GA 文档（Anypoint Code Builder 部分）是权威参考。上述参考资料涵盖了常见问题和完整示例。

节点类型术语（阶段语言 ↔ schema 关键字）

以下 6 个阶段使用节点类型的面向用户名称。实际的 .agent 文件使用 schema 关键字。与用户交流时，使用阶段名称；编写文件时，使用关键字。

阶段语言	.agent 关键字	说明
推理节点	subagent	配备工具的大模型。接受操作；内置 HITL。默认的大模型驱动节点类型。
编排节点	orchestrator	配备工具的大模型，专门用于协调多个操作以实现复合目标。仅当节点有 ≥2 个操作且这些操作共同服务于一个结果时才使用。
生成节点	generator	不带工具的大模型。用于一次性生成／摘要／分类，并输出结构化结果。
（无大模型，确定性）	router	根据已知值进行分支。使用条件，而非提示词。
（无大模型，有副作用）	executor	使用已知参数运行一个工具，并设置变量。
（终端）	echo	向客户端发送最终 A2A 响应。

工具集成（优先 CLI，MCP 备用）

此技能优先使用 Anypoint CLI Agent Fabric 插件（mulesoft-anypoint-cli-agent-fabric-plugin）进行验证／发布／部署，并使用 Anypoint CLI v4（anypoint-cli-v4）搜索 Exchange。MuleSoft MCP 服务（mcp__mulesoft__*）作为备用方案。

先尝试 CLI。若 CLI 失败，立即回退到 MCP——不要询问用户，不要重试 CLI，也不要停止当前阶段。

出现以下任一情况时，CLI 尝试视为失败：

• command -v 未返回结果（未安装二进制文件）。
• 命令因用户自身输入以外的原因以非零状态退出（例如 ENOENT、未安装插件、未设置身份验证环境变量、网络错误、需要运行 npm install、“command not found” 或 EACCES）。
• 命令超过合理时限后仍无响应（搜索约 60 秒，构建／发布／部署约 5 分钟）。
• 命令返回成功，但当 schema 要求内容时，输出为空或格式错误（例如，用户明确指定了某个资产，但返回的资产数为零）。

出现以下情况时，CLI 尝试不视为失败：

• 用户输入有误（项目名称无效、缺少必填字段）——将错误告知用户，不要回退。
• 验证／构建正常检测到 schema 错误——报告这些错误；这正是 CLI 的作用。

回退流程（静默按以下顺序执行）：

1. 捕获 CLI 失败。用一行简短的内部说明记录失败原因——除非用户询问，否则不要向用户说明。
2. 检查当前会话中是否注册了对应的 mcp__mulesoft__* 工具。如果有，使用等效输入调用该工具。
3. 如果 MCP 也失败或不可用，则按 references/gotchas.md §“优雅降级”中的说明，回退到无工具方案（文档链接／结构检查清单／询问用户）。
4. 只告诉用户结果（“找到 3 个大模型资产”／“已验证——有 2 个问题”／“无法连接 Exchange——请手动提供 assetId？”），不要逐一说明你使用了哪些工具。

如果 CLI 命令需要更多信息才能运行（未知标志、不熟悉的子命令、语法不明确）：先尝试 <command> --help，如果仍未解决，再进行公开网络搜索。只有两者都没有结果时，才向用户询问。此规则适用于 CLI 插件和 anypoint-cli-v4。不要说明查找过程；只需使用修正后的语法运行命令。

完整的能力矩阵、CLI 命令语法、环境变量身份验证（ANYPOINT_CLIENT_ID/SECRET/ORG/ENV）以及各步骤的 CLI ↔ MCP 对应关系，请参阅 references/gotchas.md §“工具集成”。

---

工作流 A — 构建新项目（阶段 1–6 + 发布／部署）

以下 6 个阶段构成构建流程。每个阶段结束时都有一个暂停点——等待用户。立即处理每条用户回复（不要等到批量处理后再更新）。

步骤 1：前置检查 + 搭建框架

1. 检测现有项目。 如果工作文件夹中有 agent-network.yaml + exchange.json + brokers/，询问：“编辑这个项目，还是在同级文件夹中搭建新项目？” 默认编辑（工作流 B）。
2. 检测架构版本。 schemaVersion: 1.0.0 → 转到转换器。
3. 用一句话确认意图： “你想让我构建一个能执行 X 的新 Agent Broker。对吗？”
4. 收集搭建框架所需的信息（调用 CLI 前询问）：
   • 项目名称（kebab-case，例如 it-help-investigation）——也会成为默认的 assetId。
   • 输出目录（默认：当前工作目录）。
   • 资源版本（开发期间默认 0.0.0；用户可在首次发布时升级版本）。
5. 通过 CLI 搭建框架。 从父目录运行 create 命令：

   anypoint-cli-agent-fabric-plugin agent-network project create \
     --name <project-name> \
     --output-dir <parent-dir> \
     --create-dir
   

   这会生成 <project-name>/agent-network.yaml + exchange.json + brokers/，并使用正确的 groupId/organizationId（从 ANYPOINT_ORG 获取）和起始模板。随后，Skill 会直接编辑生成的文件。
   • 如果 CLI 不可用，但存在 mcp__mulesoft__create_agent_network_project，则使用相同的信息调用 MCP 工具。
   • 如果两者都不可用，则直接编写规范的框架结构（agent-network.yaml 中包含 agentNetwork: 2.0.0，exchange.json 中包含 "classifier": "agentic-network"，以及空的 brokers/），并告知用户发布前需要填写 groupId/organizationId 占位值。
6. 为 agent-network.yaml 收集网络的 info： 询问 info.label（必填）和 info.description（可选）。除非用户另有指定，否则 info.version 默认为 1.0.0。立即将这些信息应用到框架中。

步骤 2：功能需求（阶段 1）

目标： 引导用户清晰地定义功能需求。拒绝模糊的回答——持续追问，直到每一项都具体明确。用户无需使用图相关术语；用自然语言描述步骤即可。

按顺序收集：

1. 触发条件——什么事件会启动流程？（几乎总是 A2A message/send。请确认。）
2. 工作流步骤和分支逻辑——“如果发生 X，就必须执行 Y。” 逐步梳理每个步骤。
3. 硬性约束——有哪些绝对限制？这些应成为路由器条件，而不是提示词句子。
4. 确定性与开放性——对于每个步骤：结果是否 100% 可预测（图分支），还是需要大模型推理/判断（大模型驱动的节点）？

如果用户对同一项连续两次给出模糊回答，则接受占位内容、标记该项，然后继续。

阶段结束时进行一次确认：“以下是我记录的内容：[项目符号摘要]。有什么遗漏吗？” 然后停止。

第 3 步：初始资产注册（阶段 2）

目标： 在 Exchange 中找到合适的资产，并将其注册到 YAML 中。

资产类型：大模型（至少 1 个）、MCP 工具、A2A Agent。

资产搜索顺序 — 针对阶段 1 中确定的每项能力：

1. 优先搜索 Private Exchange。 如果已安装 anypoint-cli-v4：anypoint-cli-v4 exchange asset list --search "<keywords>" --organization <orgId>。否则，如果 MCP search_asset 可用：使用 assetFilters: ["llm"] / ["mcp"] / ["agent"] + exchangeScope: "Private" 调用。
2. 如果 Private Exchange 中没有匹配项，则搜索 Public Exchange。 删除 --organization / 将 exchangeScope 设为 "Public"。
3. 如果两者都没有，则使用占位项。 注册为 Inline，并使用 ${var} 格式的 URL/身份验证占位符，供用户之后填写。

大模型的选择方式不同。 不要自动选择。列出在 Exchange 中找到的大模型选项（例如，claude、openai、gemini），并询问："请选择一个或多个，或创建一个新的。" 然后停止。

写入前与用户确认："已选：［列表］。确认吗？" 然后停止。

注册所有已确认的资产到 agent-network.yaml + exchange.json 中。每项资产有两种模式之一 — 参见 references/gotchas.md § "RULE-ASSET-MODE"：

• Inline（资产不在 Exchange 中）：注册表条目 + 带有 ref.name 的 context.connections。
• Exchange（资产已发布）：exchange.json.dependencies + 带有 ref.name 和 ref.namespace 的 context.connections。不添加注册表条目。

身份验证信息始终位于 context.connections.<id>.authentication。使用 ${<name>.url} / ${<name>.apiKey} 参数化 URL/密钥。在对应的 exchange.json.metadata.variables 中添加变量。将密钥标记为 "secret": true。

各类型的架构说明：

• 大模型 — Inline：info.label、metadata.platform: Gemini | OpenAI | AzureOpenai。连接：kind: llm + url + authentication。
• MCP — Inline：info.label、metadata.transport.kind（streamableHttp | sse | stdio）。注册后，询问用户要调用的 tool_name（该操作必需）。询问用户是否知道输入参数。如果知道，在 action 的 inputs: 中声明。如果不知道，则省略 inputs: — 运行时会自动发现。切勿编造工具名称或输入架构。
• A2A — Inline：info.label + interfaces 分支。当前的 A2A v1.0 Agent 使用 a2a，旧版 A2A v0.3 使用 a2a_v03（Agent Broker 保持向后兼容）。metadata.interfaces.<branch>.card 中的卡片包含 name、description、url、protocolVersion、version、capabilities、defaultInputModes、defaultOutputModes、skills。有关各分支的具体结构，请参见 references/gotchas.md § "Registry agents"。

步骤 4：技术图定义（阶段 3——Agent 脚本）

目标： 将功能需求转化为 .agent 图。这里只编写 system.instructions 和各节点指令的简要初稿——阶段 5 会进一步润色文案。

指导原则：图 = 预定义规则。LLM 节点 = 推理。 对任何可以明确硬编码的内容，都使用图。仅在确实需要推理的任务中使用 LLM 驱动的节点（reasoning/orchestrator/generate）。图充当主干，负责执行高级阶段（例如：研究 → 起草 → 审核）；在每个阶段内，LLM 驱动的节点拥有自主权。

编写图的第一版：

1. 配置。 根据用户需求选择 agent_name（kebab-case；同时作为 .agent 文件名主体和 broker id，例如 it-help-investigation）。
2. 触发器（入口点）。 每个 broker 对每个已声明的接口只能有一个触发器。kind: "a2a"、target: "brokers://<broker-id>/a2a"，on_message: 是固定的 transition to。触发器中的条件判断会导致编译错误——应在下游使用路由器。
3. LLM 驱动的节点（按阶段选择合适的类型）：
   • 推理节点（subagent 关键字）——配备工具的 LLM。默认的 LLM 驱动类型。内置 HITL。
   • 编排器节点（orchestrator 关键字）——配备工具的 LLM，专门用于协调多个操作以实现复合目标。
   • 生成节点（generator 关键字）——不配备工具的 LLM。用于一次性生成、摘要或结构化输出的分类。
4. 数据结构（变量）。 声明在节点间共享的状态。
5. 确定性连接。 每个非终止节点都有一个 on_exit: -> transition to @<nodeType>.<nodeId>。每条可达路径最终都必须终止于 echo。
6. 条件判断应放在路由器节点中。路由器声明 routes: + otherwise:，且没有 on_exit（在路由器的 on_exit 中使用 transition to 会导致编译错误）。阶段 1 的硬性约束应写入路由器条件，而不是提示词。提示词可以被忽略；路由器条件则不会。
7. 触发器之后的第一个节点不应是一个会复制 @request.payload.message 的直通 executor。应在下游直接引用 @request.payload.message.parts[0].text。
8. Echo 终点。 每条可达路径都必须以 echo 结束，且 kind: "a2a:status_update_event"（对于 artifacts，则为 kind: "a2a:artifact_update_event"）。关于 TASK_STATE_* 枚举和 a2a.* 辅助函数规则，请参阅 references/gotchas.md 中的“Echo node”一节。

编写第一版 system.instructions 和每个 LLM 驱动节点的提示词——保持简短；阶段 5 会进一步润色。

更新 agent-network.yaml 中的 brokers 条目，使其引用新的 .agent 文件。完整的编译错误规则请参阅 references/gotchas.md 中的“Compile-error rules”一节。结构模板请参阅 references/canonical-example.md。

步骤 5：将资产分配到图中（阶段 4）

目标： 将 YAML 中的资产分配给正确的 LLM 驱动节点。

指导原则：

• 让每个 LLM 驱动节点专注于一个领域。 将相似资产归入同一个节点，而不是分散到多个节点。
• 推理节点还是编排节点——根据连接的资产来选择：
  • 节点上只有 MCP 资产 → 推理节点（subagent）。
  • 节点上有任何 A2A 资产 → 编排节点（orchestrator）。
• 每个 LLM 驱动节点最多 4 项资产（A2A 和 MCP 合计）。超过此数量 → 会产生幻觉。请拆分节点。
• 最小权限原则。 一个节点使用只读工具，另一个节点使用写入权限工具。切勿混用。
• 不可逆变更（升级处理、删除、发送给客户等）必须放在由 router 控制的 executor 节点中。 切勿将其放在推理节点或编排节点上——LLM 可能会绕过路由器调用它们。幂等更新（状态更新、工单更新）可以放在编排节点上，前提是它们属于复合目标的一部分。

操作：

1. 重新阅读图、YAML 和各节点说明，以刷新上下文。
2. 为每个推理节点或编排节点分配资产：“这个节点需要哪个 YAML 资产？” 如果没有可用资产，请让用户创建一个。
3. 在 .agent 文件中绑定。每项资产都要有一个 actions: 条目（A2A：仅包含 target + kind，不包含 inputs:；MCP：包含 target、kind、tool_name，以及可选的 inputs:）。在 reasoning.actions（推理节点或编排节点）或 do: run（执行节点）中引用。
4. 所有节点分配完成后，请与用户确认：“以下是资产 → 节点的分配：[列表]。确认吗？” 然后停止。
5. 让用户为每个 LLM 驱动节点选择 LLM（不同节点可以使用不同的 LLM——例如，分类使用较便宜的模型，编排使用更强的模型）。
6. 为每个推理节点或编排节点编写一行易读的描述，说明该节点的作用。将描述存储在节点上。

完整的绑定规则请参阅 references/gotchas.md：

• § "Compile-error rules — action invocation" — 执行节点中的 A2A 裸引用与 with message =；MCP with 规则；http_headers 隐式处理。
• § "Stage 4: Bind to nodes" — 4 项资产上限、最小权限、操作别名命名。

步骤 6：完善指令（阶段 5）

目标： 完善并全面测试每个 LLM 驱动节点的指令。一次处理一个节点，切勿批量处理。

对于每个 generate、推理或编排节点：

1. 只需命名一次节点：“正在完善 classifySeverity。”（不要在后续轮次中重复说明当前处理的是哪个节点——用户记得。）
2. 展示 system.instructions 的 V1 版本（阶段 3 中的简短草稿）。
3. 只询问一次： “整体反馈如何？有什么成功标准或少样本示例吗？” 然后停止。
4. 将 V2 编写为编号步骤。 每一步对应一次工具调用或一个输出决策。不要写“提供帮助”或“保持专业”。
5. 让输出具体明确。 如果节点有 outputs.properties.severity.enum，提示词必须使用枚举字面值，明确说明 “X 时将 severity 设为 high，否则设为 low”。
6. 预想边缘情况。 如果缺少关键字段怎么办？请在指令中明确说明处理方式。
7. 逐节点进行矛盾测试。 V2 中的某个步骤是否会被确定性的图逻辑排除？请协调解决。
8. 立即将 V2 应用到文件中。然后处理下一个节点。

完善每个节点后： 执行跨节点矛盾测试——检查某个提示词步骤是否与其他节点的提示词或图冲突。向用户指出冲突并解决。

步骤 7：最终拓扑审查（阶段 6）

清理，然后验证。

清理：

1. 移除未解析的 {{...}} 标记、未使用的 exchange.json 变量。
2. 移除未使用的 registry 资源（未被 context.connections、actions 或 LLM 块引用）。
3. 移除未使用的 context.connections 条目。
4. 移除 .agent 文件中孤立的 action 定义。
5. 移除空的 YAML 键（没有条目的 registry.llms: → 删除该键）。

验证。 运行构建命令（优先使用 CLI → 其次使用 MCP → 然后使用下方的结构检查清单和安装提示）。完整命令语法见 references/gotchas.md §「步骤 7 — 验证/构建」。

结构检查清单：

• 每个节点都能从触发器到达吗？没有孤立节点。
• 每条可达路径都会在 echo 处终止吗？
• 每个 router 都有 routes（≥1）和 otherwise 吗？
• 每个 subagent/orchestrator 都有 reasoning.instructions 和至少一个 action 或 HITL 吗？
• 节点中引用的每个 action 都与 actions: 中的条目匹配吗？
• 每个 ${...} 变量都有对应的 exchange.json.metadata.variables 条目吗？
• 每个 context.connections.<id>.ref.name 都能解析到 registry 条目或 exchange.json.dependencies 吗？
• reasoning.actions 中的所有 A2A actions 都是裸引用（没有 with message =）吗？
• 所有 MCP with 参数都引用已声明的 inputs: 字段吗？
• 所有 echo state 值都属于允许的枚举吗？
• 是否通过 router 条件而非提示词来强制执行硬性约束？
• 是否设置了操作上限：max_number_of_loops 是否已从默认值 25 调低（例如，分类设为 3，编排设为 5–10）；如果调用响应较慢的下游 Agent，是否设置了 task_timeout_secs？

修复循环：

• 按文件归类错误。自动修复格式、缩进和缺少的必需键。对于缺少架构必需的引用，询问用户——绝不自动插入缺失的资源。循环修复，直到没有错误。

全部通过后：“项目已验证并准备就绪。要发布到 Exchange 并部署到运行时吗？”

步骤 8：发布（可选）

仅在用户有此意愿时执行。前提条件：CLI/MCP 上下文已通过身份验证；exchange.json 包含 assetVersion，且 secret: true 变量没有空的 default: ""。

运行发布命令（优先使用 CLI → 其次使用 MCP → 然后提供文档链接）。从输出中展示已发布资源的 URL。完整命令语法见 references/gotchas.md §「步骤 8 — 发布」。

步骤 9：部署（可选）

仅在用户有此意愿时执行。必须先完成发布。

询问用户：environmentName、targetSpace（私有空间），以及针对环境专属密钥的任何部署属性（例如，--property openai.apiKey:STAGING_API_KEY）。

**每个私有空间仅需设置一次：**如果目标空间还没有网关，请先运行网关设置命令。

运行部署命令（优先使用 CLI → 其次使用 MCP → 然后提供文档链接）。展示部署 URL/ID。完整命令语法、网关默认值和 CI 标志见 references/gotchas.md §「步骤 9 — 部署」。

---

工作流 B — 编辑现有项目

通用编辑原则：

• **先分析影响。**找出所有依赖此变更的下游节点、表达式或连接。与用户确认。
• **尽量减少改动。**只编辑用户要求的内容。例外：添加/移除 actions 时，修改节点类型（subagent ↔ orchestrator）。
• **优先更新 Registry。**新增资源应先放入 agent-network.yaml 的 registry/context（或 exchange.json.dependencies），然后再从 .agent 中引用。
• **编辑期间暂缓验证。**编辑过程中出现 lint 错误是正常的；最后再验证。

B.1 — 添加或替换资产

1. 确定模式（Inline 或 Exchange — 参见 gotchas.md）。
2. Inline： registry.{agents,mcps,llms} + 带有身份验证的 context.connections.<id> + exchange.json.metadata.variables。Exchange： exchange.json.dependencies + 带有 ref.name 和 ref.namespace 的 context.connections.<id>。
3. 在 .agent 文件中添加 actions: 条目。
4. 在目标节点的 reasoning.actions（子 Agent／编排器）或 do: run（执行器）中引用。
5. 如果操作数量发生变化，重新评估节点类型。 单个操作 → subagent。多个操作 → orchestrator。更新下游的 @<oldType>.<id> 引用。
6. 检查上限。 如果某个节点现在超过 4 个操作，建议拆分。
7. 更新 system.instructions，说明如何使用新资产。
8. 运行步骤 7（验证）。

B.2 — 更改图逻辑

编辑 .agent。每次更改后，沿着 trigger → 每个 echo 逐一检查并确认：

• 每个路由器的 when: 都引用真实且可从上游到达的输出（而不是直接引用 @request.payload）。
• 硬性约束仍写在路由器条件中，而不是提示词中。
• 没有节点变得不可达或成为死胡同。
• 路由器的 on_exit 中没有 transition to（这会导致编译错误）。

运行步骤 7。

B.3 — 优化指令

仅编辑 .agent。执行第 5 阶段的矛盾测试。如果用户粘贴了策略文档，将其转换为编号流程 — 不要原文粘贴。运行步骤 7。

B.4 — 添加或更改连接策略

编辑 agent-network.yaml。GA 架构支持策略，尽管构建流程中没有提供相关设置入口。

策略包含两部分：

1. 定义 — context.policies.<policyId>。
2. 绑定 — 从 context.connections.<connId>.policies.outbound 或 brokers.<brokerId>.interfaces.a2a.policies.{inbound,outbound} 中引用。始终通过 ID 引用。

对于通过 Exchange 发布的策略：先添加到 exchange.json.dependencies，然后再绑定。运行步骤 7。