mulesoft-anypoint-cli-agent-fabric-plugin 1.4.0 → 1.5.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 (158) hide show
  1. package/GETTING_STARTED.md +396 -0
  2. package/README.md +26 -1
  3. package/TROUBLESHOOTING.md +412 -0
  4. package/dist/commands/agent-network/project/create.d.ts +6 -2
  5. package/dist/commands/agent-network/project/create.js +44 -13
  6. package/dist/commands/agent-network/project/create.js.map +1 -1
  7. package/dist/commands/agent-network/project/deploy.js +18 -20
  8. package/dist/commands/agent-network/project/deploy.js.map +1 -1
  9. package/dist/commands/agent-network/project/publish.js +2 -1
  10. package/dist/commands/agent-network/project/publish.js.map +1 -1
  11. package/dist/commands/agent-network/project/run-local.d.ts +10 -0
  12. package/dist/commands/agent-network/project/run-local.js +168 -47
  13. package/dist/commands/agent-network/project/run-local.js.map +1 -1
  14. package/dist/commands/agent-network/project/undeploy.js +16 -9
  15. package/dist/commands/agent-network/project/undeploy.js.map +1 -1
  16. package/dist/commands/agent-network/project/unpublish.js +23 -16
  17. package/dist/commands/agent-network/project/unpublish.js.map +1 -1
  18. package/dist/errors/base-error.d.ts +1 -0
  19. package/dist/errors/base-error.js +28 -18
  20. package/dist/errors/base-error.js.map +1 -1
  21. package/dist/errors/error-factory.d.ts +36 -3
  22. package/dist/errors/error-factory.js +184 -8
  23. package/dist/errors/error-factory.js.map +1 -1
  24. package/dist/helpers/connection.d.ts +6 -2
  25. package/dist/helpers/connection.js +13 -6
  26. package/dist/helpers/connection.js.map +1 -1
  27. package/dist/helpers/project/constants.d.ts +1 -1
  28. package/dist/helpers/proxy-agent.d.ts +2 -0
  29. package/dist/helpers/proxy-agent.js +26 -0
  30. package/dist/helpers/proxy-agent.js.map +1 -0
  31. package/dist/helpers/request-logging.d.ts +4 -0
  32. package/dist/helpers/request-logging.js +96 -2
  33. package/dist/helpers/request-logging.js.map +1 -1
  34. package/dist/resources/schemas/broker-deployment-settings.schema.json +4 -0
  35. package/dist/types/agent-network-v2.d.ts +36 -9
  36. package/dist/types/agent-network-v2.js.map +1 -1
  37. package/dist/types/agent-network.d.ts +0 -4
  38. package/dist/types/agent-network.js.map +1 -1
  39. package/dist/types/types.d.ts +20 -3
  40. package/dist/utils/builders/builder.d.ts +2 -0
  41. package/dist/utils/builders/builder.js +22 -1
  42. package/dist/utils/builders/builder.js.map +1 -1
  43. package/dist/utils/builders/common/connection-facet-helpers.d.ts +2 -0
  44. package/dist/utils/builders/common/connection-facet-helpers.js +4 -1
  45. package/dist/utils/builders/common/connection-facet-helpers.js.map +1 -1
  46. package/dist/utils/builders/common/network-builder-helpers.d.ts +5 -0
  47. package/dist/utils/builders/common/network-builder-helpers.js +8 -0
  48. package/dist/utils/builders/common/network-builder-helpers.js.map +1 -1
  49. package/dist/utils/builders/common/network-metadata.js +1 -1
  50. package/dist/utils/builders/common/network-metadata.js.map +1 -1
  51. package/dist/utils/builders/common/types.d.ts +1 -1
  52. package/dist/utils/builders/local-space-resolver.d.ts +13 -3
  53. package/dist/utils/builders/local-space-resolver.js +16 -3
  54. package/dist/utils/builders/local-space-resolver.js.map +1 -1
  55. package/dist/utils/builders/policies-factory.d.ts +5 -1
  56. package/dist/utils/builders/policies-factory.js +74 -7
  57. package/dist/utils/builders/policies-factory.js.map +1 -1
  58. package/dist/utils/builders/project-builder-impl.d.ts +8 -1
  59. package/dist/utils/builders/project-builder-impl.js +17 -1
  60. package/dist/utils/builders/project-builder-impl.js.map +1 -1
  61. package/dist/utils/builders/project-builder.d.ts +8 -1
  62. package/dist/utils/builders/project-builder.js +2 -1
  63. package/dist/utils/builders/project-builder.js.map +1 -1
  64. package/dist/utils/builders/remote-space-resolver.d.ts +3 -3
  65. package/dist/utils/builders/remote-space-resolver.js +47 -32
  66. package/dist/utils/builders/remote-space-resolver.js.map +1 -1
  67. package/dist/utils/builders/v1/broker-builder.js +2 -1
  68. package/dist/utils/builders/v1/broker-builder.js.map +1 -1
  69. package/dist/utils/builders/v1/connections-builder.js +3 -0
  70. package/dist/utils/builders/v1/connections-builder.js.map +1 -1
  71. package/dist/utils/builders/v1/network-builder.js +10 -2
  72. package/dist/utils/builders/v1/network-builder.js.map +1 -1
  73. package/dist/utils/builders/v2/broker-builder.js +1 -1
  74. package/dist/utils/builders/v2/broker-builder.js.map +1 -1
  75. package/dist/utils/builders/v2/connections-builder.d.ts +5 -1
  76. package/dist/utils/builders/v2/connections-builder.js +93 -19
  77. package/dist/utils/builders/v2/connections-builder.js.map +1 -1
  78. package/dist/utils/builders/v2/llm-builder.js +17 -6
  79. package/dist/utils/builders/v2/llm-builder.js.map +1 -1
  80. package/dist/utils/builders/v2/network-builder.js +2 -0
  81. package/dist/utils/builders/v2/network-builder.js.map +1 -1
  82. package/dist/utils/constants.d.ts +15 -1
  83. package/dist/utils/constants.js +19 -4
  84. package/dist/utils/constants.js.map +1 -1
  85. package/dist/utils/deployment-settings.d.ts +1 -0
  86. package/dist/utils/deployment-settings.js.map +1 -1
  87. package/dist/utils/dry-run/dry-run-render.d.ts +1 -0
  88. package/dist/utils/dry-run/dry-run-render.js +23 -13
  89. package/dist/utils/dry-run/dry-run-render.js.map +1 -1
  90. package/dist/utils/exchange.d.ts +1 -0
  91. package/dist/utils/exchange.js +20 -0
  92. package/dist/utils/exchange.js.map +1 -1
  93. package/dist/utils/facets/agent-graph-facet.d.ts +1 -1
  94. package/dist/utils/facets/agent-graph-facet.js +8 -8
  95. package/dist/utils/facets/agent-graph-facet.js.map +1 -1
  96. package/dist/utils/facets/api-instance-facet.d.ts +2 -0
  97. package/dist/utils/facets/api-instance-facet.js +72 -14
  98. package/dist/utils/facets/api-instance-facet.js.map +1 -1
  99. package/dist/utils/facets/apim-policy-helpers.d.ts +29 -2
  100. package/dist/utils/facets/apim-policy-helpers.js +19 -5
  101. package/dist/utils/facets/apim-policy-helpers.js.map +1 -1
  102. package/dist/utils/facets/asset-facet.d.ts +1 -0
  103. package/dist/utils/facets/asset-facet.js +34 -25
  104. package/dist/utils/facets/asset-facet.js.map +1 -1
  105. package/dist/utils/facets/connection-facet.d.ts +6 -0
  106. package/dist/utils/facets/connection-facet.js +199 -17
  107. package/dist/utils/facets/connection-facet.js.map +1 -1
  108. package/dist/utils/facets/deployment-helpers.d.ts +1 -0
  109. package/dist/utils/facets/deployment-helpers.js +26 -20
  110. package/dist/utils/facets/deployment-helpers.js.map +1 -1
  111. package/dist/utils/facets/deployment-runner.js +4 -1
  112. package/dist/utils/facets/deployment-runner.js.map +1 -1
  113. package/dist/utils/facets/facets.d.ts +1 -0
  114. package/dist/utils/facets/facets.js +16 -7
  115. package/dist/utils/facets/facets.js.map +1 -1
  116. package/dist/utils/facets/mule-application-facet.js +2 -2
  117. package/dist/utils/facets/mule-application-facet.js.map +1 -1
  118. package/dist/utils/facets/secret-manager-client.d.ts +16 -0
  119. package/dist/utils/facets/secret-manager-client.js +67 -0
  120. package/dist/utils/facets/secret-manager-client.js.map +1 -0
  121. package/dist/utils/facets/secret-tls-validator.d.ts +5 -0
  122. package/dist/utils/facets/secret-tls-validator.js +60 -0
  123. package/dist/utils/facets/secret-tls-validator.js.map +1 -0
  124. package/dist/utils/gateway.js +1 -1
  125. package/dist/utils/gateway.js.map +1 -1
  126. package/dist/utils/run-local/build-status.js +2 -2
  127. package/dist/utils/run-local/build-status.js.map +1 -1
  128. package/dist/utils/run-local/index.d.ts +1 -1
  129. package/dist/utils/run-local/index.js +2 -1
  130. package/dist/utils/run-local/index.js.map +1 -1
  131. package/dist/utils/run-local/local-a2a-upstream.d.ts +1 -0
  132. package/dist/utils/run-local/local-a2a-upstream.js +5 -4
  133. package/dist/utils/run-local/local-a2a-upstream.js.map +1 -1
  134. package/dist/utils/run-local/local-tls-model.d.ts +18 -0
  135. package/dist/utils/run-local/local-tls-model.js +97 -0
  136. package/dist/utils/run-local/local-tls-model.js.map +1 -0
  137. package/dist/utils/run-local/local-tls.d.ts +37 -0
  138. package/dist/utils/run-local/local-tls.js +245 -0
  139. package/dist/utils/run-local/local-tls.js.map +1 -0
  140. package/dist/utils/run-local/policy-resolver.js +5 -0
  141. package/dist/utils/run-local/policy-resolver.js.map +1 -1
  142. package/dist/utils/run-local/runtime-environment-manager.d.ts +2 -2
  143. package/dist/utils/run-local/runtime-environment-manager.js +8 -4
  144. package/dist/utils/run-local/runtime-environment-manager.js.map +1 -1
  145. package/dist/utils/run-local/secrets-manager.d.ts +1 -0
  146. package/dist/utils/run-local/secrets-manager.js +2 -1
  147. package/dist/utils/run-local/secrets-manager.js.map +1 -1
  148. package/dist/utils/sanitize.d.ts +1 -0
  149. package/dist/utils/sanitize.js +14 -0
  150. package/dist/utils/sanitize.js.map +1 -0
  151. package/dist/utils/variables.d.ts +7 -2
  152. package/dist/utils/variables.js +46 -6
  153. package/dist/utils/variables.js.map +1 -1
  154. package/package.json +6 -4
  155. package/scripts/extract-error-catalog.js +88 -0
  156. package/templates/agentic-network/agent-network.yaml.template +1 -7
  157. package/templates/agentic-network/brokers/broker1.agent.template +1 -1
  158. 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
