translate-agent-broker-old-to-new-project

MuleSoft Agent Broker V1 到 V2 转换器

将 Agent Network V1 项目（架构 1.0.0）转换为 V2（架构 2.0.0），并生成一个全新的项目文件夹。转换过程刻意保持简单：每个 V1 broker 都会转换为一个 V2 broker，并由 Agent Script .agent 文件提供支持，该文件恰好包含一个编排器节点。V1 塞进单个 LLM 提示词中的路由、分类和条件逻辑会保留在该编排器的 system.instructions 中——升级不会将提示词拆分为多个节点。

保留用户的措辞。不要擅自发挥或“改进”源指令。将 V1 文件视为事实来源，只修改 V2 实际要求修改的内容。

如果用户想要更丰富的多节点图（将确定性路由拆分到 router 节点、将副作用移到 executor 节点、将简单的摘要任务拆分到 generator 节点），请将其引导至 build-agent-broker-project，这是自然的下一步。

适用场景

• 转换 / 升级 / 迁移 / 移植 V1 Agent Network 或 Agent Broker。
• 用户提到 schemaVersion: 1.0.0，并希望使用 agentNetwork: 2.0.0。
• 工作文件夹中包含 V1 agent-network.yaml 和 exchange.json。

对于一般的 V2 问题（不涉及转换），请引导用户使用构建器技能。

参考资料

• references/v1-example.md — 标准 V1 输入（customer-onboarding-v1）。
• references/v2-example.md — 该输入对应的标准 V2 输出。如不确定格式，请参照此文件。
• references/v2-template.agent — 第 3c 步中需要填充的编排器模板。

工作流

1. 验证输入 — 第 1 步。
2. 选择输出位置 — 第 2 步。
3. 完整读取源文件 — 从头到尾读取 V1 agent-network.yaml 和 exchange.json。
4. 转换 — 第 3 步（子步骤 3a/3b/3c）。
5. 写入输出文件夹，并添加后缀 _v2_conversion — 第 4 步。
6. 报告新路径和转换内容 — 第 5 步。

第 1 步：验证输入

确认工作文件夹确实是 V1 Agent Network 项目。不要在错误的文件夹上运行转换。

1. 确定工作文件夹。如不明确，请询问。
2. 确认两个文件都存在：agent-network.yaml（或 .yml）和 exchange.json。
3. 读取 YAML — 顶层必须包含 schemaVersion: 1.0.0。（V2 使用 agentNetwork: 2.0.0。）
4. 读取 exchange.json — 必须包含 "classifier": "agent-network"。（V2 使用 "agentic-network"。）

如果任一检查未通过，请停止并让用户指出正确的文件夹：

我在此文件夹中没有找到 V1 Agent Network 项目。需要包含 schemaVersion: 1.0.0 的 agent-network.yaml，以及包含 "classifier": "agent-network" 的 exchange.json。要转换哪个文件夹？

第 2 步：选择输出位置

新文件夹的名称为 <original>_v2_conversion。使用 AskUserQuestion 提供以下选项：

• 与源文件夹位于同一父目录（默认）。
• 用户提供的特定路径。

不要在未告知用户的情况下覆盖文件。 如果目标已存在，请询问用户是覆盖还是选择其他名称。

第 3 步：转换

转换会基于同一 V1 源生成三个输出。

3a. 构建 V2 agent-network.yaml

V2 包含以下顶层部分：agentNetwork、info、registry、context、brokers。V1 → V2 映射如下：

V1 位置	V2 位置	备注
schemaVersion: 1.0.0	agentNetwork: 2.0.0	必须为字符串。
label（顶层）	info.label	必填。
（V1 中没有）	info.version	必填。使用 1.0.0。
brokers.<id>.card.description	info.description	如果存在，将 broker 的 description 提到 info 中。
agents.<id>	registry.agents.<id>	请参见Agent 转换。
mcpServers.<id>	registry.mcps.<id>	V1 使用 mcpServers，V2 使用 mcps。
llmProviders.<id>	registry.llms.<id>	将没有 card 的 LLM 信息移入 metadata。
connections.<id>	context.connections.<id>	请参见连接转换。
brokers.<id>	brokers.<id> + ./brokers/<id>.agent	请参见Broker 转换。

Agent 转换（agents → registry.agents）

对于每个 V1 Agent：

• 将 label 提到 info.label 中。
• 保留 metadata.platform 不变。删除 metadata.protocol — GA 使用 metadata.interfaces 取代它。
• 构建 metadata.interfaces.a2a_v03.card — V1 Agent 基于 A2A v0.3，因此稳妥的转换方式是将其放入 a2a_v03（向后兼容）分支。该 card 保留 url: ${<refName>.url}、protocolVersion: 0.3.0、version: 1.0.0、capabilities.pushNotifications: false，以及 modes = [application/json, text/plain]。name 和 description 的默认值取自 Agent 的 V1 label。
• broker 本身发出 A2A v1.0 — 保留 brokers.<id>.interfaces.a2a（不要使用 a2a_v03）。
• 每个 Agent 添加一个 skills 条目。id = <agentName>-<verb>（例如 workday-create-record）；将用途复制到 name 和 description 中。

