mulesoft-anypoint-cli-agent-fabric-plugin 1.4.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (237) hide show
  1. package/GETTING_STARTED.md +396 -0
  2. package/README.md +61 -23
  3. package/TROUBLESHOOTING.md +468 -0
  4. package/dist/commands/agent-network/project/agent-console.d.ts +3 -2
  5. package/dist/commands/agent-network/project/agent-console.js +3 -1
  6. package/dist/commands/agent-network/project/agent-console.js.map +1 -1
  7. package/dist/commands/agent-network/project/broker/create.d.ts +3 -2
  8. package/dist/commands/agent-network/project/broker/create.js +3 -1
  9. package/dist/commands/agent-network/project/broker/create.js.map +1 -1
  10. package/dist/commands/agent-network/project/build.d.ts +4 -3
  11. package/dist/commands/agent-network/project/build.js +13 -8
  12. package/dist/commands/agent-network/project/build.js.map +1 -1
  13. package/dist/commands/agent-network/project/create.d.ts +11 -6
  14. package/dist/commands/agent-network/project/create.js +52 -16
  15. package/dist/commands/agent-network/project/create.js.map +1 -1
  16. package/dist/commands/agent-network/project/deploy.d.ts +4 -2
  17. package/dist/commands/agent-network/project/deploy.js +45 -26
  18. package/dist/commands/agent-network/project/deploy.js.map +1 -1
  19. package/dist/commands/agent-network/project/export-logs.d.ts +3 -2
  20. package/dist/commands/agent-network/project/export-logs.js +3 -2
  21. package/dist/commands/agent-network/project/export-logs.js.map +1 -1
  22. package/dist/commands/agent-network/project/mcp/introspect.d.ts +7 -3
  23. package/dist/commands/agent-network/project/mcp/introspect.js +14 -9
  24. package/dist/commands/agent-network/project/mcp/introspect.js.map +1 -1
  25. package/dist/commands/agent-network/project/publish.d.ts +3 -4
  26. package/dist/commands/agent-network/project/publish.js +11 -14
  27. package/dist/commands/agent-network/project/publish.js.map +1 -1
  28. package/dist/commands/agent-network/project/run-local.d.ts +14 -2
  29. package/dist/commands/agent-network/project/run-local.js +339 -60
  30. package/dist/commands/agent-network/project/run-local.js.map +1 -1
  31. package/dist/commands/agent-network/project/secrets.d.ts +3 -2
  32. package/dist/commands/agent-network/project/secrets.js +3 -1
  33. package/dist/commands/agent-network/project/secrets.js.map +1 -1
  34. package/dist/commands/agent-network/project/stop-local.d.ts +3 -2
  35. package/dist/commands/agent-network/project/stop-local.js +3 -2
  36. package/dist/commands/agent-network/project/stop-local.js.map +1 -1
  37. package/dist/commands/agent-network/project/undeploy.d.ts +3 -2
  38. package/dist/commands/agent-network/project/undeploy.js +19 -12
  39. package/dist/commands/agent-network/project/undeploy.js.map +1 -1
  40. package/dist/commands/agent-network/project/unpublish.d.ts +3 -2
  41. package/dist/commands/agent-network/project/unpublish.js +26 -19
  42. package/dist/commands/agent-network/project/unpublish.js.map +1 -1
  43. package/dist/commands/agent-network/setup/dependencies.d.ts +4 -3
  44. package/dist/commands/agent-network/setup/dependencies.js +7 -4
  45. package/dist/commands/agent-network/setup/dependencies.js.map +1 -1
  46. package/dist/commands/agent-network/setup/gateways.d.ts +3 -2
  47. package/dist/commands/agent-network/setup/gateways.js +3 -3
  48. package/dist/commands/agent-network/setup/gateways.js.map +1 -1
  49. package/dist/errors/base-error.d.ts +6 -0
  50. package/dist/errors/base-error.js +49 -20
  51. package/dist/errors/base-error.js.map +1 -1
  52. package/dist/errors/error-factory.d.ts +62 -4
  53. package/dist/errors/error-factory.js +341 -13
  54. package/dist/errors/error-factory.js.map +1 -1
  55. package/dist/helpers/connection.d.ts +6 -2
  56. package/dist/helpers/connection.js +13 -6
  57. package/dist/helpers/connection.js.map +1 -1
  58. package/dist/helpers/dependency-manager.d.ts +14 -5
  59. package/dist/helpers/dependency-manager.js +185 -51
  60. package/dist/helpers/dependency-manager.js.map +1 -1
  61. package/dist/helpers/policy-helper.js +256 -26
  62. package/dist/helpers/policy-helper.js.map +1 -1
  63. package/dist/helpers/project/constants.d.ts +1 -1
  64. package/dist/helpers/proxy-agent.d.ts +2 -0
  65. package/dist/helpers/proxy-agent.js +26 -0
  66. package/dist/helpers/proxy-agent.js.map +1 -0
  67. package/dist/helpers/proxy-fetch.d.ts +5 -0
  68. package/dist/helpers/proxy-fetch.js +102 -0
  69. package/dist/helpers/proxy-fetch.js.map +1 -0
  70. package/dist/helpers/request-logging.d.ts +4 -0
  71. package/dist/helpers/request-logging.js +96 -2
  72. package/dist/helpers/request-logging.js.map +1 -1
  73. package/dist/helpers/types.d.ts +5 -0
  74. package/dist/helpers/utils.d.ts +1 -0
  75. package/dist/helpers/utils.js +16 -1
  76. package/dist/helpers/utils.js.map +1 -1
  77. package/dist/hooks/init/check-node-version.d.ts +6 -0
  78. package/dist/hooks/init/check-node-version.js +34 -0
  79. package/dist/hooks/init/check-node-version.js.map +1 -0
  80. package/dist/resources/runtime-dependencies.json +5 -1
  81. package/dist/resources/schemas/broker-deployment-settings.schema.json +4 -0
  82. package/dist/resources/schemas/runtime-dependencies-schema.json +21 -0
  83. package/dist/types/agent-network-v2.d.ts +55 -9
  84. package/dist/types/agent-network-v2.js.map +1 -1
  85. package/dist/types/agent-network.d.ts +0 -4
  86. package/dist/types/agent-network.js.map +1 -1
  87. package/dist/types/types.d.ts +25 -3
  88. package/dist/utils/agent-fabric-commands.d.ts +24 -0
  89. package/dist/utils/agent-fabric-commands.js +39 -0
  90. package/dist/utils/agent-fabric-commands.js.map +1 -0
  91. package/dist/utils/builders/builder.d.ts +2 -0
  92. package/dist/utils/builders/builder.js +22 -1
  93. package/dist/utils/builders/builder.js.map +1 -1
  94. package/dist/utils/builders/common/connection-facet-helpers.d.ts +2 -0
  95. package/dist/utils/builders/common/connection-facet-helpers.js +4 -1
  96. package/dist/utils/builders/common/connection-facet-helpers.js.map +1 -1
  97. package/dist/utils/builders/common/network-builder-helpers.d.ts +5 -0
  98. package/dist/utils/builders/common/network-builder-helpers.js +8 -0
  99. package/dist/utils/builders/common/network-builder-helpers.js.map +1 -1
  100. package/dist/utils/builders/common/network-metadata.js +1 -1
  101. package/dist/utils/builders/common/network-metadata.js.map +1 -1
  102. package/dist/utils/builders/common/types.d.ts +1 -1
  103. package/dist/utils/builders/local-space-resolver.d.ts +13 -3
  104. package/dist/utils/builders/local-space-resolver.js +16 -3
  105. package/dist/utils/builders/local-space-resolver.js.map +1 -1
  106. package/dist/utils/builders/policies-factory.d.ts +6 -2
  107. package/dist/utils/builders/policies-factory.js +106 -8
  108. package/dist/utils/builders/policies-factory.js.map +1 -1
  109. package/dist/utils/builders/project-builder-impl.d.ts +20 -1
  110. package/dist/utils/builders/project-builder-impl.js +40 -4
  111. package/dist/utils/builders/project-builder-impl.js.map +1 -1
  112. package/dist/utils/builders/project-builder.d.ts +18 -3
  113. package/dist/utils/builders/project-builder.js +4 -2
  114. package/dist/utils/builders/project-builder.js.map +1 -1
  115. package/dist/utils/builders/remote-space-resolver.d.ts +3 -3
  116. package/dist/utils/builders/remote-space-resolver.js +47 -32
  117. package/dist/utils/builders/remote-space-resolver.js.map +1 -1
  118. package/dist/utils/builders/space-serializer.d.ts +2 -0
  119. package/dist/utils/builders/space-serializer.js +12 -2
  120. package/dist/utils/builders/space-serializer.js.map +1 -1
  121. package/dist/utils/builders/v1/broker-builder.d.ts +1 -0
  122. package/dist/utils/builders/v1/broker-builder.js +45 -9
  123. package/dist/utils/builders/v1/broker-builder.js.map +1 -1
  124. package/dist/utils/builders/v1/connections-builder.js +3 -0
  125. package/dist/utils/builders/v1/connections-builder.js.map +1 -1
  126. package/dist/utils/builders/v1/network-builder.js +22 -4
  127. package/dist/utils/builders/v1/network-builder.js.map +1 -1
  128. package/dist/utils/builders/v2/broker-builder.js +1 -1
  129. package/dist/utils/builders/v2/broker-builder.js.map +1 -1
  130. package/dist/utils/builders/v2/connection-interfaces.d.ts +5 -0
  131. package/dist/utils/builders/v2/connection-interfaces.js +68 -0
  132. package/dist/utils/builders/v2/connection-interfaces.js.map +1 -0
  133. package/dist/utils/builders/v2/connections-builder.d.ts +5 -1
  134. package/dist/utils/builders/v2/connections-builder.js +120 -20
  135. package/dist/utils/builders/v2/connections-builder.js.map +1 -1
  136. package/dist/utils/builders/v2/llm-builder.js +17 -6
  137. package/dist/utils/builders/v2/llm-builder.js.map +1 -1
  138. package/dist/utils/builders/v2/network-builder.js +10 -1
  139. package/dist/utils/builders/v2/network-builder.js.map +1 -1
  140. package/dist/utils/constants.d.ts +22 -1
  141. package/dist/utils/constants.js +26 -4
  142. package/dist/utils/constants.js.map +1 -1
  143. package/dist/utils/deployment-settings.d.ts +1 -0
  144. package/dist/utils/deployment-settings.js.map +1 -1
  145. package/dist/utils/dry-run/dry-run-render.d.ts +1 -0
  146. package/dist/utils/dry-run/dry-run-render.js +23 -13
  147. package/dist/utils/dry-run/dry-run-render.js.map +1 -1
  148. package/dist/utils/exchange.d.ts +1 -0
  149. package/dist/utils/exchange.js +20 -0
  150. package/dist/utils/exchange.js.map +1 -1
  151. package/dist/utils/facets/agent-graph-facet.d.ts +1 -1
  152. package/dist/utils/facets/agent-graph-facet.js +10 -9
  153. package/dist/utils/facets/agent-graph-facet.js.map +1 -1
  154. package/dist/utils/facets/api-instance-facet.d.ts +2 -0
  155. package/dist/utils/facets/api-instance-facet.js +75 -19
  156. package/dist/utils/facets/api-instance-facet.js.map +1 -1
  157. package/dist/utils/facets/apim-policy-helpers.d.ts +29 -2
  158. package/dist/utils/facets/apim-policy-helpers.js +19 -5
  159. package/dist/utils/facets/apim-policy-helpers.js.map +1 -1
  160. package/dist/utils/facets/asset-facet.d.ts +2 -0
  161. package/dist/utils/facets/asset-facet.js +75 -40
  162. package/dist/utils/facets/asset-facet.js.map +1 -1
  163. package/dist/utils/facets/connection-facet.d.ts +6 -0
  164. package/dist/utils/facets/connection-facet.js +202 -22
  165. package/dist/utils/facets/connection-facet.js.map +1 -1
  166. package/dist/utils/facets/deployment-helpers.d.ts +2 -1
  167. package/dist/utils/facets/deployment-helpers.js +28 -21
  168. package/dist/utils/facets/deployment-helpers.js.map +1 -1
  169. package/dist/utils/facets/deployment-runner.js +88 -6
  170. package/dist/utils/facets/deployment-runner.js.map +1 -1
  171. package/dist/utils/facets/facets.d.ts +6 -0
  172. package/dist/utils/facets/facets.js +56 -9
  173. package/dist/utils/facets/facets.js.map +1 -1
  174. package/dist/utils/facets/mule-application-facet.js +2 -2
  175. package/dist/utils/facets/mule-application-facet.js.map +1 -1
  176. package/dist/utils/facets/publication-metadata-patcher.d.ts +7 -1
  177. package/dist/utils/facets/publication-metadata-patcher.js +32 -17
  178. package/dist/utils/facets/publication-metadata-patcher.js.map +1 -1
  179. package/dist/utils/facets/secret-manager-client.d.ts +29 -0
  180. package/dist/utils/facets/secret-manager-client.js +172 -0
  181. package/dist/utils/facets/secret-manager-client.js.map +1 -0
  182. package/dist/utils/facets/secret-ref-validator.d.ts +11 -0
  183. package/dist/utils/facets/secret-ref-validator.js +80 -0
  184. package/dist/utils/facets/secret-ref-validator.js.map +1 -0
  185. package/dist/utils/facets/secret-tls-validator.d.ts +6 -0
  186. package/dist/utils/facets/secret-tls-validator.js +59 -0
  187. package/dist/utils/facets/secret-tls-validator.js.map +1 -0
  188. package/dist/utils/gateway.d.ts +3 -0
  189. package/dist/utils/gateway.js +70 -1
  190. package/dist/utils/gateway.js.map +1 -1
  191. package/dist/utils/logger.js +1 -1
  192. package/dist/utils/logger.js.map +1 -1
  193. package/dist/utils/maven-proxy.d.ts +10 -0
  194. package/dist/utils/maven-proxy.js +118 -0
  195. package/dist/utils/maven-proxy.js.map +1 -0
  196. package/dist/utils/registry/registry-errors.d.ts +4 -0
  197. package/dist/utils/registry/registry-errors.js +36 -0
  198. package/dist/utils/registry/registry-errors.js.map +1 -0
  199. package/dist/utils/registry/registry-response.d.ts +46 -0
  200. package/dist/utils/registry/registry-response.js +264 -0
  201. package/dist/utils/registry/registry-response.js.map +1 -0
  202. package/dist/utils/request-executor.d.ts +9 -1
  203. package/dist/utils/request-executor.js +6 -3
  204. package/dist/utils/request-executor.js.map +1 -1
  205. package/dist/utils/run-local/build-status.js +4 -2
  206. package/dist/utils/run-local/build-status.js.map +1 -1
  207. package/dist/utils/run-local/index.d.ts +1 -1
  208. package/dist/utils/run-local/index.js +2 -1
  209. package/dist/utils/run-local/index.js.map +1 -1
  210. package/dist/utils/run-local/local-a2a-upstream.d.ts +1 -0
  211. package/dist/utils/run-local/local-a2a-upstream.js +5 -4
  212. package/dist/utils/run-local/local-a2a-upstream.js.map +1 -1
  213. package/dist/utils/run-local/local-tls-model.d.ts +18 -0
  214. package/dist/utils/run-local/local-tls-model.js +97 -0
  215. package/dist/utils/run-local/local-tls-model.js.map +1 -0
  216. package/dist/utils/run-local/local-tls.d.ts +37 -0
  217. package/dist/utils/run-local/local-tls.js +245 -0
  218. package/dist/utils/run-local/local-tls.js.map +1 -0
  219. package/dist/utils/run-local/policy-resolver.js +5 -0
  220. package/dist/utils/run-local/policy-resolver.js.map +1 -1
  221. package/dist/utils/run-local/runtime-environment-manager.d.ts +23 -2
  222. package/dist/utils/run-local/runtime-environment-manager.js +236 -6
  223. package/dist/utils/run-local/runtime-environment-manager.js.map +1 -1
  224. package/dist/utils/run-local/secrets-manager.d.ts +1 -0
  225. package/dist/utils/run-local/secrets-manager.js +2 -1
  226. package/dist/utils/run-local/secrets-manager.js.map +1 -1
  227. package/dist/utils/sanitize.d.ts +3 -0
  228. package/dist/utils/sanitize.js +45 -0
  229. package/dist/utils/sanitize.js.map +1 -0
  230. package/dist/utils/variables.d.ts +28 -6
  231. package/dist/utils/variables.js +114 -14
  232. package/dist/utils/variables.js.map +1 -1
  233. package/package.json +12 -10
  234. package/scripts/extract-error-catalog.js +88 -0
  235. package/templates/agentic-network/agent-network.yaml.template +1 -7
  236. package/templates/agentic-network/brokers/broker1.agent.template +1 -1
  237. package/templates/agentic-network/exchange.json.template +9 -1
