diff --git a/agent-network/1.0/antora.yml b/agent-network/1.0/antora.yml new file mode 100644 index 000000000..a2fc36a46 --- /dev/null +++ b/agent-network/1.0/antora.yml @@ -0,0 +1,10 @@ +name: agent-network +title: Building Agent Networks +version: '1.0' +display_version: '1.0' +start_page: af-agent-networks.adoc +nav: +- modules/ROOT/nav.adoc +asciidoc: + attributes: + page-notice-banner-message: You're viewing version 1.0 documentation. You can edit and redeploy existing 1.0 projects, but you must create new projects with version 2.0. Switch to version 2.0. \ No newline at end of file diff --git a/modules/ROOT/assets/images/af-acb-canvas.png b/agent-network/1.0/modules/ROOT/assets/images/af-acb-canvas.png similarity index 100% rename from modules/ROOT/assets/images/af-acb-canvas.png rename to agent-network/1.0/modules/ROOT/assets/images/af-acb-canvas.png diff --git a/modules/ROOT/assets/images/af-acb-dev-agent-icon.png b/agent-network/1.0/modules/ROOT/assets/images/af-acb-dev-agent-icon.png similarity index 100% rename from modules/ROOT/assets/images/af-acb-dev-agent-icon.png rename to agent-network/1.0/modules/ROOT/assets/images/af-acb-dev-agent-icon.png diff --git a/modules/ROOT/assets/images/af-agent-network-canvas.png b/agent-network/1.0/modules/ROOT/assets/images/af-agent-network-canvas.png similarity index 100% rename from modules/ROOT/assets/images/af-agent-network-canvas.png rename to agent-network/1.0/modules/ROOT/assets/images/af-agent-network-canvas.png diff --git a/modules/ROOT/assets/images/af-onboarding-broker-example.png b/agent-network/1.0/modules/ROOT/assets/images/af-onboarding-broker-example.png similarity index 100% rename from modules/ROOT/assets/images/af-onboarding-broker-example.png rename to agent-network/1.0/modules/ROOT/assets/images/af-onboarding-broker-example.png diff --git a/modules/ROOT/assets/images/agent-fabric-architecture.png b/agent-network/1.0/modules/ROOT/assets/images/agent-fabric-architecture.png similarity index 100% rename from modules/ROOT/assets/images/agent-fabric-architecture.png rename to agent-network/1.0/modules/ROOT/assets/images/agent-fabric-architecture.png diff --git a/agent-network/1.0/modules/ROOT/nav.adoc b/agent-network/1.0/modules/ROOT/nav.adoc new file mode 100644 index 000000000..55fa4d059 --- /dev/null +++ b/agent-network/1.0/modules/ROOT/nav.adoc @@ -0,0 +1,10 @@ +.xref:af-agent-networks.adoc[Building Agent Networks] +* xref:af-agent-networks.adoc[Overview] +* xref:af-get-started.adoc[] +* xref:af-create-agent-network.adoc[] +* xref:af-define-your-agent-network-specification.adoc[] +* xref:af-publish-agent-network-assets.adoc[] +* xref:af-deploy-agent-network-targets.adoc[] +* xref:af-troubleshoot-agent-networks.adoc[] +* xref:af-build-agent-networks-in-a-ci-cd-environment.adoc[] +* xref:af-project-files.adoc[] diff --git a/modules/ROOT/pages/af-agent-networks.adoc b/agent-network/1.0/modules/ROOT/pages/af-agent-networks.adoc similarity index 99% rename from modules/ROOT/pages/af-agent-networks.adoc rename to agent-network/1.0/modules/ROOT/pages/af-agent-networks.adoc index d2deab2d0..17c167d9c 100644 --- a/modules/ROOT/pages/af-agent-networks.adoc +++ b/agent-network/1.0/modules/ROOT/pages/af-agent-networks.adoc @@ -74,7 +74,7 @@ An autonomous software component that uses goals, context, and available tools, Agents can be defined either locally in the agent network or externally in a different agent network or elsewhere in your company. Your agent network can use both locally defined and externally defined agents to complete tasks. + -include::anypoint-code-builder::partial$af-shared.adoc[tags="agent-support"] +include::partial$af-shared.adoc[tags="agent-support"] MCP server:: A service that implements the Model Context Protocol (MCP) to expose tools and data to AI clients, enabling LLMs to invoke external capabilities through a standard interface. diff --git a/modules/ROOT/pages/af-build-agent-networks-in-a-ci-cd-environment.adoc b/agent-network/1.0/modules/ROOT/pages/af-build-agent-networks-in-a-ci-cd-environment.adoc similarity index 100% rename from modules/ROOT/pages/af-build-agent-networks-in-a-ci-cd-environment.adoc rename to agent-network/1.0/modules/ROOT/pages/af-build-agent-networks-in-a-ci-cd-environment.adoc diff --git a/modules/ROOT/pages/af-create-agent-network.adoc b/agent-network/1.0/modules/ROOT/pages/af-create-agent-network.adoc similarity index 90% rename from modules/ROOT/pages/af-create-agent-network.adoc rename to agent-network/1.0/modules/ROOT/pages/af-create-agent-network.adoc index 7858d3ea2..40f934aa2 100644 --- a/modules/ROOT/pages/af-create-agent-network.adoc +++ b/agent-network/1.0/modules/ROOT/pages/af-create-agent-network.adoc @@ -30,10 +30,10 @@ To get started, try one of these suggested messages. * In Create, select *Create an Agent Network*. * From the Command Palette, run this command: *MuleSoft: Create an Agent Network Project*. . Enter a name for the project and select the location to create the project. -. Select the business group associated with the target space you created in xref:anypoint-code-builder::af-get-started.adoc[Get Started with Agent Networks]. The business group you select must be the same business group you selected when you created the target space. +. Select the business group associated with the target space you created in xref:af-get-started.adoc[Get Started with Agent Networks]. The business group you select must be the same business group you selected when you created the target space. . Select *Create Project*. -Anypoint Code Builder creates these files as part of your agent network project. These files define your agent network specification to meet your business requirements. For more information, see xref:anypoint-code-builder::af-project-files.adoc[Agent Network Project File Reference]. +Anypoint Code Builder creates these files as part of your agent network project. These files define your agent network specification to meet your business requirements. For more information, see xref:af-project-files.adoc[Agent Network Project File Reference]. * `agent-network.yaml` + diff --git a/agent-network/1.0/modules/ROOT/pages/af-define-your-agent-network-specification.adoc b/agent-network/1.0/modules/ROOT/pages/af-define-your-agent-network-specification.adoc new file mode 100644 index 000000000..5e0bf0733 --- /dev/null +++ b/agent-network/1.0/modules/ROOT/pages/af-define-your-agent-network-specification.adoc @@ -0,0 +1,165 @@ +[[define-spec]] += Define Your Agent Network Specification + +After you create your agent network project, configure `agent-network.yaml` and `exchange.json` to reflect the structure of your network. + +[[before-you-begin]] +== Before You Begin + +Make sure you review the xref:af-get-started.adoc#before-you-begin[prerequisites]. + +[TIP] +To help you identify agents that are also brokers on the Anypoint Code Builder canvas, consider appending "Broker" to the end of the name, for example `employee-onboarding-broker`. + +[[define-dev-agent]] +== Define a Network Using MuleSoft Vibes + +MuleSoft Vibes can help you configure your agent network specification. For more information, see xref:anypoint-code-builder::api-ai-create-spec.adoc[]. + +. In the Anypoint Code Builder activity bar, click the agent icon image:af-acb-dev-agent-icon.png["",18,18]. +. Give the agent information about your agent network, including the brokers, agents, MCP servers, and LLMs you want to connect. + +To get started, try one of these suggested messages. + +* Help me build an agent network configuration for my Employee Onboarding project. +* Revise my Employee Onboarding agent network project. Use OpenAI for the LLM. +* Add a new broker for employee offboarding to my HR agent network. +* Add a new skill to Offboarding broker. + +[[define-acb-ide]] +== Define a Network Using Anypoint Code Builder or IDE + +If you don't want to use MuleSoft Vibes, use Anypoint Code Builder or your IDE to edit the `agent-network.yaml` and `exchange.json` files and define your agent network and authentication. + +To understand sections of the project files and expected values, see xref:af-project-files.adoc[Agent Network Project File Reference]. The `agent-network.yaml` file can contain definitions for one or more brokers. + +If your agent network references Anypoint Exchange assets, you need to use the asset IDs in `exchange.json` to add references in the `agent-network.yaml` file. For more information, see <>. + +Use auto-completion menus in Anypoint Code Builder to speed your development. For more information, see xref:anypoint-code-builder::start-discover-ui.adoc#use-autocomplete[Use Auto-Completion Menus]. + +[[add-exchange-assets]] +== Add Exchange Assets to Your Agent Network Project + +If you have existing Exchange assets to use in your agent network, add them to the `dependencies` attribute in `exchange.json` in your project. After you add assets, edit the `agent-network.yaml` file to indicate which brokers use those assets. This applies to both assets your own business group owns and public assets from a different business group. + +For a complete example, see <>. + +=== Add Assets Using MuleSoft Vibes + +. In the Anypoint Code Builder activity bar, click the agent icon image:af-acb-dev-agent-icon.png["",18,18]. +. Tell the agent that you want to add Exchange assets to your project. MuleSoft Vibes does the rest. + +To get started, try one of these suggested messages. + +* Add tools for background check processing in my Employee Onboarding project. +* Add a Talent Pool MCP server to my Employee Onboarding agent network project. + +[[add-assets-acb]] +=== Add Assets Using Anypoint Code Builder + +To reference existing Exchange assets in your agent network project, follow these steps. This procedure applies whether the asset belongs to your own business group or to a different business group (for example, a public Exchange asset). + +. If you're not logged in already, log in to your Anypoint Platform account. +. In your Anypoint Code Builder project, choose one of the following: + * In Explorer, right-click a project file and select *Add Exchange Assets to Agent Network Project*. + * In the Command Palette, run this command: *MuleSoft: Add Agent Network Assets to Agent Network Project*. +. In Add Exchange Assets to Project, enter information about the assets to add. +. Select *Add to Project*. ++ +Assets are added to the `dependencies` attribute in the `exchange.json` file in your project. +. Edit the `agent-network.yaml` file to indicate which brokers use those assets: ++ +.. Add a connection entry for each asset in the `context.connections` section. Set `kind` to match the asset type (`a2a`, `mcp`, or `llm`), and set `ref.name` to the asset's `assetId` from `exchange.json`. +.. Reference the connection from one or more brokers (for example, from a broker's `llm`, `links`, or `tools` section). +.. If the asset belongs to a different business group than your agent network, specify the `namespace` property at the same level as `name`. Provide the `groupId` (business group ID) for the business group that the dependency belongs to. The `groupId` value is the same as the `groupId` value of the corresponding dependency in `exchange.json`. If you don't provide a `namespace` value, the same `groupId` as the agent network project is used. + +After you add dependencies, they're available as values in auto-completion menus in Anypoint Code Builder. For example, after you add `test-agent` to `exchange.json`, the value `test-agent` is available in auto-completion menus in the code editor in `agent-network.yaml` when you reference an agent. + +[[exchange-assets-example]] +=== Example: Reference an Exchange Asset from Your Agent Network + +This example shows a complete `exchange.json` and `agent-network.yaml` for a project that consumes an A2A agent (`helpCenterAgentTestV3`) from Anypoint Exchange. The same pattern applies to MCP servers and LLMs: change the connection `kind` to `mcp` or `llm`, and adjust the `dependencies` classifier in `exchange.json` accordingly. + +In `exchange.json`, the asset is listed in the `dependencies` array. The `groupId` value identifies the business group that owns the asset. If the asset belongs to a different business group than your project, use that asset's `groupId` in the connection's `namespace` value in `agent-network.yaml`. + +[source,json] +---- +{ + "main": "agent-network.yaml", + "name": "brokerV2-template", + "classifier": "agentic-network", + "organizationId": "b4c12f0a-c376-4561-878c-f4f0540c5407", + "descriptorVersion": "1.0.0", + "tags": [], + "metadata": { + "variables": { + "myAgent": { + "url": { + "description": "My External Agent URL", + "default": "", + "secret": false + } + } + } + }, + "dependencies": [ + { + "classifier": "agent-metadata", + "packaging": "zip", + "groupId": "b4c12f0a-c376-4561-878c-f4f0540c5407", + "assetId": "helpCenterAgentTestV3", + "version": "1.0.2" + } + ], + "groupId": "b4c12f0a-c376-4561-878c-f4f0540c5407", + "assetId": "brokerv2-template", + "version": "1.0.0" +} +---- + +In `agent-network.yaml`, the asset is declared as a connection in `context.connections`. The connection `kind` matches the asset type (`a2a` for an agent, `mcp` for an MCP server, or `llm` for an LLM), and `ref.name` matches the `assetId` from `exchange.json`. The `ref.namespace` value matches the asset's `groupId`. URL and credential values are typically supplied through variables defined in `exchange.json`. After defining the connection, brokers reference it by name from their `llm`, `links`, or `tools` sections. + +[source,yaml] +---- +agentNetwork: 2.0.0 +info: + label: brokerV2-template + version: v1 +registry: {} +context: + connections: + helpCenterAgentTestV3: + kind: a2a + ref: + name: helpCenterAgentTestV3 + namespace: b4c12f0a-c376-4561-878c-f4f0540c5407 + url: ${myAgent.url} +brokers: + broker1: + kind: AgentScript + implementation: ./brokers/broker1.agent + interfaces: + a2a: + card: + name: Broker 1 + description: Describe what your broker does. + url: http://localhost:8081/broker1 + version: 1.0.0 + protocolVersion: 0.3.0 + capabilities: + streaming: true + pushNotifications: false + defaultInputModes: + - text/plain + defaultOutputModes: + - text/plain + skills: + - id: my-skill + name: My Skill + description: Describe what this skill does. + tags: + - general +---- + +Because the connection in this example uses an explicit `namespace`, this same configuration works whether the asset belongs to the project's business group or to a different one (such as a public Exchange asset). To consume a public asset, copy the asset's `groupId` from Anypoint Exchange into both the `dependencies` entry in `exchange.json` and the connection's `namespace` value in `agent-network.yaml`. + diff --git a/modules/ROOT/pages/af-deploy-agent-network-targets.adoc b/agent-network/1.0/modules/ROOT/pages/af-deploy-agent-network-targets.adoc similarity index 97% rename from modules/ROOT/pages/af-deploy-agent-network-targets.adoc rename to agent-network/1.0/modules/ROOT/pages/af-deploy-agent-network-targets.adoc index fd83e5065..6e72e9882 100644 --- a/modules/ROOT/pages/af-deploy-agent-network-targets.adoc +++ b/agent-network/1.0/modules/ROOT/pages/af-deploy-agent-network-targets.adoc @@ -65,7 +65,7 @@ To get started, try one of these suggested messages. . In Anypoint Code Builder, choose one of the following: . In Explorer, right-click a project file and select *Deploy Agent Network*. . From the Command Palette, run this command: *MuleSoft: Deploy Agent Network*. -. In Deploy Agent Network, specify the environment, target space, gateways, and other deployment information. If you don't see any deployment targets to select, then you need to set up your target deployment space and set up gateways. For instructions, see xref:anypoint-code-builder::af-get-started.adoc[Get Started with Agent Networks]. +. In Deploy Agent Network, specify the environment, target space, gateways, and other deployment information. If you don't see any deployment targets to select, then you need to set up your target deployment space and set up gateways. For instructions, see xref:af-get-started.adoc[Get Started with Agent Networks]. . Select *Deploy*. . Your instances are deployed and ready to be tested. An instance is deployed for each connection defined in your agent network. If your agent network contains brokers, one instance is deployed per broker. diff --git a/modules/ROOT/pages/af-get-started.adoc b/agent-network/1.0/modules/ROOT/pages/af-get-started.adoc similarity index 97% rename from modules/ROOT/pages/af-get-started.adoc rename to agent-network/1.0/modules/ROOT/pages/af-get-started.adoc index 93f1fde29..738484df7 100644 --- a/modules/ROOT/pages/af-get-started.adoc +++ b/agent-network/1.0/modules/ROOT/pages/af-get-started.adoc @@ -1,7 +1,7 @@ [[get-started]] = Get Started with Agent Networks -include::anypoint-code-builder::partial$af-shared.adoc[tags=get-started] +include::partial$af-shared.adoc[tags=get-started] [[setup-space]] == Set Up the Private Space or Deployment Target for Your Environment diff --git a/modules/ROOT/pages/af-project-files.adoc b/agent-network/1.0/modules/ROOT/pages/af-project-files.adoc similarity index 100% rename from modules/ROOT/pages/af-project-files.adoc rename to agent-network/1.0/modules/ROOT/pages/af-project-files.adoc diff --git a/modules/ROOT/pages/af-publish-agent-network-assets.adoc b/agent-network/1.0/modules/ROOT/pages/af-publish-agent-network-assets.adoc similarity index 100% rename from modules/ROOT/pages/af-publish-agent-network-assets.adoc rename to agent-network/1.0/modules/ROOT/pages/af-publish-agent-network-assets.adoc diff --git a/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc b/agent-network/1.0/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc similarity index 97% rename from modules/ROOT/pages/af-troubleshoot-agent-networks.adoc rename to agent-network/1.0/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc index 92fc014a3..001c5b22a 100644 --- a/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc +++ b/agent-network/1.0/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc @@ -73,7 +73,7 @@ If you installed Anypoint Code Builder successfully, but you don’t see agent n === Issue: No Agent Network Deployment Targets -If you attempt to deploy an agent network, but you don’t see any deployment targets in Anypoint Code Builder or Anypoint CLI, then you need to set up your target deployment space and set up gateways. For instructions, see xref:anypoint-code-builder::af-get-started.adoc[Get Started with Agent Networks]. +If you attempt to deploy an agent network, but you don’t see any deployment targets in Anypoint Code Builder or Anypoint CLI, then you need to set up your target deployment space and set up gateways. For instructions, see xref:af-get-started.adoc[Get Started with Agent Networks]. === Error: "Cannot complete task due to issue accessing reasoning engine" diff --git a/agent-network/1.0/modules/ROOT/partials/af-shared.adoc b/agent-network/1.0/modules/ROOT/partials/af-shared.adoc new file mode 100644 index 000000000..bdbb30af5 --- /dev/null +++ b/agent-network/1.0/modules/ROOT/partials/af-shared.adoc @@ -0,0 +1,130 @@ +// +// tag::agent-support[] +Agent assets must be A2A-compliant. +// end::agent-support[] +// + +// +// tag::get-started[] +Creating agent networks is a multi-step process. Review these prerequisites and task overviews to make sure you can create agent networks efficiently. + +[[before-you-begin]] +== Before You Begin + +Before you get started, review these prerequisites. + +[[platform-requirements]] +=== Anypoint Platform Requirements and Permissions + +[cols="1,1"] +|=== +|Anypoint Platform Component |Required Permissions + +|Runtime Manager +a| + +* Manage Servers +* Create Applications +* Read Servers + +|Anypoint Code Builder +a| + +* Anypoint Code Builder +* Mule Developer Generative AI User + +|Anypoint Design Center +|Design Center Developer + +|API Manager +a| + +* Deploy API Proxies +* Manage Policies + +|Exchange +|Exchange Contributor + +|Usage +|Usage Viewer + +|CloudHub 2.0 or Runtime Fabric +|xref:runtime-fabric::limitations-self.adoc[Runtime Fabric permissions] xref:cloudhub-2::ps-assign-permissions.adoc[CloudHub 2.0 permissions] +|=== + +See xref:access-management::permissions-by-product.adoc[] for a list of all Anypoint Platform permissions. + +[[additional-reqs]] +=== Additional Requirements + +To complete these tasks, you also need: + +* Your Anypoint Platform credentials +* xref:anypoint-code-builder::start-acb.adoc[Anypoint Code Builder desktop] ++ +Allowlist Anypoint Code Builder URLs. For more information, see xref:anypoint-code-builder::urls-to-allow.adoc[Allow URLs for Anypoint Code Builder]. +* xref:gateway::flex-gateway-managed-ingress-egress.adoc[Omni Gateway Ingress and Egress gateways] + +=== MuleSoft Vibes Requirements (Optional) + +If you plan to use MuleSoft Vibes to create agent network projects, make sure you meet xref:anypoint-code-builder::mulesoft-vibes.adoc#before-you-begin[the requirements]. + +[[cli-requirements]] +=== CLI Requirements (Optional) + +If you're using the Anypoint CLI to create agent network projects, ensure you meet these requirements. + +* Node 20 (v20.19.4) or later. See https://nodejs.org/en[Nodejs.org]. +* Java 17 or later. Set the `JAVA_HOME` environment variable. +* xref:af-build-agent-networks-in-a-ci-cd-environment.adoc[Anypoint CLI Fabric Plugin] + +[[overview]] +== Task Overview + +[[step-1-setup]] +=== Step 1: Set Up Your Agent Network + +. Use Anypoint Runtime Manager to set up a private space in CloudHub 2.0 or deployment target in Runtime Fabric. ++ +See xref:af-get-started.adoc#setup-space[Set Up the Private Space or Deployment Target for Your Environment]. +. Set up Ingress and egress Omni Gateways for the private space or deployment target. ++ + * If using Anypoint Code Builder, see xref:af-get-started.adoc#setup-gateways[Set Up Agent Network Gateways for the Private Space or Deployment Target]. + * If using the Anypoint CLI, see the xref:af-build-agent-networks-in-a-ci-cd-environment.adoc#agent-network-setup-gateways[setup gateways command reference]. + +[[step-2-create]] +=== Step 2: Create a Project + +Now you're ready to create an agent network project. Choose one of these methods. + +* xref:af-create-agent-network.adoc#create-dev-agent[Create a Network Using MuleSoft Vibes] +* xref:af-create-agent-network.adoc#create-acb[Create a Network Using Anypoint Code Builder] +* xref:af-create-agent-network.adoc#create-cli[Create a Network Using the Anypoint CLI] + +[[step-3-define]] +=== Step 3: Define Your Agent Network Specification + +After you create your agent network project, configure `agent-network.yaml` and `exchange.json` to reflect the structure of your network. + +* xref:af-define-your-agent-network-specification.adoc#define-dev-agent[Define a Network Using MuleSoft Vibes] +* xref:af-define-your-agent-network-specification.adoc#define-acb-ide[Define a Network Using Anypoint Code Builder or IDE] + +[[step-4-publish]] +=== Step 4: Publish Your Agent Network Assets + +Build and publish your agent network project as Anypoint Exchange assets. When you publish the agent network, an asset is created in Exchange for each broker, agent, and MCP server that's in your agent network. + +* xref:af-publish-agent-network-assets.adoc#publish-dev-agent[Publish Your Network Using MuleSoft Vibes] +* xref:af-publish-agent-network-assets.adoc#publish-acb[Publish Your Network Using Anypoint Code Builder] +* xref:af-build-agent-networks-in-a-ci-cd-environment.adoc#agent-network-project-publish[Publish Your Network Using the Anypoint CLI] + +[[step-5-deploy]] +=== Step 5: Deploy Your Agent Network Instances + +Deploy your agent network instance to a deployment target. You can deploy to a CloudHub 2.0 private space or to a Runtime Fabric. + +* xref:af-deploy-agent-network-targets.adoc#deploy-dev-agent[Deploy Your Network Using MuleSoft Vibes] +* xref:af-deploy-agent-network-targets.adoc#deploy-acb[Deploy Your Network Using Anypoint Code Builder] +* xref:af-build-agent-networks-in-a-ci-cd-environment.adoc#agent-network-project-deploy[Deploy Your Network Using the Anypoint CLI] +// end::get-started[] +// diff --git a/agent-network/2.0/antora.yml b/agent-network/2.0/antora.yml new file mode 100644 index 000000000..d9c65eed1 --- /dev/null +++ b/agent-network/2.0/antora.yml @@ -0,0 +1,7 @@ +name: agent-network +title: Building Agent Networks +version: '2.0' +display_version: '2.0' +start_page: af-agent-networks.adoc +nav: +- modules/ROOT/nav.adoc diff --git a/agent-network/2.0/modules/ROOT/assets/image-source-files/agent-fabric-architecture-v2-shared-space.graffle b/agent-network/2.0/modules/ROOT/assets/image-source-files/agent-fabric-architecture-v2-shared-space.graffle new file mode 100644 index 000000000..870391425 Binary files /dev/null and b/agent-network/2.0/modules/ROOT/assets/image-source-files/agent-fabric-architecture-v2-shared-space.graffle differ diff --git a/agent-network/2.0/modules/ROOT/assets/images/af-acb-canvas.png b/agent-network/2.0/modules/ROOT/assets/images/af-acb-canvas.png new file mode 100644 index 000000000..fa232a501 Binary files /dev/null and b/agent-network/2.0/modules/ROOT/assets/images/af-acb-canvas.png differ diff --git a/agent-network/2.0/modules/ROOT/assets/images/af-acb-dev-agent-icon.png b/agent-network/2.0/modules/ROOT/assets/images/af-acb-dev-agent-icon.png new file mode 100644 index 000000000..208d03be5 Binary files /dev/null and b/agent-network/2.0/modules/ROOT/assets/images/af-acb-dev-agent-icon.png differ diff --git a/agent-network/2.0/modules/ROOT/assets/images/af-agent-network-canvas.png b/agent-network/2.0/modules/ROOT/assets/images/af-agent-network-canvas.png new file mode 100644 index 000000000..ef288eb66 Binary files /dev/null and b/agent-network/2.0/modules/ROOT/assets/images/af-agent-network-canvas.png differ diff --git a/agent-network/2.0/modules/ROOT/assets/images/af-it-broker-escalation-flow.png b/agent-network/2.0/modules/ROOT/assets/images/af-it-broker-escalation-flow.png new file mode 100644 index 000000000..b4d2fe887 Binary files /dev/null and b/agent-network/2.0/modules/ROOT/assets/images/af-it-broker-escalation-flow.png differ diff --git a/agent-network/2.0/modules/ROOT/assets/images/af-onboarding-broker-example.png b/agent-network/2.0/modules/ROOT/assets/images/af-onboarding-broker-example.png new file mode 100644 index 000000000..15559af71 Binary files /dev/null and b/agent-network/2.0/modules/ROOT/assets/images/af-onboarding-broker-example.png differ diff --git a/agent-network/2.0/modules/ROOT/assets/images/agent-fabric-architecture-v2-shared-space.png b/agent-network/2.0/modules/ROOT/assets/images/agent-fabric-architecture-v2-shared-space.png new file mode 100644 index 000000000..4600485cf Binary files /dev/null and b/agent-network/2.0/modules/ROOT/assets/images/agent-fabric-architecture-v2-shared-space.png differ diff --git a/agent-network/2.0/modules/ROOT/nav.adoc b/agent-network/2.0/modules/ROOT/nav.adoc new file mode 100644 index 000000000..b0fe87107 --- /dev/null +++ b/agent-network/2.0/modules/ROOT/nav.adoc @@ -0,0 +1,13 @@ +.xref:af-agent-networks.adoc[Building Agent Networks] +* xref:af-agent-networks.adoc[Overview] +* xref:af-get-started.adoc[] +* xref:af-create-agent-network.adoc[] +* xref:af-define-your-agent-network-specification.adoc[] +* xref:af-publish-agent-network-assets.adoc[] +* xref:af-deploy-agent-network-targets.adoc[] +* xref:af-troubleshoot-agent-networks.adoc[] +* xref:af-build-agent-networks-in-a-ci-cd-environment.adoc[] +* xref:af-project-files.adoc[] +** xref:af-agent-network-yaml-reference.adoc[] +** xref:af-agent-script-reference.adoc[] +* xref:af-example-it-investigation-broker.adoc[] diff --git a/agent-network/2.0/modules/ROOT/pages/af-agent-network-yaml-reference.adoc b/agent-network/2.0/modules/ROOT/pages/af-agent-network-yaml-reference.adoc new file mode 100644 index 000000000..e0d6269ef --- /dev/null +++ b/agent-network/2.0/modules/ROOT/pages/af-agent-network-yaml-reference.adoc @@ -0,0 +1,1770 @@ +[[agent-network-2-0-yaml-reference]] += Agent Network (2.0) YAML Reference + +The agent-network.yaml details the required structure and properties that define your project's assets, connections, and policies. + +* <> +* <> +* <> +* <> +* <> +* <> +* <> + +[[agent-network-section]] +== Agent Network Section + +This is the root section of the agent network. Must include at least one of `registry`, `context`, or `brokers` must be present. + +This section has these properties. + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|info +|Provides metadata about the graphs. +|<> +|No + +|agentNetwork +|This string must be the <> of the agent network specification used by the agent network document. This is not related to the document's `info.version` property. +|String +|Yes + +|registry +|Definitions of agents, agents, and MCPs, LLMs. +|<> Object +|No + +|context +|Reusable entities scoped to the graphs defined in this file (for example, connections and policies). +|Object +|No + +|brokers +|A mapping of runtime Agent Script definitions that can be executed by the platform. +|<> +|No + +|=== + +[[info-section]] +== Info Section + +This section contains basic metadata about the agent network document itself. + +*Example* + +[source,yaml] +---- +info: + label: Employee Onboarding Workflow + description: >- + A multi-agent network for employee onboarding. Orchestrates HR system setup, + Salesforce profile creation, laptop and badge requests, and Slack notifications + for new hires. + version: 1.0.0 + tags: + - employee-onboarding + - multi-agent + - hr + - production +---- + +The section has these properties. + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|label +|The human-readable name of the agent network. +|String +|Yes + +|version +|The version number of the `agent-network.yaml` file. +|String +|Yes + +|description +|A human readable summary of what the agent network does. Accepts CommonMark syntax. +|String +|No + +|tags +|Categorization tags for this agent network document. +|Array of Strings +|No + +|`summary` +|A short summary of the purpose of the agent network. +|String +|No + +|`termsOfService` +|A URI for the Terms of Service for the API. This must be in the form of a URI. +|String +|No + +|`contact` +|The contact information for the agent network. +|Object +|No + +|`contact.name` +|The identifying name of the contact person/organization. +|String +|No + +|`contact.url` +|The URI for the contact information. This must be in the form of a URI. +|String +|No + +|`contact.email` +|The email address of the contact person/organization. This must be in the form of an email address. +|String +|No + +|`license` +|The license information for the agent network. +|Object +|No + +|`license.name` +|The license name used for the agent network. +|String +|Yes (if license present) + +|`license.identifier` +|An SPDX license expression. Mutually exclusive with `license.url`. +|String +|No + +|`license.url` +|A URI for the license. This must be in the form of a URI. Mutually exclusive with `license.identifier`. +|String +|No + +|=== + +[[registry-section]] +== Registry Section + +Use this section to organize and reference reusable agents, LLMs, and MCP tools. The registry section defined in the file is considered the "local registry". Assets defined in the registry are published to Exchange. + +*Example* + +[source,yaml] +---- +registry: + agents: + hr-system-agent: + info: + label: HR System Agent + description: Agent that creates new-hire records and manages HR system setup. + metadata: + platform: AgentForce + protocol: a2a + card: + a2a: + protocolVersion: "0.3.0" + name: hr-system-agent + description: Creates and manages employee records in the HR system. + url: https://hr-agent.example.com/a2a + defaultInputModes: [application/json, text/plain] + defaultOutputModes: [application/json, text/plain] + tools: + - mcp: + ref: + name: slack-mcp + allowed: [sendMessage, listChannels] + llm: + ref: + name: Open-AI-LLM + salesforce-agent: + info: + label: Salesforce Onboarding Agent + description: Agent that provisions Salesforce profiles for new hires. + metadata: + platform: AgentForce + protocol: a2a + card: + a2a: + protocolVersion: "0.3.0" + name: salesforce-agent + description: Onboards new employees to Salesforce. + url: https://sfdc-agent.example.com/a2a + defaultInputModes: [application/json] + defaultOutputModes: [application/json] + llm: + ref: + name: Open-AI-LLM + mcps: + slack-mcp: + info: + label: Slack MCP Server + description: MCP server for sending messages and listing Slack channels. + metadata: + protocolVersion: "2024-11-05" + transport: + kind: sse + ssePath: /mcp + tools: + - name: sendMessage + description: Send a message to a Slack channel. + inputSchema: + type: object + properties: + text: { type: string } + channelId: { type: string } + - name: listChannels + description: List available Slack channels. + inputSchema: + type: object + llms: + Open-AI-LLM: + info: + label: OpenAI LLM + description: OpenAI provider for orchestration and generation nodes. + metadata: + platform: OpenAI + models: + - gpt-4o + - gpt-4o-mini + - gpt5-mini + Azure-OpenAI-LLM: + info: + label: Azure OpenAI LLM + description: Azure OpenAI for orchestration nodes. + metadata: + platform: AzureOpenai + models: + - gpt-4o +---- + +The `registry` section has these properties. + +[%header,cols="1,1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required +|Values + +|`agents` +|The list of agents defined as part of this network. +|Object +|No +|Keys: identifiers matching ^[a-zA-Z_][a-zA-Z0-9_.-]*$. Values: AgentEntity + +|`mcps` +|The list of MCP servers defined as part of this network. +|Object +|No +|Keys: identifiers. Values: MCPServerEntity + +|`llms` +|The list of LLM providers defined as part of this network. +|Object +|No +|Keys: identifiers. Values: LLMEntity Each `LLMEntity` requires `metadata.platform`: `Gemini`, `OpenAI`, or `AzureOpenai`. + +|=== + +=== Info + +All nodes in this section share these properties. + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|`label` +|The human readable short text. +|String +|No + +|`description` +|A human readable text of what this element does. Accepts CommonMark syntax. +|String +|No + +|`tags` +|Optional tags. +|Array of Strings +|No + +|=== + +=== Agents + +Each registry agent is an `AgentEntity`. The schema requires a `metadata` object. The A2A agent card, tools, and LLM reference are nested under `metadata`, not at the root of the agent. + +The agents section has these properties. + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|`agents.info` +|Metadata for the agent. +|InfoObject +|No + +|`agents.metadata` +|Platform, protocol, card, tools, and LLM wiring for the agent. +|Object +|Yes + +|`agents.metadata.platform` +|Host platform for the agent (for example, AgentForce or Bedrock). +|String +|Yes + +|`agents.metadata.protocol` +|Integration protocol for the agent; use values such as a2a or other as defined by the platform. +|String +|Yes + +|`agents.metadata.card` +|Agent card payload. Include a2a for an A2A card, or other for other card types. +|Object +|No + +|`agents.metadata.card.a2a` +|The A2A agent card. See A2A Card. +|AgentCard +|Yes (when using the a2a card branch) + +|`agents.urls` +|Named URLs for the agent. +|Array +|No + +|`agents.metadata.tools` +|The list of tool providers (MCP or A2A) +|Array[Object] +|No + +|`agents.metadata.llm` +|Reference to the LLM used by this agent (ref to a declared LLM) +|Object +|No + +|=== + +Authentication for outbound calls is configured on <> (and related policies), not on registry `AgentEntity` definitions. + +[[a2a-card]] +==== A2A Card + +This section adheres to the Agent-to-Agent (A2A) specification v1.0 and describes an agent's contract, skills, and capabilities. This is a standard A2A agent card https://a2a-protocol.org/latest/specification/#441-agentcard[as defined in the Agent2Agent (A2A) Protocol specification]. + +The A2A card section has these properties. + +[%header,cols="1,1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required +|Values + +|`name` +|Human-readable name for the agent. +|string +|Yes +|-- + +|`description` +|Human-readable description of the agent's purpose. +|string +|Yes +|-- + +|`url` +|Preferred endpoint URL for interacting with the agent. Must support preferredTransport. +|string +|Yes +|e.g. https://api.example.com/a2a/v1 + +|`version` +|Agent's own version number (format defined by provider). +|String +|Yes +|e.g. 1.0.0 + +|`protocolVersion` +|Version of the A2A protocol this agent supports. +|String +|Yes +|Default: 0.3.0 + +|`capabilities` +|Optional capabilities supported by the agent. +|AgentCapabilities +|Yes +|See below + +|`defaultInputModes` +|Default supported input MIME types for all skills (overridable per skill). +|Array of string +|Yes +|-- + +|`defaultOutputModes` +|Default supported output MIME types for all skills (overridable per skill). +|Array of string +|Yes +|-- + +|`skills` +|The set of skills or distinct capabilities the agent can perform. +|Array of AgentSkills +|Yes +|See below + +|`preferredTransport` +|Transport for the main url. Must be available at that URL. +|String +|No +|JSONRPC, GRPC, HTTP+JSON (default: JSONRPC) + +|`additionalInterfaces` +|Additional transport+URL combinations for the same agent. +|Array of AgentInterface +|No +|Each: { transport: string, url: string } + +|`additionalInterfaces.transport` +|The transport protocol for this interface. +|String +|Yes +|`JSONRPC, GRPC, HTTP+JSON)` + +|`additionalInterfaces.url` +|The URL for this additional interface. +|String (URI) +|Yes +|Valid URI string + +|`provider` +|Agent's service provider. +|AgentProvider +|No +|{ organization: string, url: string } + +|`documentationUrl` +|Optional URL to the agent's documentation. +|String +|No +|-- + +|`iconUrl` +|Optional URL to an icon for the agent. +|String +|No +|-- + +|`security` +|Security requirement objects for all interactions (OpenAPI 3.0 style; OR of ANDs). +|Array of object +|No +|Each object: scheme names -> array of scope strings + +|`securitySchemes` +|Declared security schemes (key \= scheme name). OpenAPI 3.0 Security Scheme Object. +|Object +|No +|apiKey, http, oauth2, openIdConnect, mutualTLS + +|`signatures` +|JSON Web Signatures for this AgentCard (RFC 7515 JWS). +|Array of AgentCardSignature +|No +|{ protected, signature, header? } + +|`supportsAuthenticatedExtendedCard` +|If true, the agent can return an extended card to authenticated users. +|Boolean +|No +|Default: false + +|=== + +===== Skills Properties + +Skills describe the distinct capabilities the agent can perform and have these properties. + +[%header,cols="1,1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Valid Values +|Required + +|`id` +|Unique identifier for the skill. +|String +|Any string value +|No + +|`name` +|A human-readable name for the skill. +|String +|Any string value +|No + +|`description` +|A description of what this skill does. +|String +|Any string value +|No + +|`examples` +|Usage examples demonstrating how to use this skill. +|Array of strings +|Array of example strings +|No + +|`inputModes` +|Supported input MIME types for this skill (overrides defaultInputModes). +|Array of strings +|Array of MIME type strings +|No + +|`outputModes` +|Supported output MIME types for this skill (overrides defaultOutputModes). +|Array of strings +|Array of MIME type strings +|No + +|`tags` +|Categorization tags for this skill. +|Array of strings +|Array of tag strings +|No + +|=== + +===== Capabilities Properties + +Capabilities describe optional features supported by the agent and have these properties. + +[%header,cols="1,1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Valid Values +|Required + +|`streaming` +|Indicates if the agent supports streaming responses. +|Boolean +|`true` or `false` +|No + +|`pushNotifications` +|Indicates if the agent supports push notifications. +|Boolean +|`true` or `false` +|No + +|`stateTransitionHistory` +|Indicates if the agent maintains state transition history. +|Boolean +|`true` or `false` +|No + +|`extensions` +|List of extension capabilities supported by the agent. +|Array +|Array of extension objects +|No + +|=== + +=== MCP + +The MCP Server section has these properties. + +[%header,cols="1,1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required +|Values + +|`info` +|Metadata for the MCP Server +|`InfoObject` +|No +|-- + +|`urls` +|Named URLs for the agent. array No +|Array +|No +|-- + +|`metadata` +|MCP server descriptor (how to connect and what it exposes). +|Object +|Yes +|-- + +|`metadata.protocolVersion` +|Version of the MCP protocol. +|String +|No +|"2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25" + +|`metadata.transport` +|Transport used for communication. +|MCPTransport +|Yes +|SseTransport, StreamableHttpTransport, or StdioTransport + +|`metadata.provider` +|Service provider of the MCP server. +|Object +|No +|{ organization: string, url: string } + +|`metadata.capabilities` +|Server capabilities. +|ServerCapabilities +|No +|completions, experimental, tasks, logging, prompts, resources, tools + +|`metadata.tools` +|List of tools. +|Array +|No +|action definitions + +|`metadata.resources` +|List of resources. +|Array +|No +|Resource definitions + +|`metadata.resourceTemplates` +|List of resource templates. +|Array +|No +|ResourceTemplate definitions + +|`metadata.prompts` +|List of prompts. +|Array +|No +|Prompt definitions + +|`metadata.platform` +|Platform the MCP server runs on. +|String +|No +|-- + +|`metadata.securitySchemes` +|Security schemes for authentication. +|Object +|No +|SecurityScheme by key + +|=== + +==== MCP Transport types + +The `metadata.transport` object describes how clients connect to the MCP server. The supported transport kinds are `sse`, `streamableHttp`, and `stdio`. + +*Example* + +[source,yaml] +---- +registry: + mcps: + weather-mcp: + metadata: + protocolVersion: "2025-06-18" + transport: + kind: streamableHttp + path: /weather/mcp + provider: + organization: Acme Inc. + url: https://www.acme.com + my-mcp-sse: + metadata: + transport: + kind: sse + ssePath: /mcp/sse + messagesPath: /mcp +---- + +===== SseTransport + +Sse Transport has these properties. + +[%header,cols="1,1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required +|Values + +|`kind` +|Transport type. +|String +|Yes +|`"sse"` + +|`ssePath` +|Path to the SSE endpoint. +|String +|Yes +|-- + +|`messagesPath` +|Path to the messages endpoint. +|String +|No +|Agent Graph Expression Optional + +|=== + +===== StreamableHttpTransport + +StreamableHttpTransport has these properties. + +[%header,cols="1,1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required +|Values + +|`kind` +|Transport type. +|String +|Yes +|"streamableHttp" + +|`path` +|Path to the MCP endpoint. +|String +|No +|-- + +|=== + +===== StdioTransport + +StdioTransport has these properties. + +[%header,cols="1,1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required +|Values + +|`kind` +|Transport type. +|String +|Yes +|`"stdio"` + +|`instructions` +|Instructions to run the MCP server. +|String +|No +|-- + +|=== + +=== Reference Types + +Reference types are reusable objects that point to other entities defined in the registry, such as agents, MCP servers, LLMs, connections, and policies. + +*Example* + +[source,yaml] +---- +registry: + agents: + myEvaluationAgent: + type: a2a_agent + protocol: a2a + platform: agentforce + kind: evaluation + connections: + - kind: mcp + ref: + assetId: my-mcp-server + version: 1.0.0 + allowed: + - tool-name-1 + provenance: + kind: exchange + metadata: + organizationId: my-org +---- + +Reference types used in the Registry section have these properties. + +[%header,cols="1,1,1,1,1"] +|=== +|Reference +|Description +|Type +|Required +|Values + +|`AgentRef` +|Reference to an agent. +|Object +|No +|`{ name: string, namespace?: string }` + +|`MCPRef` +|Reference to an MCP server. +|Object +|No +|`{ name: string, namespace?: string }` + +|`LLMRef` +|Reference to an LLM provider. +|Object +|No +|`{ name: string, namespace?: string }` + +|`ConnectionRef` +|Reference to a connection. +|Object +|No +|`{ name: string }` + +|`PolicyRef` +|Reference to a policy. +|Object +|No +|`{ name: string, namespace?: string }` + +|=== + +[[context-section]] +== Context Section + +This section is for reusable entities scoped to the graphs defined in the `agent-network.yaml` file. It holds definitions that are used by the document (for example, connections, policies) but are not published to the agent registry. + +*Example* + +[source,yaml] +---- +context: + connections: + hr-system-agent: + kind: a2a + ref: + name: hr-system-agent + url: https://hr-agent.example.com/a2a + salesforce-agent: + kind: a2a + ref: + name: salesforce-agent + url: https://sfdc-agent.example.com/a2a + slack-mcp: + kind: mcp + ref: + name: slack-mcp + url: https://mcp.example.com/slack + Open-AI-LLM: + kind: llm + ref: + name: Open-AI-LLM + url: https://api.openai.com/v1 + authentication: + kind: apiKey + apiKey: "${env.OPENAI_API_KEY}" + # optional: headerName (default Authorization) + # optional: policies + policies: + retry-policy: + ref: + name: retry-policy + configuration: + maxAttempts: 3 + backoffMs: 1000 +---- + +The `context` section has these properties. + +[%header,cols="1,1,1"] +|=== +|Parameter +|Description +|Type + +|connections +|The list of connections defined as part of this network. +|Connection Objects + +|policies +|Policy definitions that govern connection behavior, access, and execution. +|Policies Object + +|=== + +[[connections]] +=== Connections + +Connection definitions live in the `context` object. Each `connections` object has a kind field that determines its connection type: either `a2a`, `llm`, or mcp. + +Connection objects have these properties. + +[%header,cols="1,1,1,1"] +|=== +|Field Name +|Description +|Type +|Required + +|`kind` +|Connection type +|`mcp`, `a2a`, `or llm` +|Yes + +|`ref` +|A reference to an asset representing the target system. +|Reference Object +|Yes + +|`url` +|The base URL of the target system. +|String +|Yes + +|`authentication` +|The authentication method to use when connecting to the target system. +|Authentication Object +|No + +|`policies` +|Array of policy identifiers to apply to this connection. +|Array[String] +|No + +|=== + +You can attach policies to connection objects by referencing their policy identifier. See the <> for field definitions. + +[[policies]] +=== Policies + +This section describes reusable, composable policy bindings and definitions that govern specific behaviors or constraints related to connections. You must reference the policy identifier to attach a policy. + +For more information about applying policies via Flex Gateway in Local Mode, see: + +* https://docs.mulesoft.com/gateway/latest/flex-agent-secure[Securing Agent Interactions with Flex Gateway] +* https://docs.mulesoft.com/gateway/latest/flex-gateway-secure-local[Applying Policies in Local Mode] + +*Example* + +[source,yaml] +---- +context: + policies: + myRateLimitPolicy: + ref: + name: myReferenceObject + configuration: + - rate: 100 + unit: minute +---- + +This section has these properties. + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|ref +|Reference to a specific policy definition. +|Object +|Yes + +|ref.name +|Name of the reference definition +|String +|Yes + +|configuration +|Policy-specific configuration (structure defined by the referenced policy definition). +|Object +|Yes + +|=== + +=== Authentication + +This section defines the authentication schemes used by the agent network for authenticating when making outbound requests. + +==== Basic Client Authentication + +HTTP Basic authentication with username and password. + +*Example* + +[source,yaml] +---- +kind: basic username: my-username password: my-password headerName: Authorization +---- + +The basic object has these properties. + +[%header,cols="1,1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Valid Values +|Required + +|kind +|The authentication method type. +|String +|basic +|Yes + +|username +|Username for authentication. +|String +|String +|Yes + +|password +|Password for authentication. +|String +|String +|Yes + +|headerName +|The name of the HTTP used for basic credentials. If not specified, Authorization is used. +|String +|String. Defaults to Authorization. +|No + +|=== + +==== API Key Client Authentication + +Authenticates outbound requests by including an API key in a configurable HTTP header. + +*Example* + +[source,yaml] +---- +kind: apiKey apiKey: my-api-key-123 headerName: Authorization +---- + +An API key passed in a header has these properties. + +[%header,cols="1,1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Valid Values +|Required + +|kind +|The authentication method type. +|String +|apiKey +|Yes + +|headerName +|The name of the HTTP header that carries the API key. If not specified, Authorization is used. +|String +|String. Defaults to Authorization. +|Yes + +|apiKey +|The header or parameter name for the API key. +|String +|String +|No + +|=== + +==== API Key Client Credentials Client Authentication + +API key client credentials with client ID and client secret objects. + +*Example* + +[source,yaml] +---- +type: apikey-client-credentials client-id: + value: my-client-id + name: client_id client-secret: + value: my-client-secret + name: client_secret +---- + +The API key client credentials object has these properties. + +[%header,cols="1,1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Valid Values +|Required + +|kind +|The authentication method type. +|String +|apikey-client-credentials +|Yes + +|clientId +|Description of the client ID to be used. +|Object +|Object with value and optional name (default header name is client_id). +|Yes + +|clientId.value +|The value for the client ID. +|String +|String +|Yes + +|clientId.name +|The header or parameter name. +|String +|String +|No + +|clientSecret +|Description of the client secret to be used. +|Object +|Object with value and optional name (default header name is client_secret). +|No + +|clientSecret.value +|The value for the client secret. +|String +|String +|Yes + +|clientSecret.name +|The header or parameter name. +|String +|String +|No + +|=== + +==== OAuth 2.0 Client Credentials Grant Client Authentication + +OAuth 2.0 authentication using the Client Credentials Grant Type. Allows agents to obtain access tokens using a client ID and client secret from the token provider. + +*Example* + +[source,yaml] +---- +kind: oauth2-client-credentials clientId: my-client-id clientSecret: my-client-secret token: + url: https://my-oauth2-provider.com/token + timeout: 15 + bodyEncoding: form scopes: + - my.custom.scope + - another.scope +---- + +The oauth2-client-credentials object has these properties. + +[%header,cols="1,1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Valid Values +|Required + +|kind +|The authentication method type. +|String +|oauth2-client-credentials +|Yes + +|clientId +|The client ID to authenticate with the OAuth2 provider. +|String +|String +|Yes + +|clientSecret +|The client secret used with client ID. +|String +|String +|Yes + +|token +|Configuration for how to fetch the token. +|Object +|Token object +|Yes + +|token.url +|The URL of the token provider (token endpoint). +|String +|Valid URL string +|Yes + +|token.timeout +|Time in seconds to wait for the token service to respond. +|Number +|Any number +|No + +|token.bodyEncoding +|Content encoding for the request body. (`form = application/x-www-form-urlencoded`, `json = application/json`) +|String +|`form` or `json` +|No + +|scopes +|Array of scopes to request during token retrieval. +|Array +|Array of scope strings. Defaults to [] +|No + +|=== + +==== In-Task Authorization Code + +Use in-task authorization code when the connection needs secondary credentials obtained during a task using the OAuth 2.0 Authorization Code flow. OAuth2 tokens are extracted from message data and injected into the Authorization header for upstream calls. This supports step-up or in-task authentication (for example, when a user must re-authenticate for a sensitive action). For more information about the associated policy, see xref:gateway::policies-outbound-a2a-intask-authorization-code.adoc[]. + +*Example* + +[source,yaml] +---- +authentication: + kind: in-task-authorization-code + secondaryAuthProvider: providerName + authorizationEndpoint: https://oauth.provider.com/authorize + tokenEndpoint: https://oauth.provider.com/token + scopes: Read + redirectUri: https://oauth.provider.com/callback + responseType: code + tokenAudience: https://api.example.com/agents/my-agent + codeChallengeMethod: S256 + bodyEncoding: form + challengeResponseStatusCode: 200 + tokenTimeout: 300 +---- + +The in-task-authorization-code authentication has these properties. + +[%header,cols="1,1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Valid Values +|Required + +|kind +|Authentication type. +|String +|in-task-authorization-code +|Yes + +|authorizationEndpoint +|OAuth2 authorization endpoint URL. Used to generate the authentication challenge. +|String +|Valid URL +|Yes + +|tokenEndpoint +|OAuth2 token endpoint URL. Used to generate the authentication challenge. +|String +|Valid URL +|Yes + +|scopes +|OAuth2 scopes required for step-up authentication. +|String +|Space- or comma-separated scope list (for example, openid profile email) +|Yes + +|redirectUri +|OAuth2 redirect URI the client uses in the authorization flow. +|String +|Valid URI +|Yes + +|secondaryAuthProvider +|Name of the IdP (for example, okta, auth0). Informational only, for the authentication card. +|String +|Any string +|No + +|responseType +|OAuth2 response type. +|String +|Typically code. Default: code +|No + +|codeChallengeMethod +|PKCE code challenge method. +|String +|Typically S256. Default: S256 +|No + +|tokenAudience +|Intended recipient of the token (for example, agent1 or API URL). +|String +|Any string +|No + +|bodyEncoding +|Encoding for the token request body. +|String +|form, json. Default: form +|No + +|tokenTimeout +|Timeout in seconds for token requests. +|Integer +|Positive integer. Default: 300 +|No + +|challengeResponseStatusCode +|HTTP status code returned for auth-required challenge responses. Typically 200 for JSON-RPC compatibility. +|Integer +|HTTP status code. Default: 200 +|No + +|=== + +==== OAuth 2.0 OBO Credential Injection + +This authentication type supports OAuth 2.0 Token Exchange and Microsoft Entra ID On-Behalf-Of protocols. For more information about the associated policy, see xref:gateway::policies-outbound-oauth-obo.adoc[]. + +*Using OAuth 2.0 Token Exchange* + +[source,yaml] +---- +authentication: + kind: oauth2-obo + flow: oauth2-token-exchange + tokenEndpoint: https://oauth.provider.com/token + clientId: clientId + clientSecret: clientSecret + targetType: audience + targetValue: https://api.example.com/agents/my-agent + scope: Read #optional, OAuth 2.0 scope to request. Required for Microsoft Entra OBO (for example, api://downstream-client-id/.default). Optional for OAuth 2.0 Token Exchange (RFC 8693). + timeout: 5000 +---- + +*Using Microsoft Entra ID On-Behalf-Of* + +[source,yaml] +---- +authentication: + kind: oauth2-obo + flow: microsoft-entra-obo + tokenEndpoint: https://oauth.provider.com/token + clientId: clientId + clientSecret: clientSecret + scope: api://downstream-client-id/.default + timeout: 5000 +---- + +The `oauth2-obo` authentication has these properties. + +[%header,cols="1,1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Valid Values +|Required + +|kind +|Authentication type. +|String +|oauth2-obo +|Yes + +|flow +|Token exchange flow type. +|String +|oauth2-token-exchange, microsoft-entra-obo +|Yes + +|clientId +|OAuth2 client ID for token exchange. +|String +|String +|Yes + +|clientSecret +|OAuth2 client secret for token exchange. +|String +|String +|Yes + +|tokenEndpoint +|OAuth2 token endpoint URL for token exchange. +|String +|Valid URL +|Yes + +|targetType +|Parameter type for specifying the target service (audience for logical name, resource for physical URI). Used for OAuth 2.0 Token Exchange. +|String +|audience, resource. Default: audience +|No + +|targetValue +|Target audience URI or resource URI for the exchanged token. Required for OAuth 2.0 Token Exchange. +|String +|Valid URI +|Required when using oauth2-token-exchange with a target + +|scope +|OAuth scope to request. Required for Microsoft Entra OBO (for example, api://downstream-client-id/.default). Optional for OAuth 2.0 Token Exchange. +|String +|String +|Required for microsoft-entra-obo + +|timeout +|Timeout for token exchange requests in milliseconds. +|Integer +|Positive integer. Default: 10000 +|No + +|cibaEnabled +|When `true`, it uses Client Initiated Backchannel Authentication (CIBA) instead of standard OBO token exchange. Only valid when `flow` is `oauth2-token-exchange`. +|Boolean +|`true` or `false`. Default: `false` +|No + +|cibaEndpoint +|Backchannel authorization (`bc-authorize`) endpoint URL for CIBA. +|String +|Valid URL +|No + +|cibaLoginHintClaim +|JWT claim from the subject token to send as the CIBA `login_hint` (for example, `email,` `sub`). +|String +|String. Default: `email` +|No + +|cibaBindingMessage +|Optional message shown on the user's authentication device during CIBA approval. +|String +|String +|No + +|=== + +[[brokers-section]] +== Brokers Section + +Use this section to define brokers that orchestrate and control the flow of agent and tool invocations. Each broker object maps to an `.agent` file. You can have multiple Agent Script files in your `/brokers` directory. + +*Example* + +[source,yaml] +---- +brokers: + customerServiceAgent: + kind: AgentScript + implementation: ./brokers/customer-service.agent + interfaces: + a2a: + card: ... + policies: + inbound: + - ref: + name: rate-limit-policy + billingAgent: + kind: AgentScript + implementation: ./brokers/billing-handler.agent + interfaces: + a2a: + card: ... +---- + +The `brokers` section has these properties. + +[%header,cols="1,1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required +|Values + +|`_(broker id)_` +|Named broker definition. +|Object +|No +|Keys: identifiers matching ^[a-zA-Z_][a-zA-Z0-9_.-]*$. Values: broker entity (BrokerEntity in agent_network_v2.json) + +|`kind` +|The type of agent implementation. +|String +|Yes +|`AgentScript` + +|`implementation` +|The path to the Agent Script implementation file. +|String +|Yes +|-- + +|`interfaces` +|Exposed interfaces for this broker. +|Object +|Yes +|`a2a` + +|=== + +=== interfaces.a2a + +The `a2a` interface defines how external clients interact with a broker through the Agent2Agent protocol. It contains the broker's agent card and any inbound or outbound policy bindings. + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|`card` +|The A2A agent card. See <>. +|AgentCard +|No + +|`policies` +|Inbound and outbound policy binding lists for this interface. +|Object +|No + +|`policies.inbound` +|Policy bindings for inbound traffic. +|Array +|No + +|`policies.outbound` +|Policy bindings for outbound traffic. +|Array +|No + +|=== + +Each inbound or outbound policy requires either a reference or inline policy binding. + +==== Policy Binding Reference + +Use a policy binding reference to attach a previously declared policy to a broker interface by name. + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|`ref.name` +|Name of the declared policy binding. See <>. +|String +|Yes + +|=== + +==== Inline Policy Binding + +Use an inline policy binding to define a policy directly on the broker interface without declaring it elsewhere first. + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|`policy` +|The policy to be applied. +|Object +|Yes + +|`policy.ref` +|Reference to the policy definition. +|PolicyRef See <>. +|Yes + +|`policy.configuration` +|Policy-specific configuration. +|Object +|Yes + +|=== + +[[expressions-format]] +== Expressions Format + +Use Python expressions to resolve or calculate values that are only available at runtime. + +Enclose expressions using the {{}} evaluation wrapper. You can also use multiline statements using the https://yaml.org/spec/1.2.2/#54-line-break-characters[appropriate YAML syntax]. + +*Example* + +[source,yaml] +---- +- reasoning: + id: welcome-message + description: "Send a welcome message to the candidate." + llm: my-primary-llm + prompt: "Extract the email from {{input}} and send a greeting email to the user saying their onboarding process has started" + tools: + - ref: my-email-tool +---- + +Expressions have these properties. + +[%header,cols="1,1,1,1"] +|=== +|Variable Name +|Description +|Type +|Required + +|input +|Payload or parameters provided as input to the node. +|Type defined by Graph +|Yes + +|variables +|A mutable key-value store for variables scoped to the execution of the graph instance. +|Dict[string, any] +|Yes + +|{node-ids} +|Read-only mapping of all node definitions available in the current graph, indexed by node id. +|Dict[string, Object] +|Yes + +|=== + +{node-ids} have these properties. + +[%header,cols="1,1,1,1"] +|=== +|Variable Name +|Type +|Description +|Required + +|input +|Type defined by Graph +|Input to the node as it happened. +|Yes + +|output +|Type defined by Graph +|Output provided by the node as it happened +|Yes + +|=== + +[[exchange-json-file]] +== Exchange.JSON File + +All agent network projects have an `exchange.json` file. This file contains asset metadata available in Anypoint Exchange after publishing your agent network assets. + +*Example* + +[source,json] +---- +{ + "main": "agent-network.yaml", + "name": "Employee Onboarding Network", + "classifier": "agentic-network", + "organizationId": "85de5a54-1f33-4ea4-a1bf-8a65bc409179", + "descriptorVersion": "1.0.0", + "tags": [], + "groupId": "85de5a54-1f33-4ea4-a1bf-8a65bc409179", + "assetId": "employee-onboarding-network", + "version": "1.0.5", + "dependencies": [ + { + "groupId": "85de5a54-1f33-4ea4-a1bf-8a65bc409179", + "assetId": "hr-agent", + "version": "1.0.21", + "classifier": "agent-metadata", + "packaging": "zip" + } + ], + "metadata": { + "variables": { + "openai": { + "clientId": { + "description": "OpenAI LLM Client ID", + "default": "" + }, + "clientSecret": { + "description": "OpenAI LLM Client Secret", + "default": "", + "secret": true + }, + "url": { + "description": "OpenAI URL", + "default": "", + "secret": false + } + } + } + } +} +---- + +These key-value pairs are important for your agent network configuration: + +* groupId: ID of the Anypoint business group that owns your agent network and all the assets derived from it. +* assetId: Unique identifier for the agent network project. +* dependencies: Existing assets that this network needs to reference. +* variables: Nested in the metadata section, defines all the variables whose values shouldn't be hardcoded in the `agent-network.yaml` file. Enter these values when publishing the agent network. Each variable has a description value, a default value, and a secret value that indicates whether it's treated as sensitive or not. diff --git a/agent-network/2.0/modules/ROOT/pages/af-agent-networks.adoc b/agent-network/2.0/modules/ROOT/pages/af-agent-networks.adoc new file mode 100644 index 000000000..17cdbc740 --- /dev/null +++ b/agent-network/2.0/modules/ROOT/pages/af-agent-networks.adoc @@ -0,0 +1,230 @@ += Building Agent Networks for Agent Fabric +:page-aliases: anypoint-code-builder::af-agent-networks.adoc + +An agent network is a coordinated group of agents, brokers, LLMs, and MCP servers that acts as a central hub for defining, validating, and executing agentic processes across your enterprise. + +An agent network provides the building blocks of your agentic deployment while MuleSoft Agent Fabric helps you maximize the potential of every AI agent with centralized discovery, orchestration across agents and tools, cross-ecosystem governance, and full transparency into agentic interactions. + +You define your agent network in a simple, human-readable YAML file in Anypoint Code Builder. This approach abstracts away the underlying technical complexities, allowing you to focus on the business constraints and context of your process without needing to understand the inner workings of the orchestration engine. + +At the start of a new agent network project, we provide a YAML template and Agent Script file to give you a head start. You can use MuleSoft Vibes to configure your network, publish the assets to Anypoint Exchange, and deploy your agent network instance. + +[[key-benefits]] +== Key Benefits of Agent Networks + +Create robust, automated agent networks with these key benefits. + +* Simplified Development ++ +Define your agent processes in an intentional way using a simple YAML file, which is easier and faster than writing complex code. +* Safety and Governance ++ +Ensure control and compliance across every agent and tool interaction with enterprise-grade governance. +* Observability ++ +Gain insight into agent actions with a visual trace of their decision-making. +* Flexibility ++ +Coordinate any type of agent and tool, regardless of where it's built and deployed so you can build a diverse network of agents. +* Tool and Agent Invocation ++ +Manage the invocation of both deterministic (tool-based) and probabilistic (LLM-based) actions. + +[[hybrid-determinism]] +== The Hybrid Determinism Pattern + +Brokers in Agent Network 2.0 architecture leverage a hybrid deterministic approach by separating steps requiring probabilistic LLM reasoning from those requiring deterministic control-flow logic. + +* Probabilistic (LLM-based) nodes handle complex, open-ended decisions that require nuanced judgment, such as classification or AI-powered thinking. +* Deterministic nodes manage all remaining predefined execution paths, ensuring a fixed and guaranteed workflow once a key probabilistic judgment has been finalized. + +This structure allows brokers to apply high-level LLM intelligence where complex judgment is needed, while the overall agent graph maintains reliable, rule-based predictability across the operational flow. + +[[agent-network-components]] +== Agent Network Components + +An agent network is a collection of agents, brokers, LLMs, and MCP servers that are connected to each other. Agent networks use LLMs for reasoning and planning capabilities and integrate with Anypoint Connector for MCP (Model Context Protocol) and Anypoint Connector for Agent2Agent (A2A) communication. + +Broker:: +An intelligent routing service that coordinates task delegation across A2A-compliant agents in your enterprise. +You define a broker and its nodes in Agent Script. +Nodes are connected in a graph that encapsulates all steps that describe the orchestration of agents, tools, and large language models. +A graph-based approach to agent brokers ensures that connected paths guarantee a specific order of operations and enable more complex orchestration that combines deterministic and non-deterministic elements. ++ +After you publish your agent network, brokers appear as specialized agents in Anypoint Exchange and can be reused by other brokers. ++ +A broker graph is composed of these elements: ++ +Nodes::: +Each "step" within a graph. Nodes can be used to orchestrate actions with LLM-powered reasoning or perform deterministic actions like routing. +Trigger::: +An entry point into a graph. Triggers specify events, calls, or messages that execute workflows. All graphs must start on an A2A trigger. +Edges::: +Transitions from node to node. Input data enters the node and output data exits the node. + +Agent:: +An autonomous software component that uses goals, context, and available tools, often via a large language model (LLM), to decide and execute actions on behalf of a user or system. ++ +Agents can be defined either locally in the agent network or externally in a different agent network or elsewhere in your company. +Your agent network can use both locally defined and externally defined agents to complete tasks. ++ +include::partial$af-shared.adoc[tags="agent-support"] + +MCP server:: +A service that implements the Model Context Protocol (MCP) to expose tools and data to AI clients, enabling LLMs to invoke external capabilities through a standard interface. ++ +MCP servers can be defined either locally in the agent network or externally in a different agent network or elsewhere in your company. +Your agent network can use both locally defined and externally defined MCP servers to complete tasks. + +Registry:: +A section within an agent network project that defines the assets, connections, and policies necessary to build, execute, and govern a broker. +Assets defined in this section of an agent network file are published to Exchange and become reusable. +You can also reference existing assets from Exchange in a graph without needing to define them in the registry section. + +[[yaml-and-agent-script]] +== Agent Network YAML and Agent Script + +An agent network project defines a structured configuration for multi-agent systems, enabling orchestration of AI agents with external services, tools, and inter-agent communication. This format provides a declarative way to define agent capabilities, dependencies, and service integrations. + +An agent network project includes these files: + +---- +/my-agent-network-project + - exchange.json + - agent-network.yaml + /brokers + - broker1.agent +---- + +* `exchange.json`: Contains asset metadata available in Anypoint Exchange after publishing your agent network assets. +* `agent-network.yaml`: Contains a registry section that defines Exchange assets used in your project and a context section that defines connections and policies for the project. +* `.agent` files: Contain broker and node definitions and configurations that enable multi-agent orchestration in your project. + +For more information, see xref:af-project-files.adoc[]. + +NOTE: For a complete, working example you can use as a starting point for your own agent network project, see xref:af-example-it-investigation-broker.adoc[Example: Building an IT Investigation Broker]. The example walks through a fully configured `agent-network.yaml`, `exchange.json`, and `/brokers` directory that you can adapt to your own project. + +[[agent-network-architecture]] +== Agent Network Architecture + +This diagram shows an agent network deployed to a shared space in CloudHub 2 using a single mni Gateway for ingress and egress. The network includes agents and MCP servers and is observed in Anypoint Monitoring. + +image::agent-fabric-architecture-v2-shared-space.png[an agent network deployed to a shared space in CloudHub 2 using a single mni Gateway for ingress and egress. The network includes agents and MCP servers and is observed in Anypoint Monitoring] + +[calloutlist] +. Publish the agentic assets to Anypoint Exchange for discovery and reuse after you define the agent network (brokers, agents, MCP servers) in the agent network YAML in Anypoint Code Builder. +. Deploy the agentic assets to CloudHub 2.0 (managed in Runtime Manager). +. Enforce policies, manage connections, and emit telemetry through a single Omni Gateway that handles both ingress to brokers/API endpoints and egress to external agents and services. ++ +NOTE: In a private space using a two-gateway configuration, policies, traffic, and data are handled by separate ingress and egress Omni Gateways. + +. Collect logs, metrics, and traces from Omni Gateway and runtimes in Anypoint Monitoring. + +[[exchange-assets]] +== Agent Network Assets in Anypoint Exchange + +The following agent network asset types are supported in Exchange: + +Agent Network:: +An agent network project is published in Exchange as an Agent Network asset. The asset is a .zip file that contains all project files. To learn more, see <> or xref:af-project-files.adoc[]. + +Agents:: +Programs that perform tasks autonomously or semiautonomously. AI agents use the Agent2Agent (A2A) protocol to communicate and collaborate with each other to perform tasks. ++ +When you publish agent network projects to Exchange, the individual agentic assets defined in the agent network project file are registered as either agents or MCP servers. Brokers are published with the agent asset type and are automatically tagged as brokers for easy identification. + +LLMs (Large Language Models):: +AI assets for processing, understanding, and generating human-readable language. Agent network projects support <>. The LLM asset type defines only the provider and contract information. You define the model and connectivity details in the agent network file. + +MCP Servers:: +Applications or APIs exposed through the Model Context Protocol (MCP). MCP is an open protocol designed to standardize how applications provide context and capabilities to LLMs and AI agents. In the agent network file, MCP server assets are defined as `Tools`. + +[[llm-support]] +== Large Language Models + +Agent network brokers support the latest Gemini and OpenAI models and LLM Proxies. + +* Azure OpenAI and OpenAI API: ++ +** GPT-5.2 +** GPT-5.2 Pro +** GPT-5-mini +** GPT-5 nano +** GPT-5 ++ +For more information about these models, see the https://developers.openai.com/api/docs/models[OpenAI] documentation. +* Gemini API: ++ +** Gemini 2.5 Pro +** Gemini 2.5 Flash-Lite +** Gemini 2.5 Flash +** Gemini 3 Flash +** Gemini 3 Pro ++ +For more information about these models, see the https://ai.google.dev/gemini-api/docs/models[Gemini] documentation. + +* LLM Proxy: ++ +LLM Proxy provides a unified endpoint for multiple LLM providers including Gemini, OpenAI, Bedrock (Anthropic Claude models), and NVIDIA Nemotron. To find the supported models, see xref:gateway::flex-gateway-llm-proxy.adoc#supported-llm-providers[LLM Proxy Supported LLM Providers]. + +This table details the requirements and recommended models. + +|=== +|*Model Provider* |*Required Endpoint* |*Required Capabilities* |*Suggested Models* + +|OpenAI |`/responses` a| +* Reasoning +* Native structured output +* Function and custom tool calling +a| +* For lower latency: GPT-5-mini +* For complex reasoning: Evaluate models + +|Gemini |`/generateContent` (Native API) a| +* Native Thinking (via thinkingBudget and thinkingLevel) +* Native structured output (responseSchema) +* Function and custom tool calling +a| +* For lower latency: Gemini 2.5 Flash, Gemini 2.5 Flash-Lite +* For complex reasoning: Gemini 3 Pro (Deep Think capabilities) +|=== + +Agent networks support text-based messages and responses. Image and binary message types aren't supported. + +For configuration options, see the xref:af-agent-script-reference.adoc#llm-section[LLM Section] of the Agent Script file reference. + +[[a2a-protocol]] +== A2A Protocol + +The Agent2Agent (A2A) Protocol governs agent-to-agent communication. This protocol powers orchestration, observability, and governance features in agent networks. MuleSoft supports v1.0 of the A2A Protocol Specification. + +=== Context and Task ID Scoping in Agent Networks + +In MuleSoft agent networks, the brokers receiving a request always generate a `contextId` and `taskId`. These IDs define the state and scope of a specific conversation between two agents. A `taskId` is always matched to a `contextId`, but a `contextId` can exist without a `taskId`. + +In a multi-agent network, a client sends a request to Broker_1 and Broker_1 generates the necessary IDs for that request. When Broker_1 sends a new request to the next broker or non-broker agent in line, that broker or non-broker agent establishes a unique `contextId` and `taskId` for the new request. + +NOTE: It is not mandatory for non-broker agents to generate a `contextId` and `taskId` when receiving requests from a client. + +Consider a network with a client and two brokers (1 and 2). + +* The IDs used between the client and Broker_1 are independent of the IDs used between Broker_1 and Broker_2. +* When Broker_1 delegates a task to Broker_2, Broker_2 (acting as a server) generates its own `contextId` and `taskId`. +* Broker_1 is responsible for maintaining a mapping between its own upstream `taskId` (used to respond to its client) and the downstream `taskId` it's tracking with Broker_2. +* If Broker_2 requires more information (if it returns `status: input-required`), it provides a `contextId` and `taskId` to Broker_1. Broker_1 uses these IDs to provide the requested input to Broker_2. The client never sees Broker_2's internal IDs. + +[cols="1,1,1", options="header"] +|=== +| Relationship | Role | Logic +| Client -> Broker_1 | Broker_1 is server | Generates `contextId_1` and `taskId_1` for the client. +| Agent A -> Broker_2 | Broker_2 is server | Generates `contextId_2` and `taskId_2` for Broker_1. +| Network broker | Broker_1 | Broker_1 maps `contextId_1` and `taskId_1` to `contextId_2` and `taskId_2`. +|=== + +For more information, see https://a2a-protocol.org/latest/topics/life-of-a-task/[Life of a Task - Group Related Interactions]. + +NOTE: Agent networks don't support streaming with Server-Sent Events (SSE). + +== See Also + +* xref:af-get-started.adoc[] diff --git a/agent-network/2.0/modules/ROOT/pages/af-agent-script-reference.adoc b/agent-network/2.0/modules/ROOT/pages/af-agent-script-reference.adoc new file mode 100644 index 000000000..c496e2bad --- /dev/null +++ b/agent-network/2.0/modules/ROOT/pages/af-agent-script-reference.adoc @@ -0,0 +1,1126 @@ +[[agent-script-reference]] += Agent Script Reference + +After you configure the assets and other elements of your agent network project, you build the rest of the workflow using Agent Script. Agent Script enables you to build predictable, context-aware agent workflows that don't rely solely on interpretation by an LLM. + +* <> +* <> +* <> +* <> +* <> +* <> + +[[agent-script-structure]] +== Agent Script Structure + +The following sections explain settings and configurations specific to MuleSoft agent network projects. To learn more about Agent Script, see the https://developer.salesforce.com/docs/ai/agentforce/guide/agent-script.html[Agent Script documentation]. + +=== Dialect Referencing and Versioning + +Agent Script files contain a header specifying the dialect and a version binding. SEMVER major and minor are used for fixing to a specific dialect version. + +The dialect header specifies that the script is strictly bound to a specific version or later of the AGENTFABRIC dialect. Deploying an agent to a runtime that doesn't support this version results in an error. + +* Using major.minor (for example, `AGENTFABRIC=1.1`) binds to version 1.1 or later +* Using major only (for example, `AGENTFABRIC=1`) references the latest version within that major version + +*Example* + +[source,yaml] +---- +# @dialect: AGENTFABRIC=1.0 +---- + +=== System Section + +This section defines the `instructions` attribute, which acts as a default system prompt that will be used whenever an agentic node doesn't define a `system.instructions` of its own. + +*Example* + +[source,yaml] +---- +system: + instructions: "You are the onboarding agent" +---- + +The system section has these parameters. + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|`instructions` +|Default system prompt used when an agentic node doesn't define its own `system.instructions`. +|String +|Yes + +|=== + +=== Agent Config Section + +The config section is the standard Agent Script config section, with the addition of the optional `default_llm` field. This section defines metadata and default settings for the agent. + +*Example* + +[source,yaml] +---- +config: + agent_name: "employee-onboarding" + label: "Employee Onboarding Agent" + description: "An Agent that performs employee onboarding" +---- + +The config section has these parameters. + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|`agent_name` +|The name identifier for the agent. +|String +|- + +|`label` +|A human-readable display name for the agent. +|String +|- + +|`description` +|A description of what the agent does. +|String +|- + +|`default_llm` +|Specifies a default LLM to be used on all agentic nodes that don't specify otherwise. +|@llm reference See <> +|No + +|=== + +[[llm-section]] +=== LLM Section + +The `llm` element is where you define the LLMs to use for reasoning and generation. Each `target` must use the `llm://` URI scheme so the runtime binds to the correct governed connection. + +*Example* + +[source,yaml] +---- +llm: + open-api-llm: + target: "llm://open_ai_connection" + kind: "OpenAI" + model: "gpt5-mini" + reasoning_effort: "LOW" + gemini-llm: + target: "llm://gemini_connection" + kind: "Gemini" + model: "gemini-3-flash-preview" + thinking_level: "HIGH" + top_p: 0.3 +---- + +==== LLM Configuration: OpenAI + +The OpenAI configuration has these properties. + +The OpenAI default URL is https://api.openai.com/v1. + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|`target` +|Governed LLM connection as a URI; must use the `llm://` scheme +|URI (`llm://...`) +|Yes + +|`kind` +|Discriminator for the LLM provider; selects which provider-specific attributes apply +|String, `OpenAI` +|Yes + +|`model` +|The name of the model to use +|String +|Yes + +|`reasoning_effort` +|Constrains effort on reasoning for reasoning models. gpt-5.1 defaults to NONE, previous ones default to MEDIUM +|enum['NONE', 'MINIMAL', 'LOW', 'MEDIUM', 'HIGH'] +|No + +|`temperature` +|Controls randomness in the output +|number +|No + +|`top_p` +|Nucleus sampling parameter +|number +|No + +|`top_logprobs` +|Number of most likely tokens to return at each position +|integer +|No + +|`max_output_tokens` +|Maximum number of tokens to generate +|integer +|No + +|=== + +==== LLM Configuration: Gemini + +The Gemini configuration has these properties. + +The default Gemini URL is https://generativelanguage.googleapis.com. + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|`target` +|Governed LLM connection as a URI; must use the `llm://` scheme +|URI (`llm://...`) +|Yes + +|`kind` +|Discriminator for the LLM provider; selects which provider-specific attributes apply +|String, `Gemini` +|Yes + +|`model` +|The name of the model to use +|String +|Yes + +|`thinking_level` +|The level of thoughts tokens that the model should generate +|Enum['LOW', 'HIGH'] +|No + +|`thinking_budget` +|Indicates the thinking budget in tokens. 0 is DISABLED. -1 is AUTOMATIC. The default values and allowed ranges are model dependent +|Number +|No + +|`temperature` +|Controls the degree of randomness in token selection. Lower temperatures are good for prompts that require a less open-ended or creative response, while higher temperatures can lead to more diverse or creative results +|Number +|No + +|`top_p` +|Tokens are selected from the most to least probable until the sum of their probabilities equals this value. Use a lower value for less random responses and a higher value for more random responses +|Number +|No + +|`response_logprobs` +|Whether to return the log probabilities of the tokens that were chosen by the model at each step +|Boolean +|No + +|`max_output_tokens` +|Maximum number of tokens that can be generated in the response +|Integer +|No + +|=== + +=== Action Definitions + +You define A2A and MCP actions in Agent Script under the top-level `actions` block. Each action `target` uses a URI whose scheme is the underlying protocol (for example `a2a://` or `mcp://`), so the runtime can route the connection correctly. + +==== A2A Actions + +A2A actions execute the `message/send` A2A method and do not specify inputs or outputs. + +*Example* + +[source,yaml] +---- +actions: + hr_agent: + target: "a2a://hr_agent_connection" + kind: "a2a:send_message" +---- + +A2A actions have these properties. + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|`target` +|Governed A2A connection as a URI; must use the `a2a://` scheme +|URI (`a2a://...`) +|Yes + +|`kind` +|Indicates that this executes the message/send A2A method. +|"a2a:send_message" +|Yes + +|=== + +==== MCP Actions + +MCP actions invoke Model Context Protocol actions with optional input binding. + +*Example* + +[source,yaml] +---- +actions: + send_slack_message: + target: "mcp://slack_mcp_connection" + kind: "mcp:tool" + tool_name: "send-message" + inputs: + channel: string = "my-default-channel" + message: string +---- + +MCP actions have these properties. + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|`target` +|Governed MCP connection as a URI; must use the `mcp://` scheme +|URI (`mcp://...`) +|Yes + +|`kind` +|Constant indicating this will invoke an MCP tool +|"mcp:tool" +|Yes + +|`tool_name` +|The name of the tool to call +|String +|Yes + +|`inputs` +|Define bindable arguments. Input arguments provided are not exhaustive. The tool will auto-discover additional arguments and consider them in slot filling mode. +|Object +|No + +|=== + +=== A2A Trigger + +Triggers reference one of the interfaces defined for a broker in the agent network. Each broker must have one--and only one--trigger per each interface declared in its agent network. + +The A2A trigger reacts to send/message methods and automatically manages the task history, context ID and task IDs. The trigger also responds to various A2A protocol methods. + +* https://a2a-protocol.org/latest/specification/#313-get-task[Get Task] +* https://a2a-protocol.org/latest/specification/#314-list-tasks[List Tasks] +* https://a2a-protocol.org/latest/specification/#315-cancel-task[Cancel Task] +* https://a2a-protocol.org/latest/specification/#316-subscribe-to-task[Subscribe to Task] +* https://a2a-protocol.org/latest/specification/#317-create-push-notification-config[Create Push Notification Config] +* https://a2a-protocol.org/latest/specification/#318-get-push-notification-config[Get Push Notification Config] +* https://a2a-protocol.org/latest/specification/#319-list-push-notification-configs[List Push Notification Config] +* https://a2a-protocol.org/latest/specification/#3110-delete-push-notification-config[Delete Push Notification Config] +* https://a2a-protocol.org/latest/specification/#3111-get-extended-agent-card[Get Extended Agent Card] + +*Example* + +[source,yaml] +---- +trigger employeeOnboardingTrigger: + kind: "a2a" + target: "brokers://employee-onboarding/a2a" + on_message: -> transition to @orchestrator.hrSystemOnboard +---- + +The A2A trigger has these properties. + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|`kind` +|Value that indicates this is an A2A trigger. +|`"a2a"` +|Yes + +|`target` +|Broker interface entry point. Must use the `brokers://` URI form: `brokers:///` +|URI (`brokers://...`) +|Yes + +|`on_message` +|Procedure that executes when the A2A interface receives a new `message/send` request. Must define a transition to the workflow's initial node. +|Procedure +|Yes + +|=== + +[[node-types]] +== Node Types + +Agent network and Agent Script support these node types. + +=== Subagent Node + +This node defines a generic agent loop node, made of a prompt and a set of actions. Because it can use actions and supports human-in-the-loop flows, this node is ideal for implementing patterns like classification, semantic routing, or LLM reasoning. + +*Example* + +[source,yaml] +---- +- subagent profile-extractor: + description: "Extracts structured user profile data from text" + reasoning: + instructions: -> Extract the following information from the user's message: {!@request.payload.message.parts[0].text} + outputs: + properties: + name: + type: "string" + description: "Full name of the person" + minLength: 1 + email: + type: "string" + description: "Email address" + pattern: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$" + age: + type: "integer" + description: "Person's age" + minimum: 0 + maximum: 150 + preferences: + type: "object" + description: "User preferences" + properties: + newsletter: + type: "boolean" + description: "Whether user wants newsletter" + default: "false" + category: + type: "string" + description: "Preferred category" + enum: + - "tech" + - "business" + - "sports" + tags: + type: "array" + description: "Interest tags" + items: + type: "string" + minItems: 1 + maxItems: 10 + on_exit: -> transition to @orchestrator.process_profile +---- + +The subagent node has these properties. + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|`id` +|The node identifier, defined next to the node type. +|String +|Yes + +|`label` +|An optional short, human-readable display name for the node. +|String +|No + +|`description` +|A CommonMark string providing a description of the node. +|String +|No + +|`on_exit` +|A procedure that executes when the node execution finishes. If `on_exit` is not defined, the graph ends when the agentic node loop ends. +|Procedure, but only `transition_to` statements are allowed. +|No + +|`llm` +|Overrides the default LLM setting +|@llm reference See <> +|No + +|`system.instructions` +|Overrides the global `system.instructions` at the file root level +|String +|No + +|`reasoning.instructions` +|Session-specific query or instructions for this particular node, typically containing user provided or user related context +|String +|Yes + +|`reasoning.actions` +|The available actions +|Array[actions] +|No + +|`reasoning.outputs` +|Schema definition describing the expected structure of the agent's output +|Outputs See <> +|No + +|`reasoning.max_number_of_loops` +|The maximum number of loops an execution can take. Useful for keeping it from running too long and consuming too many tokens. Default: 25 +|Integer +|No + +|`outputs` +|A schema definition for the agentic output. +|Object See <> +|No + +|=== + +=== Orchestrator Node + +The orchestrator node is a specialization of the subagent node used for orchestrating multiple agents and MCP servers to achieve a specified goal. It is optimized for multi-agent orchestration. Use this node type for workflows that need to call multiple external agents or actions to achieve a goal. + +*Example* + +[source,yaml] +---- +orchestrator flight-booking-agent: + description: books flights by looking for the best offer across approved partners + system: + instructions: "You are a flight booking agent. The process for flight booking is: 1. Ask the user for a destination and travel dates and present them with matching alternatives using available actions. 2. Allow the user to change or refine the search. 3. Once the user selects a flight, book it using the concur agent tool." + reasoning: + instructions: -> @request.payload.message.parts[0].text + actions: + search-flight: @actions.search-flight with companyId = @variables.companyId + get-flight-info: @actions.get-flight-info + concur: @actions.concur-agent with http_headers = {"Authorization": @request.headers["Authorization"]} + outputs: + properties: + flightNumber: + type: "string" + description: "The flight identification number" + airline: + type: "string" + description: "The airline name" + max_number_of_loops: 10 + task_timeout_secs: 60 + on_exit: -> transition to @executor.send_summary +---- + +The orchestrator node has these properties. + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|`id` +|The node identifier, defined next to the node type. +|String +|Yes + +|`label` +|An optional short, human-readable display name for the node. +|String +|No + +|`description` +|A CommonMark string providing a description of the node. +|String +|No + +|`on_exit` +|A procedure that executes when the node execution finishes. If `on_exit` is not defined, the graph ends when the agentic node loop ends. +|Procedure, but only `transition_to` statements are allowed. +|No + +|`llm` +|Overrides the default LLM setting +|@llm reference See <> +|No + +|`system.instructions` +|Overrides the global `system.instructions` at the file root level +|String +|No + +|`reasoning.instructions` +|Session-specific query or instructions for this particular node, typically containing user provided or user related context +|String +|Yes + +|`reasoning.actions` +|The available actions +|Array[actions] +|No + +|`reasoning.outputs` +|Schema definition describing the expected structure of the agent's output +|Outputs See <> +|No + +|`reasoning.max_number_of_loops` +|The maximum number of loops an execution can take. Useful for keeping it from running too long and consuming too many tokens. Default: 25 +|Integer +|No + +|`outputs` +|A schema definition for the agentic output. +|Object See <> +|No + +|=== + +=== Generator Node + +The generator node calls an LLM to generate text. It is not an agent loop, and it does not support human-in-the-loop learning or other actions. It performs exactly one LLM call. Use this node for summarization, formatting, or templated text generation. + +*Example* + +[source,yaml] +---- +generator summarize-report: + description: "Generate a one-paragraph summary of the report." + prompt: "Summarize the following in one paragraph: {!@variables.report}" + on_exit: -> transition to ... +---- + +The generator node has these properties. + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|`id` +|The node identifier, defined next to the node type. +|String +|Yes + +|`label` +|An optional short, human-readable display name for the node. +|String +|No + +|`description` +|A CommonMark string providing a description of the node. +|String +|No + +|`on_exit` +|A procedure that executes when the node execution finishes. If `on_exit` is not defined, the graph ends when the agentic node ends. +|Procedure, but only `transition_to` statements are allowed. +|No + +|`llm` +|A reference to the LLM connection. +|@llm reference See <> +|No + +|`system.instructions` +|Overrides the global `system.instructions` at the file root level for this generator node. +|String +|No + +|`prompt` +|Session-specific query or instructions for this particular node, typically containing user provided or user related context. +|String +|Yes + +|`outputs` +|A schema definition for the agentic output. +|Object See <> +|No + +|=== + +=== Executor Node + +The executor node is used to execute a set of Agent Script statements, primarily for setting variables or deterministic tool invocations. Use this node to set variables or call actions with known or fixed arguments. + +*Example* + +[source,yaml] +---- +executor sendHrSlackUpdate: + do: -> run @actions.send_slack_message with text=@generator.generate-hr-slack-update-message.output with channel_id="my-onboarding-channel-id" + on_exit: -> transition to @router.countrySwitch +---- + +The executor node has these properties. + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|`id` +|The node identifier, defined next to the node type. +|String +|Yes + +|`label` +|An optional short, human-readable display name for the node. +|String +|No + +|`description` +|A CommonMark string providing a description of the node. +|String +|No + +|`on_exit` +|A procedure that executes when the node execution finishes. If `on_exit` is not defined, the graph ends when the executor ends. +|Procedure, but only `transition_to` statements are allowed. +|No + +|`do` +|Agent Script statements to execute +|procedure +|Yes + +|=== + +=== Router Node + +The router node performs dynamic transitions based on deterministic conditions. This node does not support transition to in its on_exit attribute. Use this node for branching based on structured output from a previous node. + +*Example* + +[source,yaml] +---- +router countryRouter: + routes: + - target: @orchestrator.argentinaOnboard + when: @orchestrator.hrSystemOnboard.output.country == "ARG" + label: "Argentina" + - target: @orchestrator.usOnboard + when: @orchestrator.hrSystemOnboard.output.country == "USA" + label: "USA" + otherwise: + target: @echo.invalidCountryResponse +---- + +The router node has these properties. + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|`id` +|The node identifier, defined next to the node type. +|String +|Yes + +|`label` +|An optional short, human-readable display name for the node. +|String +|No + +|`description` +|A CommonMark string providing a description of the node. +|String +|No + +|`routes` +|An array of condition and target pairs, plus an optional label field for UI. Must define at least one route. Each route contains: `target`, `when`, and optional `label`. +|Array +|Yes + +|`otherwise` +|Defines a default transition when no route condition matches. Contains: `target`. +|Object +|Yes with `routes` + +|=== + +=== Echo Node + +The echo node sends a response back to the client. The number of responses depends on the trigger interface and its configuration. Use this node for the end of a workflow, or anytime you want to emit a response. Currently only supports `a2a:response` (non-streaming). + +*Example* + +[source,yaml] +---- +echo a2a_response: + kind: "a2a:response" + task: a2a.task({ + state: "completed", + message: a2a.message({ + messageId: uuid(), + parts: [a2a.textPart("You have been onboarded! Your employee ID is " + @orchestrator.hrSystemOnboard.output.employeeId)] + }), + artifacts: a2a.parts(*@variables.artifacts), + metadata: None + }) +---- + +[%header,cols="1,1,1,1"] +|=== +|Parameter +|Description +|Type +|Required + +|`id` +|The node identifier, defined next to the node type. +|String +|Yes + +|`label` +|An optional short, human-readable display name for the node. +|String +|No + +|`description` +|A CommonMark string providing a description of the node. +|String +|No + +|`on_exit` +|A procedure that executes when the node execution finishes. If `on_exit` is not defined, the graph ends when the agentic node loop ends. +|Procedure, but only `transition_to` statements are allowed. +|No + +|`kind` +|Discriminator for the response type. Must be "a2a:response". +|String +|Yes + +|`task` +|A Task object as defined in the A2A specification. The `id`, `contextId` and `history` attributes are automatically populated by the trigger +|Task object +|Yes + +|=== + +[[a2a-namespace-functions]] +== A2A Namespace Functions + +The `a2a` namespace provides a set of functions that support A2A Task object creation. Do not prefix these functions with `@` as it's reserved for references such as `@variables`, `@actions`, `@request`, and `@orchestrator.`. + +[%header,cols="1,1,1,1,1"] +|=== +|Function +|Description +|Input Arguments +|Output +|Example + +|`a2a.task` +|Builds an A2A Task response object +|`state: str` (required) `message` (optional, from `a2a.message`) `artifacts: list` (optional, from `a2a.artifact`) `metadata: dict` (optional) +|`dict` (Task) +|`a2a.task("completed", message=a2a.message(...), artifacts=[a2a.artifact(...)])` + +|`a2a.message` +|Builds an A2A Message object +|`parts: list` (required, from `a2a.textPart/a2a.dataPart/a2a.filePart`) `role: str` (optional, default: "agent") `metadata: dict` (optional) +|`dict` (Message) +|`a2a.message([{messageId: uuid(), parts: [a2a.textPart("Hello")]}])` + +|`a2a.textPart` +|Builds a TextPart object (kind: "text") +|`text: str` (required) `metadata: dict` (optional) +|`dict` (TextPart) +|`` a2a.textPart("Employee ID: {!@orchestrator.employee.id}") `a2a.textPart("Status: Complete", metadata={priority: "high"})` `` + +|`a2a.dataPart` +|Builds a DataPart object (kind: "data") +|`data: dict` (required) `metadata: dict` (optional) +|`dict` (DataPart) +|`` a2a.dataPart({employeeId: "E123", department: "Engineering"}) `a2a.dataPart(@orchestrator.result.output)` `` + +|`a2a.filePart` +|Builds a FilePart object (kind: "file") +|`uri: str` (optional, required if bytes not provided) `bytes: str` (optional, base64-encoded) `name: str` (optional) `mime_type: str` (optional) `metadata: dict` (optional) +|`dict` (FilePart) +|`a2a.filePart(uri="https://example.com/report.pdf", name="report.pdf", mime_type="application/pdf") a2a.filePart(bytes="SGVsbG8gV29ybGQ=", name="data.txt")` + +|`a2a.artifact` +|Builds an A2A Artifact object with auto-generated ID +|`parts: list` (required, from `a2a.textPart/a2a.dataPart/a2a.filePart`) `artifact_id: str` (optional, auto-generated) `name: str` (optional) `description: str` (optional) `metadata: dict` (optional) +|`dict` (Artifact) +|`` a2a.artifact([a2a.dataPart(...)], name="Results", description="Analysis results") `a2a.artifact([a2a.filePart(...)], artifact_id="custom-id")` `` + +|`a2a.parts` +|Collects multiple items into a list for composing parts/artifacts arrays +|`*args: Any` (variable arguments) +|`list` +|`` a2a.parts(*@variables.artifacts) `a2a.parts(a2a.textPart("Part 1"), a2a.dataPart({key: "value"}))` `` + +|=== + +Usage notes: + +* Functions are designed to be composed: `a2a.task` accepts `message` created by `a2a.message`, which accepts `parts` created by `a2a.textPart`/`a2a.dataPart`/`a2a.filePart`. +* `a2a.filePart` requires either `uri` OR `bytes` (base64-encoded), but not both +* `a2a.artifact` auto-generates `artifactId` if it's not provided. +* Use `a2a.parts` with the `*` operator to unpack arrays, for example, `a2a.parts(*@variables.artifacts)`. +* All `metadata` parameters are optional and accept arbitrary dictionaries. +* For tasks, it's not necessary to define the `id`, `contextId` and `history` attributes, those are automatically populated by the trigger. + +[[built-in-functions]] +== Built-in Functions + +Use these functions in expressions alongside references and interpolations. They include time and ID helpers (`now`, `uuid`), string utilities (`strip`, `startswith`, and `endswith`), JSON parsing (`parse_json`), and common numeric helpers (`abs`, `round`, and `sum`) for deterministic math-style logic without calling external tools. + +[%header,cols="1,1,1,1,1"] +|=== +|Function +|Description +|Input arguments +|Output +|Example + +|`now` +|Current UTC time in ISO 8601 format +|None +|String (ISO 8601) +|`now()` + +|`uuid` +|Random UUID v4 +|None +|String (UUID) +|`uuid()` + +|`strip` +|Removes leading/trailing characters from a string +|String, optional chars (default: whitespace) +|String +|`strip(" hello ") -> "hello"` + +|`startswith` +|Whether a string starts with a prefix +|String, prefix +|Boolean +|`startswith("hello world", "hello")` + +|`endswith` +|Whether a string ends with a suffix +|String, suffix +|Boolean +|`endswith("report.pdf", ".pdf")` + +|`abs` +|Absolute value +|Number +|Number +|`abs(-42)` + +|`round` +|Round to optional digit count +|Number, optional `ndigits` +|Number +|`round(3.14159, 2)` + +|`sum` +|Sum of a numeric list +|List +|Number +|`sum([10, 20, 30])` + +|`parse_json` +|Parse a JSON string +|String (valid JSON) +|Object or array +|`parse_json('{"key": "value"}')` + +|=== + +[[node-outputs]] +== Node Outputs + +Use the `outputs` field to define the expected shape of the agent's response using a schema notation similar to a JSON schema. When provided, the agent produces output matching the defined structure for downstream parsing and processing. + +Each property maps to a field in the agent's output. The following types are supported. + +*Note:* Advanced JSON schema features are not supported, so do not copy patterns from generic JSON Schema tutorials unless they match what is documented here. + +[%header,cols="1,1"] +|=== +|Type +|Description + +|String +|Text values with optional constraints like `pattern` (regex), `minLength`, `maxLength`, and `enum` (allowed values). + +|Number / Integer +|Numeric values with optional constraints like `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, and `enum`. + +|Boolean +|`True` or `False` (with optional default). + +|Array +|Lists of items, where `items` define the schema for each element (can be any supported type). Supports `minItems` and `maxItems`. + +|Object +|Nested structures with their own `properties` map. Supports a `required` array to specify mandatory fields. + +|=== + +Each property definition can include: + +* `type`: The data type (required). +* `description`: A human-readable explanation of the property's purpose. +* `default`: A default value if the property is omitted. + +The `outputs` definition does not support the following: + +* `additionalProperties` or similar JSON Schema extensibility flags +* Combinators such as `anyOf`, `oneOf`, or `allOf` +* References or shared definitions (`$ref`, `$defs`) +* Composition beyond nested `object` / `array` structures as described above + +[[node-expressions-and-references]] +== Node Expressions and References + +Nodes access data from other parts of the workflow using expressions. + +The following references are used. + +[%header,cols="1,1,1"] +|=== +|Prefix +|Reference +|Example + +|`@llm.` +|LLM definitions +|`@llm.open-api-llm` + +|`@actions.` +|action definitions +|`@actions.hr_agent` + +|`@request.` +|Trigger request data +|`@request.payload`, `@request.interface` + +|`@request.headers` +|HTTP headers (case-insensitive) +|`@request.headers["Authorization"]` + +|`@variables.` +|Workflow variables +|`@variables.companyId` + +|`@..` +|Node references +|`@orchestrator.hrOnboard.output` + +|=== + +=== Accessing Node Output and Input + +Every node has `.output` (the value it produced) and `.input` (the output of whichever node transitioned into it). + +*Example* + +---- +@orchestrator.hrSystemOnboard.output.employeeId # returns the `employeeId` property of the object returned by the `hrSystemOnboard` node +@generator.writeEmailContent.output # returns the string generated by the `writeEmailContent` node +---- + +* Use `.output` when you know exactly which upstream node you're referencing. +* Use `.input` when multiple nodes transition into the current one and you want to decouple it from the specific path taken. + +In this example, `@generator.generate_email.input` returns whichever of `node_a`, `node_b`, or `node_c` actually transitioned into it. + +---- +node_a ──┐ +node_b ──┼──► generate_email ──► send_email +node_c ──┘ +---- + +=== Setting Action Headers + +Any actions that connect to an external system often need to set custom headers. Use cases range from propagating authorization headers (for example, in OBO authentication) to adding custom correlation information. + +For this, both the MCP and A2A actions automatically get an implicit optional `http_headers` parameter object type that can be used to set those: + +[source,yaml] +---- +actions: + my_hr_agent: @actions.hr_agent with http_headers = {"Authorization": @request.headers["Authorization"], "X-CorrelationId": @variables.conversationId} +---- + +=== String Interpolation + +Use `{!expression}` to embed values inside strings. + +*Example* + +[source,yaml] +---- +prompt: "The employee's country is {!@orchestrator.hrOnboard.output.country}" +---- + +=== Slot Filling + +Use slot filling (`...`) to tell an LLM to figure out a value. + +*Example* + +[source,yaml] +---- +actions: + send_message: @actions.send_slack_message with message = ... + # LLM decides the message content +---- + +=== Tool Binding at the Node Level + +When you reference a tool inside a node, you can fix, default, or slot-fill its arguments using `with`. + +*Example* + +[source,yaml] +---- +actions: + # All arguments via slot filling (LLM decides everything) + sendToDefault: @actions.send_slack + # Fix the channel, LLM fills the message + sendToFixed: @actions.send_slack with channel = "agent-fabric" + # Fix everything -- fully deterministic + fullyDeterministic: @actions.send_slack with message = @variables.calculatedMessage with channel = @variables.channelId +---- diff --git a/agent-network/2.0/modules/ROOT/pages/af-build-agent-networks-in-a-ci-cd-environment.adoc b/agent-network/2.0/modules/ROOT/pages/af-build-agent-networks-in-a-ci-cd-environment.adoc new file mode 100644 index 000000000..7c940f7a8 --- /dev/null +++ b/agent-network/2.0/modules/ROOT/pages/af-build-agent-networks-in-a-ci-cd-environment.adoc @@ -0,0 +1,55 @@ += Build Agent Networks in a CI/CD Environment +:page-aliases: anypoint-code-builder::af-build-agent-networks-in-a-ci-cd-environment.adoc + +Use the Anypoint CLI Agent Fabric plugin in CI/CD pipelines to configure agent network gateways, create and build projects, and publish and deploy networks from the command line, matching the lifecycle you can drive from Anypoint Code Builder. Automating these steps keeps environments aligned, lets you embed approvals, secrets, and quality gates in the pipeline, and avoids one-off scripts when you promote from development to staging and production. + +For installation, package updates, and release details, see https://www.npmjs.com/package/mulesoft-anypoint-cli-agent-fabric-plugin[Anypoint CLI Agent Fabric Plugin on npm]. + +== Before You Begin + +Make sure you meet the xref:af-get-started.adoc#before-you-begin[prerequisites] for this task. + +Install the Anypoint CLI Agent Fabric plugin by running this command in a terminal window: + +`npm i mulesoft-anypoint-cli-agent-fabric-plugin` + +[NOTE] +==== +The installation package has been renamed from `anypoint-cli-agent-fabric-plugin` to `mulesoft-anypoint-cli-agent-fabric-plugin`. + +If you have the previous version installed, you may encounter an `npm error EXIST: file already exists` error when updating your installation. This occurs because both versions share the same command alias. To resolve this, use the `--force` flag to overwrite the alias and point it to the new package: `npm i mulesoft-anypoint-cli-agent-fabric-plugin --force`. +==== + +=== Authentication + +You can authenticate to Anypoint Platform through the command line by running the `anypoint-cli-agent-fabric-plugin` command with a combination of parameters. + +Or, you can set a combination of environment variables before running the `anypoint-cli-agent-fabric-plugin` command. For more information, see link:https://docs.mulesoft.com/anypoint-cli/latest/auth#command-line-parameters[Command-Line Parameters and Environment Variables]. + +Set configuration file authentication using a client ID and client secret from your connected app. + +Add authentication values to the configuration file using these commands. + +---- +$ anypoint-cli-agent-fabric-plugin conf client_id myClientID + +$ anypoint-cli-agent-fabric-plugin conf client_secret myClientSecret + +$ anypoint-cli-agent-fabric-plugin conf organization myOrgId +---- + +For more information, see xref:anypoint-cli::auth.adoc[]. + +=== Create a Target Space for Your Environment + +To deploy an agent network, you need a space on CloudHub 2.0 or a deployment target on Anypoint Runtime Fabric. See xref:af-get-started.adoc#setup-space[Set Up the Space or Deployment Target for Your Environment]. + +After you create a target space, set up the ingress and egress gateways for deployment if you haven't already done so. See xref:af-get-started.adoc#setup-gateways[Set Up Agent Network Gateways for the Private Space or Deployment Target]. + +== CLI for Agent Fabric Plugin Reference + +Use these commands to set up gateways and author, publish, and deploy agent network projects. + +include::anypoint-cli::partial$agent-fabric.adoc[tag=summary] + +include::anypoint-cli::partial$agent-fabric.adoc[tag=commands] diff --git a/agent-network/2.0/modules/ROOT/pages/af-create-agent-network.adoc b/agent-network/2.0/modules/ROOT/pages/af-create-agent-network.adoc new file mode 100644 index 000000000..c153bc55f --- /dev/null +++ b/agent-network/2.0/modules/ROOT/pages/af-create-agent-network.adoc @@ -0,0 +1,83 @@ +[[create-networks]] += Create Agent Networks +:page-aliases: anypoint-code-builder::af-create-agent-network.adoc + +Whether you use MuleSoft Vibes or the visual canvas and code editor, Anypoint Code Builder includes the agent network functionality you need to get started. + +[[before-you-begin]] +== Before You Begin + +Make sure you review the xref:af-get-started.adoc#before-you-begin[prerequisites]. + +[[create-dev-agent]] +== Create a Network Using MuleSoft Vibes + +You can use natural language prompts in MuleSoft Vibes to create your project. For more information, see xref:anypoint-code-builder::api-ai-create-spec.adoc[]. + +. In the Anypoint Code Builder activity bar, click the agent icon image:af-acb-dev-agent-icon.png["",18,18]. +. Describe your agent network, including the brokers, agents, MCP servers, and LLMs you want to connect. MuleSoft Vibes generates the `agent-network.yaml` file, the `exchange.json` file, and the corresponding `.agent` files in the `/brokers` directory. + +To get started, try one of these suggested prompts: + +* Create a new agent network project called "Employee Onboarding." Add a broker that coordinates an HR agent and a CRM agent, and use OpenAI as the LLM. +* Build a Travel Planner broker that plans multi-city trips, calls a Flights MCP server for booking, and uses an LLM to generate itineraries. +* Generate an agent network project for incident management. Include a broker that coordinates the resolution of incidents reported by customers, with subagent and orchestrator nodes. + +[[create-acb]] +== Create a Network Using Anypoint Code Builder + +If you prefer not to use MuleSoft Vibes, create a new agent network project directly from the Anypoint Code Builder UI. + +. If you're not logged in, log in to your Anypoint Platform account. +. In Anypoint Code Builder, choose one of the following: + * In Create, select *Create an Agent Network*. + * From the Command Palette, run this command: *MuleSoft: Create an Agent Network Project*. +. Enter a name for the project and select the location to create the project. +. Select the business group associated with the target space you created in xref:af-get-started.adoc[Get Started with Agent Networks]. The business group you select must be the same business group you selected when you created the target space. +. Select *Create Project*. + +When the project opens, the `agent-network.yaml` file opens in the code view editor. You can open the graph canvas from the action bar. For more information, see xref:af-define-your-agent-network-specification.adoc[Define Your Agent Network]. + +[[project-files]] +== Agent Network Project Files + +Anypoint Code Builder creates the following files and directories as part of your agent network project. Together, these files define the brokers, nodes, assets, connections, and policies that make up your agent network. For full schema details, see xref:af-project-files.adoc[Agent Network Project File Reference]. + +---- +/my-agent-network-project +├── agent-network.yaml +├── exchange.json +└── /brokers + ├── broker1.agent + └── broker2.agent +---- + +* `agent-network.yaml` ++ +The top-level configuration file for the project. This file contains: ++ +** A *registry* section that declares the assets (LLMs, MCP servers, agents) used by the project, including assets created locally and assets imported from Anypoint Exchange. +** A *context* section that defines the connections (URLs, authentication) and policies that apply to those assets. + +* `exchange.json` ++ +The Anypoint Exchange manifest for the project. This file lists the project's metadata and the Exchange assets added as dependencies. When you publish your project, Exchange uses this file to register the assets. When you add an Exchange asset to your project, its asset ID and version are recorded here. + +* `/brokers` directory ++ +Contains one `.agent` file per broker in your network. Each `.agent` file is an Agent Script file that defines one broker and the nodes inside it (for example, trigger, subagent, orchestrator, generator, executor, echo, and router nodes), along with the transitions between those nodes. A project can contain multiple `.agent` files. Each file appears as its own graph on the visual canvas. + +[NOTE] +==== +For a complete, working example you can use as a starting point for your own agent network project, see xref:af-example-it-investigation-broker.adoc[Example: Building an IT Investigation Broker]. The example walks through a fully configured `agent-network.yaml`, `exchange.json`, and `/brokers` directory that you can adapt to your own brokers, agents, MCP servers, and LLMs. +==== + +[[create-cli]] +== Create a Network Using the Anypoint CLI + +If you run operations within a CI/CD environment, you can use Anypoint CLI's plugin to set up, create, build, publish, and deploy agent networks. For more information, see xref:af-build-agent-networks-in-a-ci-cd-environment.adoc[]. + +[[whats-next]] +== What's Next? + +* xref:af-define-your-agent-network-specification.adoc[] diff --git a/agent-network/2.0/modules/ROOT/pages/af-define-your-agent-network-specification.adoc b/agent-network/2.0/modules/ROOT/pages/af-define-your-agent-network-specification.adoc new file mode 100644 index 000000000..db54743cb --- /dev/null +++ b/agent-network/2.0/modules/ROOT/pages/af-define-your-agent-network-specification.adoc @@ -0,0 +1,153 @@ +[[define-spec]] += Define Your Agent Network +:page-aliases: anypoint-code-builder::af-define-your-agent-network-specification.adoc + +After you create your agent network project, configure your network by editing `agent-network.yaml`, the `.agent` files in the `/brokers` directory, and `exchange.json`. As you edit, use the read-only visual canvas alongside the code editor to verify the structure of your network and to navigate quickly between graph nodes and the code that defines them. + +[[before-you-begin]] +== Before You Begin + +Make sure you review the xref:af-get-started.adoc#before-you-begin[prerequisites] and that you have created an agent network project. See xref:af-create-agent-network.adoc[Create Agent Networks]. + +[NOTE] +==== +For a complete, working example you can use as a starting point for your own agent network project, see xref:af-example-it-investigation-broker.adoc[Example: Building an IT Investigation Broker]. The example walks through a fully configured `agent-network.yaml`, `exchange.json`, and `/brokers` directory that you can adapt to your own project. +==== + +[[define-dev-agent]] +== Define an Agent Network Using MuleSoft Vibes + +Use natural language prompts in MuleSoft Vibes to configure your agent network specification. For more information, see xref:anypoint-code-builder::api-ai-create-spec.adoc[]. + +. In the Anypoint Code Builder activity bar, click the agent icon image:af-acb-dev-agent-icon.png["",18,18]. +. Give the agent information about your agent network, including the brokers, agents, MCP servers, and LLMs you want to connect. MuleSoft Vibes updates `agent-network.yaml`, `exchange.json`, and the appropriate `.agent` files in the `/brokers` directory. + +To get started, try one of these suggested prompts: + +* Help me build an agent network configuration for my Employee Onboarding project. +* Revise my Employee Onboarding agent network project. Use OpenAI for the LLM. +* Add a new broker for employee offboarding to my HR agent network. +* Add a new skill to my Offboarding broker. + +[[define-acb-ide]] +== Define Your Network in Anypoint Code Builder + +Use the code view editor and the visual canvas together to define your agent network. The canvas is read-only and syncs automatically as you make changes to the code. Essentially, make all changes in the project files and use the canvas to navigate, verify the shape of your network, and jump back to the lines you need to edit. + +[NOTE] +==== +Using the visual canvas is optional. If you prefer a code-only workflow, you can edit `agent-network.yaml`, the `.agent` files under `/brokers`, and `exchange.json` directly without ever opening the canvas. Auto-completion menus in Anypoint Code Builder work the same way in both workflows. For more information, see xref:anypoint-code-builder::start-discover-ui.adoc#use-autocomplete[Use Auto-Completion Menus]. +==== + +image::af-acb-canvas.png["Anypoint Code Builder canvas showing two different brokers with their respective agents and MCP servers"] + +=== Open Your Project + +Open your agent network project in Anypoint Code Builder and display the canvas alongside the code editor. + +. In Anypoint Code Builder, open your agent network project. By default, `agent-network.yaml` opens in the editor. +. In the editor action bar, click *Show canvas*. ++ +The canvas opens to the right of the code editor, giving you a side-by-side layout. ++ +The canvas renders all graphs in the project from left to right. Each broker appears as its own graph with a header that includes the broker name. + +=== Edit Your Project + +With the canvas open beside the code editor, edit your project files. The visual canvas updates with your changes as you save your work. + +. Edit `agent-network.yaml` to declare assets in the *registry* section and to define connections and policies in the *context* section. +. In the Explorer, navigate to the `/brokers` directory and open the `.agent` file for the broker you want to edit (for example, `broker1.agent`). Edit the `.agent` file to define the broker, its nodes (trigger, subagent, orchestrator, generator, executor, echo, router), and the transitions between them. ++ +To understand the schema and expected values for each file, see xref:af-project-files.adoc[Agent Network Project File Reference]. +. Update `exchange.json` to manage Anypoint Exchange dependencies. You typically update this file by using the *Add Exchange Assets* action rather than editing it by hand. See <>. + +=== Navigate Between Canvas and Code View + +Use the navigation shortcuts on the canvas to jump straight to the lines you need to edit. + +. To edit a node's configuration, click the *Open in code view* icon on the node. ++ +Anypoint Code Builder opens the corresponding `.agent` file in the code editor and highlights the line that defines the node. +. To open the full Agent Script for a broker, click the *Open in code view* button in that broker's graph header. +. To zoom into a specific graph, click the graph name in the *Project Palette*. +. To switch the canvas to the Project Assets view, use the toggle at the top of the Project Palette. + +==== Adjust the Canvas View + +You can adjust nodes on the canvas view while you edit your project. + +* Use the *zoom* controls and the *organize/reset to default view* button on the canvas footer to adjust the view. +* Resize each broker's graph independently as needed. + +[[manage-project-assets]] +== Manage Project Assets + +The *Project Assets* view lists every asset (agent, LLM, MCP server, or policy) you declared in the *registry* section of `agent-network.yaml`. Here you can manage those assets or add new dependencies from Anypoint Exchange. + +. In the Project Palette, select *Project Assets*. ++ +The Project Assets view displays two sections: ++ +** *Created in Project* ++ +Lists assets you defined locally in this project. These assets get published to Anypoint Exchange when you publish the project. Each card shows the asset type icon, the asset name, and the version. +** *Imported from Exchange* ++ +Lists Exchange assets you added as dependencies via `exchange.json`. Each card shows the asset type icon, the asset name, and the version. +. Use the *search* and *filter* controls at the top of the Asset Registry to find assets across both sections. +. To open a locally defined asset's definition in `agent-network.yaml`, click the asset card. +. To open an imported asset's page in Anypoint Exchange, click the asset card. + +[[add-exchange-assets]] +== Add Exchange Assets to Your Agent Network Project + +If you have existing Exchange assets to use in your agent network, add them to the project's dependencies through the *Add Exchange Assets* action. This action updates `exchange.json` and adds the asset to the *Imported from Exchange* section of the Project Assets. + +=== Add Assets Using MuleSoft Vibes + +Use natural language prompts to let MuleSoft Vibes add Exchange assets to your project for you. + +. In the Anypoint Code Builder activity bar, click the agent icon image:af-acb-dev-agent-icon.png["",18,18]. +. Tell the agent that you want to add Exchange assets to your project. MuleSoft Vibes does the rest. + +To get started, try one of these suggested prompts: + +* Add tools for background check processing in my Employee Onboarding project. +* Add a Talent Pool MCP server to my Employee Onboarding agent network project. + +=== Add Assets from the Project Assets + +Use the *Project Assets* view to search Anypoint Exchange and add assets directly from the canvas. + +. In the Project Palette, open the *Project Assets* view. +. Click *Add Exchange Assets*. ++ +The *Add Exchange Assets to Project* UI opens with the Exchange search and listing experience. +. Search for the asset you want to add, select it, and choose the version to import. +. Click *Add to Project*. ++ +The asset is added to the `dependencies` attribute in `exchange.json` and appears in the *Imported from Exchange* section of the Asset Registry. +. Edit `agent-network.yaml` to reference the new asset from the appropriate broker's *registry* entries, and edit the relevant `.agent` files in `/brokers` to use the asset in node configurations. ++ +If you added a dependency that doesn't belong to the same business group as your agent network, specify the `namespace` property at the same level as `name` in `agent-network.yaml`. Provide the `groupId` (business group ID) for the business group that the dependency belongs to. The `groupId` value is the same as the `groupId` value of the corresponding dependency in `exchange.json`. If you don't provide a namespace value, the same `groupId` as the agent network project is used. + +[[add-assets-acb]] +=== Add Assets from the Command Palette + +You can also start the *Add Exchange Assets* flow without opening the canvas: + +. In your Anypoint Code Builder project, choose one of the following: + * In Explorer, right-click a project file and select *Add Exchange Assets to Agent Network Project*. + * In the *Command Palette*, run this command: *MuleSoft: Add Agent Network Assets to Agent Network Project*. +. In *Add Exchange Assets to Project*, search for and select the asset. +. Click *Add to Project*. + +After you add dependencies, they're available as values in auto-completion menus in the code editor. For example, after you add `test-agent` to `exchange.json`, the value `test-agent` is available in auto-completion menus in `agent-network.yaml` when you reference an agent. + +[[see-also]] +== See Also + +* xref:af-create-agent-network.adoc[Create Agent Networks] +* xref:af-project-files.adoc[Agent Network Project File Reference] +* xref:af-agent-script-reference.adoc[Agent Script Reference] diff --git a/agent-network/2.0/modules/ROOT/pages/af-deploy-agent-network-targets.adoc b/agent-network/2.0/modules/ROOT/pages/af-deploy-agent-network-targets.adoc new file mode 100644 index 000000000..494a1c8da --- /dev/null +++ b/agent-network/2.0/modules/ROOT/pages/af-deploy-agent-network-targets.adoc @@ -0,0 +1,80 @@ +[[deploy-instances]] += Deploy Agent Network Instances +:page-aliases: anypoint-code-builder::af-deploy-agent-network-targets.adoc + +Deploy your agent network instance to a deployment target. You can deploy to a CloudHub 2.0 shared space, a CloudHub 2.0 private space, or to a Runtime Fabric. When you deploy, Omni Gateway secures inbound traffic to your agent network and outbound traffic from your brokers, agents, and MCP servers. + +These Omni Gateway policies are applied automatically at deployment. + + +[%header,cols="20,40a"] +|=== +|Agent Type|Policy +|Broker +| + +** A2A Agent Card policy +** Tracing policy +** Agent Connection Telemetry policy + +|Agent + +(ingress and egress) +| + +** A2A Agent Card policy +** Tracing policy +** Agent Connection Telemetry policy + +|MCP Server + +(ingress and egress) +| + +** MCP Support policy +** Tracing policy +** Agent Connection Telemetry policy + +|=== + +[[before-you-begin]] +== Before You Begin + +Make sure you review the xref:af-get-started.adoc#before-you-begin[prerequisites]. + +When you deploy your agent network, an instance is deployed for each connection defined in your agent network. If your agent network contains brokers, an instance is deployed per broker. + +[[deploy-dev-agent]] +== Deploy Your Network Using MuleSoft Vibes + +MuleSoft Vibes can help you deploy your agent network instances. For more information, see xref:anypoint-code-builder::api-ai-create-spec.adoc[]. + +. In the Anypoint Code Builder activity bar, click the agent icon image:af-acb-dev-agent-icon.png["",18,18]. +. Tell the agent that you want to deploy your agent network. MuleSoft Vibes does the rest. + +To get started, try one of these suggested messages. + +* Deploy my agent network project to the production environment. +* Deploy the hello-world-network project to staging. +* Deploy agent network project at /path/to/project to dev environment with specific gateways. +* Deploy my agent network to CloudHub 2.0. + +[[deploy-acb]] +== Deploy Your Network Using Anypoint Code Builder + +Deploy your agent network instance to a CloudHub 2.0 space or Runtime Fabric target directly from Anypoint Code Builder. + +. If you're not logged in already, log in to your Anypoint Platform account. +. In Anypoint Code Builder, choose one of the following: + . In Explorer, right-click a project file and select *Deploy Agent Network*. + . From the Command Palette, run this command: *MuleSoft: Deploy Agent Network*. +. In Deploy Agent Network, specify the environment, target space, gateways, and other deployment information. If you don't see any deployment targets to select, then you need to set up your target deployment space and set up gateways. For instructions, see xref:af-get-started.adoc[Get Started with Agent Networks]. +. Select *Deploy*. +. Your instances are deployed and ready to be tested. An instance is deployed for each connection defined in your agent network. If your agent network contains brokers, one instance is deployed per broker. + +Next, discover your agent network assets in *Agents & Tools* in Exchange, view your agent network in Agent Visualizer, apply a governance policy in API Manager, or monitor your agent network activity in Anypoint Monitoring. + +[[deploy-cli]] +== Deploy a Network Using the Anypoint CLI + +If you run operations within a CI/CD environment, you can use Anypoint CLI's plugin to set up, create, build, publish, and deploy agent networks. For more information, see xref:af-build-agent-networks-in-a-ci-cd-environment.adoc[]. \ No newline at end of file diff --git a/agent-network/2.0/modules/ROOT/pages/af-example-it-investigation-broker.adoc b/agent-network/2.0/modules/ROOT/pages/af-example-it-investigation-broker.adoc new file mode 100644 index 000000000..4695e78e3 --- /dev/null +++ b/agent-network/2.0/modules/ROOT/pages/af-example-it-investigation-broker.adoc @@ -0,0 +1,700 @@ +[[example-building-an-it-investigation-broker]] += Example: Building an IT Investigation Broker + +In this example, the goal is to use MuleSoft Vibes to build an IT Investigation agent that triages incoming support tickets, escalates critical issues, resolves common problems through cross-platform investigation, and handles licensing requests. + +In each phase, you interact with MuleSoft Vibes as it builds your agent network project. Here's how it works. + +== Phase 1: Input Functional Requirements + +In this first phase, you define the functionality of the IT Investigation agent, which is to triage, investigate, and resolve support tickets. The agent must read incoming ticket descriptions (received via an A2A message with a Jira ticket ID), classify severity (High, Low, or too vague to classify) using an LLM's judgment, and then take the correct action. If the ticket is too vague, the agent first asks the user for clarification. + +High-severity tickets must be immediately routed for escalation using an Escalation MCP tool. Low-severity tickets require multi-agent investigation, using a Help Center agent and a License Procurement agent. + +This investigation path results in one of three deterministic outcomes: "Help Given," "License Given," or "Unresolved," the latter of which requires escalation to a human agent. Crucially, the severity classification and cross-platform investigation are open-ended, but the routing based on that classification and the final resolution must be deterministic. + +== Phase 2: Asset Registration + +In this phase, you work with MuleSoft Vibes to identify and register the necessary external tools and LLMs to support the agent's requirements. Since the investigation and resolution actions require four external assets, you select two A2A agents: the Help Center Agent for searching the knowledge base and the License Procurement Agent for checking software licenses. + +You also select two MCP tools: the Escalation MCP Server for handling high-severity cases and the Jira MCP Server for updating ticket status. + +For the LLMs, you select OpenAI GPT-5.4 for reasoning and orchestration tasks, such as cross-platform triage. You register Gemini 2.5 Flash for fast, one-shot summaries and response message generation. + +== Phase 3: Define the Broker (Agent Script) + +In this phase, MuleSoft Vibes establishes the logical workflow for the IT Investigation agent by defining a series of interconnected nodes. The graph begins with an A2A trigger node (`ticketTrigger`) that receives the incoming ticket and Jira ID. This immediately flows into a generator node (`classifySeverity`), which uses LLM reasoning to classify the ticket as High or Low, and produces a structured output. + +The deterministic `severityRouter` node then directs the process into two paths based on the classification output: + +* High: An executor node calls the Escalation MCP tool. + +* Low: An orchestrator node coordinates agents and tools to investigate, producing a structured outcome (e.g., `help_given`). A second router then directs the flow based on this outcome, with all paths concluding via an Echo node. + +== Phase 4: Asset Assignment to Graph + +In this phase, MuleSoft Vibes assigns the registered assets to the specific nodes in the graph while adhering to the principle of least privilege. + +This table shows which assets and LLMs MuleSoft Vibes mapped to which nodes. + +[%header,cols="1,1,1,1,1,1"] +|=== +|Node +|Type +|Assets +|LLM +|Total Assets +|Notes + +|`classifySeverity` +|generator +|(none) +|Gemini 2.5 Flash (default) +|0 +|Pure LLM classification (needs deep reasoning to classify ambiguous tickets). Constraint: Can only read the ticket and classify, has no actions. + +|`crossPlatformTriage` +|orchestrator +|Help Center A2A, License Procurement A2A, Jira MCP +|OpenAI GPT 5.4 +|3 +|Coordinates multi-agent investigation (needs deep reasoning). Constraint: Can investigate and update tickets, but cannot escalate. + +|`helpSummary` +|generator +|-- +|Gemini 2.5 Flash (default) +|-- +|One-shot summary generation. + +|`licenseSummary` +|generator +|-- +|Gemini 2.5 Flash (default) +|-- +|One-shot summary generation. + +|`escalateTicket` +|executor +|Escalation MCP +|-- +|1 +|Deterministic action call (no LLM). Constraint: Can only escalate, not investigate or resolve. + +|`escalateUnresolved` +|executor +|Escalation MCP +|-- +|1 +|Deterministic escalation for unresolved tickets (no LLM). Constraint: Can only escalate unresolved tickets after investigation has been exhausted. + +|`All echo nodes` +|echo +|-- +|-- +|-- +|Deterministic response formatting (no LLM). + +|=== + +== Phase 5: Instruction Refinement + +In this phase, MuleSoft Vibes writes and validates (with you) the precise natural language instructions for the LLM-powered nodes. The instructions for the `classifySeverity` node clearly define what constitutes High and Low severity, such as classifying a system outage as High severity. + +The `crossPlatformTriage` node instructions outline the required investigation steps: searching the Help Center, checking the License Procurement agent, and updating the Jira ticket. + +Furthermore, these instructions define the two structured resolution outcomes the node must produce: `help_given` or `license_given`. A rigorous contradiction test is executed to ensure that no node's instructions accidentally override the deterministic routing logic defined in the graph. All instructions are verified to align with the overall graph structure and pass the cross-node checks. + +== Phase 6: Final Topology Review + +In this final phase, MuleSoft Vibes provides a comprehensive validation of the fully defined and instructed agent topology before deployment. The review confirms the crucial separation of concerns, ensuring LLM reasoning is used only for classification, with all subsequent routing being deterministic. + +The complete separation of the three severity paths - escalation, investigation, and asking for more info - is fully validated. The topology confirms that all possible paths terminate correctly at an echo response node to communicate the outcome to the original caller. Key operational parameters are also finalized, including maximum loop limits (5 for orchestration, 3 for classification) to prevent infinite loops. An edge case is defined, specifying that if the orchestration node cannot determine a resolution, the outcome defaults to `help_given`. + +== IT Agent Broker Diagram + +The following diagram shows the workflow. + +image::af-it-broker-escalation-flow.png[Workflow diagram of the IT agent broker showing severity classification branching into escalation, investigation, and ask-for-more-info paths, each terminating in an echo response node.] + +== IT Agent Project Reference + +The following shows the project files for the IT agent. + +*Project structure* + +---- +it-help-network/ + agent-network.yaml + exchange.json + brokers/ + it-help-investigation.agent +---- + +*exchange.json* + +[source,json] +---- +{ + "main": "agent-network.yaml", + "name": "IT Help Investigation Agent Network", + "classifier": "agentic-network", + "groupId": "${organizationId}", + "assetId": "it-help-investigation-network", + "version": "1.0.0", + "description": "Triages IT support tickets, escalates critical issues, and resolves common problems through cross-platform investigation with Help Center and License Procurement agents.", + "dependencies": [], + "metadata": { + "variables": { + "helpCenterAgent": { + "url": { + "description": "Help Center Agent (Agentforce) URL", + "default": "", + "secret": false + }, + "clientId": { + "description": "Help Center Agent OAuth2 Client ID", + "default": "", + "secret": false + }, + "clientSecret": { + "description": "Help Center Agent OAuth2 Client Secret", + "default": "", + "secret": true + }, + "tokenUrl": { + "description": "Help Center Agent OAuth2 Token Endpoint", + "default": "", + "secret": false + } + }, + "licenseProcurementAgent": { + "url": { + "description": "License Procurement Agent (Scanned) URL", + "default": "", + "secret": false + }, + "clientId": { + "description": "License Procurement Agent OAuth2 Client ID", + "default": "", + "secret": false + }, + "clientSecret": { + "description": "License Procurement Agent OAuth2 Client Secret", + "default": "", + "secret": true + }, + "tokenUrl": { + "description": "License Procurement Agent OAuth2 Token Endpoint", + "default": "", + "secret": false + } + }, + "escalationMcp": { + "url": { + "description": "Escalation MCP Server URL", + "default": "", + "secret": false + }, + "apiKey": { + "description": "Escalation MCP Server API Key", + "default": "", + "secret": true + } + }, + "jiraMcp": { + "url": { + "description": "Jira MCP Server URL", + "default": "", + "secret": false + }, + "clientId": { + "description": "Jira OAuth2 Client ID for OBO Token Exchange", + "default": "", + "secret": false + }, + "clientSecret": { + "description": "Jira OAuth2 Client Secret for OBO Token Exchange", + "default": "", + "secret": true + }, + "tokenUrl": { + "description": "Jira OAuth2 Token Endpoint for OBO Token Exchange", + "default": "", + "secret": false + }, + "audience": { + "description": "Jira Target Audience URI for OBO Token Exchange", + "default": "", + "secret": false + } + }, + "gemini": { + "apiKey": { + "description": "Google Gemini API Key", + "default": "", + "secret": true + } + }, + "openai": { + "apiKey": { + "description": "OpenAI API Key", + "default": "", + "secret": true + } + } + } + } +} +---- + +*agent-network.yaml* + +[source,yaml] +---- +agentNetwork: 2.0.0 +info: + label: "IT Help Investigation Agent Network" + version: v1 +registry: + agents: + helpCenterAgent: + info: + label: Help Center Agent + metadata: + protocol: a2a + platform: Other + card: + a2a: + protocolVersion: 0.3.0 + name: Help Center Agent + description: Searches the IT knowledge base for answers to common issues. Returns relevant articles with step-by-step instructions. + url: ${ingressgw.url}/helpCenterAgent + capabilities: + pushNotifications: false + version: 1.0.0 + defaultInputModes: + - application/json + - text/plain + defaultOutputModes: + - application/json + - text/plain + skills: + - id: knowledge-search + name: Knowledge Base Search + description: Search for IT help articles and known solutions. + tags: + - knowledge-base + - it-support + examples: + - How do I reset my VPN password? + - My email is not syncing + - How do I set up two-factor authentication? + inputModes: + - application/json + - text/plain + outputModes: + - application/json + - text/plain + licenseProcurementAgent: + info: + label: License Procurement Agent + metadata: + protocol: a2a + platform: Other + card: + a2a: + protocolVersion: 0.3.0 + name: License Procurement Agent + description: Checks software license availability and provisions licenses for employees. + url: ${ingressgw.url}/licenseProcurementAgent + capabilities: + pushNotifications: false + version: 1.0.0 + defaultInputModes: + - application/json + - text/plain + defaultOutputModes: + - application/json + - text/plain + skills: + - id: license-check + name: License Check and Provision + description: Check license availability and provision for a user. + tags: + - licensing + - provisioning + examples: + - Provision a Figma license for jane.doe@company.com + - Check if we have available GitHub Enterprise seats + - I need access to Jira + inputModes: + - application/json + - text/plain + outputModes: + - application/json + - text/plain + mcps: + escalationMcp: + info: + label: Escalation MCP Server + metadata: + transport: + kind: streamableHttp + path: /mcp + jiraMcp: + info: + label: Jira MCP Server + metadata: + transport: + kind: streamableHttp + path: /mcp + llms: + gemini: + info: + label: Gemini + metadata: + platform: Gemini + openai: + info: + label: OpenAI + metadata: + platform: OpenAI +context: + connections: + helpCenterAgentConnection: + kind: a2a + ref: + name: helpCenterAgent + url: ${helpCenterAgent.url} + authentication: + kind: oauth2-client-credentials + clientId: ${helpCenterAgent.clientId} + clientSecret: ${helpCenterAgent.clientSecret} + token: + url: ${helpCenterAgent.tokenUrl} + licenseProcurementAgentConnection: + kind: a2a + ref: + name: licenseProcurementAgent + url: ${licenseProcurementAgent.url} + authentication: + kind: oauth2-client-credentials + clientId: ${licenseProcurementAgent.clientId} + clientSecret: ${licenseProcurementAgent.clientSecret} + token: + url: ${licenseProcurementAgent.tokenUrl} + escalationMcpConnection: + kind: mcp + ref: + name: escalationMcp + url: ${escalationMcp.url} + authentication: + kind: apiKey + apiKey: ${escalationMcp.apiKey} + jiraMcpConnection: + kind: mcp + ref: + name: jiraMcp + url: ${jiraMcp.url} + authentication: + kind: oauth2-obo + flow: oauth2-token-exchange + clientId: ${jiraMcp.clientId} + clientSecret: ${jiraMcp.clientSecret} + tokenEndpoint: ${jiraMcp.tokenUrl} + targetType: audience + targetValue: ${jiraMcp.audience} + geminiConnection: + kind: llm + ref: + name: gemini + url: https://generativelanguage.googleapis.com + authentication: + kind: apiKey + apiKey: ${gemini.apiKey} + openaiConnection: + kind: llm + ref: + name: openai + url: https://api.openai.com/v1 + authentication: + kind: apiKey + apiKey: ${openai.apiKey} +brokers: + it-help-investigation: + kind: AgentScript + implementation: ./brokers/it-help-investigation.agent + interfaces: + a2a: + card: + name: IT Help Desk Broker + description: Triages IT support tickets, escalates critical issues, and resolves common problems through cross-platform investigation. + url: ${ingressgw.url}/it-help-investigation + version: 1.0.0 + protocolVersion: 0.3.0 + capabilities: + streaming: false + pushNotifications: true + defaultInputModes: + - text/plain + defaultOutputModes: + - text/plain + skills: + - id: ticket-triage + name: IT Ticket Triage + description: Classifies and resolves IT support tickets. + tags: + - it-support + - help-desk +---- + +*`it-help-investigation.agent` file:* + +[source,yaml] +---- +# @dialect: AGENTFABRIC=0.1-BETA +system: + instructions: "You are an IT Help Desk agent. You triage incoming support tickets, classify their severity, and either escalate, investigate, or request more information." +config: + agent_name: "it-help-investigation" + default_llm: @llm.gemini_flash +llm: + gemini_flash: + target: "llm://geminiConnection" + kind: "Gemini" + model: "gemini-2.5-flash" + openai_gpt: + target: "llm://openaiConnection" + kind: "OpenAI" + model: "gpt-5.4" + +# -- ACTION DEFINITIONS ------------------------------------------------------- +actions: + help_center_agent: + target: "a2a://helpCenterAgentConnection" + kind: "a2a:send_message" + license_procurement_agent: + target: "a2a://licenseProcurementAgentConnection" + kind: "a2a:send_message" + escalate_ticket: + target: "mcp://escalationMcpConnection" + kind: "mcp:tool" + tool_name: "escalate" + inputs: + ticket_id: string + severity: string + reason: string + description: string + update_jira_ticket: + target: "mcp://jiraMcpConnection" + kind: "mcp:tool" + tool_name: "updateIssue" + inputs: + ticket_id: string + status: string + comment: string + +# -- TRIGGER ------------------------------------------------------------------- +trigger ticketTrigger: + kind: "a2a" + target: "brokers://it-help-investigation/a2a" + on_message: -> + transition to @generator.classifySeverity + +# -- SEVERITY CLASSIFICATION --------------------------------------------------- +generator classifySeverity: + description: "Classifies the severity of the support ticket." + label: "Classify Severity" + system: + instructions: + Classify the severity of the incoming IT support ticket and extract the Jira ticket ID. + Severity Levels: + - High: System outage, security incident, or blocking issue affecting multiple users + (e.g. "VPN is down for the entire office", "Nobody in Building 3 can connect", + "unauthorized login attempts from an IP in another country") + - Low: General IT question, software request, or single-user issue + (e.g. "I forgot my VPN password", "rate limited on my Figma MCP server", + "I need access to Tableau") + If the ticket is too vague to classify confidently, default to low severity. + The ticket_id must always be a string value matching Jira's format: at least 3 characters + (the project name), a dash, and a number (e.g. "MULE-2321"). + If no Jira ticket ID is provided in the input, default ticket_id to "MULE-0001". + prompt: -> + {!@request.payload.message.parts[0].text} + outputs: + properties: + ticket_id: + type: "string" + description: "The Jira ticket ID extracted from the input (e.g. 'MULE-2321')" + severity: + type: "string" + description: "The severity level" + enum: + - "high" + - "low" + reason: + type: "string" + description: "Brief explanation of the classification" + on_exit: -> + transition to @router.severityRouter + +# -- SEVERITY ROUTING ---------------------------------------------------------- +router severityRouter: + description: "Routes based on the classified severity." + routes: + - target: @executor.escalateTicket + when: @generator.classifySeverity.output.severity == "high" + label: "High" + otherwise: + target: @orchestrator.crossPlatformTriage + +# -- HIGH: ESCALATION --------------------------------------------------------- +executor escalateTicket: + description: "Escalates the ticket using the Escalation MCP tool." + do: -> + run @actions.escalate_ticket + with ticket_id = @generator.classifySeverity.output.ticket_id + with severity = "high" + with reason = @generator.classifySeverity.output.reason + with description = @request.payload.message.parts[0].text + on_exit: -> + transition to @echo.escalationResponse + +echo escalationResponse: + kind: "a2a:response" + task: a2a.task({ + state: "completed", + message: a2a.message({ + messageId: uuid(), + parts: [ + a2a.textPart("Ticket " + @generator.classifySeverity.output.ticket_id + " has been escalated to the on-call team due to high severity: " + @generator.classifySeverity.output.reason) + ] + }), + metadata: None + }) + +# -- LOW: CROSS-PLATFORM TRIAGE ----------------------------------------------- +orchestrator crossPlatformTriage: + description: "Investigates the ticket using Help Center and License Procurement agents." + label: "Cross-Platform Triage" + llm: @llm.openai_gpt + system: + instructions: + Investigate this low-severity IT support ticket. + Step 1: Search the Help Center agent for relevant articles or known solutions. + Step 2: If the issue involves software licensing, check with the License Procurement agent. + Step 3: Update the Jira ticket with your findings and resolution. + If you found an answer from the Help Center, set resolution to "help_given". + If you resolved a licensing issue, set resolution to "license_given". + If you could not find a solution or the issue requires human intervention, set resolution to "unresolved". + Always update the Jira ticket with resolution notes. + reasoning: + instructions: -> + {!@request.payload.message.parts[0].text} + actions: + search_help: @actions.help_center_agent + check_license: @actions.license_procurement_agent + update_ticket: @actions.update_jira_ticket + with ticket_id = @generator.classifySeverity.output.ticket_id + with http_headers = {"Authorization": @request.headers.Authorization} + outputs: + properties: + resolution: + type: "string" + description: "The resolution type" + enum: + - "help_given" + - "license_given" + - "unresolved" + summary: + type: "string" + description: "Summary of the resolution and actions taken" + on_exit: -> + transition to @router.resolutionRouter + +# -- RESOLUTION ROUTING -------------------------------------------------------- +router resolutionRouter: + description: "Routes based on the resolution type from triage." + routes: + - target: @generator.licenseSummary + when: @orchestrator.crossPlatformTriage.output.resolution == "license_given" + label: "License Given" + - target: @executor.escalateUnresolved + when: @orchestrator.crossPlatformTriage.output.resolution == "unresolved" + label: "Unresolved" + otherwise: + target: @generator.helpSummary + +# -- HELP GIVEN PATH ---------------------------------------------------------- +generator helpSummary: + description: "Generates a summary of the help resolution." + system: + instructions: "You generate clear, friendly summaries of IT help desk resolutions." + prompt: -> + Generate a resolution summary for the user. Original request: {!@request.payload.message.parts[0].text}. Resolution and actions taken: {!@orchestrator.crossPlatformTriage.output.summary} + on_exit: -> + transition to @echo.helpResponse + +echo helpResponse: + kind: "a2a:response" + task: a2a.task({ + state: "completed", + message: a2a.message({ + messageId: uuid(), + parts: [ + a2a.textPart(@generator.helpSummary.output) + ] + }), + metadata: None + }) + +# -- LICENSE GIVEN PATH -------------------------------------------------------- +generator licenseSummary: + description: "Generates a summary of the license provisioning." + system: + instructions: "You generate clear, friendly summaries of license provisioning actions." + prompt: -> + Generate a license provisioning summary for the user. Original request: {!@request.payload.message.parts[0].text}. Resolution and actions taken: {!@orchestrator.crossPlatformTriage.output.summary} + on_exit: -> + transition to @echo.licenseResponse + +echo licenseResponse: + kind: "a2a:response" + task: a2a.task({ + state: "completed", + message: a2a.message({ + messageId: uuid(), + parts: [ + a2a.textPart(@generator.licenseSummary.output) + ] + }), + metadata: None + }) + +# -- UNRESOLVED PATH ----------------------------------------------------------- +executor escalateUnresolved: + description: "Escalates an unresolved low-severity ticket to a human agent." + do: -> + run @actions.escalate_ticket + with ticket_id = @generator.classifySeverity.output.ticket_id + with severity = "low" + with reason = @orchestrator.crossPlatformTriage.output.summary + with description = @request.payload.message.parts[0].text + on_exit: -> + transition to @echo.unresolvedResponse + +echo unresolvedResponse: + kind: "a2a:response" + task: a2a.task({ + state: "completed", + message: a2a.message({ + messageId: uuid(), + parts: [ + a2a.textPart("Ticket " + @generator.classifySeverity.output.ticket_id + " could not be resolved automatically and has been escalated to a human agent. Summary: " + @orchestrator.crossPlatformTriage.output.summary) + ] + }), + metadata: None + }) +---- + + diff --git a/agent-network/2.0/modules/ROOT/pages/af-get-started.adoc b/agent-network/2.0/modules/ROOT/pages/af-get-started.adoc new file mode 100644 index 000000000..27433356b --- /dev/null +++ b/agent-network/2.0/modules/ROOT/pages/af-get-started.adoc @@ -0,0 +1,66 @@ +[[get-started]] += Get Started with Agent Networks +:page-aliases: anypoint-code-builder::af-get-started.adoc + +include::partial$af-shared.adoc[tags=get-started] + +[[setup-space]] +== Set Up the Space or Deployment Target for Your Environment + +To deploy an agent network, you need a space on CloudHub 2.0 or a deployment target on Anypoint Runtime Fabric. On CloudHub 2.0, you can deploy to a shared space or a private space. + +Use a shared space if you don't require dedicated infrastructure. Use a private space if you need workload isolation or have other requirements that a shared space doesn't satisfy. + +Depending on your deployment target: + +* CloudHub 2.0 shared space: ++ +No setup is required. Every Anypoint Platform organization includes a shared space that's available to all business groups and environments. +* CloudHub 2.0 private space: ++ +. Create a private space in CloudHub 2.0 or verify that you can access an existing private space. ++ +To create a private space, see xref:cloudhub-2::ps-create-configure.adoc[]. +We recommend naming the private space `agent-network-space`. +. xref:cloudhub-2::ps-config-env.adoc[Associate the new or existing private space with the business groups and environments] where you plan to deploy your agent network. ++ +You must complete this step so that the private space appears as a valid deployment target in Anypoint Code Builder and Anypoint CLI. +* Runtime Fabric: ++ +Create a target space for Runtime Fabric. ++ +For information about Runtime Fabric deployments, see xref:gateway::flex-gateway-managed-set-up.adoc#rtf[Managed Omni Gateway on Runtime Fabric]. + +[[setup-gateways]] +== Set Up Agent Network Gateways for the Space or Deployment Target + +After you have a target space, use the `MuleSoft: Set Up Agent Network Gateways` command to create the gateways required for deployment in either CloudHub 2.0 or Runtime Fabric. + +For agent networks, you need at least one Managed Omni Gateway in your environment. A single gateway can handle both ingress and egress traffic, which is the recommended configuration. You can also use separate gateways for ingress and egress traffic in a private space. + +For more information about gateways, see xref:gateway::flex-architecture-basic-deployments.adoc[]. + +For more information about Runtime Fabric deployments, see xref:gateway::flex-gateway-managed-set-up.adoc#rtf[Managed Omni Gateway on Runtime Fabric]. + +. In Anypoint Code Builder, from the Command Palette, run the command *MuleSoft: Set Up Agent Network Gateways*. +. If you're not logged in, log in to your Anypoint Platform account. +. Select the business group and environment. +. Select the deployment target: ++ +* *Shared Space*: The command creates one gateway named `agent-network-shared-gw` that handles both ingress and egress traffic. +* *Private Space*: Select the target space, then choose a gateway configuration: ++ +** *Single Gateway* (recommended): The command creates one gateway named `agent-network-gw` that handles both ingress and egress traffic. +** *Separate Ingress & Egress*: The command creates two gateways: ++ +*** `agent-network-ingress-gw` (with public and internal endpoint) +*** `agent-network-egress-gw` (with internal endpoint only) ++ +If you didn't associate the private space with the business group and environment, you see an error. + +If a gateway with the expected name already exists in the selected space, the command doesn't recreate it. + +[[see-also]] +== See Also + +* xref:af-create-agent-network.adoc[] diff --git a/agent-network/2.0/modules/ROOT/pages/af-project-files.adoc b/agent-network/2.0/modules/ROOT/pages/af-project-files.adoc new file mode 100644 index 000000000..b44f64446 --- /dev/null +++ b/agent-network/2.0/modules/ROOT/pages/af-project-files.adoc @@ -0,0 +1,23 @@ += Agent Network 2.0 Project File Reference +:page-aliases: anypoint-code-builder::af-project-files.adoc + +An agent network project defines a structured configuration for multi-agent systems, enabling orchestration of AI agents with external services, tools, and inter-agent communication. This format provides a declarative way to define agent capabilities, dependencies, and service integrations. + +An agent network project includes these files: + +---- +/my-agent-network-project +├── agent-network.yaml +├── exchange.json +└── /brokers + └── broker1.agent +---- + +* `exchange.json`: Contains asset metadata available in Anypoint Exchange after publishing your agent network assets. +* `agent-network.yaml`: Contains a registry section that defines Exchange assets used in your project and a context section that defines connections and policies for the project. +* `.agent` files: Contain broker and node definitions and configurations that enable multi-agent orchestration in your project. + +* xref:af-agent-network-yaml-reference.adoc[] +* xref:af-agent-script-reference.adoc[] + +NOTE: For a complete, working example you can use as a starting point for your own agent network project, see xref:af-example-it-investigation-broker.adoc[Example: Building an IT Investigation Broker]. The example walks through a fully configured `agent-network.yaml`, `exchange.json`, and `/brokers` directory that you can adapt to your own project. diff --git a/agent-network/2.0/modules/ROOT/pages/af-publish-agent-network-assets.adoc b/agent-network/2.0/modules/ROOT/pages/af-publish-agent-network-assets.adoc new file mode 100644 index 000000000..dd9b77038 --- /dev/null +++ b/agent-network/2.0/modules/ROOT/pages/af-publish-agent-network-assets.adoc @@ -0,0 +1,60 @@ +[[publish-assets]] += Publish Agent Network Assets +:page-aliases: anypoint-code-builder::af-publish-agent-network-assets.adoc + +Build and publish your agent network project as Anypoint Exchange assets. When you publish, an asset is created for each broker, agent, and MCP server that's in your agent network. The asset ID is the value of the `name` key in `agent-network.yaml`. + +For example, suppose you have an agent name of `badging-agent` in `agent-network.yaml`. After it's published, the Exchange `assetId` is `badging-agent`. + +[[before-you-begin]] +== Before You Begin + +Make sure you review the xref:af-get-started.adoc#before-you-begin[prerequisites]. + +If you want to publish your project assets to a different business group, update the relevant `groupId` in `exchange.json`. + +== Versioning Assets + +Do not specify a semantic version (for example, `1.0.1`) each time you publish your project. Instead, enter a version group (for example, `V1` or `V2`) that represents the high-level version of your agent network project. Exchange handles the semantic versioning and automatically increments the version when there are changes. + +For existing projects, specify the same version group you were previously using. Specifying a different version group triggers a major semantic version upgrade (for example, `1.x.x` to `2.x.x`) for all associated assets. + +[[publish-dev-agent]] +== Publish Your Network Using MuleSoft Vibes + +Use MuleSoft Vibes to publish your agent network specification to Anypoint Exchange. For more information, see xref:anypoint-code-builder::api-ai-create-spec.adoc[]. + +. In the Anypoint Code Builder activity bar, click the agent icon image:af-acb-dev-agent-icon.png["",18,18]. +. Tell the agent that you want to publish your agent network. MuleSoft Vibes does the rest. + +To get started, try one of these suggested messages. + +* Publish my Employee Onboarding project. +* Publish my agent network project version 1.0.0. +* Publish the hello-world-network project to Exchange. +* Publish agent network project at /path/to/project with version 2.1.0. + +[[publish-acb]] +== Publish Your Network Using Anypoint Code Builder + +Use Anypoint Code Builder to publish your agent network assets directly from your project to Anypoint Exchange. + +. If you're not logged in already, log in to your Anypoint Platform account. +. In your Anypoint Code Builder project, choose one of the following: + . In Explorer, right-click a project file and select *Publish Agent Network Assets*. + . In the Command Palette, run this command: *MuleSoft: Publish Agent Network Assets*. +. In *Publish Agent Network Project Assets*, enter a version group for the project and review the project metadata. If you want to publish project assets to a different business group, update the `groupId` in `exchange.json`. +. Select *Publish*. +. Your agents, MCP servers, and LLM provider definitions are published to Exchange. An Exchange asset is created for each element in your agent network. + +Next, discover your agent network assets in *Agents & Tools* in Exchange to get a comprehensive view of your integration, including agent and MCP server assets. Exchange automatically tags brokers for easy identification. + +[[publish-cli]] +== Publish a Network Using the Anypoint CLI + +If you run operations within a CI/CD environment, you can use Anypoint CLI's plugin to set up, create, build, publish, and deploy agent networks. For more information, see xref:af-build-agent-networks-in-a-ci-cd-environment.adoc[]. + +[[see-also]] +== See Also + +* xref:af-deploy-agent-network-targets.adoc[] diff --git a/agent-network/2.0/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc b/agent-network/2.0/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc new file mode 100644 index 000000000..e1e032bc4 --- /dev/null +++ b/agent-network/2.0/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc @@ -0,0 +1,129 @@ += Troubleshoot Agent Networks +:page-aliases: anypoint-code-builder::af-troubleshoot-agent-networks.adoc, anypoint-code-builder::af-troubleshoot-anypoint-code-builder.adoc + +Resolve common agent network errors and connectivity issues by enabling verbose logging, message logging policies, and distributed tracing. Using logs and distributed traces, you can observe agents and MCP servers and see how requests flow through brokers, which tools and policies apply, and where failures or latency originate. + +[NOTE] +Use Agent Visualizer to xref:agent-visualizer::troubleshoot-agent-network.adoc[view metrics, logs, and traces] for agents and MCP servers in your network. + +== Enable Logging to Debug Agent Brokers + +Enable logging and log levels from CloudHub 2.0 or Runtime Fabric: + +. In Runtime Manager, navigate to the application for the agent broker. +. Choose one of these options to configure logging: ++ +* xref:cloudhub-2::ch2-manage-app-logs.adoc#configure-log-levels-and-categories[CloudHub 2.0] +* xref:runtime-fabric::deploy-to-runtime-fabric.adoc#configure-logging-and-log-levels[Runtime Fabric] +. For `INSECURE-LOGGING` set the log level to `DEBUG`. + +[IMPORTANT] +`INSECURE-LOGGING` is for content that can potentially contain sensitive information, such as LLM reasoning, and inputs and outputs from agents and assets defined in your agent network. This is very likely to contain sensitive information, such as personally identifiable information (PII). Make sure to disable `INSECURE-LOGGING` after you finish troubleshooting. + +[[enable-message-logging]] +== Enable Message Logging Policy + +Edit `agent-network.yaml` to set message logging for MCP servers and agents. + +Message logging uses the xref:gateway::policies-included-message-logging.adoc[Omni Gateway Message Logging policy]. In the `connection` section of the agent or MCP server instance you want to log, add the following logging policy inside `policies`: + +[source,yaml] +---- + +policies: ## add the following inside the policy setting + - ref: + name: message-logging + namespace: business_group_UUID + configuration: + loggingConfiguration: + - itemName: "Payload" + itemData: + message: "#[payload]" + firstSection: true + secondSection: true + level: "INFO" + - itemName: "Headers" + itemData: + message: "#[attributes]" + firstSection: true + secondSection: true + level: "INFO" +---- + +[NOTE] +On non-US control planes, the value for the `namespace` parameter can change. In Exchange, check the business group in the API Gateway Message Logging Policy Template. + +== Troubleshooting Common Issues and Errors + +Use the steps in this section to diagnose and fix common problems in agent networks. + +=== Issue: Traces Not Shown + +If Anypoint Monitoring isn't showing traces for agents and MCP servers, check these settings: + +* In API Manager, verify you've enabled the tracing policy for all brokers and agents. +* In the managed Omni Gateways, verify that you've enabled Distributed Tracing for ingress and egress. + +=== Issue: No Agent Network Commands in Anypoint Code Builder + +If you installed Anypoint Code Builder successfully, but you don’t see agent network commands in the interface, verify that you have the latest version of the Anypoint Extension Pack. Then, restart VS Code. + +=== Issue: No Agent Network Deployment Targets + +If you attempt to deploy an agent network, but you don’t see any deployment targets in Anypoint Code Builder or Anypoint CLI, then you need to set up your target deployment space and set up gateways. For instructions, see xref:af-get-started.adoc[Get Started with Agent Networks]. + +=== Issue: Changes Don't Take Effect After Redeployment + +If you update `agent-network.yaml` or any `.agent` files but changes aren't reflected after you redeploy, the deployment used the last compiled `target/` directory. Every source change requires a full rebuild. + +After any source file change, run the full pipeline: + +. Build +. Publish +. Deploy + +=== Error: "Asset belongs to another project" (Error 2006) + +If the project build succeeds but it fails to publish with error `2006`, your registry keys conflict with another project in the org. Registry keys are unique across an org, so you can't copy a project and rename only the broker. This leaves the original registry key prefixes, and the first project owns those Exchange asset IDs. + +To resolve this conflict: + +* Prefix every registry key with a unique network short ID (for example, `myNetRegistry` instead of `registry`). +* If you own the conflicting project, remove or delete it before you publish the new project. + +=== Error: CrashLoopBackOff or Exit 139 with No Clear Error + +If your deployment keeps restarting without a clear error, the broker is most likely crashing on a bad upstream connection before your agent network configuration is parsed. Common causes include: + +* An expired API key +* An incorrect MCP server URL +* An MCP server returning JSON instead of SSE +* A missing A2A agent card + +Before you deploy, validate every connection with live probes. Don't troubleshoot your agent network configuration until you confirm all upstream connections are healthy. + +=== Error: "Cannot complete task due to issue accessing reasoning engine" + +This is a generic error that the broker issues when the LLM fails. To troubleshoot this error, <> on the LLM instance, and then review the logs to determine the cause of the error. + +=== Issue: LLM Responds Without Calling the Agent or Tool + +If the broker responds with information from the LLM's training data instead of delegating to your agent or calling an MCP tool, the LLM's instructions aren't explicit enough about delegation. This is especially common with Gemini on widely-known topics. + +In the broker's system instructions: + +* Add a hard directive, such as `MUST delegate IMMEDIATELY` and `NEVER answer yourself`. +* Map every intent to a specific named action. + +=== Error: "HTTP error 404: Agent card not found at /.well-known/agent-card.json" + +You can encounter this error in two different scenarios: + +. The agent card URL is incorrect. In this case: ++ +* Check that the URL you set on the connection ends with a `/`. +* Use a browser or Postman to request the agent card URL by appending `.well-known/agent-card.json` to the connection URL, for example, `https://ping-id-agent-url/pingid/.well-known/agent-card.json`. +. The A2A agent is not configured to use A2A protocol version 1.0.0. In this case: ++ +* If you created the agent with MuleSoft, verify that you are using the latest version of the Anypoint Connector for A2A (A2A Connector). +* If you are using an external agent, verify that it uses the A2A protocol version 1.0.0. \ No newline at end of file diff --git a/modules/ROOT/pages/_partials/af-shared.adoc b/agent-network/2.0/modules/ROOT/partials/af-shared.adoc similarity index 63% rename from modules/ROOT/pages/_partials/af-shared.adoc rename to agent-network/2.0/modules/ROOT/partials/af-shared.adoc index cb4547a98..e08037bff 100644 --- a/modules/ROOT/pages/_partials/af-shared.adoc +++ b/agent-network/2.0/modules/ROOT/partials/af-shared.adoc @@ -76,7 +76,7 @@ If you're using the Anypoint CLI to create agent network projects, ensure you me * Node 20 (v20.19.4) or later. See https://nodejs.org/en[Nodejs.org]. * Java 17 or later. Set the `JAVA_HOME` environment variable. -* xref:anypoint-code-builder::af-build-agent-networks-in-a-ci-cd-environment.adoc[Anypoint CLI Fabric Plugin] +* xref:af-build-agent-networks-in-a-ci-cd-environment.adoc[Anypoint CLI Fabric Plugin] [[overview]] == Task Overview @@ -84,12 +84,12 @@ If you're using the Anypoint CLI to create agent network projects, ensure you me [[step-1-setup]] === Step 1: Set Up Your Agent Network -. Use Anypoint Runtime Manager to set up a private space in CloudHub 2.0 or deployment target in Runtime Fabric. +. Use Anypoint Runtime Manager to set up a space in CloudHub 2.0 or deployment target in Runtime Fabric. + -See xref:anypoint-code-builder::af-get-started.adoc#setup-space[Set Up the Private Space or Deployment Target for Your Environment]. -. Set up Ingress and egress Omni Gateways for the private space or deployment target. +See xref:anypoint-code-builder::af-get-started.adoc#setup-space[Set Up the Space or Deployment Target for Your Environment]. +. Set up Omni Gateways for the space or deployment target. + - * If using Anypoint Code Builder, see xref:anypoint-code-builder::af-get-started.adoc#setup-gateways[Set Up Agent Network Gateways for the Private Space or Deployment Target]. + * If using Anypoint Code Builder, see xref:anypoint-code-builder::af-get-started.adoc#setup-gateways[Set Up Agent Network Gateways for the Space or Deployment Target]. * If using the Anypoint CLI, see the xref:anypoint-code-builder::af-build-agent-networks-in-a-ci-cd-environment.adoc#agent-network-setup-gateways[setup gateways command reference]. [[step-2-create]] @@ -97,34 +97,34 @@ See xref:anypoint-code-builder::af-get-started.adoc#setup-space[Set Up the Priva Now you're ready to create an agent network project. Choose one of these methods. -* xref:anypoint-code-builder::af-create-agent-network.adoc#create-dev-agent[Create a Network Using MuleSoft Vibes] -* xref:anypoint-code-builder::af-create-agent-network.adoc#create-acb[Create a Network Using Anypoint Code Builder] -* xref:anypoint-code-builder::af-create-agent-network.adoc#create-cli[Create a Network Using the Anypoint CLI] +* xref:af-create-agent-network.adoc#create-dev-agent[Create a Network Using MuleSoft Vibes] +* xref:af-create-agent-network.adoc#create-acb[Create a Network Using Anypoint Code Builder] +* xref:af-create-agent-network.adoc#create-cli[Create a Network Using the Anypoint CLI] [[step-3-define]] === Step 3: Define Your Agent Network Specification After you create your agent network project, configure `agent-network.yaml` and `exchange.json` to reflect the structure of your network. -* xref:anypoint-code-builder::af-define-your-agent-network-specification.adoc#define-dev-agent[Define a Network Using MuleSoft Vibes] -* xref:anypoint-code-builder::af-define-your-agent-network-specification.adoc#define-acb-ide[Define a Network Using Anypoint Code Builder or IDE] +* xref:af-define-your-agent-network-specification.adoc#define-dev-agent[Define a Network Using MuleSoft Vibes] +* xref:af-define-your-agent-network-specification.adoc#define-acb-ide[Define a Network Using Anypoint Code Builder or IDE] [[step-4-publish]] === Step 4: Publish Your Agent Network Assets Build and publish your agent network project as Anypoint Exchange assets. When you publish the agent network, an asset is created in Exchange for each broker, agent, and MCP server that's in your agent network. -* xref:anypoint-code-builder::af-publish-agent-network-assets.adoc#publish-dev-agent[Publish Your Network Using MuleSoft Vibes] -* xref:anypoint-code-builder::af-publish-agent-network-assets.adoc#publish-acb[Publish Your Network Using Anypoint Code Builder] -* xref:anypoint-code-builder::af-build-agent-networks-in-a-ci-cd-environment.adoc#agent-network-project-publish[Publish Your Network Using the Anypoint CLI] +* xref:af-publish-agent-network-assets.adoc#publish-dev-agent[Publish Your Network Using MuleSoft Vibes] +* xref:af-publish-agent-network-assets.adoc#publish-acb[Publish Your Network Using Anypoint Code Builder] +* xref:af-build-agent-networks-in-a-ci-cd-environment.adoc#agent-network-project-publish[Publish Your Network Using the Anypoint CLI] [[step-5-deploy]] === Step 5: Deploy Your Agent Network Instances -Deploy your agent network instance to a deployment target. You can deploy to a CloudHub 2.0 private space or to a Runtime Fabric. +Deploy your agent network instance to a deployment target. You can deploy to a CloudHub 2.0 shared space, a CloudHub 2.0 private space, or to Runtime Fabric. -* xref:anypoint-code-builder::af-deploy-agent-network-targets.adoc#deploy-dev-agent[Deploy Your Network Using MuleSoft Vibes] -* xref:anypoint-code-builder::af-deploy-agent-network-targets.adoc#deploy-acb[Deploy Your Network Using Anypoint Code Builder] -* xref:anypoint-code-builder::af-build-agent-networks-in-a-ci-cd-environment.adoc#agent-network-project-deploy[Deploy Your Network Using the Anypoint CLI] +* xref:af-deploy-agent-network-targets.adoc#deploy-dev-agent[Deploy Your Network Using MuleSoft Vibes] +* xref:af-deploy-agent-network-targets.adoc#deploy-acb[Deploy Your Network Using Anypoint Code Builder] +* xref:af-build-agent-networks-in-a-ci-cd-environment.adoc#agent-network-project-deploy[Deploy Your Network Using the Anypoint CLI] // end::get-started[] // diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 7829df9b5..5662145aa 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -29,16 +29,6 @@ *** xref:tut-slack-add-condition-to-your-flow.adoc[] *** xref:tut-slack-configure-integration.adoc[] -//AGENTFORCE -* xref:af-agent-networks.adoc[] -** xref:af-get-started.adoc[] -** xref:af-create-agent-network.adoc[] -** xref:af-define-your-agent-network-specification.adoc[] -** xref:af-publish-agent-network-assets.adoc[] -** xref:af-deploy-agent-network-targets.adoc[] -** xref:af-troubleshoot-agent-networks.adoc[] -** xref:af-build-agent-networks-in-a-ci-cd-environment.adoc[] -** xref:af-project-files.adoc[] * xref:ai-enabling-api-project-topic-center.adoc[] // USE AI TO DESIGN AN API SPEC diff --git a/modules/ROOT/pages/af-define-your-agent-network-specification.adoc b/modules/ROOT/pages/af-define-your-agent-network-specification.adoc deleted file mode 100644 index 5e5be9967..000000000 --- a/modules/ROOT/pages/af-define-your-agent-network-specification.adoc +++ /dev/null @@ -1,73 +0,0 @@ -[[define-spec]] -= Define Your Agent Network Specification - -After you create your agent network project, configure `agent-network.yaml` and `exchange.json` to reflect the structure of your network. - -[[before-you-begin]] -== Before You Begin - -Make sure you review the xref:af-get-started.adoc#before-you-begin[prerequisites]. - -[TIP] -To help you identify agents that are also brokers on the Anypoint Code Builder canvas, consider appending "Broker" to the end of the name, for example `employee-onboarding-broker`. - -[[define-dev-agent]] -== Define a Network Using MuleSoft Vibes - -MuleSoft Vibes can help you configure your agent network specification. For more information, see xref:anypoint-code-builder::api-ai-create-spec.adoc[]. - -. In the Anypoint Code Builder activity bar, click the agent icon image:af-acb-dev-agent-icon.png["",18,18]. -. Give the agent information about your agent network, including the brokers, agents, MCP servers, and LLMs you want to connect. - -To get started, try one of these suggested messages. - -* Help me build an agent network configuration for my Employee Onboarding project. -* Revise my Employee Onboarding agent network project. Use OpenAI for the LLM. -* Add a new broker for employee offboarding to my HR agent network. -* Add a new skill to Offboarding broker. - -[[define-acb-ide]] -== Define a Network Using Anypoint Code Builder or IDE - -If you don't want to use MuleSoft Vibes, use Anypoint Code Builder or your IDE to edit the `agent-network.yaml` and `exchange.json` files and define your agent network and authentication. - -To understand sections of the project files and expected values, see xref:anypoint-code-builder::af-project-files.adoc[Agent Network Project File Reference]. The `agent-network.yaml` file can contain definitions for one or more brokers. - -If your agent network references Anypoint Exchange assets, you need to use the asset IDs in `exchange.json` to add references in the `agent-network.yaml` file. For more information, see <>. - -Use auto-completion menus in Anypoint Code Builder to speed your development. For more information, see xref:anypoint-code-builder::start-discover-ui.adoc#use-autocomplete[Use Auto-Completion Menus]. - -[[add-exchange-assets]] -== Add Exchange Assets to Your Agent Network Project - -If you have existing Exchange assets to use in your agent network, add them to the `dependencies` attribute in `exchange.json` in your project. After you add assets, edit the `agent-network.yaml` file to indicate which brokers use those assets. - -=== Add Assets Using MuleSoft Vibes - -. In the Anypoint Code Builder activity bar, click the agent icon image:af-acb-dev-agent-icon.png["",18,18]. -. Tell the agent that you want to add Exchange assets to your project. MuleSoft Vibes does the rest. - -To get started, try one of these suggested messages. - -* Add tools for background check processing in my Employee Onboarding project. -* Add a Talent Pool MCP server to my Employee Onboarding agent network project. - -[[add-assets-acb]] -=== Add Assets Using Anypoint Code Builder - -. If you're not logged in already, log in to your Anypoint Platform account. -. In your Anypoint Code Builder project, choose one of the following: - * In Explorer, right-click a project file and select *Add Exchange Assets to Agent Network Project*. - * In the Command Palette, run this command: *MuleSoft: Add Agent Network Assets to Agent Network Project*. -. In Add Exchange Assets to Project, enter information about the assets to add. -. Select *Add to Project*. -+ -Assets are added to the `dependencies` attribute in the `exchange.json` file in your project. -. Edit the `agent-network.yaml` file to indicate which brokers use those assets. - - If you added a dependency that doesn't belong to the same business group as your agent network, then in `agent-network.yaml`, specify the `namespace` property at the same level as `name`. Provide the `groupId` (business group ID) for the business group that the dependency belongs to. The `groupId` value is the same as the `groupId` value of the corresponding dependency in `exchange.json`. - -If you don't provide a namespace value, the same `groupId` as the agent network project is used. - -After you add dependencies, they're available as values in auto-completion menus in Anypoint Code Builder. For example, after you add `test-agent` to `exchange.json`, the value `test-agent` is available in auto-completion menus in the code editor in `agent-network.yaml` when you reference an agent. -