不要臆造 V1 未声明的能力。如果 V1 没有写明 pushNotifications: true，则保留为 false。

MCP 转换（mcpServers → registry.mcps）

对于每个 V1 MCP 服务：

• 将 label 提到 info.label 中。如果可以从 V1 broker 的说明中安全推断，则添加简短的 info.description。
• 保留 metadata.transport 不变。
• 添加 metadata.tools 数组。对于 V1 broker 调用的每个工具（在 brokers.tools[*].mcp.allowed 中查找规范名称），添加包含 name、description 和最精简 inputSchema 的条目（type: object，并为能从 broker 说明中确定推断的参数添加 properties）。如果无法确定 schema，则将 properties 留空，不要臆造。

LLM 转换（llmProviders → registry.llms）

对于每个 V1 LLM 提供方：

• 将 label 提到 info.label 中，并将 description 提到 info.description 中。
• 保留 metadata.platform。
• 将 metadata.models 添加为列表。包括 V1 实际使用的模型（spec.llm.configuration.model）以及一个明显的同系列模型。不要加入推测性的模型。

连接转换（connections → context.connections）

V1 的扁平 connections 对象中，每个连接都有 kind、ref.name、spec.url，以及可选的 spec.configuration 用于身份验证。V2 保留这一设计，但 URL 会从 spec 中移出。

# V1
WorkdayAgentTestConnection:
  kind: agent
  ref:
    name: WorkdayAgentTest
  spec:
    url: https://...

变为

# V2
workdayAgentConnection:
  kind: a2a            # V1 'agent' becomes V2 'a2a'
  ref:
    name: workdayAgent
  url: ${workdayAgent.url}

映射规则：

• kind: agent（V1）→ kind: a2a（V2）。kind: mcp 和 kind: llm 保持不变。
• 对于 LLM 连接，将身份验证移入顶层的 authentication 块：kind: apiKey、apiKey: ${<llmName>.apiKey}。不要保留 V1 的 spec.configuration 结构。
• 将硬编码 URL 替换为 ${<refName>.url} 变量。实际 URL 值放入 exchange.json。
• V2 架构不限制连接 ID 的格式：context.connections.<id> 键可使用任何有效的 YAML 标识符（camelCase、snake_case 或 kebab-case 均可通过验证）。将 V1 的 PascalCase（如 WorkdayAgentTestConnection）转换为易读的 ID——此转换器使用 snake_case（workday_agent_connection）以保持一致，但这只是约定，并非 lint 规则。唯一的硬性要求是：ID 必须与 .agent 目标（a2a://<id>、mcp://<id>、llm://<id>）完全匹配。
• 注册表中的 ref.name 值（agents/mcps/llms）通常在 V2 中改为 camelCase（例如 workdayAgent）。

Broker 转换

V1 将 broker 的 A2A 卡片和编排器的提示词（spec.instructions）放在同一个块中。V2 将它们拆分：

• A2A 卡片保留在 agent-network.yaml 的 brokers.<broker-id>.interfaces.a2a.card 下。
• 编排器提示词移至 ./brokers/<broker-id>.agent。

V2 broker 条目（GA，A2A v1.0——broker 本身就是端点，因此其卡片省略 url 和 protocolVersion）：

brokers:
  <broker-id>:
    kind: AgentScript
    implementation: ./brokers/<broker-id>.agent
    interfaces:
      a2a:
        card:
          name: <copied from V1 card.name>
          description: <copied from V1 card.description>
          version: 1.0.0
          capabilities:
            streaming: false
            pushNotifications: <copied from V1 card.capabilities.pushNotifications, default false>
          defaultInputModes: [application/json, text/plain]
          defaultOutputModes: [application/json, text/plain]
          skills:
            - id: <copied, lowercased / kebab-cased>
              name: <copied>
              description: <copied>
              tags: <copied>
              examples: <copied if present>
              inputModes: [application/json, text/plain]
              outputModes: [application/json, text/plain]

V2 架构不限制 Broker ID 的格式：brokers: 下的键可使用任何有效的 YAML 标识符（snake_case、kebab-case 和 camelCase 均可通过验证）。将 V1 的 PascalCase（如 CustomerOnboardingBrokerTest）转换为易读的 ID——此转换器使用 snake_case（customer_onboarding）以保持一致，但这只是约定，并非 lint 规则。.agent 文件名彼此独立（例如 ./brokers/customer-onboarding.agent）。唯一的硬性规则是：触发器 target: "brokers://<broker-id>/a2a" 必须与 YAML broker 键完全匹配。