@@ -0,0 +1,396 @@
1
+ # Getting started with an Agent Network project
2
+
3
+ This guide walks through the files `agent-network project create` scaffolds, so you know what
4
+ each section is for before you start editing. It matches the default create output — create a
5
+ project yourself and follow along:
6
+
7
+ ```bash
8
+ anypoint-cli-agent-fabric-plugin agent-network project create --name my-agent-network
9
+ ```
10
+
11
+ If you hit an error along the way, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
12
+
13
+ ## Project layout
14
+
15
+ ```
16
+ my-agent-network/
17
+ ├── exchange.json # Exchange descriptor: GAV, classifier, variables
18
+ ├── agent-network.yaml # topology: registry, connections, brokers
19
+ └── brokers/
20
+ └── broker1.agent # AgentScript implementation for broker1
21
+ ```
22
+
23
+ ## `exchange.json` — the Exchange descriptor
24
+
25
+ Every Agent Network project is published to Exchange as an asset, so it needs a descriptor:
26
+
27
+ ```json
28
+ {
29
+ "name": "my-agent-network",
30
+ "classifier": "agentic-network",
31
+ "groupId": "<your-org-id>",
32
+ "assetId": "my-agent-network",
33
+ "version": "1.0.0",
34
+ "dependencies": [],
35
+ "metadata": {
36
+ "variables": {
37
+ "myAgent": {
38
+ "url": { "description": "My External Agent URL", "default": "", "secret": false }
39
+ },
40
+ "openai": {
41
+ "apiKey": { "description": "OpenAI API key", "default": "" }
42
+ }
43
+ }
44
+ }
45
+ }
46
+ ```
47
+
48
+ - **`groupId` / `assetId` / `version`** form the project's GAV — its coordinate in Exchange.
49
+ - **`classifier: "agentic-network"`** marks this as an Agent Network asset (as opposed to, say, a
50
+ connector or a Mule application).
51
+ - **`dependencies`** lists Exchange assets the project consumes. The default create scaffold leaves
52
+ this empty and declares OpenAI inline under `registry.llms` (see below). You can instead add an
53
+ `llm-metadata` dependency (for example the published `openai` asset) and point connections at it
54
+ with a namespaced `ref`.
55
+ - **`metadata.variables`** declares placeholders that `agent-network.yaml` can reference as
56
+ `${namespace.name}` (for example `${myAgent.url}`, `${openai.apiKey}`). Values are supplied at
57
+ deploy time via `--property namespace.name:value` or an interactive prompt — nothing sensitive
58
+ needs to live in the project files. Mark a variable `"secret": true` if its value shouldn't be
59
+ echoed back or logged.
60
+
61
+ ## `agent-network.yaml` — the topology
62
+
63
+ This is the file that describes what the network is made of and how the pieces connect.
64
+
65
+ ### `registry` — the building blocks
66
+
67
+ ```yaml
68
+ registry:
69
+ agents:
70
+ myAgent:
71
+ info:
72
+ label: My External Agent
73
+ metadata:
74
+ platform: Bedrock
75
+ interfaces:
76
+ a2a:
77
+ card: { ... } # an A2A AgentCard describing capabilities and skills
78
+ mcps:
79
+ myMcpServer:
80
+ info:
81
+ label: My MCP Server
82
+ metadata:
83
+ transport:
84
+ kind: streamableHttp
85
+ path: "/mcp"
86
+ llms:
87
+ openai:
88
+ info:
89
+ label: OpenAI
90
+ description: OpenAI LLM Provider
91
+ metadata:
92
+ platform: OpenAI
93
+ ```
94
+
95
+ - **`registry.agents`** — external agents this network can call. Each entry's `metadata.interfaces`
96
+ describes the protocol used to reach it (A2A is the one shown here).
97
+ - **`registry.mcps`** — Model Context Protocol servers that expose tools, and how to reach them
98
+ (transport kind and path).
99
+ - **`registry.llms`** — LLM providers declared inline in the project. The default create scaffold
100
+ uses this for OpenAI. Alternatively, omit `registry.llms` and consume a published
101
+ `llm-metadata` asset from `exchange.json` `dependencies`, referencing it from the connection
102
+ with `ref.namespace` set to that asset's group id.
103
+
104
+ Every entry here is a *declaration*; how the network actually reaches each one at runtime is
105
+ defined next, under `context.connections`.
106
+
107
+ ### `context.connections` — how to reach each registry entry
108
+
109
+ ```yaml
110
+ context:
111
+ connections:
112
+ myAgentConnection:
113
+ kind: a2a
114
+ ref: { name: myAgent }
115
+ url: ${myAgent.url}
116
+ myMcpServerConnection:
117
+ kind: mcp
118
+ ref: { name: myMcpServer }
119
+ url: ${myMcpServer.url}
120
+ openaiConnection:
121
+ kind: llm
122
+ ref: { name: openai }
123
+ url: https://api.openai.com/v1
124
+ authentication:
125
+ kind: apiKey
126
+ apiKey: ${openai.apiKey}
127
+ ```
128
+
129
+ Each connection names a `kind` (`a2a`, `mcp`, or `llm`), a `ref` back to the registry entry (or
130
+ Exchange asset) it serves, a `url` (often a `${variable}` resolved at deploy time), and — for
131
+ LLMs and any authenticated target — an `authentication` block. For an inline `registry.llms`
132
+ entry, `ref` is just `{ name: openai }`. For an Exchange `llm-metadata` dependency, add
133
+ `namespace: <group-id>` on the `ref`. Brokers reference connections by name (e.g.
134
+ `a2a://myAgentConnection`) rather than embedding URLs directly, so credentials and endpoints stay
135
+ out of the broker logic.
136
+
137
+ ### `brokers` — the orchestrating agents
138
+
139
+ ```yaml
140
+ brokers:
141
+ broker1:
142
+ kind: AgentScript
143
+ implementation: ./brokers/broker1.agent
144
+ interfaces:
145
+ a2a:
146
+ card:
147
+ name: Broker 1
148
+ description: Describe what your broker does.
149
+ skills:
150
+ - id: my-skill
151
+ name: My Skill
152
+ ```
153
+
154
+ A broker is exposed as its own A2A agent (via `interfaces.a2a.card`) and its behavior lives in a
155
+ separate `AgentScript` file referenced by `implementation`.
156
+
157
+ ## The AgentScript broker file
158
+
159
+ `brokers/broker1.agent` is where the orchestration logic lives. A minimal broker has these
160
+ sections, roughly in the order execution flows through them:
161
+
162
+ | Section | Purpose |
163
+ | --- | --- |
164
+ | `system` | Top-level instructions/persona for the broker. |
165
+ | `config` | Broker-level settings, e.g. which `llm` entry is the default. |
166
+ | `llm` | Declares LLM targets, pointing at a `context.connections` entry (`target: "llm://openaiConnection"`). |
167
+ | `actions` | Declares callable actions — an A2A call to another agent (`target: "a2a://..."`) or an MCP tool invocation (`target: "mcp://..."`). |
168
+ | `trigger <name>` | Entry point — how the broker receives work (e.g. an incoming A2A message) and which `orchestrator` node it transitions to. |
169
+ | `orchestrator <name>` | A reasoning step: given the incoming request, decide which `actions` to invoke and what to output. |
170
+ | `generator <name>` | Formats a response (e.g. turning orchestrator output into user-facing text) using an LLM call. |
171
+ | `executor <name>` | Actually runs an action (e.g. calls an MCP tool) with resolved inputs. |
172
+ | `router <name>` | Branches to different `echo` nodes based on a condition (e.g. success vs. failure). |
173
+ | `echo <name>` | Terminal node — emits the final A2A response back to the caller. |
174
+
175
+ Nodes transition to each other via `on_exit: -> transition to @<section>.<name>`, and reference
176
+ each other's outputs via `@<section>.<name>.output`. Reading a broker file top-to-bottom in
177
+ declaration order won't reflect execution order — follow the `transition to` chain starting from
178
+ the `trigger` block instead.
179
+
180
+ ## Full worked example: a weather-lookup broker
181
+
182
+ The snippets above show each piece in isolation. Here's a complete, self-contained network that
183
+ ties them together: `weatherBroker` takes a natural-language question, calls a weather MCP tool
184
+ to fetch the data, then uses an LLM to summarize it back to the user. Every field below is filled
185
+ in — the only values you need to supply are the two declared variables (`openai.apiKey` and
186
+ `weatherMcp.url`, via `--property` at deploy time).
187
+
188
+ ### `exchange.json`
189
+
190
+ ```json
191
+ {
192
+ "main": "agent-network.yaml",
193
+ "name": "weather-assistant",
194
+ "classifier": "agentic-network",
195
+ "organizationId": "68ef9520-24e9-4098-93bb-081c75e21a26",
196
+ "descriptorVersion": "1.0.0",
197
+ "apiVersion": "1.0.0",
198
+ "tags": [],
199
+ "groupId": "68ef9520-24e9-4098-93bb-081c75e21a26",
200
+ "assetId": "weather-assistant",
201
+ "version": "1.0.0",
202
+ "dependencies": [],
203
+ "metadata": {
204
+ "toolingVersion": 1,
205
+ "variables": {
206
+ "openai": {
207
+ "apiKey": { "description": "OpenAI API key", "default": "", "secret": true }
208
+ },
209
+ "weatherMcp": {
210
+ "url": { "description": "Weather MCP server URL", "default": "", "secret": false }
211
+ }
212
+ }
213
+ }
214
+ }
215
+ ```
216
+
217
+ ### `agent-network.yaml`
218
+
219
+ ```yaml
220
+ agentNetwork: 2.0.0
221
+ info:
222
+ label: Weather Assistant
223
+ version: v1
224
+ registry:
225
+ mcps:
226
+ weatherMcp:
227
+ info:
228
+ label: Weather MCP Server
229
+ metadata:
230
+ transport:
231
+ kind: streamableHttp
232
+ path: "/mcp"
233
+ llms:
234
+ openai:
235
+ info:
236
+ label: OpenAI
237
+ description: OpenAI LLM Provider
238
+ metadata:
239
+ platform: OpenAI
240
+ context:
241
+ connections:
242
+ weatherMcpConnection:
243
+ kind: mcp
244
+ ref:
245
+ name: weatherMcp
246
+ url: ${weatherMcp.url}
247
+ openaiConnection:
248
+ kind: llm
249
+ ref:
250
+ name: openai
251
+ url: https://api.openai.com/v1
252
+ authentication:
253
+ kind: apiKey
254
+ apiKey: ${openai.apiKey}
255
+ brokers:
256
+ weatherBroker:
257
+ kind: AgentScript
258
+ implementation: ./brokers/weatherBroker.agent
259
+ interfaces:
260
+ a2a:
261
+ card:
262
+ name: Weather Assistant
263
+ description: Answers questions about current weather by calling a weather MCP tool.
264
+ version: 1.0.0
265
+ capabilities:
266
+ streaming: true
267
+ pushNotifications: false
268
+ defaultInputModes:
269
+ - text/plain
270
+ defaultOutputModes:
271
+ - text/plain
272
+ skills:
273
+ - id: get-weather
274
+ name: Get Weather
275
+ description: Look up the current weather for a city.
276
+ tags:
277
+ - weather
278
+ ```
279
+
280
+ ### `brokers/weatherBroker.agent`
281
+
282
+ ```
283
+ # @dialect: AGENTFABRIC=1.1
284
+ system:
285
+ instructions: "You are a helpful weather assistant."
286
+
287
+ config:
288
+ agent_name: "weatherBroker"
289
+ default_llm: @llm.openai_llm
290
+
291
+ llm:
292
+ openai_llm:
293
+ target: "llm://openaiConnection"
294
+ kind: "OpenAI"
295
+ model: "gpt-4o-mini"
296
+
297
+ actions:
298
+ get_weather:
299
+ target: "mcp://weatherMcpConnection"
300
+ kind: "mcp:tool"
301
+ tool_name: "get-weather"
302
+ inputs:
303
+ city: string
304
+
305
+ trigger weatherTrigger:
306
+ kind: "a2a"
307
+ target: "brokers://weatherBroker/a2a"
308
+ on_message: ->
309
+ transition to @orchestrator.main
310
+
311
+ orchestrator main:
312
+ description: "Decide which city to look up and call the weather tool"
313
+ label: "Main"
314
+ system:
315
+ instructions: |
316
+ Extract the city name from the user's message. Always call
317
+ get_weather when a city is present.
318
+ reasoning:
319
+ instructions: ->
320
+ | {!@request.payload.message.parts[0].text}
321
+ actions:
322
+ get_weather: @actions.get_weather
323
+ with city = ...
324
+ outputs:
325
+ properties:
326
+ city:
327
+ type: "string"
328
+ description: "The city that was looked up"
329
+ status:
330
+ type: "string"
331
+ description: "success or failure"
332
+ on_exit: ->
333
+ transition to @executor.runWeatherLookup
334
+
335
+ executor runWeatherLookup:
336
+ do: ->
337
+ run @actions.get_weather
338
+ with city = @orchestrator.main.output.city
339
+ on_exit: ->
340
+ transition to @generator.formatResponse
341
+
342
+ generator formatResponse:
343
+ system:
344
+ instructions: "You turn raw weather data into a short, friendly summary."
345
+ prompt: ->
346
+ | Summarize this weather data for the user in one or two sentences:
347
+ {!@executor.runWeatherLookup.output}
348
+ on_exit: ->
349
+ transition to @router.resultRouter
350
+
351
+ router resultRouter:
352
+ routes:
353
+ - target: @echo.successResponse
354
+ when: @orchestrator.main.output.status == "success"
355
+ label: "Success"
356
+ otherwise:
357
+ target: @echo.errorResponse
358
+
359
+ echo successResponse:
360
+ kind: "a2a:status_update_event"
361
+ state: "TASK_STATE_COMPLETED"
362
+ message: a2a.message({
363
+ messageId: uuid(),
364
+ parts:[
365
+ a2a.textPart(@generator.formatResponse.output)
366
+ ]
367
+ })
368
+
369
+ echo errorResponse:
370
+ kind: "a2a:status_update_event"
371
+ state: "TASK_STATE_FAILED"
372
+ message: a2a.message({
373
+ messageId: uuid(),
374
+ parts:[
375
+ a2a.textPart("I couldn't find weather for that city. Please try again.")
376
+ ]
377
+ })
378
+ ```
379
+
380
+ Drop these three files into a project (`exchange.json` and `agent-network.yaml` at the root,
381
+ the broker file under `brokers/`), supply real values for `openai.apiKey` and `weatherMcp.url`
382
+ against a running weather MCP server, and `build` / `publish` / `deploy` as usual.
383
+
384
+ ## Next steps
385
+
386
+ Once the topology and broker logic look right:
387
+
388
+ ```bash
389
+ anypoint-cli-agent-fabric-plugin agent-network project build
390
+ anypoint-cli-agent-fabric-plugin agent-network project publish
391
+ anypoint-cli-agent-fabric-plugin agent-network project deploy
392
+ ```
393
+
394
+ Each stage validates and persists its output before the next one runs — see the main
395
+ [README](README.md#usage) for the full command reference, and
396
+ [TROUBLESHOOTING.md](TROUBLESHOOTING.md) if a command fails.
package/README.md CHANGED
@@ -23,10 +23,11 @@ Create a new broker in an existing agent network project
23
23
 
24
24
  ```
25
25
  USAGE
26
- $ anypoint-cli-agent-fabric-plugin agent-network project broker create -n <value> [--path <value>]
26
+ $ anypoint-cli-agent-fabric-plugin agent-network project broker create -n <value> [--debug] [--path <value>]
27
27
 
28
28
  FLAGS
29
29
  -n, --name=<value> (required) Name of the broker
30
+ --debug Enable debug logging (equivalent to ANYPOINT_LOG_LEVEL=DEBUG).
30
31
  --path=<value> [default: .] Path to the project directory (where exchange.json lives)
31
32
 
32
33
  DESCRIPTION
@@ -48,18 +49,21 @@ Build the current project using the Maven wrapper (mvnw or mvnw.cmd)
48
49
  USAGE
49
50
  $ anypoint-cli-agent-fabric-plugin agent-network project build [--password <value> [--username <value> | --client_id <value> |
50
51
  ]] [--client_secret <value> ] [--bearer <value> | | ] [--organization <value>] [--environment <value>] [--host
51
- <value>] [--collectMetrics] [--path <value>] [--debug] [--forceUpdate]
52
+ <value>] [--collectMetrics] [--debug] [--path <value>] [--forceUpdate] [--maven-proxy]
52
53
 
53
54
  FLAGS
54
55
  --bearer=<value> Token Bearer. You can define this in the ANYPOINT_BEARER environment variable.
55
56
  --client_id=<value> Client ID. You can define this in the ANYPOINT_CLIENT_ID environment variable.
56
57
  --client_secret=<value> Client Secret. You can define this in the ANYPOINT_CLIENT_SECRET environment variable.
57
58
  --[no-]collectMetrics collect metrics. You can define this in the COLLECT_METRICS environment variable.
58
- --debug Enable debug mode
59
+ --debug Enable debug mode. Sets the log level to DEBUG (equivalent to ANYPOINT_LOG_LEVEL=DEBUG)
60
+ and enables Maven -X.
59
61
  --environment=<value> Environment Name. You can define this in the ANYPOINT_ENV environment variable.
60
62
  --forceUpdate Force update the dependencies
61
63
  --host=anypoint.mulesoft.com [default: anypoint.mulesoft.com] Host URL. You can define this in the ANYPOINT_HOST
62
64
  environment variable.
65
+ --[no-]maven-proxy Generate Maven proxy settings from HTTPS_PROXY and NO_PROXY for schema 1.0.0 builds. Use
66
+ --no-maven-proxy to disable.
63
67
  --organization=<value> Organization Name. You can define this in the ANYPOINT_ORG environment variable.
64
68
  --password=<value> Password. You can define this in the ANYPOINT_PASSWORD environment variable.
65
69
  --path=<value> [default: .] The path to the project.
@@ -79,9 +83,9 @@ Create a new project in the current directory
79
83
  ```
80
84
  USAGE
81
85
  $ anypoint-cli-agent-fabric-plugin agent-network project create -n <value> [--password <value> [--username <value> | --client_id
82
- <value> | ]] [--client_secret <value> ] [--bearer <value> | | ] [--organization <value>] [--environment <value>]
83
- [--host <value>] [--collectMetrics] [-o <value>] [--group-id <value>] [--asset-id <value>] [--asset-version <value>]
84
- [--api-version <value>] [--tab-size <value>] [--create-dir] [--empty-project]
86
+ <value> | ]] [--client_secret <value> ] [--bearer <value> | | ] [--organization <value>] [--host <value>]
87
+ [--collectMetrics] [-o <value>] [--group-id <value>] [--asset-id <value>] [--asset-version <value>] [--api-version
88
+ <value>] [--tab-size <value>] [--create-dir] [--empty-project]
85
89
 