@@ -145,7 +145,7 @@ FLAGS
145
145
  --[no-]collectMetrics collect metrics. You can define this in the COLLECT_METRICS environment
146
146
  variable.
147
147
  --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,
148
+ top-level "brokers:" mapping vCores, replicas, resources.*, logging.level,
149
149
  runtimeVersion). Mutually exclusive with --deployment-property.
150
150
  --deployment-property=<value>... [default: ] Typed deployment setting in format <scope>:<name>:<value> (e.g.,
151
151
  --deployment-property brokers:vCores:0.1). Repeatable. Mutually exclusive with
@@ -180,8 +180,25 @@ EXAMPLES
180
180
  $ agent-network project deploy --property apiKey:sk-xxx --property role:user
181
181
 
182
182
  $ agent-network project deploy --path ./my-project --property myAgent.url:https://api.example.com
183
+
184
+ $ agent-network project deploy --deployment-property brokers:replicas:3
183
185
  ```
184
186
 
187
+ Replica count defaults to `1`. Set `--deployment-property brokers:replicas:3`, or use
188
+ `--deployment-properties-file settings.yaml` with numeric YAML:
189
+
190
+ ```yaml
191
+ brokers:
192
+ replicas: 3
193
+ ```
194
+
195
+ `replicas` must be an integer of at least `1`; quoted YAML strings are rejected.
196
+ It applies to Agent Graph and Mule runtime applications on CloudHub 2.0 and Runtime
197
+ Fabric, for both new deployments and redeployments, not to gateway infrastructure.
198
+ Target capacity and platform quotas still apply; deployment readiness polling does
199
+ not guarantee that every requested replica is running.
200
+
201
+
185
202
  ## `anypoint-cli-agent-fabric-plugin agent-network project publish`
186
203
 
187
204
  Publish current Agent Network project to Anypoint Platform
@@ -451,6 +468,14 @@ anypoint-cli-agent-fabric-plugin agent-network project publish
451
468
  anypoint-cli-agent-fabric-plugin agent-network project deploy
452
469
  ```
453
470
 
471
+ ## Getting started
472
+
473
+ 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.
474
+
475
+ ## Troubleshooting
476
+
477
+ 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.
478
+
454
479
  ## Development
455
480
 
456
481
  ### Prerequisites