3b. 构建 V2 exchange.json

取 V1 的 exchange.json 并执行以下操作：

• 将 "classifier": "agent-network" 改为 "classifier": "agentic-network"。
• 更新 name、assetId、version，以反映 V2 转换（例如添加 -v2 后缀）。
• 添加 description 字段。
• 对于 V1 中指向外部 URL 的每个连接，添加 metadata.variables.<refName>.url，并将该 URL 设为 default。这样 ${<refName>.url} 引用才能解析。
• 保留所有现有变量（例如 gemini.apiKey）。
• 将 API 密钥标记为 "secret": true。将 URL 标记为 "secret": false。

3c. 构建 Agent 脚本 <broker-id>.agent

使用 references/v2-template.agent 作为结构骨架，并填入占位符。重要的命名和内容规则：

动作命名：

• 对于每个 V1 关联 Agent，创建一个 a2a:send_message 动作。将 Agent 名称转换为 snake_case（例如，WorkdayAgentTest → workday_agent）。
• 对于 brokers.tools[*].mcp.allowed 中列出的每个 V1 MCP 工具，创建一个 mcp:tool 动作。选择一个能体现工具用途的 snake_case 动作 ID（例如，SlackMcpServer.send_status_update → send_slack_status_update）。始终原样保留 tool_name。
• 不要向 MCP 动作添加 inputs:。 V1 没有工具输入架构。V2 运行时会自动发现工具的参数。根据编排器的描述推断 inputs: 属于编造，会产生错误的架构。
• 唯一需要添加 inputs: 的情况，是之后通过 with 修复参数值或为参数设置默认值（例如，固定 channel_id）。转换时不应引入这种做法。

推理动作别名：

• 在 reasoning.actions 中，使用简短易读的别名（例如，workday、salesforce、slack_update），不要重复使用动作 ID。这样编排器指令对人更易读。

保留提示词：

• 将 V1 中的 spec.instructions 原样复制到编排器的 system.instructions 中。
• 只进行机械性修改：
  • 如果提示词中提到了 MCP 工具，将带点号的 MCP 工具名称替换为新的 V2 动作别名。
  • 仅在明显的错别字可能造成困扰时进行修正（例如，"this a long running task" → "this is a long running task"）。如有疑问，保留用户的原文。
• 不要将提示词拆分到多个节点中。 不要添加路由器、执行器或生成器。整个编排在一个编排器中运行——这是明确的约束。

步骤 4：写入输出

<chosen_path>/<original_folder_name>_v2_conversion/
├── agent-network.yaml
├── exchange.json
└── brokers/
    └── <broker-id>.agent

使用 mkdir -p 创建目录，并使用 Write 写入文件。跳过 .mvn、.vscode、.cursor、target/ 和其他 IDE 文件夹——它们不属于项目规范。如果目标已存在，请先询问是否覆盖。

写入后，列出创建的文件。

步骤 5：报告

告知用户：

• 新文件夹的完整路径。
• Broker 名称和编排器节点 ID。
• 一句话说明：这是简单的 V1→V2 转换，包含一个编排器节点；如需更丰富的多节点图（路由器/生成器/执行器拆分），请使用 build-agent-broker-project。

常见错误及避免方法

• 不要保留 schemaVersion: 1.0.0——V2 使用 agentNetwork: 2.0.0。
• 不要保留 V1 的 agent-network 分类标识——V2 使用 agentic-network。
• 不要创建额外节点（路由器、生成器、执行器）。用户需要的是单个编排器。
• 不要为了“改进”而重写用户的提示词。
• 不要硬编码 URL——通过 ${<name>.url} 参数化，并将值放入 exchange.json。
• 不要忘记 info.version（V2 必需，V1 中没有）。
• 不要将身份验证配置块放入注册表中——身份验证应位于 context.connections.<name>.authentication。
• 不要在 V1→V2 转换期间向 MCP 动作添加 inputs:。V1 没有架构，因此任何 inputs: 配置块都是根据描述猜测的。
• 不要在注册表 Agent 上输出 metadata.protocol 或扁平的 metadata.card——GA 使用 metadata.interfaces.<branch>.card。将 V1 转换后的 Agent 放在 a2a_v03 下（向后兼容）；Broker 本身使用 a2a（v1.0）。
• 不要在 echo 节点中输出带有嵌套 task: a2a.task({...}) 的 kind: "a2a:response"——GA 使用 kind: "a2a:status_update_event"（状态 + 消息）或 kind: "a2a:artifact_update_event"（工件 + append/lastChunk）。状态值为 TASK_STATE_* 常量。
• 不要输出 # @dialect: AGENTFABRIC=0.1-BETA 或 # @dialect: AGENTFABRIC=0.1——GA 应使用 # @dialect: AGENTFABRIC=1.0。