86
90
  FLAGS
87
91
  -n, --name=<value> (required) Name of the project
@@ -94,9 +98,9 @@ FLAGS
94
98
  --client_secret=<value> Client Secret. You can define this in the ANYPOINT_CLIENT_SECRET environment variable.
95
99
  --[no-]collectMetrics collect metrics. You can define this in the COLLECT_METRICS environment variable.
96
100
  --[no-]create-dir Create new directory at output-dir for the new project using project's name
101
+ --debug Enable debug logging (equivalent to ANYPOINT_LOG_LEVEL=DEBUG).
97
102
  --empty-project Scaffold a minimal project with no example content: only exchange.json and a bare
98
103
  agent-network.yaml, with no brokers directory
99
- --environment=<value> Environment Name. You can define this in the ANYPOINT_ENV environment variable.
100
104
  --group-id=<value> Group Id (GAV)
101
105
  --host=anypoint.mulesoft.com [default: anypoint.mulesoft.com] Host URL. You can define this in the ANYPOINT_HOST
102
106
  environment variable.
@@ -120,10 +124,10 @@ Deploys the Agent Network application
120
124
  USAGE
121
125
  $ anypoint-cli-agent-fabric-plugin agent-network project deploy [--password <value> [--username <value> | --client_id <value> |
122
126
  ]] [--client_secret <value> ] [--bearer <value> | | ] [--organization <value>] [--environment <value>] [--host
123
- <value>] [--collectMetrics] [-g <value>] [-i <value>] [-e <value>] [-t <value>] [--dont-wait-for-agent-network]
124
- [--disable-tracing] [--property <value>] [--deployment-properties-file <value>] [--deployment-property <value>]
125
- [--path <value>] [--max-retries <value>] [--request-timeout <value>] [--process-timeout <value>]
126
- [--disable-autopublish] [--json]
127
+ <value>] [--collectMetrics] [--debug] [-g <value>] [-i <value>] [-e <value>] [-t <value>]
128
+ [--dont-wait-for-agent-network] [--disable-tracing] [--property <value>] [--deployment-properties-file <value>]
129
+ [--deployment-property <value>] [--path <value>] [--max-retries <value>] [--request-timeout <value>]
130
+ [--process-timeout <value>] [--disable-autopublish] [--json]
127
131
 
128
132
  FLAGS
129
133
  -e, --egress-gw=<value> Name of the target egress gw (separate-gateways mode; requires --ingress-gw).
@@ -144,12 +148,14 @@ FLAGS
144
148
  variable.
145
149
  --[no-]collectMetrics collect metrics. You can define this in the COLLECT_METRICS environment
146
150
  variable.
151
+ --debug Enable debug logging (equivalent to ANYPOINT_LOG_LEVEL=DEBUG).
147
152
  --deployment-properties-file=<value> Path to a YAML file of typed deployment settings, keyed by scope (e.g. a
148
- top-level "brokers:" mapping vCores, resources.*, logging.level,
153
+ top-level "brokers:" mapping vCores, replicas, resources.*, logging.level,
149
154
  runtimeVersion). Mutually exclusive with --deployment-property.
150
155
  --deployment-property=<value>... [default: ] Typed deployment setting in format <scope>:<name>:<value> (e.g.,
151
156
  --deployment-property brokers:vCores:0.1). Repeatable. Mutually exclusive with
152
- --deployment-properties-file.
157
+ --deployment-properties-file. brokers:replicas other than 1 is rejected on
158
+ Runtime Fabric.
153
159
  --disable-autopublish Disable automatic publishing when lock file is not found.
154
160
  --disable-tracing Disable tracing functionalities
155
161
  --dont-wait-for-agent-network Do not wait for the Agent Network to be ready
@@ -180,8 +186,28 @@ EXAMPLES
180
186
  $ agent-network project deploy --property apiKey:sk-xxx --property role:user
181
187
 
182
188
  $ agent-network project deploy --path ./my-project --property myAgent.url:https://api.example.com
189
+
190
+ $ agent-network project deploy --deployment-property brokers:replicas:3
191
+
192
+ $ agent-network project deploy --deployment-property brokers:resources.cpu.reserved:50m
193
+ ```
194
+
195
+ Replica count defaults to `1`. Set `--deployment-property brokers:replicas:3`, or use
196
+ `--deployment-properties-file settings.yaml` with numeric YAML:
197
+
198
+ ```yaml
199
+ brokers:
200
+ replicas: 3
183
201
  ```
184
202
 
203
+ `replicas` must be an integer of at least `1`; quoted YAML strings are rejected.
204
+ On CloudHub 2.0 and private space it maps to `target.replicas` for Agent Graph and
205
+ Mule runtime applications, for both new deployments and redeployments. Runtime Fabric
206
+ always sends `1`, and an explicit replica count other than `1` is rejected. It does
207
+ not scale gateway infrastructure. Target capacity and platform quotas still apply;
208
+ deployment readiness polling does not guarantee that every requested replica is running.
209
+
210
+
185
211
  ## `anypoint-cli-agent-fabric-plugin agent-network project publish`
186
212
 
187
213
  Publish current Agent Network project to Anypoint Platform
@@ -190,14 +216,15 @@ Publish current Agent Network project to Anypoint Platform
190
216
  USAGE
191
217
  $ anypoint-cli-agent-fabric-plugin agent-network project publish [--password <value> [--username <value> | --client_id <value> |
192
218
  ]] [--client_secret <value> ] [--bearer <value> | | ] [--organization <value>] [--environment <value>] [--host
193
- <value>] [--collectMetrics] [--json] [--path <value>] [--debug]
219
+ <value>] [--collectMetrics] [--debug] [--json] [--path <value>]
194
220
 
195
221
  FLAGS
196
222
  --bearer=<value> Token Bearer. You can define this in the ANYPOINT_BEARER environment variable.
197
223
  --client_id=<value> Client ID. You can define this in the ANYPOINT_CLIENT_ID environment variable.
198
224
  --client_secret=<value> Client Secret. You can define this in the ANYPOINT_CLIENT_SECRET environment variable.
199
225
  --[no-]collectMetrics collect metrics. You can define this in the COLLECT_METRICS environment variable.
200
- --debug Enable debug mode
226
+ --debug Enable debug mode. Sets the log level to DEBUG (equivalent to ANYPOINT_LOG_LEVEL=DEBUG)
227
+ and prints the Exchange publish response.
201
228
  --environment=<value> Environment Name. You can define this in the ANYPOINT_ENV environment variable.
202
229
  --host=anypoint.mulesoft.com [default: anypoint.mulesoft.com] Host URL. You can define this in the ANYPOINT_HOST
203
230
  environment variable.
@@ -224,8 +251,8 @@ Undeploys the Agent Network application, removing all deployed resources
224
251
  USAGE
225
252
  $ anypoint-cli-agent-fabric-plugin agent-network project undeploy [--password <value> [--username <value> | --client_id <value> |
226
253
  ]] [--client_secret <value> ] [--bearer <value> | | ] [--organization <value>] [--environment <value>] [--host
227
- <value>] [--collectMetrics] [--path <value> | --gav <value>] [--api-version <value>] [--request-timeout <value>]
228
- [--process-timeout <value>] [--dry-run | ] [--json]
254
+ <value>] [--collectMetrics] [--debug] [--path <value> | --gav <value>] [--api-version <value>] [--request-timeout
255
+ <value>] [--process-timeout <value>] [--dry-run | ] [--json]
229
256
 
230
257
  FLAGS
231
258
  --api-version=<value> [default: v1] Api Version used to discover remotely deployed resources when using --gav.
@@ -233,6 +260,7 @@ FLAGS
233
260
  --client_id=<value> Client ID. You can define this in the ANYPOINT_CLIENT_ID environment variable.
234
261
  --client_secret=<value> Client Secret. You can define this in the ANYPOINT_CLIENT_SECRET environment variable.
235
262
  --[no-]collectMetrics collect metrics. You can define this in the COLLECT_METRICS environment variable.
263
+ --debug Enable debug logging (equivalent to ANYPOINT_LOG_LEVEL=DEBUG).
236
264
  --dry-run Preview the deploy-plane resources that would be undeployed without deleting anything.
237
265
  --environment=<value> Environment Name. You can define this in the ANYPOINT_ENV environment variable.
238
266
  --gav=<value> Parent asset GAV (groupId:assetId:version). Discovers deployed resources remotely.
@@ -271,8 +299,8 @@ Removes the Agent Network assets from Anypoint Exchange. By default performs a s
271
299
  USAGE
272
300
  $ anypoint-cli-agent-fabric-plugin agent-network project unpublish [--password <value> [--username <value> | --client_id <value> |
273
301
  ]] [--client_secret <value> ] [--bearer <value> | | ] [--organization <value>] [--environment <value>] [--host
274
- <value>] [--collectMetrics] [--path <value> | --gav <value>] [--api-version <value>] [--hard-delete] [--dry-run | ]
275
- [--json]
302
+ <value>] [--collectMetrics] [--debug] [--path <value> | --gav <value>] [--api-version <value>] [--hard-delete]
303
+ [--dry-run | ] [--json]
276
304
 
277
305
  FLAGS
278
306
  --api-version=<value> [default: v1] Api Version used to discover remotely published assets when using --gav.
@@ -280,6 +308,7 @@ FLAGS
280
308
  --client_id=<value> Client ID. You can define this in the ANYPOINT_CLIENT_ID environment variable.
281
309
  --client_secret=<value> Client Secret. You can define this in the ANYPOINT_CLIENT_SECRET environment variable.
282
310
  --[no-]collectMetrics collect metrics. You can define this in the COLLECT_METRICS environment variable.
311
+ --debug Enable debug logging (equivalent to ANYPOINT_LOG_LEVEL=DEBUG).
283
312
  --dry-run Preview the Exchange assets that would be unpublished without deleting anything.
284
313
  --environment=<value> Environment Name. You can define this in the ANYPOINT_ENV environment variable.
285
314
  --gav=<value> Parent asset GAV (groupId:assetId:version). Discovers assets remotely. Use --environment
@@ -325,8 +354,8 @@ Set up the Agent Network environment with the required gateways.
325
354
  USAGE
326
355
  $ anypoint-cli-agent-fabric-plugin agent-network setup gateways [--password <value> [--username <value> | --client_id <value> |
327
356
  ]] [--client_secret <value> ] [--bearer <value> | | ] [--organization <value>] [--environment <value>] [--host
328
- <value>] [--collectMetrics] [-t <value>] [-g <value>] [-i <value>] [-e <value>] [--dont-wait-for-gateways-running]
329
- [--update]
357
+ <value>] [--collectMetrics] [--debug] [-t <value>] [-g <value>] [-i <value>] [-e <value>]
358
+ [--dont-wait-for-gateways-running] [--update]
330
359
 
331
360
  FLAGS
332
361
  -e, --egress-gw=<value> Name of the egress gw (separate-gateway mode; requires --ingress-gw)
@@ -340,6 +369,7 @@ FLAGS
340
369
  --client_secret=<value> Client Secret. You can define this in the ANYPOINT_CLIENT_SECRET environment
341
370
  variable.
342
371
  --[no-]collectMetrics collect metrics. You can define this in the COLLECT_METRICS environment variable.
372
+ --debug Enable debug logging (equivalent to ANYPOINT_LOG_LEVEL=DEBUG).
343
373
  --dont-wait-for-gateways-running Do not wait for the Gateways to be running
344
374
  --environment=<value> Environment Name. You can define this in the ANYPOINT_ENV environment variable.
345
375
  --host=anypoint.mulesoft.com [default: anypoint.mulesoft.com] Host URL. You can define this in the ANYPOINT_HOST
@@ -356,7 +386,7 @@ DESCRIPTION
356
386
 
357
387
  ## `anypoint-cli-agent-fabric-plugin conf [KEY] [VALUE]`
358
388
 
359
- Manage authentication credentials in a configuration file (config.json)
389
+ Manage authentication credentials in a configuration file (config.json)
360
390
 
361
391
  ```
362
392
  USAGE
@@ -451,11 +481,19 @@ anypoint-cli-agent-fabric-plugin agent-network project publish
451
481
  anypoint-cli-agent-fabric-plugin agent-network project deploy
452
482
  ```
453
483
 
484
+ ## Getting started
485
+
486
+ New to Agent Network projects? See [GETTING_STARTED.md](GETTING_STARTED.md) for a walkthrough of what `agent-network project create` scaffolds — the `exchange.json` descriptor, the `agent-network.yaml` topology (registry, connections, brokers), and the sections of an AgentScript broker file.
487
+
488
+ ## Troubleshooting
489
+
490
+ Hitting an error? See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for a reference of every CLI error code and a guide to common dependent-service failures (Exchange, API Manager, Runtime Fabric, Gateway Manager, Access Management), each with likely causes and fixes.
491
+
454
492
  ## Development
455
493
 
456
494
  ### Prerequisites
457
495
 
458
- - Node.js >= 20.0.0
496
+ - Node.js >= 22.23.4 (22.x), >= 24.22.1 (24.x), or >= 26.12.1
459
497
  - npm
460
498
 
461
499
  ### Setup