# mulesoft Building Agent Networks - Full Documentation

<!-- document id=35ab40b44e4f610087e93ef7c0b8876e3a01c67560d52e7c9a5bcfbd69a4a4b8 url=/mulesoft/current/en-us/agent-network/latest/af-agent-network-yaml-reference.md -->

---
product: Building Agent Networks
version: 2.0
is-latest-version: true
---

# Agent Network (2.0) YAML Reference

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The `agent-network.yaml` file details the required structure and properties that define your
project’s assets, connections, and policies.

- [Agent Network Section](#agent-network-section)

- [Info Section](#info-section)

- [Registry Section](#registry-section)

- [Context Section](#context-section)

- [Brokers Section](#brokers-section)

- [Expressions Format](#expressions-format)

- [Exchange JSON File](#exchange-json-file)

  - [Runtime System Limits Configuration](#runtime-system-limits)

## Agent Network Section

This is the root section of the agent network. Must include at least one of `registry`, `context`,
or `brokers`.

This section has these properties.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p>info</p></td><td><p>Provides metadata about the graphs.</p></td><td><p><a href="#info-section">info Object</a></p></td><td><p>No</p></td></tr><tr><td><p>agentNetwork</p></td><td><p>This string must be the version number of the agent network specification used by the agent network document. This is not related to the document’s <code>info.version</code> property.</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p>registry</p></td><td><p>Definitions of agents, MCPs, and LLMs.</p></td><td><p><a href="#registry-section">registry</a> Object</p></td><td><p>No</p></td></tr><tr><td><p>context</p></td><td><p>Reusable entities scoped to the graphs defined in this file (for example, connections and policies).</p></td><td><p>Object</p></td><td><p>No</p></td></tr><tr><td><p>brokers</p></td><td><p>A mapping of runtime Agent Script definitions that can be executed by the platform.</p></td><td><p><a href="#brokers-section">brokers Object</a></p></td><td><p>No</p></td></tr></tbody></table>

## Info Section

This section contains basic metadata about the agent network document itself.

**Example**

```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.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p>label</p></td><td><p>The human-readable name of the agent network.</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p>version</p></td><td><p>The version number of the <code>agent-network.yaml</code> file.</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p>description</p></td><td><p>A human readable summary of what the agent network does.  Accepts CommonMark syntax.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p>tags</p></td><td><p>Categorization tags for this agent network document.</p></td><td><p>Array of Strings</p></td><td><p>No</p></td></tr><tr><td><p><code>summary</code></p></td><td><p>A short summary of the purpose of the agent network.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>termsOfService</code></p></td><td><p>A URI for the Terms of Service for the API. This must be in the form of a URI.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>contact</code></p></td><td><p>The contact information for the agent network.</p></td><td><p>Object</p></td><td><p>No</p></td></tr><tr><td><p><code>contact.name</code></p></td><td><p>The identifying name of the contact person/organization.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>contact.url</code></p></td><td><p>The URI for the contact information. This must be in the form of a URI.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>contact.email</code></p></td><td><p>The email address of the contact person/organization. This must be in the form of an email address.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>license</code></p></td><td><p>The license information for the agent network.</p></td><td><p>Object</p></td><td><p>No</p></td></tr><tr><td><p><code>license.name</code></p></td><td><p>The license name used for the agent network.</p></td><td><p>String</p></td><td><p>Yes (if license present)</p></td></tr><tr><td><p><code>license.identifier</code></p></td><td><p>An SPDX license expression. Mutually exclusive with <code>license.url</code>.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>license.url</code></p></td><td><p>A URI for the license. This must be in the form of a URI. Mutually exclusive with <code>license.identifier</code>.</p></td><td><p>String</p></td><td><p>No</p></td></tr></tbody></table>

## 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**

```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
        interfaces:
          a2a:
            card:
              name: hr-system-agent
              description: Creates and manages employee records in the HR system.
              version: "1.0.0"
              capabilities: {}
              defaultInputModes: [application/json, text/plain]
              defaultOutputModes: [application/json, text/plain]
              supportedInterfaces:
                - url: https://hr-agent.example.com/a2a
                  protocolBinding: JSONRPC
                  protocolVersion: "1.0"
              skills: []
        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
        interfaces:
          a2a:
            card:
              name: salesforce-agent
              description: Onboards new employees to Salesforce.
              version: "1.0.0"
              capabilities: {}
              defaultInputModes: [application/json]
              defaultOutputModes: [application/json]
              supportedInterfaces:
                - url: https://sfdc-agent.example.com/a2a
                  protocolBinding: JSONRPC
                  protocolVersion: "1.0"
              skills: []
        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.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th><th>Values</th></tr></thead><tbody><tr><td><p><code>agents</code></p></td><td><p>The list of agents defined as part of this network.</p></td><td><p>Object</p></td><td><p>No</p></td><td><p>Keys: identifiers matching ^[a-zA-Z_][a-zA-Z0-9_.-]*$. Values: AgentEntity</p></td></tr><tr><td><p><code>mcps</code></p></td><td><p>The list of MCP servers defined as part of this network.</p></td><td><p>Object</p></td><td><p>No</p></td><td><p>Keys: identifiers. Values: MCPServerEntity</p></td></tr><tr><td><p><code>llms</code></p></td><td><p>The list of LLM providers defined as part of this network.</p></td><td><p>Object</p></td><td><p>No</p></td><td><p>Keys: identifiers. Values: LLMEntity. Each <code>LLMEntity</code> requires <code>metadata.platform</code>, which can be <code>Gemini</code>, <code>OpenAI</code>, <code>AzureOpenai</code>, or a custom platform name.</p></td></tr></tbody></table>

### LLMs

Each LLM entity requires `metadata.platform`. The optional `metadata.authentication` array declares
the authentication kinds that the LLM platform supports and can provide default configuration
values. If `authentication` is absent, the LLM platform’s authentication requirements are unknown.
An array that contains only `kind: none` explicitly declares that the platform doesn’t require
authentication.

LLM metadata can declare `none`, `basic`, `apiKey`, `apikey-client-credentials`,
`oauth2-client-credentials`, `amazonSigv4`, or `custom`. A connection to the LLM can’t use `custom`
authentication.

For example, this LLM declares OAuth 2.0 client credentials authentication and its token endpoint as
defaults:

```yaml
registry:
  llms:
    my-llm:
      info:
        label: My LLM
      metadata:
        platform: SomeCustomPlatform
        authentication:
          - kind: oauth2-client-credentials
            defaultConfiguration:
              token:
                url: https://auth.example.com/token
```

### Info

All nodes in this section share these properties.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>label</code></p></td><td><p>The human readable short text.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>description</code></p></td><td><p>A human readable text of what this element does. Accepts CommonMark syntax.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>tags</code></p></td><td><p>Optional tags.</p></td><td><p>Array of Strings</p></td><td><p>No</p></td></tr></tbody></table>

### Agents

Each registry agent is an `AgentEntity`. The schema requires a `metadata` object. The interfaces,
tools, and LLM reference are nested under `metadata`, not at the root of the agent.

The agents section has these properties.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>agents.info</code></p></td><td><p>Metadata for the agent.</p></td><td><p>InfoObject</p></td><td><p>No</p></td></tr><tr><td><p><code>agents.metadata</code></p></td><td><p>Platform, interfaces, tools, and LLM wiring for the agent.</p></td><td><p>Object</p></td><td><p>Yes</p></td></tr><tr><td><p><code>agents.metadata.platform</code></p></td><td><p>Host platform for the agent (for example, AgentForce or Bedrock).</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p><code>agents.metadata.interfaces</code></p></td><td><p>The interfaces that this agent supports. At least one of <code>a2a</code>, <code>a2a_v03</code>, or <code>other</code> must be present.</p></td><td><p>Object</p></td><td><p>Yes</p></td></tr><tr><td><p><code>agents.metadata.interfaces.a2a</code></p></td><td><p>A2A protocol version 1.x interface definition. Contains the agent card.</p></td><td><p>Object</p></td><td><p>No (at least one interface required)</p></td></tr><tr><td><p><code>agents.metadata.interfaces.a2a.card</code></p></td><td><p>The A2A v1 agent card. See <a href="#a2a-card">A2A Card</a>.</p></td><td><p>AgentCard</p></td><td><p>No</p></td></tr><tr><td><p><code>agents.metadata.interfaces.a2a_v03</code></p></td><td><p>A2A protocol version 0.3.x interface definition (legacy).</p></td><td><p>Object</p></td><td><p>No (at least one interface required)</p></td></tr><tr><td><p><code>agents.metadata.interfaces.a2a_v03.card</code></p></td><td><p>The A2A v0.3 agent card.</p></td><td><p>AgentCard</p></td><td><p>No</p></td></tr><tr><td><p><code>agents.metadata.interfaces.other</code></p></td><td><p>Other protocol interface definition.</p></td><td><p>Object</p></td><td><p>No (at least one interface required)</p></td></tr><tr><td><p><code>agents.metadata.interfaces.other.protocol</code></p></td><td><p>The protocol name for this interface.</p></td><td><p>String</p></td><td><p>Yes (when using other)</p></td></tr><tr><td><p><code>agents.metadata.interfaces.other.card</code></p></td><td><p>The card for this protocol.</p></td><td><p>Object</p></td><td><p>No</p></td></tr><tr><td><p><code>agents.urls</code></p></td><td><p>Named URLs for the agent.</p></td><td><p>Array</p></td><td><p>No</p></td></tr><tr><td><p><code>agents.metadata.tools</code></p></td><td><p>The list of tool providers (MCP or A2A)</p></td><td><p>Array[Object]</p></td><td><p>No</p></td></tr><tr><td><p><code>agents.metadata.llm</code></p></td><td><p>Reference to the LLM used by this agent (ref to a declared LLM)</p></td><td><p>Object</p></td><td><p>No</p></td></tr></tbody></table>

Authentication for outbound calls is configured on [`connections`](#connections) (and related
policies), not on registry `AgentEntity` definitions.

> [!NOTE] If you are connecting to an agent that uses A2A protocol version 0.3.x, use the `a2a_v03`
> interface key instead of `a2a`. The `a2a` key targets A2A protocol version 1.x.

#### 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
[as defined in the Agent2Agent (A2A) Protocol specification](https://a2a-protocol.org/latest/specification/#441-agentcard).

The A2A card section has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th><th>Values</th></tr></thead><tbody><tr><td><p><code>name</code></p></td><td><p>A human-readable name for the agent.</p></td><td><p>String</p></td><td><p>No</p></td><td><p> — </p></td></tr><tr><td><p><code>description</code></p></td><td><p>A human-readable description of the agent.</p></td><td><p>String</p></td><td><p>No</p></td><td><p> — </p></td></tr><tr><td><p><code>version</code></p></td><td><p>The version of the agent (format defined by provider).</p></td><td><p>String</p></td><td><p>No</p></td><td><p>for example, 1.0.0</p></td></tr><tr><td><p><code>capabilities</code></p></td><td><p>Optional capabilities supported by the agent.</p></td><td><p>AgentCapabilities</p></td><td><p>No</p></td><td><p>See <a href="#capabilities-properties">Capabilities Properties</a></p></td></tr><tr><td><p><code>defaultInputModes</code></p></td><td><p>Interaction modes the agent supports across all skills (media types).</p></td><td><p>Array of String</p></td><td><p>No</p></td><td><p> — </p></td></tr><tr><td><p><code>defaultOutputModes</code></p></td><td><p>Media types supported as outputs from this agent.</p></td><td><p>Array of String</p></td><td><p>No</p></td><td><p> — </p></td></tr><tr><td><p><code>skills</code></p></td><td><p>The set of skills or distinct capabilities the agent can perform.</p></td><td><p>Array of AgentSkill</p></td><td><p>No</p></td><td><p>See <a href="#skills-properties">Skills Properties</a></p></td></tr><tr><td><p><code>supportedInterfaces</code></p></td><td><p>Transport and URL combinations for interacting with the agent.</p></td><td><p>Array of AgentInterface</p></td><td><p>No</p></td><td><p>See <a href="#agent-interface-properties">Agent Interface Properties</a></p></td></tr><tr><td><p><code>provider</code></p></td><td><p>The service provider of the agent.</p></td><td><p>AgentProvider</p></td><td><p>No</p></td><td><p>{ organization: string, url: string }</p></td></tr><tr><td><p><code>documentationUrl</code></p></td><td><p>A URL providing additional documentation about the agent.</p></td><td><p>String</p></td><td><p>No</p></td><td><p> — </p></td></tr><tr><td><p><code>iconUrl</code></p></td><td><p>A URL to an icon for the agent.</p></td><td><p>String</p></td><td><p>No</p></td><td><p> — </p></td></tr><tr><td><p><code>security</code></p></td><td><p>Security requirement objects for all interactions (OpenAPI 3.0 style; OR of ANDs).</p></td><td><p>Array of Object</p></td><td><p>No</p></td><td><p>Each object: scheme names → array of scope strings</p></td></tr><tr><td><p><code>securitySchemes</code></p></td><td><p>Declared security schemes (key \= scheme name). OpenAPI 3.0 Security Scheme Object.</p></td><td><p>Object</p></td><td><p>No</p></td><td><p>apiKey, http, oauth2, openIdConnect, mutualTLS</p></td></tr><tr><td><p><code>signatures</code></p></td><td><p>JSON Web Signatures for this AgentCard (RFC 7515 JWS).</p></td><td><p>Array of AgentCardSignature</p></td><td><p>No</p></td><td><p>{ protected, signature, header? }</p></td></tr></tbody></table>

##### Skills Properties

Skills describe the distinct capabilities the agent can perform and have these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>id</code></p></td><td><p>Unique identifier for the skill.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>No</p></td></tr><tr><td><p><code>name</code></p></td><td><p>A human-readable name for the skill.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>No</p></td></tr><tr><td><p><code>description</code></p></td><td><p>A description of what this skill does.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>No</p></td></tr><tr><td><p><code>examples</code></p></td><td><p>Usage examples demonstrating how to use this skill.</p></td><td><p>Array of strings</p></td><td><p>Array of example strings</p></td><td><p>No</p></td></tr><tr><td><p><code>inputModes</code></p></td><td><p>Supported input MIME types for this skill (overrides defaultInputModes).</p></td><td><p>Array of strings</p></td><td><p>Array of MIME type strings</p></td><td><p>No</p></td></tr><tr><td><p><code>outputModes</code></p></td><td><p>Supported output MIME types for this skill (overrides defaultOutputModes).</p></td><td><p>Array of strings</p></td><td><p>Array of MIME type strings</p></td><td><p>No</p></td></tr><tr><td><p><code>tags</code></p></td><td><p>Categorization tags for this skill.</p></td><td><p>Array of strings</p></td><td><p>Array of tag strings</p></td><td><p>No</p></td></tr><tr><td><p><code>securityRequirements</code></p></td><td><p>Security requirements specific to this skill.</p></td><td><p>Array of SecurityRequirement</p></td><td><p>Array of security requirement objects</p></td><td><p>No</p></td></tr></tbody></table>

##### Capabilities Properties

Capabilities describe optional features supported by the agent and have these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>streaming</code></p></td><td><p>Indicates if the agent supports streaming responses.</p></td><td><p>Boolean</p></td><td><p><code>true</code> or <code>false</code></p></td><td><p>No</p></td></tr><tr><td><p><code>pushNotifications</code></p></td><td><p>Indicates if the agent supports push notifications.</p></td><td><p>Boolean</p></td><td><p><code>true</code> or <code>false</code></p></td><td><p>No</p></td></tr><tr><td><p><code>extendedAgentCard</code></p></td><td><p>Indicates if the agent supports providing an extended agent card when authenticated.</p></td><td><p>Boolean</p></td><td><p><code>true</code> or <code>false</code></p></td><td><p>No</p></td></tr><tr><td><p><code>extensions</code></p></td><td><p>List of protocol extensions supported by the agent.</p></td><td><p>Array of AgentExtension</p></td><td><p>See below</p></td><td><p>No</p></td></tr></tbody></table>

##### Agent Extension Properties

Each extension object describes a protocol extension supported by the agent.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>uri</code></p></td><td><p>The unique URI identifying the extension.</p></td><td><p>String</p></td><td><p>Any URI string</p></td><td><p>No</p></td></tr><tr><td><p><code>description</code></p></td><td><p>Human-readable description of how this agent uses the extension.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>No</p></td></tr><tr><td><p><code>required</code></p></td><td><p>If true, the client must understand and comply with the extension’s requirements.</p></td><td><p>Boolean</p></td><td><p><code>true</code> or <code>false</code> (default: <code>false</code>)</p></td><td><p>No</p></td></tr><tr><td><p><code>params</code></p></td><td><p>Extension-specific configuration parameters.</p></td><td><p>Object</p></td><td><p>Any JSON object</p></td><td><p>No</p></td></tr></tbody></table>

##### Agent Interface Properties

Each interface object declares a transport and URL combination for interacting with the agent.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>url</code></p></td><td><p>The URL where this interface is available.</p></td><td><p>String</p></td><td><p>Valid URI string</p></td><td><p>No</p></td></tr><tr><td><p><code>protocolBinding</code></p></td><td><p>The protocol binding for this interface.</p></td><td><p>String</p></td><td><p><code>JSONRPC</code>, <code>GRPC</code>, <code>HTTP+JSON</code></p></td><td><p>No</p></td></tr><tr><td><p><code>protocolVersion</code></p></td><td><p>The A2A protocol version for this interface.</p></td><td><p>String</p></td><td><p>For example, 1.0<br><br>IMPORTANT: The A2A protocol version you declare for a connection must match the deployed agent’s actual runtime protocol version. A mismatch causes the platform to apply the wrong Agent Card policy, which prevents the agent card URL from being rewritten to the egress proxy and results in a <code>401 Unauthorized</code> error at runtime rather than a version error.</p></td><td><p>No</p></td></tr><tr><td><p><code>tenant</code></p></td><td><p>Tenant ID to be used in the request when calling the agent.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>No</p></td></tr></tbody></table>

### MCP

The MCP Server section has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th><th>Values</th></tr></thead><tbody><tr><td><p><code>info</code></p></td><td><p>Metadata for the MCP Server</p></td><td><p><code>InfoObject</code></p></td><td><p>No</p></td><td><p> — </p></td></tr><tr><td><p><code>urls</code></p></td><td><p>Named URLs for the MCP server.</p></td><td><p>Array</p></td><td><p>No</p></td><td><p> — </p></td></tr><tr><td><p><code>metadata</code></p></td><td><p>MCP server descriptor (how to connect and what it exposes).</p></td><td><p>Object</p></td><td><p>Yes</p></td><td><p> — </p></td></tr><tr><td><p><code>metadata.protocolVersion</code></p></td><td><p>Version of the MCP protocol.</p></td><td><p>String</p></td><td><p>No</p></td><td><p>"2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25"</p></td></tr><tr><td><p><code>metadata.transport</code></p></td><td><p>Transport used for communication.</p></td><td><p>MCPTransport</p></td><td><p>Yes</p></td><td><p>SseTransport, StreamableHttpTransport, or StdioTransport</p></td></tr><tr><td><p><code>metadata.provider</code></p></td><td><p>Service provider of the MCP server.</p></td><td><p>Object</p></td><td><p>No</p></td><td><p>{ organization: string, url: string }</p></td></tr><tr><td><p><code>metadata.capabilities</code></p></td><td><p>Server capabilities.</p></td><td><p>ServerCapabilities</p></td><td><p>No</p></td><td><p>completions, experimental, tasks, logging, prompts, resources, tools</p></td></tr><tr><td><p><code>metadata.tools</code></p></td><td><p>List of tools.</p></td><td><p>Array</p></td><td><p>No</p></td><td><p>action definitions</p></td></tr><tr><td><p><code>metadata.resources</code></p></td><td><p>List of resources.</p></td><td><p>Array</p></td><td><p>No</p></td><td><p>Resource definitions</p></td></tr><tr><td><p><code>metadata.resourceTemplates</code></p></td><td><p>List of resource templates.</p></td><td><p>Array</p></td><td><p>No</p></td><td><p>ResourceTemplate definitions</p></td></tr><tr><td><p><code>metadata.prompts</code></p></td><td><p>List of prompts.</p></td><td><p>Array</p></td><td><p>No</p></td><td><p>Prompt definitions</p></td></tr><tr><td><p><code>metadata.platform</code></p></td><td><p>Platform the MCP server runs on.</p></td><td><p>String</p></td><td><p>No</p></td><td><p> — </p></td></tr><tr><td><p><code>metadata.securitySchemes</code></p></td><td><p>Security schemes for authentication.</p></td><td><p>Object</p></td><td><p>No</p></td><td><p>SecurityScheme by key</p></td></tr></tbody></table>

#### 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**

```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.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th><th>Values</th></tr></thead><tbody><tr><td><p><code>kind</code></p></td><td><p>Transport type.</p></td><td><p>String</p></td><td><p>Yes</p></td><td><p><code>"sse"</code></p></td></tr><tr><td><p><code>ssePath</code></p></td><td><p>Path to the SSE endpoint.</p></td><td><p>String</p></td><td><p>Yes</p></td><td><p> — </p></td></tr><tr><td><p><code>messagesPath</code></p></td><td><p>Path to the messages endpoint.</p></td><td><p>String</p></td><td><p>No</p></td><td><p>Agent Graph Expression Optional</p></td></tr></tbody></table>

##### StreamableHttpTransport

StreamableHttpTransport has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th><th>Values</th></tr></thead><tbody><tr><td><p><code>kind</code></p></td><td><p>Transport type.</p></td><td><p>String</p></td><td><p>Yes</p></td><td><p>"streamableHttp"</p></td></tr><tr><td><p><code>path</code></p></td><td><p>Path to the MCP endpoint.</p></td><td><p>String</p></td><td><p>No</p></td><td><p> — </p></td></tr></tbody></table>

##### StdioTransport

StdioTransport has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th><th>Values</th></tr></thead><tbody><tr><td><p><code>kind</code></p></td><td><p>Transport type.</p></td><td><p>String</p></td><td><p>Yes</p></td><td><p><code>"stdio"</code></p></td></tr><tr><td><p><code>instructions</code></p></td><td><p>Instructions to run the MCP server.</p></td><td><p>String</p></td><td><p>No</p></td><td><p> — </p></td></tr></tbody></table>

### 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**

```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.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Reference</th><th>Description</th><th>Type</th><th>Required</th><th>Values</th></tr></thead><tbody><tr><td><p><code>AgentRef</code></p></td><td><p>Reference to an agent.</p></td><td><p>Object</p></td><td><p>No</p></td><td><p><code>{ name: string, namespace?: string }</code></p></td></tr><tr><td><p><code>MCPRef</code></p></td><td><p>Reference to an MCP server.</p></td><td><p>Object</p></td><td><p>No</p></td><td><p><code>{ name: string, namespace?: string }</code></p></td></tr><tr><td><p><code>LLMRef</code></p></td><td><p>Reference to an LLM provider.</p></td><td><p>Object</p></td><td><p>No</p></td><td><p><code>{ name: string, namespace?: string }</code></p></td></tr><tr><td><p><code>ConnectionRef</code></p></td><td><p>Reference to a connection.</p></td><td><p>Object</p></td><td><p>No</p></td><td><p><code>{ name: string }</code></p></td></tr><tr><td><p><code>PolicyRef</code></p></td><td><p>Reference to a policy.</p></td><td><p>Object</p></td><td><p>No</p></td><td><p><code>{ name: string, namespace?: string }</code></p></td></tr></tbody></table>

## 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**

```yaml
context:
  connections:
    hr_system_agent:
      kind: a2a
      ref:
        name: hr-system-agent
      url: https://hr-agent.example.com/a2a
      policies:
        outbound:
          - ref:
              name: retry-policy
    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
    openai_llm:
      kind: llm
      ref:
        name: Open-AI-LLM
      url: https://api.openai.com/v1
      authentication:
        kind: apiKey
        apiKey: "${env.OPENAI_API_KEY}"
  policies:
    retry-policy:
      ref:
        name: retry-policy
      configuration:
        maxAttempts: 3
        backoffMs: 1000
```

The `context` section has these properties.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th></tr></thead><tbody><tr><td><p>connections</p></td><td><p>The list of connections defined as part of this network.</p></td><td><p>Connection Objects</p></td></tr><tr><td><p>policies</p></td><td><p>Policy definitions that govern connection behavior, access, and execution.</p></td><td><p>Policies Object</p></td></tr></tbody></table>

### 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.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Field Name</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>kind</code></p></td><td><p>Connection type</p></td><td><p><code>mcp</code>, <code>a2a</code>, or <code>llm</code></p></td><td><p>Yes</p></td></tr><tr><td><p><code>ref</code></p></td><td><p>A reference to an asset representing the target system.</p></td><td><p>Reference Object</p></td><td><p>Yes</p></td></tr><tr><td><p><code>url</code></p></td><td><div><div><p>The base URL of the target system. For <code>llm</code> use these defaults:</p></div><div><ul><li><p>OpenAI: <code>https://api.openai.com/v1</code></p></li><li><p>Gemini: <code>https://generativelanguage.googleapis.com</code></p></li><li><p>Bedrock OpenAI: <code>https://bedrock-mantle.&lt;YOUR_REGION&gt;.api.aws/v1</code></p></li><li><p>Azure OpenAI: <code>https://&lt;YOUR_RESOURCE_NAME&gt;.openai.azure.com/openai/v1</code></p></li></ul></div></div></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>authentication</code></p></td><td><p>The authentication method to use when connecting to the target system.</p></td><td><p>Authentication Object</p></td><td><p>No (Yes for <code>llm</code> connections)</p></td></tr><tr><td><p><code>policies</code></p></td><td><p>Policy bindings to apply to this connection, organized by traffic direction.</p></td><td><p>Object</p></td><td><p>No</p></td></tr><tr><td><p><code>policies.inbound</code></p></td><td><p>Policy bindings applied to inbound traffic.</p></td><td><p>Array</p></td><td><p>No</p></td></tr><tr><td><p><code>policies.outbound</code></p></td><td><p>Policy bindings applied to outbound traffic.</p></td><td><p>Array</p></td><td><p>No</p></td></tr><tr><td><p><code>card</code></p></td><td><p>Configuration for fetching the target agent’s agent card. Valid only when <code>kind</code> is <code>a2a</code>. See <a href="#a2a-connection-card">A2A Connection Card</a>.</p></td><td><p>Object</p></td><td><p>No</p></td></tr><tr><td><p><code>interfaces</code></p></td><td><p>The protocol bindings the agent serves, each under a sub-path of <code>url</code>. Valid only when <code>kind</code> is <code>a2a</code>. See <a href="#a2a-connection-interfaces">A2A Connection Interfaces</a>.</p></td><td><p>Object</p></td><td><p>No</p></td></tr></tbody></table>

For `llm` connections, `authentication` is required. LLM connections support `none`, `basic`,
`apiKey`, `apikey-client-credentials`, `oauth2-client-credentials`, and `amazonSigv4`. The
authentication kind must be one that the referenced LLM asset declares in its metadata. LLM
connections don’t support `oauth2-obo`, `in-task-authorization-code`, or `custom` authentication.

For example, to connect to an LLM that uses OAuth 2.0 client credentials authentication:

```yaml
context:
  connections:
    my-llm-connection:
      kind: llm
      ref:
        name: my-llm
      url: https://api.example.com/v1
      authentication:
        kind: oauth2-client-credentials
        clientId: my-client-id
        clientSecret: my-client-secret
        token:
          url: https://auth.example.com/token
        scopes:
          - my.custom.scope
```

You can attach policies to connection objects by referencing their policy identifier or by defining
an inline policy binding. See the [policies object](#policies) for field definitions.

#### A2A Connection Card

Use `card` on an `a2a` connection when the target agent requires different credentials to fetch its
agent card than the connection’s runtime `authentication`.

**Example**

```yaml
context:
   connections:
     hr_system_agent:
       kind: a2a
       ref:
         name: hr-system-agent
        authentication:
          kind: oauth2-client-credentials
          clientId: runtime-client-id
          clientSecret: runtime-client-secret
          token:
            url: https://my-oauth2-provider.com/token
       card:
         authentication:
            kind: apiKey
            apiKey: card-api-key
```

The `card` object has these properties.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>authentication</code></p></td><td><p>The authentication to use when fetching the agent’s card. See <a href="#authentication">Authentication</a>.</p></td><td><p>Authentication Object</p></td><td><p>No</p></td></tr></tbody></table>

#### A2A Connection Interfaces

For `a2a` connections, `interfaces` declares which protocol bindings the target agent serves. Each
binding is served under a sub-path of the connection’s `url`.

**Example**

```yaml
context:
  connections:
    hr_system_agent:
      kind: a2a
      ref:
        name: hr-system-agent
      url: https://hr-agent.example.com
      interfaces:
        jsonrpc:
          basePath: /a2a
        http:
          basePath: /rest
```

The `interfaces` object has these properties.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>jsonrpc</code></p></td><td><p>The JSON-RPC binding.</p></td><td><p>Object</p></td><td><p>No</p></td></tr><tr><td><p><code>jsonrpc.basePath</code></p></td><td><p>Sub-path of <code>url</code> that serves the JSON-RPC binding.</p></td><td><p>String</p></td><td><p>Yes (if <code>jsonrpc</code> present)</p></td></tr><tr><td><p><code>http</code></p></td><td><p>The HTTP+JSON (REST) binding.</p></td><td><p>Object</p></td><td><p>No</p></td></tr><tr><td><p><code>http.basePath</code></p></td><td><p>Sub-path of <code>url</code> that serves the HTTP+JSON binding.</p></td><td><p>String</p></td><td><p>Yes (if <code>http</code> present)</p></td></tr><tr><td><p><code>grpc</code></p></td><td><p>The gRPC binding.</p></td><td><p>Object</p></td><td><p>No</p></td></tr><tr><td><p><code>grpc.basePath</code></p></td><td><p>Sub-path of <code>url</code> that serves the gRPC binding.</p></td><td><p>String</p></td><td><p>Yes (if <code>grpc</code> present)</p></td></tr></tbody></table>

### 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 Omni Gateway in Local Mode, see:

- [Securing Agent Interactions with Omni Gateway](https://docs.mulesoft.com/gateway/latest/flex-agent-secure)

- [Applying Policies in Local Mode](https://docs.mulesoft.com/gateway/latest/flex-gateway-secure-local)

**Example**

```yaml
context:
  policies:
    myRateLimitPolicy:
      ref:
        name: myReferenceObject
      configuration:
        - rate: 100
          unit: minute
```

This section has these properties.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p>ref</p></td><td><p>Reference to a specific policy definition.</p></td><td><p>Object</p></td><td><p>Yes</p></td></tr><tr><td><p>ref.name</p></td><td><p>Name of the reference definition</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p>configuration</p></td><td><p>Policy-specific configuration (structure defined by the referenced policy definition).</p></td><td><p>Object</p></td><td><p>Yes</p></td></tr></tbody></table>

> [!NOTE] Agent Network uses Omni Gateway. Some policies are available for both Omni Gateway and
> Mule Gateway. For these policies, use these policy definition versions:
>
> - JWT Validation: `0.12.0`. See
>   [JWT Validation Policy](https://docs.mulesoft.com/gateway/latest/policies-included-jwt-validation#agent-network-version).
>
> - OpenID Connect OAuth 2.0 Token Enforcement: `0.11.0`. See
>   [OpenID Connect OAuth 2.0 Token Enforcement Policy](https://docs.mulesoft.com/gateway/latest/policies-included-openid-token-enforcement#agent-network-version).
>
> For these policies only, policy definition versions that start with `1` are for Mule Gateway and
> cause an error.

### Authentication

This section defines the authentication schemes used by the agent network for authenticating when
making outbound requests.

#### No Client Authentication

Use `none` to explicitly declare that a connection doesn’t require authentication. This is different
from omitting the `authentication` object.

**Example**

```yaml
kind: none
```

The no-authentication object has this property.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p>kind</p></td><td><p>The authentication method type.</p></td><td><p>String</p></td><td><p>none</p></td><td><p>Yes</p></td></tr></tbody></table>

#### Basic Client Authentication

HTTP Basic authentication with username and password.

**Example**

```yaml
kind: basic
username: my-username
password: my-password
headerName: Authorization
```

The basic object has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p>kind</p></td><td><p>The authentication method type.</p></td><td><p>String</p></td><td><p>basic</p></td><td><p>Yes</p></td></tr><tr><td><p>username</p></td><td><p>Username for authentication.</p></td><td><p>String</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p>password</p></td><td><p>Password for authentication.</p></td><td><p>String</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p>headerName</p></td><td><p>The name of the HTTP used for basic credentials. If not specified, Authorization is used.</p></td><td><p>String</p></td><td><p>String. Defaults to Authorization.</p></td><td><p>No</p></td></tr></tbody></table>

#### API Key Client Authentication

Authenticates outbound requests by including an API key in a configurable HTTP header.

**Example**

```yaml
kind: apiKey
apiKey: my-api-key-123
headerName: Authorization
```

An API key passed in a header has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p>kind</p></td><td><p>The authentication method type.</p></td><td><p>String</p></td><td><p>apiKey</p></td><td><p>Yes</p></td></tr><tr><td><p>headerName</p></td><td><p>The name of the HTTP header that carries the API key. If not specified, Authorization is used.</p></td><td><p>String</p></td><td><p>String. Defaults to Authorization.</p></td><td><p>No</p></td></tr><tr><td><p>apiKey</p></td><td><p>The header or parameter name for the API key.</p></td><td><p>String</p></td><td><p>String</p></td><td><p>No</p></td></tr></tbody></table>

#### API Key Client Credentials Client Authentication

API key client credentials with client ID and client secret objects.

**Example**

```yaml
kind: apikey-client-credentials
clientId:
  value: my-client-id
  name: client_id
clientSecret:
  value: my-client-secret
  name: client_secret
```

The API key client credentials object has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p>kind</p></td><td><p>The authentication method type.</p></td><td><p>String</p></td><td><p>apikey-client-credentials</p></td><td><p>Yes</p></td></tr><tr><td><p>clientId</p></td><td><p>Description of the client ID to be used.</p></td><td><p>Object</p></td><td><p>Object with value and optional name (default header name is client_id).</p></td><td><p>Yes</p></td></tr><tr><td><p>clientId.value</p></td><td><p>The value for the client ID.</p></td><td><p>String</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p>clientId.name</p></td><td><p>The header or parameter name.</p></td><td><p>String</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p>clientSecret</p></td><td><p>Description of the client secret to be used.</p></td><td><p>Object</p></td><td><p>Object with value and optional name (default header name is client_secret).</p></td><td><p>No</p></td></tr><tr><td><p>clientSecret.value</p></td><td><p>The value for the client secret.</p></td><td><p>String</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p>clientSecret.name</p></td><td><p>The header or parameter name.</p></td><td><p>String</p></td><td><p>String</p></td><td><p>No</p></td></tr></tbody></table>

#### Amazon Signature Version 4 Client Authentication

Use `amazonSigv4` to sign outbound requests with AWS Signature Version 4. If you don’t provide
static credentials, credentials are resolved from the platform’s AWS credential provider chain.

**Example**

```yaml
kind: amazonSigv4
awsAccessKeyId: my-access-key-id
awsSecretAccessKey: my-secret-access-key
awsSessionToken: my-session-token
awsRegion: us-east-1
serviceName: bedrock
```

The Amazon Signature Version 4 object has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p>kind</p></td><td><p>The authentication method type.</p></td><td><p>String</p></td><td><p>amazonSigv4</p></td><td><p>Yes</p></td></tr><tr><td><p>awsAccessKeyId</p></td><td><p>Static AWS access key ID for signing requests.</p></td><td><p>String</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p>awsSecretAccessKey</p></td><td><p>Static AWS secret access key for signing requests.</p></td><td><p>String</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p>awsSessionToken</p></td><td><p>AWS session token for temporary credentials. When present, it is sent as <code>X-Amz-Security-Token</code>.</p></td><td><p>String</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p>awsRegion</p></td><td><p>AWS Region in the SigV4 credential scope. It must match the upstream endpoint region.</p></td><td><p>String</p></td><td><p>String. Defaults to <code>us-east-1</code>.</p></td><td><p>No</p></td></tr><tr><td><p>serviceName</p></td><td><p>AWS service name in the SigV4 credential scope.</p></td><td><p>String</p></td><td><p>String. Defaults to <code>bedrock</code>.</p></td><td><p>No</p></td></tr></tbody></table>

#### 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**

```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.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p>kind</p></td><td><p>The authentication method type.</p></td><td><p>String</p></td><td><p>oauth2-client-credentials</p></td><td><p>Yes</p></td></tr><tr><td><p>clientId</p></td><td><p>The client ID to authenticate with the OAuth2 provider.</p></td><td><p>String</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p>clientSecret</p></td><td><p>The client secret used with client ID.</p></td><td><p>String</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p>token</p></td><td><p>Configuration for how to fetch the token.</p></td><td><p>Object</p></td><td><p>Token object</p></td><td><p>Yes</p></td></tr><tr><td><p>token.url</p></td><td><p>The URL of the token provider (token endpoint).</p></td><td><p>String</p></td><td><p>Valid URL string</p></td><td><p>Yes</p></td></tr><tr><td><p>token.timeout</p></td><td><p>Time in seconds to wait for the token service to respond.</p></td><td><p>Number</p></td><td><p>Any number</p></td><td><p>No</p></td></tr><tr><td><p>token.bodyEncoding</p></td><td><p>Content encoding for the request body. (<code>form = application/x-www-form-urlencoded</code>, <code>json = application/json</code>)</p></td><td><p>String</p></td><td><p><code>form</code> or <code>json</code></p></td><td><p>No</p></td></tr><tr><td><p>scopes</p></td><td><p>Array of scopes to request during token retrieval.</p></td><td><p>Array</p></td><td><p>Array of scope strings. Defaults to []</p></td><td><p>No</p></td></tr></tbody></table>

#### 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
[A2A In-Task Authorization Code Policy](https://docs.mulesoft.com/gateway/latest/policies-outbound-a2a-intask-authorization-code).

**Example**

```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.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p>kind</p></td><td><p>Authentication type.</p></td><td><p>String</p></td><td><p>in-task-authorization-code</p></td><td><p>Yes</p></td></tr><tr><td><p>authorizationEndpoint</p></td><td><p>OAuth2 authorization endpoint URL. Used to generate the authentication challenge.</p></td><td><p>String</p></td><td><p>Valid URL</p></td><td><p>Yes</p></td></tr><tr><td><p>tokenEndpoint</p></td><td><p>OAuth2 token endpoint URL. Used to generate the authentication challenge.</p></td><td><p>String</p></td><td><p>Valid URL</p></td><td><p>Yes</p></td></tr><tr><td><p>scopes</p></td><td><p>OAuth2 scopes required for step-up authentication.</p></td><td><p>String</p></td><td><p>Space- or comma-separated scope list (for example, openid profile email)</p></td><td><p>Yes</p></td></tr><tr><td><p>redirectUri</p></td><td><p>OAuth2 redirect URI the client uses in the authorization flow.</p></td><td><p>String</p></td><td><p>Valid URI</p></td><td><p>Yes</p></td></tr><tr><td><p>secondaryAuthProvider</p></td><td><p>Name of the IdP (for example, okta, auth0). Informational only, for the authentication card.</p></td><td><p>String</p></td><td><p>Any string</p></td><td><p>No</p></td></tr><tr><td><p>responseType</p></td><td><p>OAuth2 response type.</p></td><td><p>String</p></td><td><p>Typically code. Default: code</p></td><td><p>No</p></td></tr><tr><td><p>codeChallengeMethod</p></td><td><p>PKCE code challenge method.</p></td><td><p>String</p></td><td><p>Typically S256. Default: S256</p></td><td><p>No</p></td></tr><tr><td><p>tokenAudience</p></td><td><p>Intended recipient of the token (for example, agent1 or API URL).</p></td><td><p>String</p></td><td><p>Any string</p></td><td><p>No</p></td></tr><tr><td><p>bodyEncoding</p></td><td><p>Encoding for the token request body.</p></td><td><p>String</p></td><td><p>form, json. Default: form</p></td><td><p>No</p></td></tr><tr><td><p>tokenTimeout</p></td><td><p>Timeout in seconds for token requests.</p></td><td><p>Integer</p></td><td><p>Positive integer. Default: 300</p></td><td><p>No</p></td></tr><tr><td><p>challengeResponseStatusCode</p></td><td><p>HTTP status code returned for auth-required challenge responses. Typically 200 for JSON-RPC compatibility.</p></td><td><p>Integer</p></td><td><p>HTTP status code. Default: 200</p></td><td><p>No</p></td></tr><tr><td><p>distributed</p></td><td><p>Share token cache across replicas. Required for fully managed gateway or any multi-replica deployment.</p></td><td><p>Boolean</p></td><td><p><code>true</code> or <code>false</code>. Default: <code>false</code></p></td><td><p>No</p></td></tr><tr><td><p>subjectTokenType</p></td><td><p>The token type identifier for the subject token.</p></td><td><p>String</p></td><td><p>Default: <code>urn:ietf:params:oauth:token-type:access_token</code></p></td><td><p>No</p></td></tr><tr><td><p>requestedTokenType</p></td><td><p>The desired token type for the issued token.</p></td><td><p>String</p></td><td><p>Any string</p></td><td><p>No</p></td></tr></tbody></table>

#### 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
[OAuth 2.0 OBO Credential Injection Policy](https://docs.mulesoft.com/gateway/latest/policies-outbound-oauth-obo).

**Using OAuth 2.0 Token Exchange**

```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
    timeout: 5000
```

**Using Microsoft Entra ID On-Behalf-Of**

```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.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p>kind</p></td><td><p>Authentication type.</p></td><td><p>String</p></td><td><p>oauth2-obo</p></td><td><p>Yes</p></td></tr><tr><td><p>flow</p></td><td><p>Token exchange flow type.</p></td><td><p>String</p></td><td><p>oauth2-token-exchange, microsoft-entra-obo</p></td><td><p>Yes</p></td></tr><tr><td><p>clientId</p></td><td><p>OAuth2 client ID for token exchange.</p></td><td><p>String</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p>clientSecret</p></td><td><p>OAuth2 client secret for token exchange.</p></td><td><p>String</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p>tokenEndpoint</p></td><td><p>OAuth2 token endpoint URL for token exchange.</p></td><td><p>String</p></td><td><p>Valid URL</p></td><td><p>Yes</p></td></tr><tr><td><p>targetType</p></td><td><p>Parameter type for specifying the target service (audience for logical name, resource for physical URI). Used for OAuth 2.0 Token Exchange.</p></td><td><p>String</p></td><td><p>audience, resource. Default: audience</p></td><td><p>No</p></td></tr><tr><td><p>targetValue</p></td><td><p>Target audience URI or resource URI for the exchanged token. Required for OAuth 2.0 Token Exchange.</p></td><td><p>String</p></td><td><p>Valid URI</p></td><td><p>Required when using oauth2-token-exchange with a target</p></td></tr><tr><td><p>scope</p></td><td><p>OAuth scope to request. Required for Microsoft Entra OBO (for example, api://downstream-client-id/.default). Optional for OAuth 2.0 Token Exchange.</p></td><td><p>String</p></td><td><p>String</p></td><td><p>Required for microsoft-entra-obo</p></td></tr><tr><td><p>timeout</p></td><td><p>Timeout for token exchange requests in milliseconds.</p></td><td><p>Integer</p></td><td><p>Positive integer. Default: 10000</p></td><td><p>No</p></td></tr><tr><td><p>cibaEnabled</p></td><td><p>When <code>true</code>, it uses Client Initiated Backchannel Authentication (CIBA) instead of standard OBO token exchange. Only valid when <code>flow</code> is <code>oauth2-token-exchange</code>.</p></td><td><p>Boolean</p></td><td><p><code>true</code> or <code>false</code>. Default: <code>false</code></p></td><td><p>No</p></td></tr><tr><td><p>cibaEndpoint</p></td><td><p>Backchannel authorization (<code>bc-authorize</code>) endpoint URL for CIBA.</p></td><td><p>String</p></td><td><p>Valid URL</p></td><td><p>No</p></td></tr><tr><td><p>cibaLoginHintClaim</p></td><td><p>JWT claim from the subject token to send as the CIBA <code>login_hint</code> (for example, <code>email,</code> <code>sub</code>).</p></td><td><p>String</p></td><td><p>String. Default: <code>email</code></p></td><td><p>No</p></td></tr><tr><td><p>cibaBindingMessage</p></td><td><p>Optional message shown on the user’s authentication device during CIBA approval.</p></td><td><p>String</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p>distributed</p></td><td><p>Share token cache across replicas. Required for fully managed gateway or any multi-replica deployment.</p></td><td><p>Boolean</p></td><td><p><code>true</code> or <code>false</code>. Default: <code>false</code></p></td><td><p>No</p></td></tr></tbody></table>

## 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**

```yaml
brokers:
  customer_service_agent:
    kind: AgentScript
    implementation: ./brokers/customer-service.agent
    interfaces:
      a2a:
        card:
          name: customer-service-agent
          description: Routes customer service requests.
          version: "1.0.0"
        policies:
          inbound:
            - ref:
                name: rate-limit-policy
  billing_agent:
    kind: AgentScript
    implementation: ./brokers/billing-handler.agent
    interfaces:
      a2a:
        card:
          name: billing-agent
          description: Handles billing inquiries.
          version: "1.0.0"
```

The `brokers` section has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th><th>Values</th></tr></thead><tbody><tr><td><p><code><em>(broker id)</em></code></p></td><td><p>Named broker definition.</p></td><td><p>Object</p></td><td><p>No</p></td><td><p>Keys: identifiers using only lowercase <code>a</code>–<code>z</code>, <code>0</code>–<code>9</code>, and non-trailing underscores (<code>_</code>). Values: broker entity (BrokerEntity in agent_network_v2.json)</p></td></tr><tr><td><p><code>kind</code></p></td><td><p>The type of agent implementation.</p></td><td><p>String</p></td><td><p>Yes</p></td><td><p><code>AgentScript</code></p></td></tr><tr><td><p><code>implementation</code></p></td><td><p>The path to the Agent Script implementation file.</p></td><td><p>String</p></td><td><p>Yes</p></td><td><p> — </p></td></tr><tr><td><p><code>interfaces</code></p></td><td><p>Exposed interfaces for this broker.</p></td><td><p>Object</p></td><td><p>Yes</p></td><td><p><code>a2a</code></p></td></tr></tbody></table>

### 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.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>card</code></p></td><td><p>The A2A agent card. See <a href="#a2a-card">A2A Card</a>.</p></td><td><p>AgentCard</p></td><td><p>No</p></td></tr><tr><td><p><code>policies</code></p></td><td><p>Inbound and outbound policy binding lists for this interface.</p></td><td><p>Object</p></td><td><p>No</p></td></tr><tr><td><p><code>policies.inbound</code></p></td><td><p>Policy bindings for inbound traffic.</p></td><td><p>Array</p></td><td><p>No</p></td></tr><tr><td><p><code>policies.outbound</code></p></td><td><p>Policy bindings for outbound traffic.</p></td><td><p>Array</p></td><td><p>No</p></td></tr></tbody></table>

#### User Identity and Task Security

The broker derives a `userId` from the authentication context of the security policy applied at the
broker’s ingress. This `userId` secures
[A2A task management operations](https://docs.mulesoft.com/agent-network/latest/af-agent-script-reference#a2a-trigger), ensuring that only the
authenticated user who owns a task can query or modify it. This includes `SendMessage` and
`SendStreamingMessage` operations that target an existing task.

If no authentication policy is configured at the broker’s ingress, or if a `userId` cannot be
determined from the authentication context, the broker continues to orchestrate normally. However,
A2A task management operations (such as querying task status, canceling a task, or sending messages
to an existing task) are not available for tasks created without an associated `userId`.

#### Policy Binding Reference

Use a policy binding reference to attach a previously declared policy to a broker interface by name.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>ref.name</code></p></td><td><p>Name of the declared policy binding. See <a href="#policies">Policies</a>.</p></td><td><p>String</p></td><td><p>Yes</p></td></tr></tbody></table>

#### Inline Policy Binding

Use an inline policy binding to define a policy directly on the broker interface without declaring
it elsewhere first.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>policy</code></p></td><td><p>The policy to be applied.</p></td><td><p>Object</p></td><td><p>Yes</p></td></tr><tr><td><p><code>policy.ref</code></p></td><td><p>Reference to the policy definition.</p></td><td><p>PolicyRef See <a href="#policies">Policies</a>.</p></td><td><p>Yes</p></td></tr><tr><td><p><code>policy.configuration</code></p></td><td><p>Policy-specific configuration.</p></td><td><p>Object</p></td><td><p>Yes</p></td></tr></tbody></table>

## 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 [appropriate YAML syntax](https://yaml.org/spec/1.2.2/#54-line-break-characters).

**Example**

```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.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Variable Name</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p>input</p></td><td><p>Payload or parameters provided as input to the node.</p></td><td><p>Type defined by Graph</p></td><td><p>Yes</p></td></tr><tr><td><p>variables</p></td><td><p>A mutable key-value store for variables scoped to the execution of the graph instance.</p></td><td><p>Dict[string, any]</p></td><td><p>Yes</p></td></tr><tr><td><p>{node-ids}</p></td><td><p>Read-only mapping of all node definitions available in the current graph, indexed by node id.</p></td><td><p>Dict[string, Object]</p></td><td><p>Yes</p></td></tr></tbody></table>

{node-ids} have these properties.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Variable Name</th><th>Type</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><p>input</p></td><td><p>Type defined by Graph</p></td><td><p>Input to the node as it happened.</p></td><td><p>Yes</p></td></tr><tr><td><p>output</p></td><td><p>Type defined by Graph</p></td><td><p>Output provided by the node as it happened</p></td><td><p>Yes</p></td></tr></tbody></table>

## 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**

```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.

For more information about versioning assets in agent network projects, see
[Version Assets](https://docs.mulesoft.com/agent-network/latest/af-publish-agent-network-assets#version-assets).

### Runtime System Limits Configuration

You can configure runtime system limits for your agent network by adding specific variables to the
`metadata.variables` section of your `exchange.json` file. These variables control graph execution
behavior and help prevent infinite loops or excessive resource usage.

**Example**

```json
{
  "main": "agent-network.yaml",
  "name": "it-investigation-GA-version",
  "classifier": "agentic-network",
  "organizationId": "{YOUR ORG ID}",
  "descriptorVersion": "1.0.0",
  "tags": [],
  "metadata": {
    "variables": {
      "openai": {
        "apiKey": {
          "description": "OpenAI API key",
          "default": "",
          "secret": true
        }
      },
      "MODULE_GRAPH_ERROR_SETTINGS_MAX_HANDOFF_ITERATIONS": {
        "description": "max node-to-node transitions per turn",
        "secret": false,
        "default": "30"
      },
      "MODULE_GRAPH_ERROR_SETTINGS_MAX_REASONING_ITERATIONS": {
        "description": "max LLM reasoning loops within a single node",
        "secret": false,
        "default": "20"
      },
      "MODULE_GRAPH_ERROR_SETTINGS_MAX_SUBGRAPH_DEPTH": {
        "description": "max subgraph nesting depth",
        "secret": false,
        "default": "10"
      },
      "MODULE_GRAPH_ERROR_SETTINGS_MAX_NODE_TOOL_CALL_ITERATIONS": {
        "description": "max tool_executor runs per node",
        "secret": false,
        "default": "20"
      },
      "MODULE_GRAPH_ERROR_SETTINGS_MAX_TURN_TOOL_CALL_COUNTS": {
        "description": "total tool invocations across all nodes per turn",
        "secret": false,
        "default": "50"
      },
      "MODULE_GRAPH_ERROR_SETTINGS_MAX_STATE_SIZE_BYTES": {
        "description": "max accumulated state size in bytes (10 MB)",
        "secret": false,
        "default": "10485760"
      }
    }
  },
  "apiVersion": "v1.0",
  "dependencies": [],
  "groupId": "{YOUR ORG ID}",
  "assetId": "it-investigation-GA-version",
  "version": "1.0.0"
}
```

#### Runtime System Limit Variables

The following table describes the runtime system limit variables you can configure:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Variable Name</th><th>Description</th><th>Default Value</th></tr></thead><tbody><tr><td><p><code>MODULE_GRAPH_ERROR_SETTINGS_MAX_HANDOFF_ITERATIONS</code></p></td><td><p>Maximum number of node-to-node transitions allowed per turn. Controls how many times execution can move between nodes in the agent network graph during a single conversation turn.</p></td><td><p>30</p></td></tr><tr><td><p><code>MODULE_GRAPH_ERROR_SETTINGS_MAX_REASONING_ITERATIONS</code></p></td><td><p>Maximum number of LLM reasoning loops allowed within a single node. Limits how many times the LLM can iterate on its reasoning before producing a result.</p></td><td><p>20</p></td></tr><tr><td><p><code>MODULE_GRAPH_ERROR_SETTINGS_MAX_SUBGRAPH_DEPTH</code></p></td><td><p>Maximum nesting depth for subgraphs. Controls how deeply agent networks can be nested within other agent networks.</p></td><td><p>10</p></td></tr><tr><td><p><code>MODULE_GRAPH_ERROR_SETTINGS_MAX_NODE_TOOL_CALL_ITERATIONS</code></p></td><td><p>Maximum number of tool executor runs allowed per node. Limits how many times a node can invoke tool execution during its processing.</p></td><td><p>20</p></td></tr><tr><td><p><code>MODULE_GRAPH_ERROR_SETTINGS_MAX_TURN_TOOL_CALL_COUNTS</code></p></td><td><p>Total number of tool invocations allowed across all nodes per turn. Provides a global limit on tool usage during a single conversation turn.</p></td><td><p>50</p></td></tr><tr><td><p><code>MODULE_GRAPH_ERROR_SETTINGS_MAX_STATE_SIZE_BYTES</code></p></td><td><p>Maximum accumulated state size in bytes. Limits the total amount of state data that can be accumulated during graph execution. Default is 10 MB (10485760 bytes).</p></td><td><p>10485760</p></td></tr><tr><td><p><code>OBJECT_STORE_DEFAULT_TTL_MS</code></p></td><td><p>Maximum amount of time, in milliseconds, for data persistence. The default is 24 hours (86,400,000 ms).</p></td><td><p>30 days (2,592,000,000 ms)</p></td></tr></tbody></table>

Specify all runtime system limit variables as string values in the `exchange.json` file. All
variables are non-sensitive (`secret: false`).

<!-- document id=ab506a9446d04ed817f5bfdec93df567ca5a42e0a1c7ffde7188b9113a9c500b url=/mulesoft/current/en-us/agent-network/latest/af-project-files.md -->

---
product: Building Agent Networks
version: 2.0
is-latest-version: true
---

# Agent Network 2.0 Project File Reference

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

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
project file 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.

For complete schema details, see:

- [Agent Network (2.0) YAML Reference](https://docs.mulesoft.com/agent-network/latest/af-agent-network-yaml-reference)

- [Agent Script Reference](https://docs.mulesoft.com/agent-network/latest/af-agent-script-reference)

> [!NOTE] For a complete, working example you can use as a starting point for your own agent network
> project, see [Example: Building an IT Investigation Broker](https://docs.mulesoft.com/agent-network/latest/af-example-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.

<!-- document id=af885c7549202ba29c9007b521c74ecc6633a74d6206a6466fc621b20dd373a0 url=/mulesoft/current/en-us/agent-network/1.0/af-project-files.md -->

---
product: Building Agent Networks
version: 1.0
---

# Agent Network Project File Reference

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Configure and publish your agent network using two key files: `agent-network.yaml` and
`exchange.json`. The `agent-network.yaml` file defines agent behaviors, tools, and inter-agent
communication, while `exchange.json` contains metadata for Anypoint Exchange publication.
Understanding these files enables you to orchestrate multi-agent systems with external services and
manage asset dependencies across your organization.

- [agent-network.yaml](#agent-network-yaml)

- [exchange.json file element](#exchange-json-file-element)

## Agent Network YAML

The agent network YAML file 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.

For example, think of the YAML as your organizational chart for digital labor. Each internal
organization (for example, HR, IT, Sales, or Engineering) has a hierarchical structure through which
actors collaborate. Jobs are split into tasks and assigned.

Just like with human labor, digital agents require coordination. We call these coordinators
"brokers". These are special types of agents in your agent network capable of receiving a user
message, identifying the goal, determining the necessary steps to be carried out, and delegating
each step to the proper agent, even if the agent is part of a different broker.

The `agent-network.yaml` file uses these sections.

- [Brokers](#brokers-section)

  - [Card](#card-section)

  - [Spec](#spec-section)

    - [LLM](#llm-section)

    - [Instructions](#instructions-section)

    - [Links](#links-section)

    - [Tools](#tools-section)

    - [Policies](#policies-section)

    - [Error Handling](#error-handling)

- [Agents](#agents-section)

- [MCPServers](#mcp-servers-section)

- [LLM Providers](#llmproviders-section)

- [Connections](#connections-section)

## Brokers Section

`brokers`

This section defines the AI assets in your agent network. A broker is an intelligent routing service
that coordinates task delegation across specialized agents in your enterprise. It’s defined by the
agents and MCP servers it can use to accomplish tasks. The broker name is used as the `assetId` in
the `exchange.json` file. The `groupId` defaults to the associated business group value used in
`exchange.json`.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th></tr></thead><tbody><tr><td><p><code>brokers</code></p></td><td><p>The list of brokers defined in your agent network.</p></td><td><p>Object</p></td><td><p>Object with property names matching this pattern: <code>^[a-zA-Z_][a-zA-Z0-9_.-]*$</code>. The name must start with a letter or an underscore and can contain letters, numbers, underscores, dots, or hyphens. The name cannot be: <code>default</code>, <code>defaults</code>, <code>system</code>, <code>local</code>, <code>null</code></p></td></tr></tbody></table>

The `broker` element has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>card</code></p></td><td><p>Agent card definition.</p></td><td><p>Object</p></td><td><p>Refer to the <code>card</code> object properties.</p></td><td><p>Yes</p></td></tr><tr><td><p><code>spec</code></p></td><td><p>Broker specification.</p></td><td><p>Object</p></td><td><p>Refer to the <code>spec</code> object properties.</p></td><td><p>Yes</p></td></tr></tbody></table>

### Card Section

`card`

This section adheres to the Agent-to-Agent (A2A) specification v0.3.0 and describes the broker’s
contract, skills, and capabilities. This is a standard A2A agent card
[as defined in the Agent2Agent (A2A) Protocol specification.](https://a2a-protocol.org/latest/specification/#55-agentcard-object-structure).

The `card` element has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>protocolVersion</code></p></td><td><p>The version of the A2A protocol this agent supports.</p></td><td><p>String</p></td><td><p>A2A protocol version (for example, "0.3.0")</p></td><td><p>No</p></td></tr><tr><td><p><code>name</code></p></td><td><p>A human-readable name for the agent.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>No</p></td></tr><tr><td><p><code>description</code></p></td><td><p>A human-readable description of the agent, assisting users and other agents in understanding its purpose.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>No</p></td></tr><tr><td><p><code>url</code></p></td><td><p>The preferred endpoint URL for interacting with the agent. This URL must support the transport specified by 'preferredTransport'.</p></td><td><p>String (URI)</p></td><td><p>Valid URI string</p></td><td><p>No</p></td></tr><tr><td><p><code>preferredTransport</code></p></td><td><p>The transport protocol for the preferred endpoint (the main 'url' field).</p></td><td><p>String</p></td><td><p><code>JSONRPC</code>, <code>GRPC</code>, <code>HTTP+JSON</code>. Defaults to <code>JSONRPC</code></p></td><td><p>No</p></td></tr><tr><td><p><code>additionalInterfaces</code></p></td><td><p>A list of additional supported interfaces (transport and URL combinations).</p></td><td><p>Array</p></td><td><p>Array of interface objects (See <a href="#additionalinterfaces-properties">AdditionalInterfaces properties</a>)</p></td><td><p>No</p></td></tr><tr><td><p><code>iconUrl</code></p></td><td><p>An optional URL to an icon for the agent.</p></td><td><p>String (URI)</p></td><td><p>Valid URI string</p></td><td><p>No</p></td></tr><tr><td><p><code>provider</code></p></td><td><p>Information about the agent’s service provider.</p></td><td><p>Object</p></td><td><p>Object with provider properties (See <a href="#provider-properties">provider properties</a>)</p></td><td><p>No</p></td></tr><tr><td><p><code>version</code></p></td><td><p>The agent’s own version number. The format is defined by the provider.</p></td><td><p>String</p></td><td><p>Version string (for example, "1.0.0")</p></td><td><p>No</p></td></tr><tr><td><p><code>documentationUrl</code></p></td><td><p>An optional URL to the agent’s documentation.</p></td><td><p>String (URI)</p></td><td><p>Valid URI string</p></td><td><p>No</p></td></tr><tr><td><p><code>capabilities</code></p></td><td><p>A declaration of optional capabilities supported by the agent.</p></td><td><p>Object</p></td><td><p>Object with capability properties (See <a href="#capabilities-properties">capabilities properties</a>)</p></td><td><p>No</p></td></tr><tr><td><p><code>securitySchemes</code></p></td><td><p>A declaration of the security schemes available to authorize requests.</p></td><td><p>Object</p></td><td><p>Keys are scheme names; values follow the OpenAPI 3.0 Security Scheme Object</p></td><td><p>No</p></td></tr><tr><td><p><code>security</code></p></td><td><p>A list of security requirement objects that apply to all agent interactions.</p></td><td><p>Array</p></td><td><p>Array of security requirement objects</p></td><td><p>No</p></td></tr><tr><td><p><code>defaultInputModes</code></p></td><td><p>Default set of supported input MIME types for all skills, which can be overridden on a per-skill basis.</p></td><td><p>Array of strings</p></td><td><p>Array of MIME type strings (for example, <code>["application/json", "text/plain"]</code>)</p></td><td><p>No</p></td></tr><tr><td><p><code>defaultOutputModes</code></p></td><td><p>Default set of supported output MIME types for all skills, which can be overridden on a per-skill basis.</p></td><td><p>Array of strings</p></td><td><p>Array of MIME type strings (for example, <code>["application/json", "text/plain"]</code>)</p></td><td><p>No</p></td></tr><tr><td><p><code>skills</code></p></td><td><p>The set of skills, or distinct capabilities, that the agent can perform.</p></td><td><p>Array</p></td><td><p>Array of skill objects (See <a href="#skills-properties">skills properties</a>)</p></td><td><p>No</p></td></tr><tr><td><p><code>supportsAuthenticatedExtendedCard</code></p></td><td><p>Indicates if the agent can provide an extended agent card with additional details to authenticated users.</p></td><td><p>Boolean</p></td><td><p><code>true</code> or <code>false</code>. Defaults to <code>false</code></p></td><td><p>No</p></td></tr><tr><td><p><code>signatures</code></p></td><td><p>JSON Web Signatures computed for this AgentCard.</p></td><td><p>Array</p></td><td><p>Array of signature objects</p></td><td><p>No</p></td></tr></tbody></table>

#### `provider` Properties

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>organization</code></p></td><td><p>The name of the organization providing the agent.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>No</p></td></tr><tr><td><p><code>url</code></p></td><td><p>The URL of the organization.</p></td><td><p>String (URI)</p></td><td><p>Valid URI string</p></td><td><p>No</p></td></tr></tbody></table>

#### `additionalInterfaces` Properties

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>url</code></p></td><td><p>The URL for this additional interface.</p></td><td><p>String (URI)</p></td><td><p>Valid URI string</p></td><td><p>Yes</p></td></tr><tr><td><p><code>transport</code></p></td><td><p>The transport protocol for this interface.</p></td><td><p>String</p></td><td><p><code>JSONRPC</code>, <code>GRPC</code>, <code>HTTP+JSON</code></p></td><td><p>Yes</p></td></tr></tbody></table>

#### `skills` Properties

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>id</code></p></td><td><p>Unique identifier for the skill.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>No</p></td></tr><tr><td><p><code>name</code></p></td><td><p>A human-readable name for the skill.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>No</p></td></tr><tr><td><p><code>description</code></p></td><td><p>A description of what this skill does.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>No</p></td></tr><tr><td><p><code>examples</code></p></td><td><p>Usage examples demonstrating how to use this skill.</p></td><td><p>Array of strings</p></td><td><p>Array of example strings</p></td><td><p>No</p></td></tr><tr><td><p><code>inputModes</code></p></td><td><p>Supported input MIME types for this skill (overrides defaultInputModes).</p></td><td><p>Array of strings</p></td><td><p>Array of MIME type strings</p></td><td><p>No</p></td></tr><tr><td><p><code>outputModes</code></p></td><td><p>Supported output MIME types for this skill (overrides defaultOutputModes).</p></td><td><p>Array of strings</p></td><td><p>Array of MIME type strings</p></td><td><p>No</p></td></tr><tr><td><p><code>tags</code></p></td><td><p>Categorization tags for this skill.</p></td><td><p>Array of strings</p></td><td><p>Array of tag strings</p></td><td><p>No</p></td></tr></tbody></table>

#### `capabilities` Properties

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>streaming</code></p></td><td><p>Indicates if the agent supports streaming responses.</p></td><td><p>Boolean</p></td><td><p><code>true</code> or <code>false</code></p></td><td><p>No</p></td></tr><tr><td><p><code>pushNotifications</code></p></td><td><p>Indicates if the agent supports push notifications.</p></td><td><p>Boolean</p></td><td><p><code>true</code> or <code>false</code></p></td><td><p>No</p></td></tr><tr><td><p><code>stateTransitionHistory</code></p></td><td><p>Indicates if the agent maintains state transition history.</p></td><td><p>Boolean</p></td><td><p><code>true</code> or <code>false</code></p></td><td><p>No</p></td></tr><tr><td><p><code>extensions</code></p></td><td><p>List of extension capabilities supported by the agent.</p></td><td><p>Array</p></td><td><p>Array of extension objects (See <a href="#extensions-properties">extensions properties</a>)</p></td><td><p>No</p></td></tr></tbody></table>

#### `extensions`

Example

```yaml
brokers:
  employee-onboarding-broker: # The name that the agent (broker) will be referenced by. This value is used as the asset ID in Anypoint Exchange.
    card:
      protocolVersion: 0.3.0 # A2A protocol version that the broker supports.
      name: Employee Onboarding Broker
      description:
        This agent acts as a broker for employee onboarding. It orchestrates the onboarding process
        by leveraging available tools to ensure new employees have access to all of the required
        systems for their daily work.
      url: ${agentregistry.url}/employee-onboarding-broker # URL where the broker is hosted. Represents the preferred endpoint as declared by the broker.
      provider:
        organization: MuleSoft
        url: https://www.mulesoft.com/
      defaultInputModes: # Supported media types for input
        - application/json
        - text/plain
      defaultOutputModes: # Supported media types for output
        - application/json
      skills:
        - id: onboarding-agent
          name: Onboarding Agent
          description:
            This agent acts as a broker. It orchestrates the use of specialized tools and agents,
            including MCP (Model Context Protocol) servers, to manage employee onboarding.
          examples: # Usage examples
            - Onboard a new sales employee. Employee name is 'Alex Smith', email is
              'alex.smith@example.com', and phone number is '555-123-4567'.
          inputModes:
            - application/json
            - text/plain
          outputModes:
            - application/json
            - text/plain
          tags: [onboarding] # Categorization tags
      capabilities:
        streaming: false
        pushNotifications: false
        stateTransitionHistory: false
        extensions:
          - uri: "https://example.com/ext/konami-code/v1"
            description: "Description text"
            required: false
            params:
              hints: "Hint text"
      version: 1.0.0 # Agent (broker) version
```

The `extensions` element has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>uri</code></p></td><td><p>URI identifying the extension.</p></td><td><p>String (URI)</p></td><td><p>Valid URI string</p></td><td><p>No</p></td></tr><tr><td><p><code>description</code></p></td><td><p>Description of the extension.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>No</p></td></tr><tr><td><p><code>required</code></p></td><td><p>Indicates if this extension is required.</p></td><td><p>Boolean</p></td><td><p><code>true</code> or <code>false</code></p></td><td><p>No</p></td></tr><tr><td><p><code>params</code></p></td><td><p>Parameters for the extension.</p></td><td><p>Object</p></td><td><p>Any object (for example, <code>{"hints": "Hint text"}</code>)</p></td><td><p>No</p></td></tr></tbody></table>

### Spec Section

`spec`

This section configures the broker’s internal implementation. You can think of this section as the
source code for your broker.

In this section, specify the LLM to use, custom instructions, available tools, and error handling.
The `links` section defines the agents that are available to this broker. Essentially, the `links`
section is where you define the agent network.

The `spec` element has these properties.

<table><colgroup><col> <col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th><th>Default</th></tr></thead><tbody><tr><td><p><code>llm</code></p></td><td><p>LLM configuration for the broker.</p></td><td><p>Object</p></td><td><p>See <a href="#llm-section">LLM</a></p></td><td><p>Yes</p></td><td><p>-</p></td></tr><tr><td><p><code>instructions</code></p></td><td><p>Set of custom instructions that will inform the orchestration.</p></td><td><p>Array of strings</p></td><td><p>Array of instruction strings</p></td><td><p>Yes</p></td><td><p>-</p></td></tr><tr><td><p><code>links</code></p></td><td><p>Defines the list of agents that this agent connects to.</p></td><td><p>Array</p></td><td><p>Array of link objects (See <a href="#links-section">Links</a>)</p></td><td><p>Yes</p></td><td><p>-</p></td></tr><tr><td><p><code>maxNumberOfLoops</code></p></td><td><p>The maximum number of steps that a task can take. Useful for keeping orchestrations from running too long and consuming too many tokens.</p></td><td><p>Integer</p></td><td><p>Positive integer</p></td><td><p>No</p></td><td><p>25</p></td></tr><tr><td><p><code>maxConsecutiveErrors</code></p></td><td><p>The maximum number of errors that the orchestrator will attempt to recover from before returning a failed status.</p></td><td><p>Integer</p></td><td><p>Positive integer</p></td><td><p>No</p></td><td><p>3</p></td></tr><tr><td><p><code>taskTimeoutSecs</code></p></td><td><p>A timeout (in seconds) for how long each orchestration task should run.</p></td><td><p>Integer</p></td><td><p>Positive integer</p></td><td><p>No</p></td><td><p>60</p></td></tr><tr><td><p><code>tools</code></p></td><td><p>The tools available to this broker.</p></td><td><p>Array</p></td><td><p>Array of tool objects (See <a href="#tools-section">Tools</a>)</p></td><td><p>No</p></td><td><p>-</p></td></tr><tr><td><p><code>policies</code></p></td><td><p>Policy bindings to be applied.</p></td><td><p>Array</p></td><td><p>Array of PolicyBinding objects (See <a href="#policies-section">Policies</a>)</p></td><td><p>No</p></td><td><p>-</p></td></tr></tbody></table>

#### LLM Section

`llm`

The value of this section is a reference to one of the LLMs defined in Anypoint Exchange or in the
`llmProviders` section of `agent-network.yaml`. Because it’s a reference, you can choose to share
the same LLM across all the brokers in your agent network. Or, you can have different brokers use
different LLMs to better suit their tasks. If using an LLM Proxy, configure the LLM Proxy as either
an OpenAI or Gemini LLM depending on the proxy’s format.

For more information about supported LLMs, see
[Large Language Models](https://docs.mulesoft.com/agent-network/1.0/af-agent-networks#llm-support).

The `llm` element has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>ref</code></p></td><td><p>The reference to the LLM to be used by the orchestrator.</p></td><td><p>String</p></td><td><p>See <a href="#llmproviders-section">LLM Providers</a></p></td><td><p>Yes</p></td></tr><tr><td><p><code>connection.ref</code></p></td><td><p>Connection reference.</p></td><td><p>String</p></td><td><p>See <a href="#connections-section">Connections</a></p></td><td><p>No</p></td></tr><tr><td><p><code>configuration.model</code></p></td><td><p>The name of the model to use.</p></td><td><p>String</p></td><td><p>Model name string</p></td><td><p>Yes</p></td></tr><tr><td><p><code>configuration.openAI</code></p></td><td><p>OpenAI specific configuration settings.</p></td><td><p>Object</p></td><td><p>Object with OpenAI settings</p></td><td><p>No</p></td></tr><tr><td><p><code>configuration.openAI.reasoningEffort</code></p></td><td><p>Constrains reasoning effort for reasoning models. Useful for managing performance and reason-token usage.</p></td><td><p>String</p></td><td><div><div><ul><li><p><code>NONE</code> (default for GPT-5.1)</p></li><li><p><code>MINIMAL</code></p></li><li><p><code>LOW</code></p></li><li><p><code>MEDIUM</code> (default for versions previous to GPT-5.1)</p></li><li><p><code>HIGH</code></p></li></ul></div></div></td><td><p>No</p></td></tr><tr><td><p><code>configuration.openAI.temperature</code></p></td><td><p>Controls randomness in the output. Requires GPT-5.1 and <code>reasoningEffort</code> set to <code>NONE</code>.</p></td><td><p>Number</p></td><td><p>Any number</p></td><td><p>No</p></td></tr><tr><td><p><code>configuration.openAI.topP</code></p></td><td><p>Nucleus sampling parameter. Requires GPT-5.1 and <code>reasoningEffort</code> set to <code>NONE</code>.</p></td><td><p>Number</p></td><td><p>Any number</p></td><td><p>No</p></td></tr><tr><td><p><code>configuration.openAI.topLogprobs</code></p></td><td><p>Number of most likely tokens to return at each position. Requires GPT-5.1 and <code>reasoningEffort</code> set to <code>NONE</code>.</p></td><td><p>Integer</p></td><td><p>Any integer</p></td><td><p>No</p></td></tr><tr><td><p><code>configuration.openAI.maxOutputTokens</code></p></td><td><p>Maximum number of tokens to generate.</p></td><td><p>Integer</p></td><td><p>Any integer</p></td><td><p>No</p></td></tr><tr><td><p><code>configuration.gemini</code></p></td><td><p>Gemini-specific configuration settings.</p></td><td><p>Object</p></td><td><p>Object with Gemini settings</p></td><td><p>No</p></td></tr><tr><td><p><code>configuration.gemini.thinkingBudget</code></p></td><td><p>Sets a token budget for the reasoning phase. (Applies only to Gemini 2.5 series.)</p></td><td><p>Integer</p></td><td><div><div><ul><li><p><code>0</code> (Disabled)</p></li><li><p><code>-1</code> (Automatic)</p></li><li><p><code>1024</code> to <code>32768</code></p></li></ul></div></div></td><td><p>No</p></td></tr><tr><td><p><code>configuration.gemini.thinkingLevel</code></p></td><td><p>Controls the depth of the reasoning process. (Applies only to Gemini 3 series.)</p></td><td><p>String</p></td><td><div><div><ul><li><p><code>High</code> (Default)</p></li><li><p><code>Low</code></p></li></ul></div></div></td><td><p>No</p></td></tr><tr><td><p><code>configuration.gemini.temperature</code></p></td><td><p>Controls randomness.</p></td><td><p>Number</p></td><td><p>For Gemini 3 and Gemini 2.5, Google recommends keeping this at <code>1.0</code> (default) to avoid breaking the reasoning chain.</p></td><td><p>No</p></td></tr><tr><td><p><code>configuration.gemini.topP</code></p></td><td><p>Nucleus sampling parameter.</p></td><td><p>Number</p></td><td><p>Any number</p></td><td><p>No</p></td></tr><tr><td><p><code>configuration.gemini.responseLogprobs</code></p></td><td><p>Whether to return log probabilities.</p></td><td><p>Boolean</p></td><td><p>true or false</p></td><td><p>No</p></td></tr><tr><td><p><code>configuration.gemini.maxOutputTokens</code></p></td><td><p>Maximum number of tokens that can be generated in the response.</p></td><td><p>Integer</p></td><td><p>Any integer</p></td><td><p>No</p></td></tr></tbody></table>

#### Instructions Section

`instructions`

Provides instructions that are specific to the broker. Instructions often focus on business-oriented
concerns. For example, here’s instructions for an employee onboarding broker.

```yaml
instructions:
  - |
    You're an Employee Onboarding Broker. Coordinate onboarding of a new employee across the systems needed for day-to-day work.
    ## The process for onboarding an employee is:
    - Onboard in HR: Create the new employee record. Fetch the address using available tools. Don't ask for the address unless you're not sure how to get it.
    - Onboard in CRM: Create the employee's CRM profile.
    - Send a Slack status update using SlackMcpServer.send_status_update (include contextId from input).
    - Request an employee laptop in Zendesk and initiate the employee badge request.
    - Send another Slack status update using SlackMcpServer.send_status_update (include contextId from input).
    - IT system setup: Provision the ping ID system for the employee.
    ## Final Response
    - Return a plain-text human-readable summary of all steps and actions taken, formatted as a bulleted list. Don't include tool names in the summary.
```

Here’s another example of instructions for a customer service broker. This broker coordinates
management of customer-reported incidents.

```yaml
instructions:
  - |
    You're an Incident Management Broker. Your primary responsibility is to coordinate the resolution of incidents reported by customers.
    The process for incident management is:
      1. Fetch CRM case details: Retrieve the latest critical case details for the customer.
      2. Fetch entitlement details: Obtain the customer's entitlement information.
      3. Fetch on-call engineer: Identify the current on-call engineer for the incident.
      4. Create Slack war room and invite on-call engineer: Set up a Slack war room channel and invite the on-call engineer.
      5. Summarize actions: Provide a clear, human-readable summary of the steps performed, including information about the created Slack channel and the on-call engineer assigned.
```

You don’t have to provide instructions like "split the message into tasks", or "select the best
tool". The broker does that on its own.

The `instructions` element has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>instructions</code></p></td><td><p>Set of custom instructions that will inform the behavior of the broker.</p></td><td><p>Array of strings</p></td><td><p>Array of instruction strings. Each item in the array is a string containing custom instructions for the broker</p></td><td><p>Yes</p></td></tr><tr><td><p><code>instructions[]</code></p></td><td><p>Individual instruction string.</p></td><td><p>String</p></td><td><p>Any string value. Typically contains business-oriented instructions, process descriptions, or guidelines for the broker’s behavior.</p></td><td><p>-</p></td></tr></tbody></table>

#### Tools Section

`tools`

Tools provide agents with external capabilities. When a broker needs to access an external service
that’s not another agent, it reaches out to an MCP server.

By default, the broker has access to all the tools available on the MCP server. However, most modern
LLMs can only handle around 20 to 25 tools per context before starting to hallucinate. Limit the
available tools to the minimum needed. You can apply that filtering through the allowed list.

Example

```yaml
tools:
  - mcp:
      ref:
        name: talent-pool-mcp # Exchange asset ID of MCP server. By default, the groupId for this asset is the same as that in exchange.json.
      allowed: # Allowlist specific tools
        - TalentPoolMcpServer.match_email_to_address
      headersToPropagate: [Authorization, X-Request-Id] # Optional. Header names to forward when invoking this tool.
  - mcp:
      ref:
        name: slack-mcp
      allowed:
        - SlackMcpServer.send_status_update
```

The `tools` element has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>mcp.ref</code></p></td><td><p>The reference to the MCP server that is available to this broker.</p></td><td><p>String</p></td><td><p>See <a href="#mcp-servers-section">MCP Servers</a></p></td><td><p>Yes</p></td></tr><tr><td><p><code>mcp.connection.ref</code></p></td><td><p>Connection reference.</p></td><td><p>String</p></td><td><p>See <a href="#connections-section">Connections</a></p></td><td><p>No</p></td></tr><tr><td><p><code>mcp.allowed</code></p></td><td><p>Filters the list of tools advertised by the MCP server to only those in this list. Mutually exclusive with 'denied'.</p></td><td><p>Array of strings</p></td><td><p>Array of tool name strings</p></td><td><p>No</p></td></tr><tr><td><p><code>mcp.headersToPropagate</code></p></td><td><p>The names of the request headers to propagate when the broker invokes this tool.</p></td><td><p>Array of strings</p></td><td><p>Array of header name strings</p></td><td><p>No</p></td></tr></tbody></table>

#### Links Section

`links`

This section is the most important part of the spec, as it defines the agents that are available to
a broker. It enables interagent communication and orchestration. The broker relies on the agents
linked here to execute the appropriate actions to complete a user’s goal.

Example 1

```yaml
links:
  - agent:
      ref:
        name: hr-agent # Exchange asset ID of the linked agent. By default, the groupId for this asset is the same as that in exchange.json.
        namespace: # Optional. If the asset was defined in a different business group, set the corresponding groupId here.
      headersToPropagate: [Authorization, X-Correlation-Id] # Optional. Header names to forward when invoking this agent.
  - agent:
      ref:
        name: badging-agent
  - agent:
      ref:
        name: crm-agent
  - agent:
      ref:
        name: zendesk-agent
  - agent:
      ref:
        name: it-agent
```

Keep this section short. Don’t add all available agents. Just like `tools`, excess values here lead
to drops in agent network accuracy and determinism.

Instead, use a multi-level hierarchical approach. This favors traceability and management and helps
keep context sizes in check.

Example 2

In this example, the Onboarding Broker orchestrates the process of onboarding a new hire. It
orchestrates work with the IT, HR and security brokers, which also happen to be brokers in the same
agent network.

Assets, IT Stock, HR, Payroll, and Badges agents are also called **leaf agents**. These aren’t
brokers but preexisting agents whose purpose isn’t to coordinate work, but to act.

![Diagram showing an employee onboarding broker and its agents](/mulesoft/current/en-us/agent-network/1.0/_images/af-onboarding-broker-example.png)

The `links` element has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>links</code></p></td><td><p>Defines the list of agents that this agent connects to. This defines the agent network and enables inter-agent communication and orchestration.</p></td><td><p>Array</p></td><td><p>Array of link objects</p></td><td><p>Yes</p></td></tr><tr><td><p><code>links[]</code></p></td><td><p>A link object in the links array.</p></td><td><p>Object</p></td><td><p>Object with <code>agent</code> property</p></td><td><p>Yes</p></td></tr><tr><td><p><code>links[].agent</code></p></td><td><p>Agent connection configuration.</p></td><td><p>Object</p></td><td><p>Object with agent properties</p></td><td><p>Yes</p></td></tr><tr><td><p><code>links[].agent.ref.name</code></p></td><td><p>Exchange asset ID of the linked agent. This references the <code>assetId</code> that the agent has in Anypoint Exchange, not the human-friendly name.</p></td><td><p>String</p></td><td><p>Asset ID string (for example, "hr-agent", "crm-agent"). By default, the groupId for this asset is the same as that in exchange.json</p></td><td><p>Yes</p></td></tr><tr><td><p><code>links[].agent.ref.namespace</code></p></td><td><p>Business group ID (groupId) where the asset is defined. Use this when the asset was defined in a different business group than the current one.</p></td><td><p>String</p></td><td><p>Group ID string. To find the groupId, look in the <code>dependencies</code> section in <code>exchange.json</code></p></td><td><p>No</p></td></tr><tr><td><p><code>links[].agent.connection.ref</code></p></td><td><p>Connection reference.</p></td><td><p>String</p></td><td><p>See <a href="#connections-section">Connections</a>. This references a connection defined in the <code>connections</code> section</p></td><td><p>No</p></td></tr><tr><td><p><code>links[].agent.headersToPropagate</code></p></td><td><p>The names of the request headers to propagate when the broker invokes this agent.</p></td><td><p>Array of strings</p></td><td><p>Array of header name strings</p></td><td><p>No</p></td></tr></tbody></table>

#### Policies Section

`policies`

The `policies` section contains the list of policies to apply to the broker. It contains a reference
to the policy that needs to be added as a dependency to the agent network project.

Example

```yaml
policies:
  - ref:
      name: # Exchange asset ID of the policy. By default, the groupId for this asset is the same as that in exchange.json.
      namespace: # Optional. If the policy was defined in a different business group, set the corresponding groupId here.
    configuration:
      policyConfig1: policyConfig1Value
```

Apply policies at the broker or at the connection. Reference the policy definition and apply the
configuration.

For more information about applying policies via Omni Gateway in Local Mode, see:

- [Securing Agent Interactions with Omni Gateway](https://docs.mulesoft.com/gateway/latest/agent-secure)

- [Applying Policies in Local Mode](https://docs.mulesoft.com/gateway/latest/gateway-secure-local)

> [!NOTE] When you add governance policies to your project, those policies persist between
> deployments. However, if you add governance policies at runtime, those policies won’t persist.

The `policies` element has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>ref</code></p></td><td><p>Policy reference.</p></td><td><p>String</p></td><td><p>See <a href="#policies-section">Policies</a></p></td><td><p>Yes</p></td></tr><tr><td><p><code>configuration</code></p></td><td><p>Policy configuration.</p></td><td><p>Object</p></td><td><p>Any object</p></td><td><p>Yes</p></td></tr></tbody></table>

### Error Handling

Use these properties to handle error scenarios. Define these properties within the `spec` section of
a broker configuration.

<table><colgroup><col> <col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th><th>Default</th></tr></thead><tbody><tr><td><p><code>maxNumberOfLoops</code></p></td><td><p>The maximum number of steps that a task can take. Useful for keeping orchestrations from running too long and consuming too many tokens.</p></td><td><p>Integer</p></td><td><p>Positive integer</p></td><td><p>No</p></td><td><p>25</p></td></tr><tr><td><p><code>maxConsecutiveErrors</code></p></td><td><p>The maximum number of errors that the orchestrator will attempt to recover from before returning a failed status.</p></td><td><p>Integer</p></td><td><p>Positive integer</p></td><td><p>No</p></td><td><p>3</p></td></tr><tr><td><p><code>taskTimeoutSecs</code></p></td><td><p>A timeout (in seconds) for how long each orchestration task should run.</p></td><td><p>Integer</p></td><td><p>Positive integer (seconds)</p></td><td><p>No</p></td><td><p>60</p></td></tr></tbody></table>

#### Error Handling Considerations

- `maxNumberOfLoops`

  - Each step in an orchestration consumes tokens.

  - Complex tasks may require more steps.

  - Simple tasks should complete with fewer steps.

  - The default of 25 maximum loops is suitable for most use cases.

- `maxConsecutiveErrors`

  - Allows the orchestrator to retry failed operations.

  - Prevents infinite retry loops.

  - Default of `3` attempts provides a balance between resilience and failure detection. After
    reaching this limit, the orchestration returns a failed status.

- `taskTimeoutSecs`

  - Applies to each individual orchestration task.

  - Accounts for network latency and external service response times.

  - Default of 60 seconds is suitable for most API-based operations. Tasks exceeding this timeout
    are terminated.

## Agents Section

`agents`

Reference agents defined in a different agent network, or another agent used in your company. Any
agent is valid, as long as it supports A2A as its communication protocol. For more information, see
[af-agent-networks.adoc#a2a-protocol](https://docs.mulesoft.com/agent-network/1.0/af-agent-networks#a2a-protocol)

Example

```yaml
agents:
  hr-agent: # Used as the assetId of the asset published to Anypoint Exchange. The default groupId is the associated value used in exchange.json.
    metadata:
      platform: azure
      protocol: a2a
  badging-agent:
    metadata:
      platform: azure
      protocol: a2a
  crm-agent:
    metadata:
      platform: azure
      protocol: a2a
  zendesk-agent:
    metadata:
      platform: azure
      protocol: a2a
  it-agent:
    metadata:
      platform: azure
      protocol: a2a
```

The `agents` element has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>label</code></p></td><td><p>A label for this agent.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>No</p></td></tr><tr><td><p><code>description</code></p></td><td><p>A description for this agent.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>No</p></td></tr><tr><td><p><code>tags</code></p></td><td><p>Tags associated with this agent.</p></td><td><p>Array</p></td><td><p>Array of string values</p></td><td><p>No</p></td></tr><tr><td><p><code>card</code></p></td><td><p>Agent card definition.</p></td><td><p>Object</p></td><td><p>See <a href="#card-section">Card</a></p></td><td><p>No</p></td></tr><tr><td><p><code>metadata</code></p></td><td><p>Agent metadata configuration.</p></td><td><p>Object</p></td><td><p>Object with <code>protocol</code> property</p></td><td><p>Yes</p></td></tr><tr><td><p><code>metadata.platform</code></p></td><td><p>The name of the platform running this agent. For example, Bedrock, AgentForce, etc.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>No</p></td></tr><tr><td><p><code>metadata.protocol</code></p></td><td><p>The name of the protocol. For example, a2a.</p></td><td><p>String</p></td><td><p><code>a2a</code>, <code>other</code></p></td><td><p>Yes</p></td></tr><tr><td><p><code>metadata.links</code></p></td><td><p>Defines the list of agents that this agent connects to.</p></td><td><p>Array</p></td><td><p>Array of objects with <code>agent.ref</code> property</p></td><td><p>No</p></td></tr><tr><td><p><code>metadata.tools</code></p></td><td><p>Defines the list of tools that this agent connects to.</p></td><td><p>Array</p></td><td><p>Array of objects with <code>mcp.ref</code> property</p></td><td><p>No</p></td></tr></tbody></table>

## MCP Servers Section

`mcpServers`

This section lists the MCP servers in your agent network. Use these servers to obtain relevant
context and generate notifications. To apply governance to an MCP server using the agent network
file, it must be in your `agent-network.yaml` file or published to Anypoint Exchange as an asset.

Example

```yaml
mcpServers:
  talent-pool-mcp: # Value used as the assetId in exchange.json. The groupId defaults to the associated value used in exchange.json.
    metadata:
      transport: # Communication method
        kind: streamableHttp # HTTP-based transport
        path: /mcp
        # OR
        sse: # Server-Sent Events transport
          ssePath: /sse
          messagesPath: /messages
      tools: # Server-level tool filtering
        allowed: [tool1, tool2]
  slack-mcp:
    metadata:
      transport:
        kind: streamableHttp
        path: /mcp
```

We support both MCP `streamableHttp` and SSE transports, but we recommend `streamableHttp`.

Just like in the `brokers` section, an allowed attribute is available to filter the available tools.
The allowed attribute in the `brokers` section is more granular and applied only to that specific
broker. In the `mcpServers` section, this attribute applies to the MCP server as a whole, filtering
at the group level.

The `mcpServers` element has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>label</code></p></td><td><p>A label for this MCP server.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>No</p></td></tr><tr><td><p><code>description</code></p></td><td><p>A description for this MCP server.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>No</p></td></tr><tr><td><p><code>tags</code></p></td><td><p>Tags associated with this MCP server.</p></td><td><p>Array</p></td><td><p>Array of string values</p></td><td><p>No</p></td></tr><tr><td><p><code>metadata</code></p></td><td><p>MCP server metadata configuration.</p></td><td><p>Object</p></td><td><p>See <a href="#mcp-servers-section">MCP Servers</a></p></td><td><p>Yes</p></td></tr><tr><td><p><code>metadata.transport</code></p></td><td><p>Communication method configuration for the MCP server.</p></td><td><p>Object</p></td><td><p>Object with transport properties</p></td><td><p>No</p></td></tr><tr><td><p><code>metadata.transport.kind</code></p></td><td><p>The transport protocol type.</p></td><td><p>String</p></td><td><p><code>streamableHttp</code>, <code>sse</code></p></td><td><p>Yes</p></td></tr><tr><td><p><code>metadata.transport.path</code></p></td><td><p>The path for the <code>streamableHttp</code> transport.</p></td><td><p>String</p></td><td><p>Any string value (for example, <code>/mcp</code>)</p></td><td><p>No</p></td></tr><tr><td><p><code>metadata.transport.sse.ssePath</code></p></td><td><p>The SSE path for Server-Sent Events transport.</p></td><td><p>String</p></td><td><p>Any string value (for example, <code>/sse</code>)</p></td><td><p>No</p></td></tr><tr><td><p><code>metadata.transport.sse.messagesPath</code></p></td><td><p>The messages path for Server-Sent Events transport.</p></td><td><p>String</p></td><td><p>Any string value (for example, <code>/messages</code>)</p></td><td><p>No</p></td></tr><tr><td><p><code>metadata.tools</code></p></td><td><p>Server-level tool filtering configuration.</p></td><td><p>Object</p></td><td><p>Object with <code>allowed</code> array property</p></td><td><p>No</p></td></tr><tr><td><p><code>metadata.tools.allowed</code></p></td><td><p>Filters the list of tools advertised by the MCP server to only those in this list.</p></td><td><p>Array</p></td><td><p>Array of tool name strings</p></td><td><p>No</p></td></tr></tbody></table>

## LLMProviders Section

`llmProviders`

Configure the LLMs the brokers use for reasoning. For more information about supported LLMs, see
[Large Language Models](https://docs.mulesoft.com/agent-network/1.0/af-agent-networks#llm-support).

The `llmProviders` element has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>llmProviders</code></p></td><td><p>The list of LLM providers defined as part of this network.</p></td><td><p>Object</p></td><td><p>Object with property names matching pattern: <code>^[a-zA-Z_][a-zA-Z0-9_.-]*$</code> (must start with letter or underscore, can contain letters, numbers, underscores, dots, hyphens). Each property value is an llmEntity object</p></td><td><p>-</p></td></tr><tr><td><p><code>label</code></p></td><td><p>A label for this LLM.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>No</p></td></tr><tr><td><p><code>description</code></p></td><td><p>The description of this LLM.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>No</p></td></tr><tr><td><p><code>metadata</code></p></td><td><p>LLM metadata configuration.</p></td><td><p>Object</p></td><td><p>Either WellKnownLLM or CustomLLM object (See <a href="#metadata-properties">metadata properties</a>)</p></td><td><p>Yes</p></td></tr></tbody></table>

### `metadata` Properties

The `metadata` property uses a `oneOf` structure, so it must be either a `WellKnownLLM` or a
`CustomLLM` object but not both.

The `WellKnownLLM` object has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>platform</code></p></td><td><p>The LLM platform provider.</p></td><td><p>String</p></td><td><p><code>OpenAI</code>, <code>AzureOpenai</code></p></td><td><p>Yes</p></td></tr><tr><td><p><code>models</code></p></td><td><p>List of available models for this platform.</p></td><td><p>Array of strings</p></td><td><p>Array of model name strings</p></td><td><p>No</p></td></tr></tbody></table>

The `CustomLLM` object has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>platform</code></p></td><td><p>The LLM platform provider name.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>Yes</p></td></tr><tr><td><p><code>models</code></p></td><td><p>List of available models for this platform.</p></td><td><p>Array of strings</p></td><td><p>Array of model name strings</p></td><td><p>No</p></td></tr><tr><td><p><code>transcoder.ref</code></p></td><td><p>Reference to the transcoder policy.</p></td><td><p>String</p></td><td><p>See <a href="#policies-section">Policies</a></p></td><td><p>No</p></td></tr></tbody></table>

## Connections Section

`connections`

The `connections` section defines one or more connections to instances of an agent network asset.
For example, if an agent is deployed multiple times across regions and environments, you can define
a connection for each deployed agent instance, regardless of whether it’s used by a broker or not.

Connections are elements that are deployed, but they don’t have Exchange assets that represent them.
They’re connected to assets (agents, MCP servers, LLMs). They’re deployed in API Manager in the
egress gateway.

To define multiple connections for the same asset, put them in a resource file and reference the
file in this section.

Example

```yaml
connections:
  hr-agent:
    kind: agent
    ref:
      name: hr-agent # Use the same name as in the associated entry in the agents section or use the Exchange asset ID.
    spec:
      url: https://hr-a2a-agent-inkbh1.paga8m.usa-w1.cloudhub.io/hr-agent/
      authentication:
        kind: oauth2-client-credentials
        token:
          bodyEncoding: form
          timeout: 300
          url: test.com # Use a variable
        clientId: clientId # Use a variable like ${hrAgent.clientId} and define in in exchange.json so the user is prompted for the value at deployment.
        clientSecret: clientSecret # Use a variable

  badging-agent:
    kind: agent
    ref:
      name: badging-agent
    spec:
      url: https://badge-agent-inkbh1.paga8m.usa-w1.cloudhub.io/badge-agent/
      authentication:
        kind: oauth2-client-credentials
        token:
          bodyEncoding: form
          timeout: 300
          url: test.com
        clientId: clientId
        clientSecret: clientSecret

  crm-agent:
    kind: agent
    ref:
      name: crm-agent
    spec:
      url: https://crm-a2a-agent-inkbh1.paga8m.usa-w1.cloudhub.io/crm-agent/
      authentication:
        kind: oauth2-client-credentials
        token:
          bodyEncoding: form
          timeout: 300
          url: test.com
        clientId: clientId
        clientSecret: clientSecret

  zendesk-agent:
    kind: agent
    ref:
      name: zendesk-agent
    spec:
      url: https://zendesk-a2a-agent-inkbh1.paga8m.usa-w1.cloudhub.io/zendesk/
      authentication:
        kind: oauth2-client-credentials
        token:
          bodyEncoding: form
          timeout: 300
          url: test.com
        clientId: clientId
        clientSecret: clientSecret

  it-agent:
    kind: agent
    ref:
      name: it-agent
    spec:
      url: https://ping-id-a2a-agent-inkbh1.paga8m.usa-w1.cloudhub.io/pingid/
      authentication:
        kind: oauth2-client-credentials
        token:
          bodyEncoding: form
          timeout: 300
          url: test.com
        clientId: clientId
        clientSecret: clientSecret

  my-openAI:
    kind: llm
    ref:
      name: my-openAI
    spec:
      url: https://api.openai.com/v1/
      configuration:
        apiKey: ${openai.apiKey} # Define the API key of an LLM Proxy as <<clientId>>:<<clientSecret>>

  talent-pool-mcp:
    kind: mcp
    ref:
      name: talent-pool-mcp
    spec:
      url: https://talent-pool-mcp-server-inkbh1.paga8m.usa-w1.cloudhub.io/
      authentication:
        kind: apiKey
        apiKey: ${talentPool.apiKey} # Define variable in exchange.json
        headerName: X-MCP-API-Key # Optional, defaults to Authorization

  slack-mcp:
    kind: mcp
    ref:
      name: slack-mcp
    spec:
      url: https://slack-mcp-server-inkbh1.paga8m.usa-w1.cloudhub.io/
      authentication:
        kind: apiKey
        apiKey: ${slack.apiKey} # Define variable in exchange.json
        headerName: X-API-Key
```

The `connections` element has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>connections</code></p></td><td><p>The list of connections defined as part of this network.</p></td><td><p>Object</p></td><td><p>Object with property names matching pattern: <code>^[a-zA-Z_][a-zA-Z0-9_.-]*$</code> (must start with letter or underscore, can contain letters, numbers, underscores, dots, hyphens). Each property value is a ConnectionElement object</p></td><td><p>-</p></td></tr><tr><td><p><code>kind</code></p></td><td><p>The type of connection.</p></td><td><p>String</p></td><td><p><code>agent</code>, <code>llm</code>, <code>mcp</code></p></td><td><p>Yes</p></td></tr><tr><td><p><code>ref</code></p></td><td><p>Reference to the asset this connection is for.</p></td><td><p>Object</p></td><td><p>Object with reference properties (See <a href="#ref-element">ref properties</a>)</p></td><td><p>Yes</p></td></tr><tr><td><p><code>ref.name</code></p></td><td><p>Exchange asset ID of the connected asset.</p></td><td><p>String</p></td><td><p>Asset ID string. For agents, use the same name as in the associated entry in the agents section or use the Exchange asset ID. For LLMs, use the name from llmProviders. For MCP servers, use the name from mcpServers</p></td><td><p>Yes</p></td></tr><tr><td><p><code>ref.namespace</code></p></td><td><p>Business group ID (groupId) where the asset is defined. Use this when the asset was defined in a different business group than the current one.</p></td><td><p>String</p></td><td><p>Group ID string. To find the groupId, look in the <code>dependencies</code> section in <code>exchange.json</code></p></td><td><p>No</p></td></tr><tr><td><p><code>spec</code></p></td><td><p>Connection specification. Properties vary by connection kind.</p></td><td><p>Object</p></td><td><p>Object with spec properties (See <a href="#spec-section">Spec</a>)</p></td><td><p>Yes</p></td></tr><tr><td><p><code>spec.url</code></p></td><td><p>The URL for the connection endpoint.</p></td><td><p>String</p></td><td><p>Valid URL string</p></td><td><p>Yes (for agent and llm), No (for mcp)</p></td></tr><tr><td><p><code>spec.authentication</code></p></td><td><p>Authentication configuration for the connection.</p></td><td><p>Object</p></td><td><p>Authentication object (See <a href="#authentication-types">Authentication types</a>)</p></td><td><p>No</p></td></tr><tr><td><p><code>spec.authentication.kind</code></p></td><td><p>The type of authentication.</p></td><td><p>String</p></td><td><p><code>basic</code>, <code>oauth2-client-credentials</code>, <code>apikey-client-credentials</code>, <code>apiKey</code>, <code>in-task-authorization-code</code>, and <code>oauth2-obo</code></p></td><td><p>Yes (when authentication is specified)</p></td></tr><tr><td><p><code>spec.authentication.username</code></p></td><td><p>The username for basic authentication.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>Yes (for basic auth)</p></td></tr><tr><td><p><code>spec.authentication.password</code></p></td><td><p>The password for basic authentication.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>Yes (for basic auth)</p></td></tr><tr><td><p><code>spec.authentication.headerName</code></p></td><td><p>The name of the header in which to set the key. If not specified, 'Authorization' is set by default.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>No</p></td></tr><tr><td><p><code>spec.authentication.clientId</code></p></td><td><p>The client ID for OAuth 2.0 or API key client credentials authentication.</p></td><td><p>String or Object</p></td><td><div><div><ul><li><p>API key client requires an object with <code>value</code> and optional <code>name</code> properties.</p></li><li><p>OAuth 2.0 requires a string value.</p></li></ul></div></div></td><td><p>Yes (for oauth2-client-credentials and apikey-client-credentials)</p></td></tr><tr><td><p><code>spec.authentication.clientSecret</code></p></td><td><p>The client secret for OAuth 2.0 or API key client credentials authentication.</p></td><td><p>String or Object</p></td><td><div><div><ul><li><p>API key client requires an object with <code>value</code> and optional <code>name</code> properties.</p></li><li><p>OAuth 2.0 requires a string value.</p></li></ul></div></div></td><td><p>Yes (for oauth2-client-credentials and apikey-client-credentials)</p></td></tr><tr><td><p><code>spec.authentication.token</code></p></td><td><p>Configuration on how to fetch the OAuth 2.0 token.</p></td><td><p>Object</p></td><td><p>Object with token properties</p></td><td><p>Yes (for oauth2-client-credentials)</p></td></tr><tr><td><p><code>spec.authentication.token.url</code></p></td><td><p>The URL of the token provider.</p></td><td><p>String</p></td><td><p>Valid URL string</p></td><td><p>Yes</p></td></tr><tr><td><p><code>spec.authentication.token.timeout</code></p></td><td><p>Time in seconds to wait for the service to return the token.</p></td><td><p>Number</p></td><td><p>Any number</p></td><td><p>No</p></td></tr><tr><td><p><code>spec.authentication.token.bodyEncoding</code></p></td><td><p>The encoding format for the token request body.</p></td><td><p>String</p></td><td><p><code>form</code>, <code>json</code></p></td><td><p>No</p></td></tr><tr><td><p><code>spec.authentication.scopes</code></p></td><td><p>An array of scopes to request for OAuth 2.0.</p></td><td><p>Array</p></td><td><p>Array of scope strings</p></td><td><p>No</p></td></tr><tr><td><p><code>spec.authentication.apiKey</code></p></td><td><p>The value of the API key for API key authentication.</p></td><td><p>String</p></td><td><p>Any string value</p></td><td><p>Yes (for apiKey)</p></td></tr><tr><td><p><code>spec.configuration</code></p></td><td><p>LLM-specific configuration object.</p></td><td><p>Object</p></td><td><p>Any object</p></td><td><p>Yes (for llm connections)</p></td></tr><tr><td><p><code>spec.policies</code></p></td><td><p>Policy bindings to be applied to the connection.</p></td><td><p>Array</p></td><td><p>Array of PolicyBinding objects (See <a href="#policies-section">Policies</a>)</p></td><td><p>No</p></td></tr><tr><td><p><code>spec.policies[].ref</code></p></td><td><p>Policy reference.</p></td><td><p>Object</p></td><td><p>Object with <code>name</code> and optional <code>namespace</code> properties</p></td><td><p>Yes</p></td></tr><tr><td><p><code>spec.policies[].ref.name</code></p></td><td><p>Exchange asset ID of the policy. By default, the groupId for this asset is the same as that in exchange.json.</p></td><td><p>String</p></td><td><p>Asset ID string</p></td><td><p>Yes</p></td></tr><tr><td><p><code>spec.policies[].ref.namespace</code></p></td><td><p>Optional. If the policy was defined in a different business group, set the corresponding groupId here.</p></td><td><p>String</p></td><td><p>Group ID string</p></td><td><p>No</p></td></tr><tr><td><p><code>spec.policies[].configuration</code></p></td><td><p>Policy configuration.</p></td><td><p>Object</p></td><td><p>Any object</p></td><td><p>Yes</p></td></tr></tbody></table>

### Connection Resolution

Connection resolution happens at deployment time. The connection reference can be explicit or
implicit.

#### Explicit

In this example, the connection to use is **weather-agent-connection**. At deployment, it validates
that a connection with the given name exists in the egress gateway on the specified environment.

Example

```yaml
- agent:
    ref:
      name: weather-agent

    connection:
      ref:
        name: weather-agent-connection
```

#### Implicit

If a connection isn’t specified, it defaults to a connection whose name matches the target asset’s
name.

In this example, at deployment a connection to the specified agent asset (weather-agent) is searched
for. If it exists, it’s injected. If not, it fails with an exception.

Example

```yaml
- agent:
    ref:
      name: weather-agent
```

### Authentication Types

Connection authentication is always expressed in accordance with
[Open API authentication methods](https://swagger.io/docs/specification/v3_0/authentication/).

These examples show how to define each supported authentication type in YAML.

Both agents and MCP servers support the same authentication types with custom header capabilities
API Key Authentication and Basic Authentication.

#### Basic Authentication

```yaml
authentication:
  kind: basic
  username: "username"
  password: "password"
```

Using custom header:

```yaml
authentication:
  kind: basic
  username: "username"
  password: "password"
  headerName: X-API-Authorization # Custom header instead of default "Authorization"
```

The `basic` authentication has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>kind</code></p></td><td><p>Authentication type.</p></td><td><p>String</p></td><td><p><code>basic</code></p></td><td><p>Yes</p></td></tr><tr><td><p><code>username</code></p></td><td><p>The username for authentication.</p></td><td><p>String</p></td><td><p>Any string</p></td><td><p>Yes</p></td></tr><tr><td><p><code>password</code></p></td><td><p>The password for authentication.</p></td><td><p>String</p></td><td><p>Any string</p></td><td><p>Yes</p></td></tr><tr><td><p><code>headerName</code></p></td><td><p>The name of the header in which to set the credentials. If not specified, <code>Authorization</code> is used.</p></td><td><p>String</p></td><td><p>Any string</p></td><td><p>No</p></td></tr></tbody></table>

#### OAuth 2.0 Client Credentials

```yaml
authentication:
  kind: oauth2-client-credentials
  clientId: "client_id"
  clientSecret: "client_secret"
  token:
    url: "https://oauth.provider.com/token"
    bodyEncoding: form
    timeout: 300
  scopes: ["read", "write"] # Optional
```

The `oauth2-client-credentials` authentication has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>kind</code></p></td><td><p>Authentication type.</p></td><td><p>String</p></td><td><p><code>oauth2-client-credentials</code></p></td><td><p>Yes</p></td></tr><tr><td><p><code>clientId</code></p></td><td><p>The client ID.</p></td><td><p>String</p></td><td><p>Any string</p></td><td><p>Yes</p></td></tr><tr><td><p><code>clientSecret</code></p></td><td><p>The client secret.</p></td><td><p>String</p></td><td><p>Any string</p></td><td><p>Yes</p></td></tr><tr><td><p><code>token</code></p></td><td><p>Configuration for fetching the token.</p></td><td><p>Object</p></td><td><p>Object with token properties</p></td><td><p>Yes</p></td></tr><tr><td><p><code>token.url</code></p></td><td><p>The URL of the token provider.</p></td><td><p>String</p></td><td><p>Valid URL</p></td><td><p>Yes</p></td></tr><tr><td><p><code>token.timeout</code></p></td><td><p>Time in seconds to wait for the service to return the token.</p></td><td><p>Number</p></td><td><p>Any number</p></td><td><p>No</p></td></tr><tr><td><p><code>token.bodyEncoding</code></p></td><td><p>The encoding format for the token request body.</p></td><td><p>String</p></td><td><p><code>form</code>, <code>json</code></p></td><td><p>No</p></td></tr><tr><td><p><code>scopes</code></p></td><td><p>An array of scopes to request.</p></td><td><p>Array</p></td><td><p>Array of scope strings</p></td><td><p>No</p></td></tr></tbody></table>

#### Anypoint Client Credentials

```yaml
authentication:
  kind: apikey-client-credentials
  clientId: "client_id"
  clientSecret: "client_secret"
```

The `apikey-client-credentials` authentication has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>kind</code></p></td><td><p>Authentication type.</p></td><td><p>String</p></td><td><p><code>apikey-client-credentials</code></p></td><td><p>Yes</p></td></tr><tr><td><p><code>clientId</code></p></td><td><p>The client ID.</p></td><td><p>Object</p></td><td><p>Object with <code>value</code> and optional <code>name</code> (default header name is <code>client_id</code>)</p></td><td><p>Yes</p></td></tr><tr><td><p><code>clientSecret</code></p></td><td><p>The client secret.</p></td><td><p>Object</p></td><td><p>Object with <code>value</code> and optional <code>name</code> (default header name is <code>client_secret</code>)</p></td><td><p>Yes</p></td></tr></tbody></table>

#### API Key Authentication

```yaml
authentication:
  kind: api-key
  apiKey: ${agent.apiKey} # Define variable in exchange.json
  headerName: X-API-Key # Optional, defaults to Authorization
```

Using custom header:

```yaml
authentication:
  kind: apiKey
  apiKey: ${agent.apiKey}
  headerName: X-Custom-Auth-Token # Custom header name
```

The `apiKey` authentication has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>kind</code></p></td><td><p>Authentication type.</p></td><td><p>String</p></td><td><p><code>apiKey</code></p></td><td><p>Yes</p></td></tr><tr><td><p><code>apiKey</code></p></td><td><p>The value of the API key.</p></td><td><p>String</p></td><td><p>Any string</p></td><td><p>Yes</p></td></tr><tr><td><p><code>headerName</code></p></td><td><p>The name of the header in which to set the key. If not specified, <code>Authorization</code> is used.</p></td><td><p>String</p></td><td><p>Any string</p></td><td><p>No</p></td></tr></tbody></table>

#### 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
[A2A In-Task Authorization Code Policy](https://docs.mulesoft.com/gateway/latest/policies-outbound-a2a-intask-authorization-code).

```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 #Optional, Status code for challenge response. Default: 200.
  tokenTimeout: 300 #Optional. Timeout in seconds for token requests. Default: 300.
```

The `in-task-authorization-code` authentication has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>kind</code></p></td><td><p>Authentication type.</p></td><td><p>String</p></td><td><p><code>in-task-authorization-code</code></p></td><td><p>Yes</p></td></tr><tr><td><p><code>authorizationEndpoint</code></p></td><td><p>OAuth2 authorization endpoint URL. Used to generate the authentication challenge.</p></td><td><p>String</p></td><td><p>Valid URL</p></td><td><p>Yes</p></td></tr><tr><td><p><code>tokenEndpoint</code></p></td><td><p>OAuth2 token endpoint URL. Used to generate the authentication challenge.</p></td><td><p>String</p></td><td><p>Valid URL</p></td><td><p>Yes</p></td></tr><tr><td><p><code>scopes</code></p></td><td><p>OAuth2 scopes required for step-up authentication.</p></td><td><p>String</p></td><td><p>Space- or comma-separated scope list (for example, <code>openid profile email</code>)</p></td><td><p>Yes</p></td></tr><tr><td><p><code>redirectUri</code></p></td><td><p>OAuth2 redirect URI the client uses in the authorization flow.</p></td><td><p>String</p></td><td><p>Valid URI</p></td><td><p>Yes</p></td></tr><tr><td><p><code>secondaryAuthProvider</code></p></td><td><p>Name of the IdP (for example, <code>okta</code>, <code>auth0</code>). Informational only, for the authentication card.</p></td><td><p>String</p></td><td><p>Any string</p></td><td><p>No</p></td></tr><tr><td><p><code>responseType</code></p></td><td><p>OAuth2 response type.</p></td><td><p>String</p></td><td><p>Typically <code>code</code>. Default: <code>code</code></p></td><td><p>No</p></td></tr><tr><td><p><code>codeChallengeMethod</code></p></td><td><p>PKCE code challenge method.</p></td><td><p>String</p></td><td><p>Typically <code>S256</code>. Default: <code>S256</code></p></td><td><p>No</p></td></tr><tr><td><p><code>tokenAudience</code></p></td><td><p>Intended recipient of the token (for example, <code>agent1</code> or API URL).</p></td><td><p>String</p></td><td><p>Any string</p></td><td><p>No</p></td></tr><tr><td><p><code>bodyEncoding</code></p></td><td><p>Encoding for the token request body.</p></td><td><p>String</p></td><td><p><code>form</code>, <code>json</code>. Default: <code>form</code></p></td><td><p>No</p></td></tr><tr><td><p><code>tokenTimeout</code></p></td><td><p>Timeout in seconds for token requests.</p></td><td><p>Integer</p></td><td><p>Positive integer. Default: 300</p></td><td><p>No</p></td></tr><tr><td><p><code>challengeResponseStatusCode</code></p></td><td><p>HTTP status code returned for auth-required challenge responses. Typically 200 for JSON-RPC compatibility.</p></td><td><p>Integer</p></td><td><p>HTTP status code. Default: 200</p></td><td><p>No</p></td></tr></tbody></table>

#### 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
[OAuth 2.0 OBO Credential Injection Policy](https://docs.mulesoft.com/gateway/latest/policies-outbound-oauth-obo).

Using OAuth 2.0 Token Exchange:

```yaml
authentication:
  kind: oauth2-obo
  flow: oauth2-token-exchange
  tokenEndpoint: https://oauth.provider.com/token
  clientId: clientId
  clientSecret: clientSecret
  targetType: audience # Optional. Logical identifier (audience) or physical URI (resource). Default: audience.
  targetValue: https://api.example.com/agents/my-agent
  scope: Read # Optional for OAuth 2.0 Token Exchange (RFC 8693). Required for Microsoft Entra OBO and CIBA.
  timeout: 5000 # Optional. Timeout for token exchange requests in milliseconds. Default: 10000.
```

Using Microsoft Entra ID On-Behalf-Of:

```yaml
authentication:
  kind: oauth2-obo
  flow: microsoft-entra-obo
  tokenEndpoint: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
  clientId: clientId
  clientSecret: clientSecret
  scope: api://downstream-client-id/.default # Required for Microsoft Entra OBO flows.
  timeout: 8000 # Optional. Timeout for token exchange requests in milliseconds. Default: 10000.
```

Using OAuth 2.0 Token Exchange with CIBA (client-initiated backchannel authentication):

```yaml
authentication:
  kind: oauth2-obo
  flow: oauth2-token-exchange
  tokenEndpoint: https://oauth.provider.com/token
  clientId: clientId
  clientSecret: clientSecret
  scope: openid # Required for CIBA flow.
  enableCIBA: true # Optional. Enables OAuth 2.0 Token Exchange with CIBA flow. Available only for OAuth 2.0 Token Exchange.
  CIBABackchannelEndpoint: https://oauth.provider.com/bc-authorize # Required when enableCIBA is true. The backchannel authentication endpoint.
  loginHintClaim: email # Optional. JWT claim from incoming subject token to send as login_hint in CIBA request. Default: email.
  bindingMessage: "Please approve this request on your device" # Optional. Human-readable message displayed on authentication device.
  timeout: 10000 # Optional. Timeout for token exchange requests in milliseconds. Default: 10000.
```

The `oauth2-obo` authentication has these properties.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Valid Values</th><th>Required</th></tr></thead><tbody><tr><td><p><code>kind</code></p></td><td><p>Authentication type.</p></td><td><p>String</p></td><td><p><code>oauth2-obo</code></p></td><td><p>Yes</p></td></tr><tr><td><p><code>flow</code></p></td><td><p>Token exchange flow type.</p></td><td><p>String</p></td><td><p><code>oauth2-token-exchange</code>, <code>microsoft-entra-obo</code></p></td><td><p>Yes</p></td></tr><tr><td><p><code>clientId</code></p></td><td><p>OAuth2 client ID for token exchange.</p></td><td><p>String</p></td><td><p>Any string</p></td><td><p>Yes</p></td></tr><tr><td><p><code>clientSecret</code></p></td><td><p>OAuth2 client secret for token exchange.</p></td><td><p>String</p></td><td><p>Any string</p></td><td><p>Yes</p></td></tr><tr><td><p><code>tokenEndpoint</code></p></td><td><p>OAuth2 token endpoint URL for token exchange.</p></td><td><p>String</p></td><td><p>Valid URL</p></td><td><p>Yes</p></td></tr><tr><td><p><code>targetType</code></p></td><td><p>Parameter type for specifying the target service (audience for logical name, resource for physical URI). Used for OAuth 2.0 Token Exchange.</p></td><td><p>String</p></td><td><p><code>audience</code>, <code>resource</code>. Default: <code>audience</code></p></td><td><p>No</p></td></tr><tr><td><p><code>targetValue</code></p></td><td><p>Target audience URI or resource URI for the exchanged token. Required for OAuth 2.0 Token Exchange.</p></td><td><p>String</p></td><td><p>Valid URI</p></td><td><p>Required when using <code>oauth2-token-exchange</code> with a target</p></td></tr><tr><td><p><code>scope</code></p></td><td><p>OAuth scope to request. Required for Microsoft Entra OBO (e.g. <code>api://downstream-client-id/.default</code>). Optional for OAuth 2.0 Token Exchange.</p></td><td><p>String</p></td><td><p>Any string</p></td><td><p>Required for <code>microsoft-entra-obo</code></p></td></tr><tr><td><p><code>timeout</code></p></td><td><p>Timeout for token exchange requests in milliseconds.</p></td><td><p>Integer</p></td><td><p>Positive integer. Default: 10000</p></td><td><p>No</p></td></tr><tr><td><p><code>enableCIBA</code></p></td><td><p>Enables OAuth 2.0 Token Exchange with CIBA flow. Available only for OAuth 2.0 Token Exchange.</p></td><td><p>Boolean</p></td><td><p><code>true</code></p></td><td><p>No</p></td></tr><tr><td><p><code>CIBABackchannelEndpoint`</code></p></td><td><p>The backchannel authentication endpoint (<code>bc-authorize</code>) used to initiate the CIBA flow.</p></td><td><p>String</p></td><td><p><code><a href="https://oauth.provider.com/bc-authorize">https://oauth.provider.com/bc-authorize</a></code></p></td><td><p>Required when <strong>enableCIBA</strong> is <code>true</code>.</p></td></tr><tr><td><p><code>loginHintClaim</code></p></td><td><p>JWT claim from the incoming subject token to send as <code>login_hint</code> in the CIBA request. If no hint is specified, <code>email</code> is used.</p></td><td><p>String</p></td><td><p><code>preferred_username</code></p></td><td><p>No</p></td></tr><tr><td><p><code>bindingMessage</code></p></td><td><p>Human-readable message sent as <code>binding_message</code> in the CIBA request and displayed on the authentication device.</p></td><td><p>String</p></td><td><p><code>Please approve the transaction on your device</code></p></td><td><p>No</p></td></tr></tbody></table>

## exchange.json File Element

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

```json
{
  "main": "agent-network.yaml",
  "name": "Employee Onboarding Network",
  "classifier": "agent-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.

When the agent network is published, all the assets derived from it share the same `groupId`
(business group) defined in the `exchange.json` file.

### Ref Element

The `ref` element is used in different elements in the agent network YAML, and is important for your
agent network configuration.

The `ref` element represents another asset that exists in Exchange. The type of asset referenced
depends on the context (such as agent, MCP server, LLM provider). The semantic is always that of
referencing an asset that exists in Exchange, or will exist when the agent network is published
(meaning, it’s defined in the file). If referenced, it’s in the `dependencies` section of
`exchange.json`.

This example represents a link to an HR agent. The `name` attribute doesn’t point to the agent’s
human friendly or logical name (which can change); instead, it references the `assetId` that
`hr-agent` has in Exchange.

```yaml
links:
  - agent:
      ref:
        name: hr-agent
```

The `hr-agent` asset can either exist already, or can be defined in this same YAML. In either case,
the Exchange `assetId` is the key to this reference.

In some cases, the `ref` element needs to point to an asset that’s defined in a different business
group. For this, the `ref#namespace` attribute can be used to reference the asset’s `groupId`. To
find the `groupId`, look in the `dependencies` section in the `exchange.json` file.

```yaml
links:
  - agent:
      ref:
        name: hr-agent
        namespace: <the groupId>
```

<!-- document id=c99900a612845346d48cd17a482535172e03b67eb8e0e29217cb3633d8dc6241 url=/mulesoft/current/en-us/agent-network/latest/af-agent-script-reference.md -->

---
product: Building Agent Networks
version: 2.0
is-latest-version: true
---

# Agent Script Reference

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

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)

- [Node Types](#node-types)

- [A2A Namespace Functions](#a2a-namespace-functions)

- [Built-in Functions](#built-in-functions)

- [Node Outputs](#node-outputs)

- [Node Expressions and References](#node-expressions-and-references)

## Agent Script Structure

The following sections explain settings and configurations specific to MuleSoft agent network
projects. To learn more about Agent Script, see the
[Agent Script documentation](https://developer.salesforce.com/docs/ai/agentforce/guide/agent-script.html).

### 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**

```yaml
# @dialect: AGENTFABRIC=1.0
```

### System Section

This section defines the `instructions` attribute, which acts as a default system prompt used
whenever an agentic node doesn’t define its own `system.instructions`.

**Example**

```yaml
system:
  instructions: "You are the onboarding agent"
```

The system section has these parameters.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>instructions</code></p></td><td><p>Default system prompt used when an agentic node doesn’t define its own <code>system.instructions</code>.</p></td><td><p>String</p></td><td><p>Yes</p></td></tr></tbody></table>

### 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**

```yaml
config:
  agent_name: "employee-onboarding"
  label: "Employee Onboarding Agent"
  description: "An Agent that performs employee onboarding"
```

The config section has these parameters.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>agent_name</code></p></td><td><p>The name identifier for the agent.</p></td><td><p>String</p></td><td><p>-</p></td></tr><tr><td><p><code>label</code></p></td><td><p>A human-readable display name for the agent.</p></td><td><p>String</p></td><td><p>-</p></td></tr><tr><td><p><code>description</code></p></td><td><p>A description of what the agent does.</p></td><td><p>String</p></td><td><p>-</p></td></tr><tr><td><p><code>default_llm</code></p></td><td><p>Specifies a default LLM to be used on all agentic nodes that don’t specify otherwise.</p></td><td><p>@llm reference See <a href="#llm-section">LLM</a></p></td><td><p>No</p></td></tr></tbody></table>

### 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**

```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.

> [!NOTE] Bedrock OpenAI uses the `openai.` prefix for model names (for example, `openai.gpt-5.5`),
> which differs from the model names used with OpenAI and Azure OpenAI.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>target</code></p></td><td><p>Governed LLM connection as a URI; must use the <code>llm://</code> scheme</p></td><td><p>URI (<code>llm://…​</code>)</p></td><td><p>Yes</p></td></tr><tr><td><p><code>kind</code></p></td><td><p>Discriminator for the LLM provider; selects which provider-specific attributes apply</p></td><td><p>String, <code>OpenAI</code></p></td><td><p>Yes</p></td></tr><tr><td><p><code>model</code></p></td><td><p>The name of the model to use</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p><code>reasoning_effort</code></p></td><td><p>Constrains effort on reasoning for reasoning models. gpt-5.1 defaults to <code>NONE</code>; previous ones default to <code>MEDIUM</code>.</p></td><td><p>enum['NONE', 'MINIMAL', 'LOW', 'MEDIUM', 'HIGH']</p></td><td><p>No</p></td></tr><tr><td><p><code>temperature</code></p></td><td><p>Controls randomness in the output</p></td><td><p>number</p></td><td><p>No</p></td></tr><tr><td><p><code>top_p</code></p></td><td><p>Nucleus sampling parameter</p></td><td><p>number</p></td><td><p>No</p></td></tr><tr><td><p><code>top_logprobs</code></p></td><td><p>Number of most likely tokens to return at each position</p></td><td><p>integer</p></td><td><p>No</p></td></tr><tr><td><p><code>max_output_tokens</code></p></td><td><p>Maximum number of tokens to generate</p></td><td><p>integer</p></td><td><p>No</p></td></tr></tbody></table>

#### LLM Configuration: Gemini

The Gemini configuration has these properties.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>target</code></p></td><td><p>Governed LLM connection as a URI; must use the <code>llm://</code> scheme</p></td><td><p>URI (<code>llm://…​</code>)</p></td><td><p>Yes</p></td></tr><tr><td><p><code>kind</code></p></td><td><p>Discriminator for the LLM provider; selects which provider-specific attributes apply</p></td><td><p>String, <code>Gemini</code></p></td><td><p>Yes</p></td></tr><tr><td><p><code>model</code></p></td><td><p>The name of the model to use</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p><code>thinking_level</code></p></td><td><p>The level of thoughts tokens that the model should generate</p></td><td><p>Enum['LOW', 'HIGH']</p></td><td><p>No</p></td></tr><tr><td><p><code>thinking_budget</code></p></td><td><p>Indicates the thinking budget in tokens. 0 is DISABLED. -1 is AUTOMATIC. The default values and allowed ranges are model dependent</p></td><td><p>Number</p></td><td><p>No</p></td></tr><tr><td><p><code>temperature</code></p></td><td><p>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</p></td><td><p>Number</p></td><td><p>No</p></td></tr><tr><td><p><code>top_p</code></p></td><td><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</p></td><td><p>Number</p></td><td><p>No</p></td></tr><tr><td><p><code>response_logprobs</code></p></td><td><p>Whether to return the log probabilities of the tokens that were chosen by the model at each step</p></td><td><p>Boolean</p></td><td><p>No</p></td></tr><tr><td><p><code>max_output_tokens</code></p></td><td><p>Maximum number of tokens that can be generated in the response</p></td><td><p>Integer</p></td><td><p>No</p></td></tr></tbody></table>

### 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**

```yaml
actions:
  hr_agent:
    target: "a2a://hr_agent_connection"
    kind: "a2a:send_message"
```

A2A actions have these properties.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>target</code></p></td><td><p>Governed A2A connection as a URI; must use the <code>a2a://</code> scheme</p></td><td><p>URI (<code>a2a://…​</code>)</p></td><td><p>Yes</p></td></tr><tr><td><p><code>kind</code></p></td><td><p>Indicates that this executes the message/send A2A method.</p></td><td><p>"a2a:send_message"</p></td><td><p>Yes</p></td></tr></tbody></table>

#### MCP Actions

MCP actions invoke Model Context Protocol actions with optional input binding.

**Example**

```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.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>target</code></p></td><td><p>Governed MCP connection as a URI; must use the <code>mcp://</code> scheme</p></td><td><p>URI (<code>mcp://…​</code>)</p></td><td><p>Yes</p></td></tr><tr><td><p><code>kind</code></p></td><td><p>Constant indicating that this invokes an MCP tool</p></td><td><p>"mcp:tool"</p></td><td><p>Yes</p></td></tr><tr><td><p><code>tool_name</code></p></td><td><p>The name of the tool to call</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p><code>inputs</code></p></td><td><p>Define bindable arguments. Input arguments provided are not exhaustive. The tool will auto-discover additional arguments and consider them in slot filling mode.</p></td><td><p>Object</p></td><td><p>No</p></td></tr></tbody></table>

### 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.

> [!NOTE] Agent network only supports triggers using JSON-RPC or HTTP JSON transport.

- [Get Task](https://a2a-protocol.org/latest/specification/#313-get-task)

- [List Tasks](https://a2a-protocol.org/latest/specification/#314-list-tasks)

- [Cancel Task](https://a2a-protocol.org/latest/specification/#315-cancel-task)

- [Subscribe to Task](https://a2a-protocol.org/latest/specification/#316-subscribe-to-task)

- [Get Extended Agent Card](https://a2a-protocol.org/latest/specification/#3111-get-extended-agent-card)

**Example**

```yaml
trigger employeeOnboardingTrigger:
  kind: "a2a"
  target: "brokers://employee-onboarding/a2a"
  on_message: -> transition to @orchestrator.hrSystemOnboard
```

The A2A trigger has these properties.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>kind</code></p></td><td><p>Value that indicates this is an A2A trigger.</p></td><td><p><code>"a2a"</code></p></td><td><p>Yes</p></td></tr><tr><td><p><code>target</code></p></td><td><p>Broker interface entry point. Must use the <code>brokers://</code> URI form: <code>brokers://&lt;brokerName&gt;/&lt;interfaceName&gt;</code></p></td><td><p>URI (<code>brokers://…​</code>)</p></td><td><p>Yes</p></td></tr><tr><td><p><code>on_message</code></p></td><td><p>Procedure that executes when the A2A interface receives a new <code>message/send</code> request. Must define a transition to the workflow’s initial node.</p></td><td><p>Procedure</p></td><td><p>Yes</p></td></tr></tbody></table>

## Node Types

Agent network and Agent Script support these node types.

### Choosing the Right Node Type

Use this table to decide which node type fits your use case.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th></th><th>Subagent</th><th>Orchestrator</th><th>Generator</th><th>Executor</th></tr></thead><tbody><tr><td><p><strong>Uses an LLM</strong></p></td><td><p>Yes (reasoning loop)</p></td><td><p>Yes (reasoning loop)</p></td><td><p>Yes (single call)</p></td><td><p>No</p></td></tr><tr><td><p><strong>Calls actions (A2A/MCP)</strong></p></td><td><p>Yes—​LLM chooses when and how</p></td><td><p>Yes—​LLM coordinates multiple agents/tools</p></td><td><p>No</p></td><td><p>Yes—​deterministic, fully-bound arguments</p></td></tr><tr><td><p><strong>Number of LLM iterations</strong></p></td><td><p>Multiple (configurable loop)</p></td><td><p>Multiple (configurable loop)</p></td><td><p>Exactly one</p></td><td><p>Zero</p></td></tr><tr><td><p><strong>Slot filling (<code>…​</code>)</strong></p></td><td><p>Yes</p></td><td><p>Yes</p></td><td><p>No</p></td><td><p>No</p></td></tr><tr><td><p><strong>Structured output schema</strong></p></td><td><p>Yes</p></td><td><p>Yes</p></td><td><p>Yes</p></td><td><p>No</p></td></tr><tr><td><p><strong>Best for</strong></p></td><td><p>Single-task reasoning: classification, extraction, semantic routing, human-in-the-loop decisions</p></td><td><p>Multi-agent coordination: delegating to several agents/tools to achieve a complex goal</p></td><td><p>One-shot text generation: summaries, formatting, templated responses</p></td><td><p>Deterministic execution: calling actions with known arguments, setting variables, no LLM judgment needed</p></td></tr></tbody></table>

#### Orchestrator vs. Subagent: When to Use Which

Both the orchestrator and subagent nodes run an LLM reasoning loop with access to actions. These are
the key differences.

- **Orchestrator** is optimized for workflows where the LLM must coordinate multiple external agents
  and tools to achieve a goal. The LLM decides which agents to call, in what order, and how to
  combine their results. Use it when the node needs access to two or more actions and the sequencing
  between them requires judgment.

- **Subagent** is a general-purpose reasoning node ideal for single-task work: classifying input,
  extracting structured data, making a routing decision, or interacting with one tool. It also
  supports human-in-the-loop patterns where the LLM can request clarification.

> [!TIP] If the node coordinates multiple agents or tools toward a shared goal, use `orchestrator`.
> If it reasons about a single task (even if it uses one action), use `subagent`.

### 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**

```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
       max_number_of_loops: 5
       max_consecutive_errors: 5
       task_timeout_secs: 30
     on_exit: -> transition to @orchestrator.process_profile
```

The subagent node has these properties.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>id</code></p></td><td><p>The node identifier, defined next to the node type.</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p><code>label</code></p></td><td><p>An optional short, human-readable display name for the node.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>description</code></p></td><td><p>A CommonMark string providing a description of the node.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>on_exit</code></p></td><td><p>A procedure that executes when the node execution finishes. If <code>on_exit</code> is not defined, the graph ends when the agentic node loop ends.</p></td><td><p>Procedure, but only <code>transition_to</code> statements are allowed.</p></td><td><p>No</p></td></tr><tr><td><p><code>llm</code></p></td><td><p>Overrides the default LLM setting</p></td><td><p>@llm reference See <a href="#llm-section">LLM Section</a></p></td><td><p>No</p></td></tr><tr><td><p><code>system.instructions</code></p></td><td><p>Overrides the global <code>system.instructions</code> at the file root level</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>reasoning.instructions</code></p></td><td><p>Session-specific query or instructions for this particular node, typically containing user provided or user related context</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p><code>reasoning.actions</code></p></td><td><p>The available actions</p></td><td><p>Array[actions]</p></td><td><p>No</p></td></tr><tr><td><p><code>reasoning.outputs</code></p></td><td><p>Schema definition describing the expected structure of the agent’s output</p></td><td><p>Outputs See <a href="#node-outputs">Node Outputs</a></p></td><td><p>No</p></td></tr><tr><td><p><code>reasoning.max_number_of_loops</code></p></td><td><p>The maximum number of loops an execution can take. Useful for keeping the execution from running too long and consuming too many tokens. Default: 25</p></td><td><p>Integer</p></td><td><p>No</p></td></tr><tr><td><p><code>reasoning.max_consecutive_errors</code></p></td><td><p>The maximum number of consecutive errors allowed during execution. Useful for keeping the node from running too long and consuming too many tokens.</p></td><td><p>Integer</p></td><td><p>No</p></td></tr><tr><td><p><code>reasoning.task_timeout_secs</code></p></td><td><p>A timeout (in seconds) for the total node execution.</p></td><td><p>Integer</p></td><td><p>No</p></td></tr><tr><td><p><code>outputs</code></p></td><td><p>A schema definition for the agentic output.</p></td><td><p>Object See <a href="#node-outputs">Node Outputs</a></p></td><td><p>No</p></td></tr></tbody></table>

### 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**

```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"]}
       max_number_of_loops: 10
       max_consecutive_errors: 10
       task_timeout_secs: 60
     outputs:
       properties:
         flightNumber:
           type: "string"
           description: "The flight identification number"
         airline:
           type: "string"
           description: "The airline name"
     on_exit: -> transition to @executor.send_summary
```

The orchestrator node has these properties.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>id</code></p></td><td><p>The node identifier, defined next to the node type.</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p><code>label</code></p></td><td><p>An optional short, human-readable display name for the node.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>description</code></p></td><td><p>A CommonMark string providing a description of the node.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>on_exit</code></p></td><td><p>A procedure that executes when the node execution finishes. If <code>on_exit</code> is not defined, the graph ends when the agentic node loop ends.</p></td><td><p>Procedure, but only <code>transition_to</code> statements are allowed.</p></td><td><p>No</p></td></tr><tr><td><p><code>llm</code></p></td><td><p>Overrides the default LLM setting</p></td><td><p>@llm reference See <a href="#llm-section">LLM Section</a></p></td><td><p>No</p></td></tr><tr><td><p><code>system.instructions</code></p></td><td><p>Overrides the global <code>system.instructions</code> at the file root level</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>reasoning.instructions</code></p></td><td><p>Session-specific query or instructions for this particular node, typically containing user provided or user related context</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p><code>reasoning.actions</code></p></td><td><p>The available actions</p></td><td><p>Array[actions]</p></td><td><p>No</p></td></tr><tr><td><p><code>reasoning.outputs</code></p></td><td><p>Schema definition describing the expected structure of the agent’s output</p></td><td><p>Outputs See <a href="#node-outputs">Node Outputs</a></p></td><td><p>No</p></td></tr><tr><td><p><code>reasoning.max_number_of_loops</code></p></td><td><p>The maximum number of loops an execution can take. Useful for keeping the execution from running too long and consuming too many tokens. Default: 25</p></td><td><p>Integer</p></td><td><p>No</p></td></tr><tr><td><p><code>reasoning.max_consecutive_errors</code></p></td><td><p>The maximum number of consecutive errors allowed during execution. Useful for keeping the node from running too long and consuming too many tokens.</p></td><td><p>Integer</p></td><td><p>No</p></td></tr><tr><td><p><code>reasoning.task_timeout_secs</code></p></td><td><p>A timeout (in seconds) for the total node execution.</p></td><td><p>Integer</p></td><td><p>No</p></td></tr><tr><td><p><code>outputs</code></p></td><td><p>A schema definition for the agentic output.</p></td><td><p>Object See <a href="#node-outputs">Node Outputs</a></p></td><td><p>No</p></td></tr></tbody></table>

### 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**

```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.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>id</code></p></td><td><p>The node identifier, defined next to the node type.</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p><code>label</code></p></td><td><p>An optional short, human-readable display name for the node.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>description</code></p></td><td><p>A CommonMark string providing a description of the node.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>on_exit</code></p></td><td><p>A procedure that executes when the node execution finishes. If <code>on_exit</code> is not defined, the graph ends when the agentic node ends.</p></td><td><p>Procedure, but only <code>transition_to</code> statements are allowed.</p></td><td><p>No</p></td></tr><tr><td><p><code>llm</code></p></td><td><p>A reference to the LLM connection.</p></td><td><p>@llm reference See <a href="#llm-section">LLM Section</a></p></td><td><p>No</p></td></tr><tr><td><p><code>system.instructions</code></p></td><td><p>Overrides the global <code>system.instructions</code> at the file root level for this generator node.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>prompt</code></p></td><td><p>Session-specific query or instructions for this particular node, typically containing user provided or user related context.</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p><code>outputs</code></p></td><td><p>A schema definition for the agentic output.</p></td><td><p>Object See <a href="#node-outputs">Node Outputs</a></p></td><td><p>No</p></td></tr></tbody></table>

### Executor Node

The executor node executes Agent Script statements deterministically and no LLM is involved. Because
there is no LLM reasoning loop, every action argument must be fully resolved at execution time (you
cannot use slot filling `…​` in an executor). Use this node when you need to call an action with
known arguments, store a computed value in a variable, or chain multiple deterministic steps before
transitioning.

**Example**

```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
```

**Example with multiple statements:**

```yaml
executor prepareAndNotify:
  description: "Sets the ticket status variable and sends a Slack notification."
  do:
    -> set @variables.ticketStatus = "resolved" run @actions.send_slack_message with text="Ticket "
    + @generator.classifySeverity.output.ticket_id + " resolved" with
    channel_id=@variables.notificationChannel
  on_exit: -> transition to @echo.finalResponse
```

The executor node has these properties.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>id</code></p></td><td><p>The node identifier, defined next to the node type.</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p><code>label</code></p></td><td><p>An optional short, human-readable display name for the node.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>description</code></p></td><td><p>A CommonMark string providing a description of the node.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>on_exit</code></p></td><td><p>A procedure that executes when the node execution finishes. If <code>on_exit</code> is not defined, the graph ends when the executor ends.</p></td><td><p>Procedure, but only <code>transition_to</code> statements are allowed.</p></td><td><p>No</p></td></tr><tr><td><p><code>do</code></p></td><td><p>A procedure containing one or more Agent Script statements to execute deterministically. See <a href="#executor-supported-statements">Supported Statements in <code>do</code></a>.</p></td><td><p>Procedure</p></td><td><p>Yes</p></td></tr></tbody></table>

#### Supported Statements in `do`

The `do` block accepts a procedure (`→`) containing one or more of these statements:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Statement</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><p><code>run @actions.&lt;name&gt;</code></p></td><td><p>Invoke a defined action. Use <code>with</code> to bind arguments from variables, node outputs, or literal values. All arguments must be fully resolved (no slot filling). Multiple <code>with</code> clauses can be chained.</p></td><td><p><code>run @actions.escalate</code> or <code>run @actions.send_slack_message with text=@generator.summary.output with channel_id="my-channel"</code></p></td></tr><tr><td><p><code>set @variables.&lt;name&gt; = &lt;expression&gt;</code></p></td><td><p>Store a value in a workflow variable for use in downstream nodes.</p></td><td><p><code>set @variables.ticketStatus = "escalated"</code></p></td></tr></tbody></table>

### Router Node

The router node performs dynamic transitions based on deterministic conditions. This node doesn’t
support `transition to` in its `on_exit` attribute. Use this node for branching based on structured
output from a previous node.

**Example**

```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.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>id</code></p></td><td><p>The node identifier, defined next to the node type.</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p><code>label</code></p></td><td><p>An optional short, human-readable display name for the node.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>description</code></p></td><td><p>A CommonMark string providing a description of the node.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>routes</code></p></td><td><p>An array of condition and target pairs, plus an optional label field for UI. Must define at least one route. Each route contains: <code>target</code>, <code>when</code>, and optional <code>label</code>.</p></td><td><p>Array</p></td><td><p>Yes</p></td></tr><tr><td><p><code>otherwise</code></p></td><td><p>Defines a default transition when no route condition matches. Contains: <code>target</code>.</p></td><td><p>Object</p></td><td><p>Yes with <code>routes</code></p></td></tr></tbody></table>

### 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.

**Example**

```yaml
echo addArtifact:
  kind: "a2a:artifact_update_event"
  artifact: a2a.artifact({
    artifactId: uuid(),
    name: "myArtifact",
    description: "this is optional",
    parts: [
      a2a.textPart("You have been onboarded! Your employee ID is " + @orchestrator.hrSystemOnboard.output.employeeId)
    ],
    metadata: {},
  }),
  append: false
  lastChunk: false

echo setStatus:
  kind: "a2a:status_update_event"
  state: "TASK_STATE_COMPLETED",
  message: a2a.message({
    messageId: uuid(),
    parts: [
      a2a.textPart("You have been onboarded! Your employee ID is " + @orchestrator.hrSystemOnboard.output.employeeId)
    ]
  })
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Type</th><th>Required</th></tr></thead><tbody><tr><td><p><code>id</code></p></td><td><p>The node identifier, defined next to the node type.</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p><code>label</code></p></td><td><p>An optional short, human-readable display name for the node.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>description</code></p></td><td><p>A CommonMark string providing a description of the node.</p></td><td><p>String</p></td><td><p>No</p></td></tr><tr><td><p><code>on_exit</code></p></td><td><p>A procedure that executes when the node execution finishes. If <code>on_exit</code> is not defined, the graph ends when the agentic node loop ends.</p></td><td><p>Procedure, but only <code>transition_to</code> statements are allowed.</p></td><td><p>No</p></td></tr><tr><td><p><code>kind</code></p></td><td><p>Discriminator for the event type. Valid values: <code>a2a:status_update_event</code>, <code>a2a:artifact_update_event</code>.</p></td><td><p>String</p></td><td><p>Yes</p></td></tr><tr><td><p><code>state</code></p></td><td><p>The task state. Used with <code>a2a:status_update_event</code> kind.</p></td><td><p>String</p></td><td><p>Yes (for <code>status_update_event</code>)</p></td></tr><tr><td><p><code>message</code></p></td><td><p>A message object created via <code>a2a.message()</code>. Used with <code>a2a:status_update_event</code> kind.</p></td><td><p>Message object</p></td><td><p>Yes (for <code>status_update_event</code>)</p></td></tr><tr><td><p><code>artifact</code></p></td><td><p>An artifact object created via <code>a2a.artifact()</code>. Used with <code>a2a:artifact_update_event</code> kind.</p></td><td><p>Artifact object</p></td><td><p>Yes (for <code>artifact_update_event</code>)</p></td></tr><tr><td><p><code>append</code></p></td><td><p>Whether to append to an existing artifact. Used with <code>a2a:artifact_update_event</code> kind.</p></td><td><p>Boolean</p></td><td><p>No</p></td></tr><tr><td><p><code>lastChunk</code></p></td><td><p>Whether this is the last chunk of the artifact. Used with <code>a2a:artifact_update_event</code> kind.</p></td><td><p>Boolean</p></td><td><p>No</p></td></tr><tr><td><p><code>metadata</code></p></td><td><p>Optional metadata dictionary.</p></td><td><p>dict</p></td><td><p>No</p></td></tr></tbody></table>

The following table summarizes echo node parameters organized by `kind`.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Kind</th><th>Required Parameters</th><th>Optional Parameters</th></tr></thead><tbody><tr><td><p><code>a2a:artifact_update_event</code></p></td><td><p><code>artifact</code> (object created via <code>a2a.artifact()</code>)</p></td><td><p><code>append</code> (boolean), <code>lastChunk</code> (boolean)</p></td></tr><tr><td><p><code>a2a:status_update_event</code></p></td><td><p><code>state</code> (string), <code>message</code> (object created via <code>a2a.message()</code>)</p></td><td><p><code>metadata</code> (dict)</p></td></tr></tbody></table>

#### Echo Node Behavior

The following table describes echo node behavior based on the A2A operation used by the client.

<table><colgroup><col> <col></colgroup><thead><tr><th>Operation / Condition</th><th>Echo Behavior</th></tr></thead><tbody><tr><td><p><code>SendMessage</code> with <code>returnImmediately = false</code></p></td><td><p>Each echo invocation updates the stored task. Each echo invocation emits a push notification payload for all created push notifications. A consolidated response is emitted when the graph ends or is suspended.</p></td></tr><tr><td><p><code>SendMessage</code> with <code>returnImmediately = true</code></p></td><td><p>An immediate response is sent before graph execution is triggered. The response includes the task and context ID. A stored task entry with the response already exists before graph execution begins. All echo invocations update the stored task atomically (including consolidated and individual events). Each echo invocation emits a push notification payload for all created push notifications.</p></td></tr><tr><td><p><code>SendStreamingMessage</code></p></td><td><p>All echo invocations update the stored task atomically (including consolidated and individual events). All individual events are sent through the event stream. Each echo invocation emits a push notification payload for all created push notifications.</p></td></tr><tr><td><p><code>SubscribeToTask</code></p></td><td><p>This condition works on top of the scenarios above. Any task in a non-terminal state can be subscribed to. Whenever echo is executed, events are pushed to all subscribed clients.</p></td></tr></tbody></table>

## 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.<nodeId>`.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Function</th><th>Description</th><th>Input Arguments</th><th>Output</th><th>Example</th></tr></thead><tbody><tr><td><p><code>a2a.message</code></p></td><td><p>Builds an A2A Message object</p></td><td><p><code>messageId: str</code> (required) <code>parts: list</code> (required, from <code>a2a.textPart/a2a.dataPart/a2a.filePart</code>) <code>role: str</code> (optional, default: "agent") <code>metadata: dict</code> (optional)</p></td><td><p><code>dict</code> (Message)</p></td><td><p><code>a2a.message({messageId: uuid(), parts: [a2a.textPart("Hello")]})</code></p></td></tr><tr><td><p><code>a2a.textPart</code></p></td><td><p>Builds a TextPart object (kind: "text")</p></td><td><p><code>text: str</code> (required) <code>metadata: dict</code> (optional)</p></td><td><p><code>dict</code> (TextPart)</p></td><td><p><code>a2a.textPart("Employee ID: {!@orchestrator.employee.id}") <code>a2a.textPart("Status: Complete", metadata={priority: "high"})</code></code></p></td></tr><tr><td><p><code>a2a.dataPart</code></p></td><td><p>Builds a DataPart object (kind: "data")</p></td><td><p><code>data: dict</code> (required) <code>metadata: dict</code> (optional)</p></td><td><p><code>dict</code> (DataPart)</p></td><td><p><code>a2a.dataPart({employeeId: "E123", department: "Engineering"}) <code>a2a.dataPart(@orchestrator.result.output)</code></code></p></td></tr><tr><td><p><code>a2a.filePart</code></p></td><td><p>Builds a FilePart object (kind: "file")</p></td><td><p><code>uri: str</code> (optional, required if bytes not provided) <code>bytes: str</code> (optional, base64-encoded) <code>name: str</code> (optional) <code>mime_type: str</code> (optional) <code>metadata: dict</code> (optional)</p></td><td><p><code>dict</code> (FilePart)</p></td><td><p><code>a2a.filePart(uri="https://example.com/report.pdf", name="report.pdf", mime_type="application/pdf") a2a.filePart(bytes="SGVsbG8gV29ybGQ=", name="data.txt")</code></p></td></tr><tr><td><p><code>a2a.artifact</code></p></td><td><p>Builds an A2A Artifact object</p></td><td><p><code>artifactId: str</code> (optional, auto-generated) <code>name: str</code> (optional) <code>description: str</code> (optional) <code>parts: list</code> (required, from <code>a2a.textPart/a2a.dataPart/a2a.filePart</code>) <code>metadata: dict</code> (optional)</p></td><td><p><code>dict</code> (Artifact)</p></td><td><p><code>a2a.artifact({artifactId: uuid(), name: "Results", parts: [a2a.dataPart(…​)]})</code></p></td></tr></tbody></table>

Usage notes:

- Functions are designed to be composed: `a2a.message` and `a2a.artifact` accept `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.

- 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

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.

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Function</th><th>Description</th><th>Input arguments</th><th>Output</th><th>Example</th></tr></thead><tbody><tr><td><p><code>now</code></p></td><td><p>Current UTC time in ISO 8601 format</p></td><td><p>None</p></td><td><p>String (ISO 8601)</p></td><td><p><code>now()</code></p></td></tr><tr><td><p><code>uuid</code></p></td><td><p>Random UUID v4</p></td><td><p>None</p></td><td><p>String (UUID)</p></td><td><p><code>uuid()</code></p></td></tr><tr><td><p><code>strip</code></p></td><td><p>Removes leading/trailing characters from a string</p></td><td><p>String, optional chars (default: whitespace)</p></td><td><p>String</p></td><td><p><code>strip(" hello ") → "hello"</code></p></td></tr><tr><td><p><code>startswith</code></p></td><td><p>Whether a string starts with a prefix</p></td><td><p>String, prefix</p></td><td><p>Boolean</p></td><td><p><code>startswith("hello world", "hello")</code></p></td></tr><tr><td><p><code>endswith</code></p></td><td><p>Whether a string ends with a suffix</p></td><td><p>String, suffix</p></td><td><p>Boolean</p></td><td><p><code>endswith("report.pdf", ".pdf")</code></p></td></tr><tr><td><p><code>abs</code></p></td><td><p>Absolute value</p></td><td><p>Number</p></td><td><p>Number</p></td><td><p><code>abs(-42)</code></p></td></tr><tr><td><p><code>round</code></p></td><td><p>Round to optional digit count</p></td><td><p>Number, optional <code>ndigits</code></p></td><td><p>Number</p></td><td><p><code>round(3.14159, 2)</code></p></td></tr><tr><td><p><code>sum</code></p></td><td><p>Sum of a numeric list</p></td><td><p>List</p></td><td><p>Number</p></td><td><p><code>sum([10, 20, 30])</code></p></td></tr><tr><td><p><code>parse_json</code></p></td><td><p>Parse a JSON string</p></td><td><p>String (valid JSON)</p></td><td><p>Object or array</p></td><td><p><code>parse_json('{"key": "value"}')</code></p></td></tr></tbody></table>

## 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. These 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.

<table><colgroup><col> <col></colgroup><thead><tr><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><p>String</p></td><td><p>Text values with optional constraints like <code>pattern</code> (regex), <code>minLength</code>, <code>maxLength</code>, and <code>enum</code> (allowed values).</p></td></tr><tr><td><p>Number / Integer</p></td><td><p>Numeric values with optional constraints like <code>minimum</code>, <code>maximum</code>, <code>exclusiveMinimum</code>, <code>exclusiveMaximum</code>, and <code>enum</code>.</p></td></tr><tr><td><p>Boolean</p></td><td><p><code>True</code> or <code>False</code> (with optional default).</p></td></tr><tr><td><p>Array</p></td><td><p>Lists of items, where <code>items</code> define the schema for each element (can be any supported type). Supports <code>minItems</code> and <code>maxItems</code>.</p></td></tr><tr><td><p>Object</p></td><td><p>Nested structures with their own <code>properties</code> map. Supports a <code>required</code> array to specify mandatory fields.</p></td></tr></tbody></table>

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 doesn’t support:

- `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

Nodes access data from other parts of the workflow using expressions.

These references are used.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Prefix</th><th>Reference</th><th>Example</th></tr></thead><tbody><tr><td><p><code>@llm.</code></p></td><td><p>LLM definitions</p></td><td><p><code>@llm.open-api-llm</code></p></td></tr><tr><td><p><code>@actions.</code></p></td><td><p>action definitions</p></td><td><p><code>@actions.hr_agent</code></p></td></tr><tr><td><p><code>@request.</code></p></td><td><p>Trigger request data</p></td><td><p><code>@request.payload</code>, <code>@request.interface</code></p></td></tr><tr><td><p><code>@request.headers</code></p></td><td><p>HTTP headers (case-insensitive)</p></td><td><p><code>@request.headers["Authorization"]</code></p></td></tr><tr><td><p><code>@variables.</code></p></td><td><p>Workflow variables</p></td><td><p><code>@variables.companyId</code></p></td></tr><tr><td><p><code>@&lt;nodeType&gt;.&lt;nodeId&gt;.</code></p></td><td><p>Node references</p></td><td><p><code>@orchestrator.hrOnboard.output</code></p></td></tr></tbody></table>

### Accessing Node Output and Input

Every node has `.output` (the value it produced) and `.input` (the output of whichever node
transitioned into it).

- If a node doesn’t produce a value (for example, a router), its `.output` is `None`.

- If the preceding node is a trigger, `.input` is `None`.

**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

#### When to Use `.output` vs `.input`

Use `.output` when you know exactly which upstream node you need data from. In a straight-line
graph, `.output` is the simplest approach:

process ──► generate\_email ──► send\_email

- `generate_email` reads `@subagent.process.output` as the source content.

- `send_email` reads `@generator.generate_email.output` as its content.

An expression can target any preceding node in the graph, not only the node immediately before the
current node.

To decouple a node from the path that reached it, use `.input`. In this example,
`@generator.generate_email.input` returns the output from whichever of `node_a`, `node_b`, or
`node_c` transitioned into `generate_email`:

node\_a ──┐ node\_b ──┼──► generate\_email ──► send\_email node\_c ──┘

### Accessing Trigger Data

The `@request` namespace provides access to the trigger’s incoming request data. Use `@request`
expressions to read the payload, headers, and other properties of the request that started the
workflow.

- `@request.payload`: Returns the request payload. For the `on_message` handler of the A2A trigger,
  this expression returns a `SendMessageRequest` object.

- `@request.interface`: Returns the name of the interface that produced the message (for example,
  `a2a`).

For A2A triggers, these additional references are also available:

- `@request.headers`: A case-insensitive dictionary of the HTTP request headers. For example,
  `@request.headers["Authorization"]` and `@request.headers["authorization"]` return the same value.

- `@request.taskId`: The current A2A task ID, either provided in the request or automatically
  generated by the trigger.

- `@request.contextId`: The current A2A context ID, either provided in the request or automatically
  generated by the trigger.

**Example**

```yaml
reasoning:
  instructions: -> @request.payload.message.parts[0].text
  actions:
    concur: @actions.concur-agent with http_headers = {"Authorization": @request.headers["Authorization"]}
```

### 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:

```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**

```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**

```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**

```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
```

<!-- document id=84c477ea687517bf4aa0228bd564c5c620a9dde6c3454c0b1d7a2650d7a4d10b url=/mulesoft/current/en-us/agent-network/1.0/af-build-agent-networks-in-a-ci-cd-environment.md -->

---
product: Building Agent Networks
version: 1.0
---

# Build Agent Networks in a CI/CD Environment

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

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
[Anypoint CLI Agent Fabric Plugin on npm](https://www.npmjs.com/package/mulesoft-anypoint-cli-agent-fabric-plugin).

## Before You Begin

Make sure you meet the [prerequisites](https://docs.mulesoft.com/agent-network/1.0/af-get-started#before-you-begin) 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
[Command-Line Parameters and Environment Variables](https://docs.mulesoft.com/anypoint-cli/latest/auth#command-line-parameters).

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
[Authentication to the Anypoint Platform CLI](https://docs.mulesoft.com/anypoint-cli/latest/auth).

### 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
[Set Up the Space or Deployment Target for Your Environment](https://docs.mulesoft.com/agent-network/1.0/af-get-started#setup-space).

After you have a target space, set up the gateway or gateways for deployment if you haven’t already
done so. See
[Set Up Agent Network Gateways for the Space or Deployment Target](https://docs.mulesoft.com/agent-network/1.0/af-get-started#setup-gateways).

## CLI for Agent Fabric Plugin Reference

Use these commands to set up gateways and author, publish, and deploy agent network projects.

<table><colgroup><col> <col></colgroup><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><a href="https://docs.mulesoft.com/anypoint-cli/latest/agent-fabric#agent-network-project-build">agent-network:project:build</a></p></div></div></td><td><div><div><p>Builds the agent network project and validates configuration</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/anypoint-cli/latest/agent-fabric#agent-network-project-create">agent-network:project:create</a></p></div></div></td><td><div><div><p>Creates a new agent network project and generates the initial configuration files</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/anypoint-cli/latest/agent-fabric#agent-network-project-deploy">agent-network:project:deploy</a></p></div></div></td><td><div><div><p>Deploys the agent network project to the target environment</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/anypoint-cli/latest/agent-fabric#agent-network-project-publish">agent-network:project:publish</a></p></div></div></td><td><div><div><p>Publishes the agent network project to Anypoint Exchange</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/anypoint-cli/latest/agent-fabric#agent-network-project-undeploy">agent-network:project:undeploy</a></p></div></div></td><td><div><div><p>Undeploys the agent network project and removes all deployed runtime resources</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/anypoint-cli/latest/agent-fabric#agent-network-project-unpublish">agent-network:project:unpublish</a></p></div></div></td><td><div><div><p>Unpublishes the agent network project asset versions from Anypoint Exchange</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/anypoint-cli/latest/agent-fabric#agent-network-setup-gateways">agent-network:setup:gateways</a></p></div></div></td><td><div><div><p>Sets up the gateways for the agent network</p></div></div></td></tr></tbody></table>

## agent-network:project:build

\> anypoint-cli-agent-fabric-plugin agent-network project build \[flags\]

Builds the current agent network project using the Maven wrapper (`mvnw` or `mvnw.cmd`). This
command validates the configuration and generates the artifacts required for publishing and
deployment.

In addition to the [default flags](https://docs.mulesoft.com/anypoint-cli/latest/#default-options), this command accepts
these flags:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Flag</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p><code>--bearer &lt;value&gt;</code></p></div></div></td><td><div><div><p>Bearer token<br>You can also set it with <code>ANYPOINT_BEARER</code> env variable</p></div></div></td><td><div><div><p><code>--bearer myBearerToken</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_id &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client ID<br>You can also set it with the <code>ANYPOINT_CLIENT_ID</code> env variable</p></div></div></td><td><div><div><p><code>--client_id myClientID</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_secret &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client Secret<br>You can also set it with the <code>ANYPOINT_CLIENT_SECRET</code> env variable</p></div></div></td><td><div><div><p><code>--client_secret myClientSecret</code></p></div></div></td></tr><tr><td><div><div><p><code>--[no-]collectMetrics</code></p></div></div></td><td><div><div><p>Collect metrics<br>You can also set it with the <code>COLLECT_METRICS</code> env variable</p></div></div></td><td><div><div><p><code>--no-collectMetrics</code></p></div></div></td></tr><tr><td><div><div><p><code>--debug</code></p></div></div></td><td><div><div><p>Enable debug mode</p></div></div></td><td><div><div><p><code>--debug</code></p></div></div></td></tr><tr><td><div><div><p><code>--environment &lt;value&gt;</code></p></div></div></td><td><div><div><p>Environment name<br>You can also set it with the <code>ANYPOINT_ENV</code> variable</p></div></div></td><td><div><div><p><code>--environment Sandbox</code></p></div></div></td></tr><tr><td><div><div><p><code>--forceUpdate</code></p></div></div></td><td><div><div><p>Force update the dependencies</p></div></div></td><td><div><div><p><code>--forceUpdate</code></p></div></div></td></tr><tr><td><div><div><p><code>--host &lt;value&gt;</code></p></div></div></td><td><div><div><p>Host URL<br>Default: <code>anypoint.mulesoft.com</code><br>You can also set it with the <code>ANYPOINT_HOST</code> variable</p></div></div></td><td><div><div><p><code>--host mycompany.anypoint.mulesoft.com</code></p></div></div></td></tr><tr><td><div><div><p><code>--organization &lt;value&gt;</code></p></div></div></td><td><div><div><p>Organization name<br>You can also set it with the <code>ANYPOINT_ORG</code> variable</p></div></div></td><td><div><div><p><code>--organization MyOrg</code></p></div></div></td></tr><tr><td><div><div><p><code>--password &lt;value&gt;</code></p></div></div></td><td><div><div><p>Password<br>You can also set it with the <code>ANYPOINT_PASSWORD</code> variable</p></div></div></td><td><div><div><p><code>--password myPassword</code></p></div></div></td></tr><tr><td><div><div><p><code>--path &lt;value&gt;</code></p></div></div></td><td><div><div><p>Path to the project<br>Default: <code>.</code></p></div></div></td><td><div><div><p><code>--path ./my-agent-network</code></p></div></div></td></tr><tr><td><div><div><p><code>--username &lt;value&gt;</code></p></div></div></td><td><div><div><p>Username<br>You can also set it with the <code>ANYPOINT_USERNAME</code> variable</p></div></div></td><td><div><div><p><code>--username myuser@example.com</code></p></div></div></td></tr></tbody></table>

### Example

$ anypoint-cli-agent-fabric-plugin agent-network project build

## agent-network:project:create

\> anypoint-cli-agent-fabric-plugin agent-network project create --name <projectName> \[flags\]

Creates a new agent network project in the current directory. The command generates a project folder
with initial configuration files, including `agent-network.yaml`.

In addition to the [default flags](https://docs.mulesoft.com/anypoint-cli/latest/#default-options), this command accepts
these flags:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Flag</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p><code>-n, --name &lt;value&gt;</code></p></div></div></td><td><div><div><p>(Required) Name of the project</p></div></div></td><td><div><div><p><code>--name my-agent-network</code></p></div></div></td></tr><tr><td><div><div><p><code>-o, --output-dir &lt;value&gt;</code></p></div></div></td><td><div><div><p>Output directory for the project</p></div></div></td><td><div><div><p><code>--output-dir ./projects</code></p></div></div></td></tr><tr><td><div><div><p><code>--api-version &lt;value&gt;</code></p></div></div></td><td><div><div><p>API version<br>Default: <code>v1</code></p></div></div></td><td><div><div><p><code>--api-version v2</code></p></div></div></td></tr><tr><td><div><div><p><code>--asset-id &lt;value&gt;</code></p></div></div></td><td><div><div><p>Asset name (GAV). Valid characters are 'A-Z', 'a-z', '0-9', '_' and '-'.</p></div></div></td><td><div><div><p><code>--asset-id my-asset</code></p></div></div></td></tr><tr><td><div><div><p><code>--asset-version &lt;value&gt;</code></p></div></div></td><td><div><div><p>Asset version (GAV)<br>Default: <code>0.0.0</code></p></div></div></td><td><div><div><p><code>--asset-version 1.2.0</code></p></div></div></td></tr><tr><td><div><div><p><code>--bearer &lt;value&gt;</code></p></div></div></td><td><div><div><p>Bearer token<br>You can also set it with the <code>ANYPOINT_BEARER</code> variable</p></div></div></td><td><div><div><p><code>--bearer myBearerToken</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_id &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client ID<br>You can also set it with the <code>ANYPOINT_CLIENT_ID</code> variable</p></div></div></td><td><div><div><p><code>--client_id myClientID</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_secret &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client Secret<br>You can also set it with the <code>ANYPOINT_CLIENT_SECRET</code> variable</p></div></div></td><td><div><div><p><code>--client_secret myClientSecret</code></p></div></div></td></tr><tr><td><div><div><p><code>--[no-]collectMetrics</code></p></div></div></td><td><div><div><p>Collect metrics<br>You can also set it with the <code>COLLECT_METRICS</code> variable</p></div></div></td><td><div><div><p><code>--no-collectMetrics</code></p></div></div></td></tr><tr><td><div><div><p><code>--[no-]create-dir</code></p></div></div></td><td><div><div><p>Create a new directory under <code>output-dir</code> using the project name</p></div></div></td><td><div><div><p><code>--create-dir</code></p></div></div></td></tr><tr><td><div><div><p><code>--environment &lt;value&gt;</code></p></div></div></td><td><div><div><p>Environment name<br>You can also set it with the <code>ANYPOINT_ENV</code> variable</p></div></div></td><td><div><div><p><code>--environment Sandbox</code></p></div></div></td></tr><tr><td><div><div><p><code>--group-id &lt;value&gt;</code></p></div></div></td><td><div><div><p>Group ID (GAV)</p></div></div></td><td><div><div><p><code>--group-id com.myorg</code></p></div></div></td></tr><tr><td><div><div><p><code>--host &lt;value&gt;</code></p></div></div></td><td><div><div><p>Host URL<br>Default: <code>anypoint.mulesoft.com</code><br>You can also set it with the <code>ANYPOINT_HOST</code> variable</p></div></div></td><td><div><div><p><code>--host mycompany.anypoint.mulesoft.com</code></p></div></div></td></tr><tr><td><div><div><p><code>--organization &lt;value&gt;</code></p></div></div></td><td><div><div><p>Organization name<br>You can also set it with the <code>ANYPOINT_ORG</code> env variable</p></div></div></td><td><div><div><p><code>--organization MyOrg</code></p></div></div></td></tr><tr><td><div><div><p><code>--password &lt;value&gt;</code></p></div></div></td><td><div><div><p>Password<br>You can also set it with the <code>ANYPOINT_PASSWORD</code> variable</p></div></div></td><td><div><div><p><code>--password myPassword</code></p></div></div></td></tr><tr><td><div><div><p><code>--tab-size &lt;value&gt;</code></p></div></div></td><td><div><div><p>Tab size for indenting the API specification<br>Default: <code>2</code></p></div></div></td><td><div><div><p><code>--tab-size 4</code></p></div></div></td></tr><tr><td><div><div><p><code>--username &lt;value&gt;</code></p></div></div></td><td><div><div><p>Username<br>You can also set it with the <code>ANYPOINT_USERNAME</code> variable</p></div></div></td><td><div><div><p><code>--username myuser@example.com</code></p></div></div></td></tr></tbody></table>

### Example

$ anypoint-cli-agent-fabric-plugin agent-network project create --name my-agent-network

## agent-network:project:deploy

\> anypoint-cli-agent-fabric-plugin agent-network project deploy \[flags\]

Deploys the agent network application. By default, the command uses single-gateway mode with the
`agent-network-gw` gateway. You can override this using the `-g` flag or switch to separate-gateways
mode using `-i` and `-e` flags.

In addition to the [default flags](https://docs.mulesoft.com/anypoint-cli/latest/#default-options), this command accepts
these flags:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Flag</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p><code>-e, --egress-gw &lt;value&gt;</code></p></div></div></td><td><div><div><p>Name of the target egress gateway (separate-gateways mode; requires <code>--ingress-gw</code>). When no gateway flags are provided, deploy defaults to single-gateway mode using <code>agent-network-gw</code>.</p></div></div></td><td><div><div><p><code>--egress-gw custom-egress</code></p></div></div></td></tr><tr><td><div><div><p><code>-g, --gateway &lt;value&gt;</code></p></div></div></td><td><div><div><p>Name of the gateway for single-gateway mode (recommended). Mutually exclusive with <code>--ingress-gw</code> and <code>--egress-gw</code>.</p></div></div></td><td><div><div><p><code>--gateway my-gateway</code></p></div></div></td></tr><tr><td><div><div><p><code>-i, --ingress-gw &lt;value&gt;</code></p></div></div></td><td><div><div><p>Name of the target ingress gateway. Combine with <code>--egress-gw</code> for separate-gateways mode; on its own it selects single-gateway mode using this gateway. When no gateway flags are provided, deploy defaults to single-gateway mode using <code>agent-network-gw</code>.</p></div></div></td><td><div><div><p><code>--ingress-gw custom-ingress</code></p></div></div></td></tr><tr><td><div><div><p><code>-t, --target-space &lt;value&gt;</code></p></div></div></td><td><div><div><p>Name of the target space to deploy. In single-gateway mode, optional; when provided it must match the gateway’s target space (validated, not used for lookup). In separate-gateways mode, defaults to <code>agent-network-space</code>.</p></div></div></td><td><div><div><p><code>--target-space my-space</code></p></div></div></td></tr><tr><td><div><div><p><code>--bearer &lt;value&gt;</code></p></div></div></td><td><div><div><p>Bearer token<br>You can also set it with the <code>ANYPOINT_BEARER</code> variable</p></div></div></td><td><div><div><p><code>--bearer myBearerToken</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_id &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client ID<br>You can also set it with the <code>ANYPOINT_CLIENT_ID</code> variable</p></div></div></td><td><div><div><p><code>--client_id myClientID</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_secret &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client Secret<br>You can also set it with the <code>ANYPOINT_CLIENT_SECRET</code> variable</p></div></div></td><td><div><div><p><code>--client_secret myClientSecret</code></p></div></div></td></tr><tr><td><div><div><p><code>--[no-]collectMetrics</code></p></div></div></td><td><div><div><p>Collect metrics<br>You can also set it with the <code>COLLECT_METRICS</code> variable</p></div></div></td><td><div><div><p><code>--no-collectMetrics</code></p></div></div></td></tr><tr><td><div><div><p><code>--disable-tracing</code></p></div></div></td><td><div><div><p>Disable tracing functionalities</p></div></div></td><td><div><div><p><code>--disable-tracing</code></p></div></div></td></tr><tr><td><div><div><p><code>--dont-wait-for-agent-network</code></p></div></div></td><td><div><div><p>Do not wait for the agent network to be ready</p></div></div></td><td><div><div><p><code>--dont-wait-for-agent-network</code></p></div></div></td></tr><tr><td><div><div><p><code>--environment &lt;value&gt;</code></p></div></div></td><td><div><div><p>Environment name<br>You can also set it with the <code>ANYPOINT_ENV</code> variable</p></div></div></td><td><div><div><p><code>--environment Sandbox</code></p></div></div></td></tr><tr><td><div><div><p><code>--host &lt;value&gt;</code></p></div></div></td><td><div><div><p>Host URL<br>Default: <code>anypoint.mulesoft.com</code><br>You can also set it with the <code>ANYPOINT_HOST</code> variable</p></div></div></td><td><div><div><p><code>--host mycompany.anypoint.mulesoft.com</code></p></div></div></td></tr><tr><td><div><div><p><code>--max-retries &lt;value&gt;</code></p></div></div></td><td><div><div><p>Max retries to check the status of the deploying application<br>Default: <code>3</code></p></div></div></td><td><div><div><p><code>--max-retries 5</code></p></div></div></td></tr><tr><td><div><div><p><code>--organization &lt;value&gt;</code></p></div></div></td><td><div><div><p>Organization name<br>You can also set it with the <code>ANYPOINT_ORG</code> variable</p></div></div></td><td><div><div><p><code>--organization MyOrg</code></p></div></div></td></tr><tr><td><div><div><p><code>--password &lt;value&gt;</code></p></div></div></td><td><div><div><p>Password<br>You can also set it with the <code>ANYPOINT_PASSWORD</code> variable</p></div></div></td><td><div><div><p><code>--password myPassword</code></p></div></div></td></tr><tr><td><div><div><p><code>--path &lt;value&gt;</code></p></div></div></td><td><div><div><p>Path to the project<br>Default: <code>.</code></p></div></div></td><td><div><div><p><code>--path ./my-agent-network</code></p></div></div></td></tr><tr><td><div><div><p><code>--process-timeout &lt;value&gt;</code></p></div></div></td><td><div><div><p>Process timeout in milliseconds<br>Default: <code>600000</code></p></div></div></td><td><div><div><p><code>--process-timeout 900000</code></p></div></div></td></tr><tr><td><div><div><p><code>--property &lt;value&gt;</code></p></div></div></td><td><div><div><p>Property to override in <code>name:value</code> format</p></div></div></td><td><div><div><p><code>--property apiKey:sk-xxx</code></p></div></div></td></tr><tr><td><div><div><p><code>--request-timeout &lt;value&gt;</code></p></div></div></td><td><div><div><p>Request timeout in milliseconds<br>Default: <code>60000</code></p></div></div></td><td><div><div><p><code>--request-timeout 120000</code></p></div></div></td></tr><tr><td><div><div><p><code>--username &lt;value&gt;</code></p></div></div></td><td><div><div><p>Username<br>You can also set it with the <code>ANYPOINT_USERNAME</code> variable</p></div></div></td><td><div><div><p><code>--username myuser@example.com</code></p></div></div></td></tr><tr><td><div><div><p><code>--json</code></p></div></div></td><td><div><div><p>Format output as JSON</p></div></div></td><td><div><div><p><code>--json</code></p></div></div></td></tr></tbody></table>

### Example

$ anypoint-cli-agent-fabric-plugin agent-network project deploy

$ anypoint-cli-agent-fabric-plugin agent-network project deploy --property apiKey:sk-xxx

$ anypoint-cli-agent-fabric-plugin agent-network project deploy --property apiKey:sk-xxx --property
role:user

$ anypoint-cli-agent-fabric-plugin agent-network project deploy --path ./my-project --property
myAgent.url:https://api.example.com

## agent-network:project:publish

\> anypoint-cli-agent-fabric-plugin agent-network project publish \[flags\]

Publishes the current agent network project to Anypoint Exchange. The command outputs links and
details for all created assets.

In addition to the [default flags](https://docs.mulesoft.com/anypoint-cli/latest/#default-options), this command accepts
these flags:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Flag</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p><code>--bearer &lt;value&gt;</code></p></div></div></td><td><div><div><p>Bearer token<br>You can also set it with the <code>ANYPOINT_BEARER</code> variable</p></div></div></td><td><div><div><p><code>--bearer myBearerToken</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_id &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client ID<br>You can also set it with the <code>ANYPOINT_CLIENT_ID</code> variable</p></div></div></td><td><div><div><p><code>--client_id myClientID</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_secret &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client Secret<br>You can also set it with the <code>ANYPOINT_CLIENT_SECRET</code> variable</p></div></div></td><td><div><div><p><code>--client_secret myClientSecret</code></p></div></div></td></tr><tr><td><div><div><p><code>--[no-]collectMetrics</code></p></div></div></td><td><div><div><p>Collect metrics<br>You can also set it with the <code>COLLECT_METRICS</code> variable</p></div></div></td><td><div><div><p><code>--no-collectMetrics</code></p></div></div></td></tr><tr><td><div><div><p><code>--debug</code></p></div></div></td><td><div><div><p>Enable debug mode</p></div></div></td><td><div><div><p><code>--debug</code></p></div></div></td></tr><tr><td><div><div><p><code>--environment &lt;value&gt;</code></p></div></div></td><td><div><div><p>Environment name<br>You can also set it with the <code>ANYPOINT_ENV</code> variable</p></div></div></td><td><div><div><p><code>--environment Sandbox</code></p></div></div></td></tr><tr><td><div><div><p><code>--host &lt;value&gt;</code></p></div></div></td><td><div><div><p>Host URL<br>Default: <code>anypoint.mulesoft.com</code><br>You can also set it with the <code>ANYPOINT_HOST</code> variable</p></div></div></td><td><div><div><p><code>--host mycompany.anypoint.mulesoft.com</code></p></div></div></td></tr><tr><td><div><div><p><code>--organization &lt;value&gt;</code></p></div></div></td><td><div><div><p>Organization name<br>You can also set it with <code>ANYPOINT_ORG</code> env variable</p></div></div></td><td><div><div><p><code>--organization MyOrg</code></p></div></div></td></tr><tr><td><div><div><p><code>--password &lt;value&gt;</code></p></div></div></td><td><div><div><p>Password<br>You can also set it with the <code>ANYPOINT_PASSWORD</code> variable</p></div></div></td><td><div><div><p><code>--password myPassword</code></p></div></div></td></tr><tr><td><div><div><p><code>--path &lt;value&gt;</code></p></div></div></td><td><div><div><p>Path to the project<br>Default: <code>.</code></p></div></div></td><td><div><div><p><code>--path ./my-agent-network</code></p></div></div></td></tr><tr><td><div><div><p><code>--username &lt;value&gt;</code></p></div></div></td><td><div><div><p>Username<br>You can also set it with the <code>ANYPOINT_USERNAME</code> variable</p></div></div></td><td><div><div><p><code>--username myuser@example.com</code></p></div></div></td></tr><tr><td><div><div><p><code>--json</code></p></div></div></td><td><div><div><p>Format output as JSON</p></div></div></td><td><div><div><p><code>--json</code></p></div></div></td></tr></tbody></table>

### Example

$ anypoint-cli-agent-fabric-plugin agent-network project publish

## agent-network:project:undeploy

\> anypoint-cli-agent-fabric-plugin agent-network project undeploy \[flags\]

Undeploys the agent network application, removing all deployed resources.

In addition to the [default flags](https://docs.mulesoft.com/anypoint-cli/latest/#default-options), this command accepts
these flags:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Flag</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p><code>--api-version &lt;value&gt;</code></p></div></div></td><td><div><div><p>API version used to discover remotely deployed resources when using <code>--gav</code><br>Default: <code>v1</code></p></div></div></td><td><div><div><p><code>--api-version v1</code></p></div></div></td></tr><tr><td><div><div><p><code>--bearer &lt;value&gt;</code></p></div></div></td><td><div><div><p>Bearer token<br>You can also set it with the <code>ANYPOINT_BEARER</code> variable</p></div></div></td><td><div><div><p><code>--bearer myBearerToken</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_id &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client ID<br>You can also set it with the <code>ANYPOINT_CLIENT_ID</code> variable</p></div></div></td><td><div><div><p><code>--client_id myClientID</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_secret &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client Secret<br>You can also set it with the <code>ANYPOINT_CLIENT_SECRET</code> variable</p></div></div></td><td><div><div><p><code>--client_secret myClientSecret</code></p></div></div></td></tr><tr><td><div><div><p><code>--[no-]collectMetrics</code></p></div></div></td><td><div><div><p>Collect metrics<br>You can also set it with the <code>COLLECT_METRICS</code> variable</p></div></div></td><td><div><div><p><code>--no-collectMetrics</code></p></div></div></td></tr><tr><td><div><div><p><code>--dry-run</code></p></div></div></td><td><div><div><p>Preview the deploy-plane resources that would be undeployed without deleting anything</p></div></div></td><td><div><div><p><code>--dry-run</code></p></div></div></td></tr><tr><td><div><div><p><code>--environment &lt;value&gt;</code></p></div></div></td><td><div><div><p>Environment name<br>You can also set it with the <code>ANYPOINT_ENV</code> variable</p></div></div></td><td><div><div><p><code>--environment Sandbox</code></p></div></div></td></tr><tr><td><div><div><p><code>--gav &lt;value&gt;</code></p></div></div></td><td><div><div><p>Parent asset GAV (<code>groupId:assetId:version</code>). Discovers deployed resources remotely. Requires an environment to be selected</p></div></div></td><td><div><div><p><code>--gav myOrgId:my-network:0.0.0</code></p></div></div></td></tr><tr><td><div><div><p><code>--host &lt;value&gt;</code></p></div></div></td><td><div><div><p>Host URL<br>Default: <code>anypoint.mulesoft.com</code><br>You can also set it with the <code>ANYPOINT_HOST</code> variable</p></div></div></td><td><div><div><p><code>--host mycompany.anypoint.mulesoft.com</code></p></div></div></td></tr><tr><td><div><div><p><code>--json</code></p></div></div></td><td><div><div><p>Format output as JSON</p></div></div></td><td><div><div><p><code>--json</code></p></div></div></td></tr><tr><td><div><div><p><code>--organization &lt;value&gt;</code></p></div></div></td><td><div><div><p>Organization name<br>You can also set it with the <code>ANYPOINT_ORG</code> variable</p></div></div></td><td><div><div><p><code>--organization MyOrg</code></p></div></div></td></tr><tr><td><div><div><p><code>--password &lt;value&gt;</code></p></div></div></td><td><div><div><p>Password<br>You can also set it with the <code>ANYPOINT_PASSWORD</code> variable</p></div></div></td><td><div><div><p><code>--password myPassword</code></p></div></div></td></tr><tr><td><div><div><p><code>--path &lt;value&gt;</code></p></div></div></td><td><div><div><p>Path to the project. Discovers deployed resources remotely from the project lock file. Requires an environment to be selected. Mutually exclusive with <code>--gav</code></p></div></div></td><td><div><div><p><code>--path ./my-project</code></p></div></div></td></tr><tr><td><div><div><p><code>--process-timeout &lt;value&gt;</code></p></div></div></td><td><div><div><p>Process timeout in milliseconds<br>Default: <code>900000</code></p></div></div></td><td><div><div><p><code>--process-timeout 900000</code></p></div></div></td></tr><tr><td><div><div><p><code>--request-timeout &lt;value&gt;</code></p></div></div></td><td><div><div><p>Request timeout in milliseconds<br>Default: <code>60000</code></p></div></div></td><td><div><div><p><code>--request-timeout 60000</code></p></div></div></td></tr><tr><td><div><div><p><code>--username &lt;value&gt;</code></p></div></div></td><td><div><div><p>Username<br>You can also set it with the <code>ANYPOINT_USERNAME</code> variable</p></div></div></td><td><div><div><p><code>--username myuser@example.com</code></p></div></div></td></tr></tbody></table>

### Examples

Undeploy from the current project:

$ anypoint-cli-agent-fabric-plugin agent-network project undeploy --environment Sandbox

Undeploy from a specific project path:

$ anypoint-cli-agent-fabric-plugin agent-network project undeploy --path ./my-project --environment
Sandbox

Undeploy using GAV coordinates:

$ anypoint-cli-agent-fabric-plugin agent-network project undeploy --gav myOrgId:my-network:0.0.0
--environment Sandbox

Preview resources that would be undeployed (dry run):

$ anypoint-cli-agent-fabric-plugin agent-network project undeploy --dry-run --environment Sandbox

## agent-network:project:unpublish

\> anypoint-cli-agent-fabric-plugin agent-network project unpublish \[flags\]

Removes the agent network assets from Anypoint Exchange. By default performs a soft-delete; use
`--hard-delete` for irreversible removal.

To prevent orphaned runtime references to deleted Exchange assets, run
`agent-network project undeploy` before `unpublish`.

In addition to the [default flags](https://docs.mulesoft.com/anypoint-cli/latest/#default-options), this command accepts
these flags:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Flag</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p><code>--api-version &lt;value&gt;</code></p></div></div></td><td><div><div><p>API version used to discover remotely published assets when using <code>--gav</code><br>Default: <code>v1</code></p></div></div></td><td><div><div><p><code>--api-version v1</code></p></div></div></td></tr><tr><td><div><div><p><code>--bearer &lt;value&gt;</code></p></div></div></td><td><div><div><p>Bearer token<br>You can also set it with the <code>ANYPOINT_BEARER</code> variable</p></div></div></td><td><div><div><p><code>--bearer myBearerToken</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_id &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client ID<br>You can also set it with the <code>ANYPOINT_CLIENT_ID</code> variable</p></div></div></td><td><div><div><p><code>--client_id myClientID</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_secret &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client Secret<br>You can also set it with the <code>ANYPOINT_CLIENT_SECRET</code> variable</p></div></div></td><td><div><div><p><code>--client_secret myClientSecret</code></p></div></div></td></tr><tr><td><div><div><p><code>--[no-]collectMetrics</code></p></div></div></td><td><div><div><p>Collect metrics<br>You can also set it with the <code>COLLECT_METRICS</code> variable</p></div></div></td><td><div><div><p><code>--no-collectMetrics</code></p></div></div></td></tr><tr><td><div><div><p><code>--dry-run</code></p></div></div></td><td><div><div><p>Preview the Exchange assets that would be unpublished without deleting anything</p></div></div></td><td><div><div><p><code>--dry-run</code></p></div></div></td></tr><tr><td><div><div><p><code>--environment &lt;value&gt;</code></p></div></div></td><td><div><div><p>Environment name<br>You can also set it with the <code>ANYPOINT_ENV</code> variable</p></div></div></td><td><div><div><p><code>--environment Sandbox</code></p></div></div></td></tr><tr><td><div><div><p><code>--gav &lt;value&gt;</code></p></div></div></td><td><div><div><p>Parent asset GAV (<code>groupId:assetId:version</code>). Discovers assets remotely. Use <code>--environment</code> to enable the active API instances safety check</p></div></div></td><td><div><div><p><code>--gav myOrgId:my-network:0.0.0</code></p></div></div></td></tr><tr><td><div><div><p><code>--hard-delete</code></p></div></div></td><td><div><div><p>Permanently delete assets from Exchange. This cannot be undone</p></div></div></td><td><div><div><p><code>--hard-delete</code></p></div></div></td></tr><tr><td><div><div><p><code>--host &lt;value&gt;</code></p></div></div></td><td><div><div><p>Host URL<br>Default: <code>anypoint.mulesoft.com</code><br>You can also set it with the <code>ANYPOINT_HOST</code> variable</p></div></div></td><td><div><div><p><code>--host mycompany.anypoint.mulesoft.com</code></p></div></div></td></tr><tr><td><div><div><p><code>--json</code></p></div></div></td><td><div><div><p>Format output as JSON</p></div></div></td><td><div><div><p><code>--json</code></p></div></div></td></tr><tr><td><div><div><p><code>--organization &lt;value&gt;</code></p></div></div></td><td><div><div><p>Organization name<br>You can also set it with the <code>ANYPOINT_ORG</code> variable</p></div></div></td><td><div><div><p><code>--organization MyOrg</code></p></div></div></td></tr><tr><td><div><div><p><code>--password &lt;value&gt;</code></p></div></div></td><td><div><div><p>Password<br>You can also set it with the <code>ANYPOINT_PASSWORD</code> variable</p></div></div></td><td><div><div><p><code>--password myPassword</code></p></div></div></td></tr><tr><td><div><div><p><code>--path &lt;value&gt;</code></p></div></div></td><td><div><div><p>Path to the project. Reads the published assets from the project lock file. Select an environment to enable the active API instances safety check. Mutually exclusive with <code>--gav</code></p></div></div></td><td><div><div><p><code>--path ./my-project</code></p></div></div></td></tr><tr><td><div><div><p><code>--username &lt;value&gt;</code></p></div></div></td><td><div><div><p>Username<br>You can also set it with the <code>ANYPOINT_USERNAME</code> variable</p></div></div></td><td><div><div><p><code>--username myuser@example.com</code></p></div></div></td></tr></tbody></table>

### Examples

Unpublish with soft-delete:

$ anypoint-cli-agent-fabric-plugin agent-network project unpublish --environment Sandbox

Unpublish from a specific project path:

$ anypoint-cli-agent-fabric-plugin agent-network project unpublish --path ./my-project --environment
Sandbox

Unpublish with hard-delete (irreversible):

$ anypoint-cli-agent-fabric-plugin agent-network project unpublish --hard-delete --environment
Sandbox

Unpublish using GAV coordinates:

$ anypoint-cli-agent-fabric-plugin agent-network project unpublish --gav myOrgId:my-network:0.0.0
--environment Sandbox

Preview assets that would be unpublished (dry run):

$ anypoint-cli-agent-fabric-plugin agent-network project unpublish --dry-run --environment Sandbox

## agent-network:setup:gateways

\> anypoint-cli-agent-fabric-plugin agent-network setup gateways \[flags\]

Sets up the agent network environment with the required gateways in the specified target space
(private space, RTF, or shared space). This step is required only if the target space doesn’t
already have gateways. In the typical (happy path) workflow, you run it once per target space before
the first deployment.

In addition to the [default flags](https://docs.mulesoft.com/anypoint-cli/latest/#default-options), this command accepts
these flags:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Flag</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p><code>-e, --egress-gw &lt;value&gt;</code></p></div></div></td><td><div><div><p>Name of the egress gateway (separate-gateway mode; requires <code>--ingress-gw</code>)</p></div></div></td><td><div><div><p><code>--egress-gw my-egress</code></p></div></div></td></tr><tr><td><div><div><p><code>-g, --gateway &lt;value&gt;</code></p></div></div></td><td><div><div><p>Name of the gateway for single-gateway mode (recommended). Mutually exclusive with <code>--ingress-gw</code> and <code>--egress-gw</code>.</p></div></div></td><td><div><div><p><code>--gateway my-gateway</code></p></div></div></td></tr><tr><td><div><div><p><code>-i, --ingress-gw &lt;value&gt;</code></p></div></div></td><td><div><div><p>Name of the ingress gateway (separate-gateway mode)</p></div></div></td><td><div><div><p><code>--ingress-gw my-ingress</code></p></div></div></td></tr><tr><td><div><div><p><code>-t, --target-space &lt;value&gt;</code></p></div></div></td><td><div><div><p>Name of the target space (private space, RTF, or shared space) where you set up the agent network environment<br>Default: <code>agent-network-space</code></p></div></div></td><td><div><div><p><code>--target-space my-space</code></p></div></div></td></tr><tr><td><div><div><p><code>--bearer &lt;value&gt;</code></p></div></div></td><td><div><div><p>Bearer token<br>You can also set it with the <code>ANYPOINT_BEARER</code> variable</p></div></div></td><td><div><div><p><code>--bearer myBearerToken</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_id &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client ID<br>You can also set it with the <code>ANYPOINT_CLIENT_ID</code> variable</p></div></div></td><td><div><div><p><code>--client_id myClientID</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_secret &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client Secret<br>You can also set it with the <code>ANYPOINT_CLIENT_SECRET</code> variable</p></div></div></td><td><div><div><p><code>--client_secret myClientSecret</code></p></div></div></td></tr><tr><td><div><div><p><code>--[no-]collectMetrics</code></p></div></div></td><td><div><div><p>Collect metrics<br>You can also set it with the <code>COLLECT_METRICS</code> variable</p></div></div></td><td><div><div><p><code>--no-collectMetrics</code></p></div></div></td></tr><tr><td><div><div><p><code>--dont-wait-for-gateways-running</code></p></div></div></td><td><div><div><p>Do not wait for the gateways to be running</p></div></div></td><td><div><div><p><code>--dont-wait-for-gateways-running</code></p></div></div></td></tr><tr><td><div><div><p><code>--environment &lt;value&gt;</code></p></div></div></td><td><div><div><p>Environment name<br>You can also set it with the <code>ANYPOINT_ENV</code> variable</p></div></div></td><td><div><div><p><code>--environment Sandbox</code></p></div></div></td></tr><tr><td><div><div><p><code>--host &lt;value&gt;</code></p></div></div></td><td><div><div><p>Host URL<br>Default: <code>anypoint.mulesoft.com</code><br>You can also set it with the <code>ANYPOINT_HOST</code> variable</p></div></div></td><td><div><div><p><code>--host mycompany.anypoint.mulesoft.com</code></p></div></div></td></tr><tr><td><div><div><p><code>--organization &lt;value&gt;</code></p></div></div></td><td><div><div><p>Organization name<br>You can also set it with the <code>ANYPOINT_ORG</code> variable</p></div></div></td><td><div><div><p><code>--organization MyOrg</code></p></div></div></td></tr><tr><td><div><div><p><code>--password &lt;value&gt;</code></p></div></div></td><td><div><div><p>Password<br>You can also set it with the <code>ANYPOINT_PASSWORD</code> variable</p></div></div></td><td><div><div><p><code>--password myPassword</code></p></div></div></td></tr><tr><td><div><div><p><code>--username &lt;value&gt;</code></p></div></div></td><td><div><div><p>Username<br>You can also set it with the <code>ANYPOINT_USERNAME</code> variable</p></div></div></td><td><div><div><p><code>--username myuser@example.com</code></p></div></div></td></tr></tbody></table>

### Example

$ anypoint-cli-agent-fabric-plugin agent-network setup gateways --target-space my-space

<!-- document id=3956e6189f935c303813f92b7d45a1847112dcdadd0f627ae797f246c277c1f5 url=/mulesoft/current/en-us/agent-network/latest/af-build-agent-networks-in-a-ci-cd-environment.md -->

---
product: Building Agent Networks
version: 2.0
is-latest-version: true
---

# Build Agent Networks in a CI/CD Environment

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

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
[Anypoint CLI Agent Fabric Plugin on npm](https://www.npmjs.com/package/mulesoft-anypoint-cli-agent-fabric-plugin).

If a plugin command fails, see [Troubleshoot Agent Fabric CLI Errors](https://docs.mulesoft.com/agent-network/latest/af-troubleshoot-errors).

## Before You Begin

If you’re using the Anypoint CLI to create agent network projects, ensure you install these
requirements.

- Node 20 (v20.19.4) or later. See [Nodejs.org](https://nodejs.org/en).

  Follow the steps in the installer, and then from a terminal verify that `node -v` returns a Node
  20 version.

- Java 17 or later. Set the `JAVA_HOME` environment variable.

- [Anypoint CLI Agent Fabric Plugin](https://www.npmjs.com/package/mulesoft-anypoint-cli-agent-fabric-plugin)

  Install the Anypoint CLI Agent Fabric plugin by running this command in a terminal window:

  `npm install mulesoft-anypoint-cli-agent-fabric-plugin`

### 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
[Command-Line Parameters and Environment Variables](https://docs.mulesoft.com/anypoint-cli/latest/auth#command-line-parameters).

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
[Authentication to the Anypoint Platform CLI](https://docs.mulesoft.com/anypoint-cli/latest/auth).

### 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
[Set Up the Space or Deployment Target for Your Environment](https://docs.mulesoft.com/agent-network/latest/af-get-started#setup-space).

After you create a target space, set up the ingress and egress gateways for deployment if you
haven’t already done so. See
[Set Up Agent Network Gateways for the Space or Deployment Target](https://docs.mulesoft.com/agent-network/latest/af-get-started#setup-gateways).

## CLI for Agent Fabric Plugin Reference

Use these commands to set up gateways and author, publish, and deploy agent network projects.

<table><colgroup><col> <col></colgroup><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><a href="https://docs.mulesoft.com/anypoint-cli/latest/agent-fabric#agent-network-project-build">agent-network:project:build</a></p></div></div></td><td><div><div><p>Builds the agent network project and validates configuration</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/anypoint-cli/latest/agent-fabric#agent-network-project-create">agent-network:project:create</a></p></div></div></td><td><div><div><p>Creates a new agent network project and generates the initial configuration files</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/anypoint-cli/latest/agent-fabric#agent-network-project-deploy">agent-network:project:deploy</a></p></div></div></td><td><div><div><p>Deploys the agent network project to the target environment</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/anypoint-cli/latest/agent-fabric#agent-network-project-publish">agent-network:project:publish</a></p></div></div></td><td><div><div><p>Publishes the agent network project to Anypoint Exchange</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/anypoint-cli/latest/agent-fabric#agent-network-project-undeploy">agent-network:project:undeploy</a></p></div></div></td><td><div><div><p>Undeploys the agent network project and removes all deployed runtime resources</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/anypoint-cli/latest/agent-fabric#agent-network-project-unpublish">agent-network:project:unpublish</a></p></div></div></td><td><div><div><p>Unpublishes the agent network project asset versions from Anypoint Exchange</p></div></div></td></tr><tr><td><div><div><p><a href="https://docs.mulesoft.com/anypoint-cli/latest/agent-fabric#agent-network-setup-gateways">agent-network:setup:gateways</a></p></div></div></td><td><div><div><p>Sets up the gateways for the agent network</p></div></div></td></tr></tbody></table>

## agent-network:project:build

\> anypoint-cli-agent-fabric-plugin agent-network project build \[flags\]

Builds the current agent network project using the Maven wrapper (`mvnw` or `mvnw.cmd`). This
command validates the configuration and generates the artifacts required for publishing and
deployment.

In addition to the [default flags](https://docs.mulesoft.com/anypoint-cli/latest/#default-options), this command accepts
these flags:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Flag</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p><code>--bearer &lt;value&gt;</code></p></div></div></td><td><div><div><p>Bearer token<br>You can also set it with <code>ANYPOINT_BEARER</code> env variable</p></div></div></td><td><div><div><p><code>--bearer myBearerToken</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_id &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client ID<br>You can also set it with the <code>ANYPOINT_CLIENT_ID</code> env variable</p></div></div></td><td><div><div><p><code>--client_id myClientID</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_secret &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client Secret<br>You can also set it with the <code>ANYPOINT_CLIENT_SECRET</code> env variable</p></div></div></td><td><div><div><p><code>--client_secret myClientSecret</code></p></div></div></td></tr><tr><td><div><div><p><code>--[no-]collectMetrics</code></p></div></div></td><td><div><div><p>Collect metrics<br>You can also set it with the <code>COLLECT_METRICS</code> env variable</p></div></div></td><td><div><div><p><code>--no-collectMetrics</code></p></div></div></td></tr><tr><td><div><div><p><code>--debug</code></p></div></div></td><td><div><div><p>Enable debug mode</p></div></div></td><td><div><div><p><code>--debug</code></p></div></div></td></tr><tr><td><div><div><p><code>--environment &lt;value&gt;</code></p></div></div></td><td><div><div><p>Environment name<br>You can also set it with the <code>ANYPOINT_ENV</code> variable</p></div></div></td><td><div><div><p><code>--environment Sandbox</code></p></div></div></td></tr><tr><td><div><div><p><code>--forceUpdate</code></p></div></div></td><td><div><div><p>Force update the dependencies</p></div></div></td><td><div><div><p><code>--forceUpdate</code></p></div></div></td></tr><tr><td><div><div><p><code>--host &lt;value&gt;</code></p></div></div></td><td><div><div><p>Host URL<br>Default: <code>anypoint.mulesoft.com</code><br>You can also set it with the <code>ANYPOINT_HOST</code> variable</p></div></div></td><td><div><div><p><code>--host mycompany.anypoint.mulesoft.com</code></p></div></div></td></tr><tr><td><div><div><p><code>--organization &lt;value&gt;</code></p></div></div></td><td><div><div><p>Organization name<br>You can also set it with the <code>ANYPOINT_ORG</code> variable</p></div></div></td><td><div><div><p><code>--organization MyOrg</code></p></div></div></td></tr><tr><td><div><div><p><code>--password &lt;value&gt;</code></p></div></div></td><td><div><div><p>Password<br>You can also set it with the <code>ANYPOINT_PASSWORD</code> variable</p></div></div></td><td><div><div><p><code>--password myPassword</code></p></div></div></td></tr><tr><td><div><div><p><code>--path &lt;value&gt;</code></p></div></div></td><td><div><div><p>Path to the project<br>Default: <code>.</code></p></div></div></td><td><div><div><p><code>--path ./my-agent-network</code></p></div></div></td></tr><tr><td><div><div><p><code>--username &lt;value&gt;</code></p></div></div></td><td><div><div><p>Username<br>You can also set it with the <code>ANYPOINT_USERNAME</code> variable</p></div></div></td><td><div><div><p><code>--username myuser@example.com</code></p></div></div></td></tr></tbody></table>

### Example

$ anypoint-cli-agent-fabric-plugin agent-network project build

## agent-network:project:create

\> anypoint-cli-agent-fabric-plugin agent-network project create --name <projectName> \[flags\]

Creates a new agent network project in the current directory. The command generates a project folder
with initial configuration files, including `agent-network.yaml`.

In addition to the [default flags](https://docs.mulesoft.com/anypoint-cli/latest/#default-options), this command accepts
these flags:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Flag</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p><code>-n, --name &lt;value&gt;</code></p></div></div></td><td><div><div><p>(Required) Name of the project</p></div></div></td><td><div><div><p><code>--name my-agent-network</code></p></div></div></td></tr><tr><td><div><div><p><code>-o, --output-dir &lt;value&gt;</code></p></div></div></td><td><div><div><p>Output directory for the project</p></div></div></td><td><div><div><p><code>--output-dir ./projects</code></p></div></div></td></tr><tr><td><div><div><p><code>--api-version &lt;value&gt;</code></p></div></div></td><td><div><div><p>API version<br>Default: <code>v1</code></p></div></div></td><td><div><div><p><code>--api-version v2</code></p></div></div></td></tr><tr><td><div><div><p><code>--asset-id &lt;value&gt;</code></p></div></div></td><td><div><div><p>Asset name (GAV). Valid characters are 'A-Z', 'a-z', '0-9', '_' and '-'.</p></div></div></td><td><div><div><p><code>--asset-id my-asset</code></p></div></div></td></tr><tr><td><div><div><p><code>--asset-version &lt;value&gt;</code></p></div></div></td><td><div><div><p>Asset version (GAV)<br>Default: <code>0.0.0</code></p></div></div></td><td><div><div><p><code>--asset-version 1.2.0</code></p></div></div></td></tr><tr><td><div><div><p><code>--bearer &lt;value&gt;</code></p></div></div></td><td><div><div><p>Bearer token<br>You can also set it with the <code>ANYPOINT_BEARER</code> variable</p></div></div></td><td><div><div><p><code>--bearer myBearerToken</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_id &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client ID<br>You can also set it with the <code>ANYPOINT_CLIENT_ID</code> variable</p></div></div></td><td><div><div><p><code>--client_id myClientID</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_secret &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client Secret<br>You can also set it with the <code>ANYPOINT_CLIENT_SECRET</code> variable</p></div></div></td><td><div><div><p><code>--client_secret myClientSecret</code></p></div></div></td></tr><tr><td><div><div><p><code>--[no-]collectMetrics</code></p></div></div></td><td><div><div><p>Collect metrics<br>You can also set it with the <code>COLLECT_METRICS</code> variable</p></div></div></td><td><div><div><p><code>--no-collectMetrics</code></p></div></div></td></tr><tr><td><div><div><p><code>--[no-]create-dir</code></p></div></div></td><td><div><div><p>Create a new directory under <code>output-dir</code> using the project name</p></div></div></td><td><div><div><p><code>--create-dir</code></p></div></div></td></tr><tr><td><div><div><p><code>--environment &lt;value&gt;</code></p></div></div></td><td><div><div><p>Environment name<br>You can also set it with the <code>ANYPOINT_ENV</code> variable</p></div></div></td><td><div><div><p><code>--environment Sandbox</code></p></div></div></td></tr><tr><td><div><div><p><code>--group-id &lt;value&gt;</code></p></div></div></td><td><div><div><p>Group ID (GAV)</p></div></div></td><td><div><div><p><code>--group-id com.myorg</code></p></div></div></td></tr><tr><td><div><div><p><code>--host &lt;value&gt;</code></p></div></div></td><td><div><div><p>Host URL<br>Default: <code>anypoint.mulesoft.com</code><br>You can also set it with the <code>ANYPOINT_HOST</code> variable</p></div></div></td><td><div><div><p><code>--host mycompany.anypoint.mulesoft.com</code></p></div></div></td></tr><tr><td><div><div><p><code>--organization &lt;value&gt;</code></p></div></div></td><td><div><div><p>Organization name<br>You can also set it with the <code>ANYPOINT_ORG</code> env variable</p></div></div></td><td><div><div><p><code>--organization MyOrg</code></p></div></div></td></tr><tr><td><div><div><p><code>--password &lt;value&gt;</code></p></div></div></td><td><div><div><p>Password<br>You can also set it with the <code>ANYPOINT_PASSWORD</code> variable</p></div></div></td><td><div><div><p><code>--password myPassword</code></p></div></div></td></tr><tr><td><div><div><p><code>--tab-size &lt;value&gt;</code></p></div></div></td><td><div><div><p>Tab size for indenting the API specification<br>Default: <code>2</code></p></div></div></td><td><div><div><p><code>--tab-size 4</code></p></div></div></td></tr><tr><td><div><div><p><code>--username &lt;value&gt;</code></p></div></div></td><td><div><div><p>Username<br>You can also set it with the <code>ANYPOINT_USERNAME</code> variable</p></div></div></td><td><div><div><p><code>--username myuser@example.com</code></p></div></div></td></tr></tbody></table>

### Example

$ anypoint-cli-agent-fabric-plugin agent-network project create --name my-agent-network

## agent-network:project:deploy

\> anypoint-cli-agent-fabric-plugin agent-network project deploy \[flags\]

Deploys the agent network application. By default, the command uses single-gateway mode with the
`agent-network-gw` gateway. You can override this using the `-g` flag or switch to separate-gateways
mode using `-i` and `-e` flags.

In addition to the [default flags](https://docs.mulesoft.com/anypoint-cli/latest/#default-options), this command accepts
these flags:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Flag</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p><code>-e, --egress-gw &lt;value&gt;</code></p></div></div></td><td><div><div><p>Name of the target egress gateway (separate-gateways mode; requires <code>--ingress-gw</code>). When no gateway flags are provided, deploy defaults to single-gateway mode using <code>agent-network-gw</code>.</p></div></div></td><td><div><div><p><code>--egress-gw custom-egress</code></p></div></div></td></tr><tr><td><div><div><p><code>-g, --gateway &lt;value&gt;</code></p></div></div></td><td><div><div><p>Name of the gateway for single-gateway mode (recommended). Mutually exclusive with <code>--ingress-gw</code> and <code>--egress-gw</code>.</p></div></div></td><td><div><div><p><code>--gateway my-gateway</code></p></div></div></td></tr><tr><td><div><div><p><code>-i, --ingress-gw &lt;value&gt;</code></p></div></div></td><td><div><div><p>Name of the target ingress gateway. Combine with <code>--egress-gw</code> for separate-gateways mode; on its own it selects single-gateway mode using this gateway. When no gateway flags are provided, deploy defaults to single-gateway mode using <code>agent-network-gw</code>.</p></div></div></td><td><div><div><p><code>--ingress-gw custom-ingress</code></p></div></div></td></tr><tr><td><div><div><p><code>-t, --target-space &lt;value&gt;</code></p></div></div></td><td><div><div><p>Name of the target space to deploy. In single-gateway mode, optional; when provided it must match the gateway’s target space (validated, not used for lookup). In separate-gateways mode, defaults to <code>agent-network-space</code>.</p></div></div></td><td><div><div><p><code>--target-space my-space</code></p></div></div></td></tr><tr><td><div><div><p><code>--bearer &lt;value&gt;</code></p></div></div></td><td><div><div><p>Bearer token<br>You can also set it with the <code>ANYPOINT_BEARER</code> variable</p></div></div></td><td><div><div><p><code>--bearer myBearerToken</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_id &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client ID<br>You can also set it with the <code>ANYPOINT_CLIENT_ID</code> variable</p></div></div></td><td><div><div><p><code>--client_id myClientID</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_secret &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client Secret<br>You can also set it with the <code>ANYPOINT_CLIENT_SECRET</code> variable</p></div></div></td><td><div><div><p><code>--client_secret myClientSecret</code></p></div></div></td></tr><tr><td><div><div><p><code>--[no-]collectMetrics</code></p></div></div></td><td><div><div><p>Collect metrics<br>You can also set it with the <code>COLLECT_METRICS</code> variable</p></div></div></td><td><div><div><p><code>--no-collectMetrics</code></p></div></div></td></tr><tr><td><div><div><p><code>--disable-tracing</code></p></div></div></td><td><div><div><p>Disable tracing functionalities</p></div></div></td><td><div><div><p><code>--disable-tracing</code></p></div></div></td></tr><tr><td><div><div><p><code>--dont-wait-for-agent-network</code></p></div></div></td><td><div><div><p>Do not wait for the agent network to be ready</p></div></div></td><td><div><div><p><code>--dont-wait-for-agent-network</code></p></div></div></td></tr><tr><td><div><div><p><code>--environment &lt;value&gt;</code></p></div></div></td><td><div><div><p>Environment name<br>You can also set it with the <code>ANYPOINT_ENV</code> variable</p></div></div></td><td><div><div><p><code>--environment Sandbox</code></p></div></div></td></tr><tr><td><div><div><p><code>--host &lt;value&gt;</code></p></div></div></td><td><div><div><p>Host URL<br>Default: <code>anypoint.mulesoft.com</code><br>You can also set it with the <code>ANYPOINT_HOST</code> variable</p></div></div></td><td><div><div><p><code>--host mycompany.anypoint.mulesoft.com</code></p></div></div></td></tr><tr><td><div><div><p><code>--max-retries &lt;value&gt;</code></p></div></div></td><td><div><div><p>Max retries to check the status of the deploying application<br>Default: <code>3</code></p></div></div></td><td><div><div><p><code>--max-retries 5</code></p></div></div></td></tr><tr><td><div><div><p><code>--organization &lt;value&gt;</code></p></div></div></td><td><div><div><p>Organization name<br>You can also set it with the <code>ANYPOINT_ORG</code> variable</p></div></div></td><td><div><div><p><code>--organization MyOrg</code></p></div></div></td></tr><tr><td><div><div><p><code>--password &lt;value&gt;</code></p></div></div></td><td><div><div><p>Password<br>You can also set it with the <code>ANYPOINT_PASSWORD</code> variable</p></div></div></td><td><div><div><p><code>--password myPassword</code></p></div></div></td></tr><tr><td><div><div><p><code>--path &lt;value&gt;</code></p></div></div></td><td><div><div><p>Path to the project<br>Default: <code>.</code></p></div></div></td><td><div><div><p><code>--path ./my-agent-network</code></p></div></div></td></tr><tr><td><div><div><p><code>--process-timeout &lt;value&gt;</code></p></div></div></td><td><div><div><p>Process timeout in milliseconds<br>Default: <code>600000</code></p></div></div></td><td><div><div><p><code>--process-timeout 900000</code></p></div></div></td></tr><tr><td><div><div><p><code>--property &lt;value&gt;</code></p></div></div></td><td><div><div><p>Property to override in <code>name:value</code> format</p></div></div></td><td><div><div><p><code>--property apiKey:sk-xxx</code></p></div></div></td></tr><tr><td><div><div><p><code>--request-timeout &lt;value&gt;</code></p></div></div></td><td><div><div><p>Request timeout in milliseconds<br>Default: <code>60000</code></p></div></div></td><td><div><div><p><code>--request-timeout 120000</code></p></div></div></td></tr><tr><td><div><div><p><code>--username &lt;value&gt;</code></p></div></div></td><td><div><div><p>Username<br>You can also set it with the <code>ANYPOINT_USERNAME</code> variable</p></div></div></td><td><div><div><p><code>--username myuser@example.com</code></p></div></div></td></tr><tr><td><div><div><p><code>--json</code></p></div></div></td><td><div><div><p>Format output as JSON</p></div></div></td><td><div><div><p><code>--json</code></p></div></div></td></tr></tbody></table>

### Example

$ anypoint-cli-agent-fabric-plugin agent-network project deploy

$ anypoint-cli-agent-fabric-plugin agent-network project deploy --property apiKey:sk-xxx

$ anypoint-cli-agent-fabric-plugin agent-network project deploy --property apiKey:sk-xxx --property
role:user

$ anypoint-cli-agent-fabric-plugin agent-network project deploy --path ./my-project --property
myAgent.url:https://api.example.com

## agent-network:project:publish

\> anypoint-cli-agent-fabric-plugin agent-network project publish \[flags\]

Publishes the current agent network project to Anypoint Exchange. The command outputs links and
details for all created assets.

In addition to the [default flags](https://docs.mulesoft.com/anypoint-cli/latest/#default-options), this command accepts
these flags:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Flag</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p><code>--bearer &lt;value&gt;</code></p></div></div></td><td><div><div><p>Bearer token<br>You can also set it with the <code>ANYPOINT_BEARER</code> variable</p></div></div></td><td><div><div><p><code>--bearer myBearerToken</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_id &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client ID<br>You can also set it with the <code>ANYPOINT_CLIENT_ID</code> variable</p></div></div></td><td><div><div><p><code>--client_id myClientID</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_secret &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client Secret<br>You can also set it with the <code>ANYPOINT_CLIENT_SECRET</code> variable</p></div></div></td><td><div><div><p><code>--client_secret myClientSecret</code></p></div></div></td></tr><tr><td><div><div><p><code>--[no-]collectMetrics</code></p></div></div></td><td><div><div><p>Collect metrics<br>You can also set it with the <code>COLLECT_METRICS</code> variable</p></div></div></td><td><div><div><p><code>--no-collectMetrics</code></p></div></div></td></tr><tr><td><div><div><p><code>--debug</code></p></div></div></td><td><div><div><p>Enable debug mode</p></div></div></td><td><div><div><p><code>--debug</code></p></div></div></td></tr><tr><td><div><div><p><code>--environment &lt;value&gt;</code></p></div></div></td><td><div><div><p>Environment name<br>You can also set it with the <code>ANYPOINT_ENV</code> variable</p></div></div></td><td><div><div><p><code>--environment Sandbox</code></p></div></div></td></tr><tr><td><div><div><p><code>--host &lt;value&gt;</code></p></div></div></td><td><div><div><p>Host URL<br>Default: <code>anypoint.mulesoft.com</code><br>You can also set it with the <code>ANYPOINT_HOST</code> variable</p></div></div></td><td><div><div><p><code>--host mycompany.anypoint.mulesoft.com</code></p></div></div></td></tr><tr><td><div><div><p><code>--organization &lt;value&gt;</code></p></div></div></td><td><div><div><p>Organization name<br>You can also set it with <code>ANYPOINT_ORG</code> env variable</p></div></div></td><td><div><div><p><code>--organization MyOrg</code></p></div></div></td></tr><tr><td><div><div><p><code>--password &lt;value&gt;</code></p></div></div></td><td><div><div><p>Password<br>You can also set it with the <code>ANYPOINT_PASSWORD</code> variable</p></div></div></td><td><div><div><p><code>--password myPassword</code></p></div></div></td></tr><tr><td><div><div><p><code>--path &lt;value&gt;</code></p></div></div></td><td><div><div><p>Path to the project<br>Default: <code>.</code></p></div></div></td><td><div><div><p><code>--path ./my-agent-network</code></p></div></div></td></tr><tr><td><div><div><p><code>--username &lt;value&gt;</code></p></div></div></td><td><div><div><p>Username<br>You can also set it with the <code>ANYPOINT_USERNAME</code> variable</p></div></div></td><td><div><div><p><code>--username myuser@example.com</code></p></div></div></td></tr><tr><td><div><div><p><code>--json</code></p></div></div></td><td><div><div><p>Format output as JSON</p></div></div></td><td><div><div><p><code>--json</code></p></div></div></td></tr></tbody></table>

### Example

$ anypoint-cli-agent-fabric-plugin agent-network project publish

## agent-network:project:undeploy

\> anypoint-cli-agent-fabric-plugin agent-network project undeploy \[flags\]

Undeploys the agent network application, removing all deployed resources.

In addition to the [default flags](https://docs.mulesoft.com/anypoint-cli/latest/#default-options), this command accepts
these flags:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Flag</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p><code>--api-version &lt;value&gt;</code></p></div></div></td><td><div><div><p>API version used to discover remotely deployed resources when using <code>--gav</code><br>Default: <code>v1</code></p></div></div></td><td><div><div><p><code>--api-version v1</code></p></div></div></td></tr><tr><td><div><div><p><code>--bearer &lt;value&gt;</code></p></div></div></td><td><div><div><p>Bearer token<br>You can also set it with the <code>ANYPOINT_BEARER</code> variable</p></div></div></td><td><div><div><p><code>--bearer myBearerToken</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_id &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client ID<br>You can also set it with the <code>ANYPOINT_CLIENT_ID</code> variable</p></div></div></td><td><div><div><p><code>--client_id myClientID</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_secret &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client Secret<br>You can also set it with the <code>ANYPOINT_CLIENT_SECRET</code> variable</p></div></div></td><td><div><div><p><code>--client_secret myClientSecret</code></p></div></div></td></tr><tr><td><div><div><p><code>--[no-]collectMetrics</code></p></div></div></td><td><div><div><p>Collect metrics<br>You can also set it with the <code>COLLECT_METRICS</code> variable</p></div></div></td><td><div><div><p><code>--no-collectMetrics</code></p></div></div></td></tr><tr><td><div><div><p><code>--dry-run</code></p></div></div></td><td><div><div><p>Preview the deploy-plane resources that would be undeployed without deleting anything</p></div></div></td><td><div><div><p><code>--dry-run</code></p></div></div></td></tr><tr><td><div><div><p><code>--environment &lt;value&gt;</code></p></div></div></td><td><div><div><p>Environment name<br>You can also set it with the <code>ANYPOINT_ENV</code> variable</p></div></div></td><td><div><div><p><code>--environment Sandbox</code></p></div></div></td></tr><tr><td><div><div><p><code>--gav &lt;value&gt;</code></p></div></div></td><td><div><div><p>Parent asset GAV (<code>groupId:assetId:version</code>). Discovers deployed resources remotely. Requires an environment to be selected</p></div></div></td><td><div><div><p><code>--gav myOrgId:my-network:0.0.0</code></p></div></div></td></tr><tr><td><div><div><p><code>--host &lt;value&gt;</code></p></div></div></td><td><div><div><p>Host URL<br>Default: <code>anypoint.mulesoft.com</code><br>You can also set it with the <code>ANYPOINT_HOST</code> variable</p></div></div></td><td><div><div><p><code>--host mycompany.anypoint.mulesoft.com</code></p></div></div></td></tr><tr><td><div><div><p><code>--json</code></p></div></div></td><td><div><div><p>Format output as JSON</p></div></div></td><td><div><div><p><code>--json</code></p></div></div></td></tr><tr><td><div><div><p><code>--organization &lt;value&gt;</code></p></div></div></td><td><div><div><p>Organization name<br>You can also set it with the <code>ANYPOINT_ORG</code> variable</p></div></div></td><td><div><div><p><code>--organization MyOrg</code></p></div></div></td></tr><tr><td><div><div><p><code>--password &lt;value&gt;</code></p></div></div></td><td><div><div><p>Password<br>You can also set it with the <code>ANYPOINT_PASSWORD</code> variable</p></div></div></td><td><div><div><p><code>--password myPassword</code></p></div></div></td></tr><tr><td><div><div><p><code>--path &lt;value&gt;</code></p></div></div></td><td><div><div><p>Path to the project. Discovers deployed resources remotely from the project lock file. Requires an environment to be selected. Mutually exclusive with <code>--gav</code></p></div></div></td><td><div><div><p><code>--path ./my-project</code></p></div></div></td></tr><tr><td><div><div><p><code>--process-timeout &lt;value&gt;</code></p></div></div></td><td><div><div><p>Process timeout in milliseconds<br>Default: <code>900000</code></p></div></div></td><td><div><div><p><code>--process-timeout 900000</code></p></div></div></td></tr><tr><td><div><div><p><code>--request-timeout &lt;value&gt;</code></p></div></div></td><td><div><div><p>Request timeout in milliseconds<br>Default: <code>60000</code></p></div></div></td><td><div><div><p><code>--request-timeout 60000</code></p></div></div></td></tr><tr><td><div><div><p><code>--username &lt;value&gt;</code></p></div></div></td><td><div><div><p>Username<br>You can also set it with the <code>ANYPOINT_USERNAME</code> variable</p></div></div></td><td><div><div><p><code>--username myuser@example.com</code></p></div></div></td></tr></tbody></table>

### Examples

Undeploy from the current project:

$ anypoint-cli-agent-fabric-plugin agent-network project undeploy --environment Sandbox

Undeploy from a specific project path:

$ anypoint-cli-agent-fabric-plugin agent-network project undeploy --path ./my-project --environment
Sandbox

Undeploy using GAV coordinates:

$ anypoint-cli-agent-fabric-plugin agent-network project undeploy --gav myOrgId:my-network:0.0.0
--environment Sandbox

Preview resources that would be undeployed (dry run):

$ anypoint-cli-agent-fabric-plugin agent-network project undeploy --dry-run --environment Sandbox

## agent-network:project:unpublish

\> anypoint-cli-agent-fabric-plugin agent-network project unpublish \[flags\]

Removes the agent network assets from Anypoint Exchange. By default performs a soft-delete; use
`--hard-delete` for irreversible removal.

To prevent orphaned runtime references to deleted Exchange assets, run
`agent-network project undeploy` before `unpublish`.

In addition to the [default flags](https://docs.mulesoft.com/anypoint-cli/latest/#default-options), this command accepts
these flags:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Flag</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p><code>--api-version &lt;value&gt;</code></p></div></div></td><td><div><div><p>API version used to discover remotely published assets when using <code>--gav</code><br>Default: <code>v1</code></p></div></div></td><td><div><div><p><code>--api-version v1</code></p></div></div></td></tr><tr><td><div><div><p><code>--bearer &lt;value&gt;</code></p></div></div></td><td><div><div><p>Bearer token<br>You can also set it with the <code>ANYPOINT_BEARER</code> variable</p></div></div></td><td><div><div><p><code>--bearer myBearerToken</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_id &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client ID<br>You can also set it with the <code>ANYPOINT_CLIENT_ID</code> variable</p></div></div></td><td><div><div><p><code>--client_id myClientID</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_secret &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client Secret<br>You can also set it with the <code>ANYPOINT_CLIENT_SECRET</code> variable</p></div></div></td><td><div><div><p><code>--client_secret myClientSecret</code></p></div></div></td></tr><tr><td><div><div><p><code>--[no-]collectMetrics</code></p></div></div></td><td><div><div><p>Collect metrics<br>You can also set it with the <code>COLLECT_METRICS</code> variable</p></div></div></td><td><div><div><p><code>--no-collectMetrics</code></p></div></div></td></tr><tr><td><div><div><p><code>--dry-run</code></p></div></div></td><td><div><div><p>Preview the Exchange assets that would be unpublished without deleting anything</p></div></div></td><td><div><div><p><code>--dry-run</code></p></div></div></td></tr><tr><td><div><div><p><code>--environment &lt;value&gt;</code></p></div></div></td><td><div><div><p>Environment name<br>You can also set it with the <code>ANYPOINT_ENV</code> variable</p></div></div></td><td><div><div><p><code>--environment Sandbox</code></p></div></div></td></tr><tr><td><div><div><p><code>--gav &lt;value&gt;</code></p></div></div></td><td><div><div><p>Parent asset GAV (<code>groupId:assetId:version</code>). Discovers assets remotely. Use <code>--environment</code> to enable the active API instances safety check</p></div></div></td><td><div><div><p><code>--gav myOrgId:my-network:0.0.0</code></p></div></div></td></tr><tr><td><div><div><p><code>--hard-delete</code></p></div></div></td><td><div><div><p>Permanently delete assets from Exchange. This cannot be undone</p></div></div></td><td><div><div><p><code>--hard-delete</code></p></div></div></td></tr><tr><td><div><div><p><code>--host &lt;value&gt;</code></p></div></div></td><td><div><div><p>Host URL<br>Default: <code>anypoint.mulesoft.com</code><br>You can also set it with the <code>ANYPOINT_HOST</code> variable</p></div></div></td><td><div><div><p><code>--host mycompany.anypoint.mulesoft.com</code></p></div></div></td></tr><tr><td><div><div><p><code>--json</code></p></div></div></td><td><div><div><p>Format output as JSON</p></div></div></td><td><div><div><p><code>--json</code></p></div></div></td></tr><tr><td><div><div><p><code>--organization &lt;value&gt;</code></p></div></div></td><td><div><div><p>Organization name<br>You can also set it with the <code>ANYPOINT_ORG</code> variable</p></div></div></td><td><div><div><p><code>--organization MyOrg</code></p></div></div></td></tr><tr><td><div><div><p><code>--password &lt;value&gt;</code></p></div></div></td><td><div><div><p>Password<br>You can also set it with the <code>ANYPOINT_PASSWORD</code> variable</p></div></div></td><td><div><div><p><code>--password myPassword</code></p></div></div></td></tr><tr><td><div><div><p><code>--path &lt;value&gt;</code></p></div></div></td><td><div><div><p>Path to the project. Reads the published assets from the project lock file. Select an environment to enable the active API instances safety check. Mutually exclusive with <code>--gav</code></p></div></div></td><td><div><div><p><code>--path ./my-project</code></p></div></div></td></tr><tr><td><div><div><p><code>--username &lt;value&gt;</code></p></div></div></td><td><div><div><p>Username<br>You can also set it with the <code>ANYPOINT_USERNAME</code> variable</p></div></div></td><td><div><div><p><code>--username myuser@example.com</code></p></div></div></td></tr></tbody></table>

### Examples

Unpublish with soft-delete:

$ anypoint-cli-agent-fabric-plugin agent-network project unpublish --environment Sandbox

Unpublish from a specific project path:

$ anypoint-cli-agent-fabric-plugin agent-network project unpublish --path ./my-project --environment
Sandbox

Unpublish with hard-delete (irreversible):

$ anypoint-cli-agent-fabric-plugin agent-network project unpublish --hard-delete --environment
Sandbox

Unpublish using GAV coordinates:

$ anypoint-cli-agent-fabric-plugin agent-network project unpublish --gav myOrgId:my-network:0.0.0
--environment Sandbox

Preview assets that would be unpublished (dry run):

$ anypoint-cli-agent-fabric-plugin agent-network project unpublish --dry-run --environment Sandbox

## agent-network:setup:gateways

\> anypoint-cli-agent-fabric-plugin agent-network setup gateways \[flags\]

Sets up the agent network environment with the required gateways in the specified target space
(private space, RTF, or shared space). This step is required only if the target space doesn’t
already have gateways. In the typical (happy path) workflow, you run it once per target space before
the first deployment.

In addition to the [default flags](https://docs.mulesoft.com/anypoint-cli/latest/#default-options), this command accepts
these flags:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Flag</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p><code>-e, --egress-gw &lt;value&gt;</code></p></div></div></td><td><div><div><p>Name of the egress gateway (separate-gateway mode; requires <code>--ingress-gw</code>)</p></div></div></td><td><div><div><p><code>--egress-gw my-egress</code></p></div></div></td></tr><tr><td><div><div><p><code>-g, --gateway &lt;value&gt;</code></p></div></div></td><td><div><div><p>Name of the gateway for single-gateway mode (recommended). Mutually exclusive with <code>--ingress-gw</code> and <code>--egress-gw</code>.</p></div></div></td><td><div><div><p><code>--gateway my-gateway</code></p></div></div></td></tr><tr><td><div><div><p><code>-i, --ingress-gw &lt;value&gt;</code></p></div></div></td><td><div><div><p>Name of the ingress gateway (separate-gateway mode)</p></div></div></td><td><div><div><p><code>--ingress-gw my-ingress</code></p></div></div></td></tr><tr><td><div><div><p><code>-t, --target-space &lt;value&gt;</code></p></div></div></td><td><div><div><p>Name of the target space (private space, RTF, or shared space) where you set up the agent network environment<br>Default: <code>agent-network-space</code></p></div></div></td><td><div><div><p><code>--target-space my-space</code></p></div></div></td></tr><tr><td><div><div><p><code>--bearer &lt;value&gt;</code></p></div></div></td><td><div><div><p>Bearer token<br>You can also set it with the <code>ANYPOINT_BEARER</code> variable</p></div></div></td><td><div><div><p><code>--bearer myBearerToken</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_id &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client ID<br>You can also set it with the <code>ANYPOINT_CLIENT_ID</code> variable</p></div></div></td><td><div><div><p><code>--client_id myClientID</code></p></div></div></td></tr><tr><td><div><div><p><code>--client_secret &lt;value&gt;</code></p></div></div></td><td><div><div><p>Client Secret<br>You can also set it with the <code>ANYPOINT_CLIENT_SECRET</code> variable</p></div></div></td><td><div><div><p><code>--client_secret myClientSecret</code></p></div></div></td></tr><tr><td><div><div><p><code>--[no-]collectMetrics</code></p></div></div></td><td><div><div><p>Collect metrics<br>You can also set it with the <code>COLLECT_METRICS</code> variable</p></div></div></td><td><div><div><p><code>--no-collectMetrics</code></p></div></div></td></tr><tr><td><div><div><p><code>--dont-wait-for-gateways-running</code></p></div></div></td><td><div><div><p>Do not wait for the gateways to be running</p></div></div></td><td><div><div><p><code>--dont-wait-for-gateways-running</code></p></div></div></td></tr><tr><td><div><div><p><code>--environment &lt;value&gt;</code></p></div></div></td><td><div><div><p>Environment name<br>You can also set it with the <code>ANYPOINT_ENV</code> variable</p></div></div></td><td><div><div><p><code>--environment Sandbox</code></p></div></div></td></tr><tr><td><div><div><p><code>--host &lt;value&gt;</code></p></div></div></td><td><div><div><p>Host URL<br>Default: <code>anypoint.mulesoft.com</code><br>You can also set it with the <code>ANYPOINT_HOST</code> variable</p></div></div></td><td><div><div><p><code>--host mycompany.anypoint.mulesoft.com</code></p></div></div></td></tr><tr><td><div><div><p><code>--organization &lt;value&gt;</code></p></div></div></td><td><div><div><p>Organization name<br>You can also set it with the <code>ANYPOINT_ORG</code> variable</p></div></div></td><td><div><div><p><code>--organization MyOrg</code></p></div></div></td></tr><tr><td><div><div><p><code>--password &lt;value&gt;</code></p></div></div></td><td><div><div><p>Password<br>You can also set it with the <code>ANYPOINT_PASSWORD</code> variable</p></div></div></td><td><div><div><p><code>--password myPassword</code></p></div></div></td></tr><tr><td><div><div><p><code>--username &lt;value&gt;</code></p></div></div></td><td><div><div><p>Username<br>You can also set it with the <code>ANYPOINT_USERNAME</code> variable</p></div></div></td><td><div><div><p><code>--username myuser@example.com</code></p></div></div></td></tr></tbody></table>

### Example

$ anypoint-cli-agent-fabric-plugin agent-network setup gateways --target-space my-space

## Configure CPU and Memory Resources for an Agent Broker

Configure CPU and memory resources for brokers when you deploy an agent network with Anypoint CLI.
By default, brokers reserve `20m` of CPU and `700Mi` of memory, with limits of `2000m` CPU and
`700Mi` memory.

Specify the resource settings in a deployment configuration file or directly in the deploy command.
Don’t use both methods in the same command.

To specify the settings in a deployment configuration file:

1.  Create a `deployment-config.yaml` file with the resource settings:

    ```yaml
    brokers:
      resources.cpu.reserved: 20m
      resources.cpu.limit: 2000m
      resources.memory.reserved: 700Mi
      resources.memory.limit: 700Mi
    ```

2.  Pass the file to the deploy command with `--deployment-properties-file`:

    \--deployment-properties-file=/path/to/deployment-config.yaml

To specify a resource setting directly in the deploy command, use `--deployment-property` with the
broker scope, resource property, and value. For example, to reserve `50m` of CPU:

\--deployment-property brokers:resources:cpu:reserved:50m

<!-- document id=fb44c9794fdb111a36740b50815b29dce5ab0bff02fecd35689b1020a29491f7 url=/mulesoft/current/en-us/agent-network/1.0/af-agent-networks.md -->

---
product: Building Agent Networks
version: 1.0
---

# Building Agent Networks for Agent Fabric

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

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 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 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.

## Example Use Case: Employee Onboarding

In this example, the goal is to seamlessly activate a new hire across HR, IT, Security, and
Facilities with a single, policy‑governed experience.

Here’s how it works:

- Discover

  Publish existing agents and tools (HRIS, Identity, ITSM, Payroll, Facilities, LMS) in Anypoint
  Exchange for reuse.

- Orchestrate

  An agent broker decomposes the task of onboarding the new hire (create HR record, provision
  identity, assign hardware, grant app access, enroll in benefits and training), calling MCP and A2A
  agents as needed, with human‑in‑the‑loop approvals where required.

- Govern

  Omni Gateway enforces authentication, least‑privilege access, and guardrails. API Manager policies
  ensure consistent controls across all calls and data exchanges.

- Observe

  Monitoring and traces (beta) give end‑to‑end visibility into progress, failures, and latency.
  Visualization shows which agents interacted and where bottlenecks occurred.

- Reuse

  The onboarding definition (YAML) is versioned and shareable, enabling rapid adaptation for roles,
  regions, or subsidiaries without rebuilding flows.

- Trust and Compliance

  Centralized credentials, audit trails, and policy inheritance support security, privacy, and
  regulatory requirements (PII handling, approvals, and separation of duties).

With this experience, you get faster time‑to‑productivity, fewer handoffs, lower error rates, and a
consistent new‑hire experience across the enterprise.

## 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 specialized A2A-compliant
agents in your enterprise. A broker is defined by the agents and MCP servers it can leverage to
accomplish tasks. Brokers originate from MuleSoft and are referenced in the agent network YAML.

After you publish your agent network, brokers appear as specialized agents in Anypoint Exchange and
can be reused by other brokers.

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.

Agent assets must be A2A-compliant.

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.

### Agent Networks in Anypoint Code Builder

When you create agent networks, the Anypoint Code Builder canvas shows the brokers, agents, and MCP
servers you’ve configured.

![Anypoint Code Builder canvas showing brokers, agents, and MCP servers](/mulesoft/current/en-us/agent-network/1.0/_images/af-agent-network-canvas.png)

<table><tbody><tr><td><i data-value="1"></i><b>1</b></td><td>The <strong>Brokers</strong> component groups brokers defined locally in your agent network YAML. It can include assets defined locally within the project and assets previously published to Anypoint Exchange, either by your organization or third parties.<div><p>Brokers can reference other brokers defined within the project.</p></div><div><p>Agent network projects don’t require brokers. They can contain only agents and MCP servers defined within the agent network project.</p></div></td></tr><tr><td><i data-value="2"></i><b>2</b></td><td>The <strong>Agents</strong> component groups agents defined locally in your agent network YAML.<div><p>These agents will be published to Exchange.</p></div></td></tr><tr><td><i data-value="3"></i><b>3</b></td><td>The <strong>MCP Servers</strong> component groups MCP servers defined locally in your agent network YAML.<div><p>These servers will be published to Exchange.</p></div></td></tr><tr><td><i data-value="4"></i><b>4</b></td><td>An asset that has been defined within this agent network project.<div><p>The asset might also be published to Exchange.</p></div></td></tr><tr><td><i data-value="5"></i><b>5</b></td><td>An asset that has been added to this agent network project from Exchange.</td></tr></tbody></table>

## Agent Network Architecture

This diagram shows an agent network with agents and MCP servers, traffic through Omni Gateway,
governed by API Manager, and observed in Anypoint Monitoring and Agent Visualizer.

![Agent Fabric showing agents and MCP servers defined in YAML and published to Exchange](/mulesoft/current/en-us/agent-network/1.0/_images/agent-fabric-architecture.png)

<table><tbody><tr><td><i data-value="1"></i><b>1</b></td><td>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.</td></tr><tr><td><i data-value="2"></i><b>2</b></td><td>Deploy the agentic assets to CloudHub 2.0 (managed in Runtime Manager).</td></tr><tr><td><i data-value="3"></i><b>3</b></td><td>Enforce policies on incoming traffic to the network with an ingress Omni Gateway, which sits in front of brokers and API endpoints.</td></tr><tr><td><i data-value="4"></i><b>4</b></td><td>Enforce policies, manage connections, and emit telemetry data with an egress Omni Gateway, which sits on outbound paths from brokers and agents to external agents and services.<div><div data-type="NOTE">In a shared space, or in a private space using a single-gateway configuration, callouts policies, traffic, and data are handled by one Omni Gateway.</div></div></td></tr><tr><td><i data-value="5"></i><b>5</b></td><td>Collect logs, metrics, and traces from Omni Gateway and runtimes in Anypoint Monitoring.</td></tr></tbody></table>

## 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
    [OpenAI](https://developers.openai.com/api/docs/models) 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
    [Gemini](https://ai.google.dev/gemini-api/docs/models) 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
  [LLM Proxy Supported LLM Providers](https://docs.mulesoft.com/general/model-proxy#supported-llm-providers).

This table details the requirements and recommended models.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th><strong>Model Provider</strong></th><th><strong>Required Endpoint</strong></th><th><strong>Required Capabilities</strong></th><th><strong>Suggested Models</strong></th></tr></thead><tbody><tr><td><p>OpenAI</p></td><td><p><code>/responses</code></p></td><td><div><div><ul><li><p>Reasoning</p></li><li><p>Native structured output</p></li><li><p>Function and custom tool calling</p></li></ul></div></div></td><td><div><div><ul><li><p>For lower latency: GPT-5-mini</p></li><li><p>For complex reasoning: Evaluate models</p></li></ul></div></div></td></tr><tr><td><p>Gemini</p></td><td><p><code>/generateContent</code> (Native API)</p></td><td><div><div><ul><li><p>Native Thinking (via thinkingBudget and thinkingLevel)</p></li><li><p>Native structured output (responseSchema)</p></li><li><p>Function and custom tool calling</p></li></ul></div></div></td><td><div><div><ul><li><p>For lower latency: Gemini 2.5 Flash, Gemini 2.5 Flash-Lite</p></li><li><p>For complex reasoning: Gemini 3 Pro (Deep Think capabilities)</p></li></ul></div></div></td></tr></tbody></table>

Agent networks support text-based messages and responses. Image and binary message types aren’t
supported.

## A2A Protocol

The Agent2Agent (A2A) Protocol governs agent-to-agent communication. This protocol powers
orchestration, observability, and governance features in agent networks. MuleSoft supports v0.3.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.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Relationship</th><th>Role</th><th>Logic</th></tr></thead><tbody><tr><td><p>Client → Broker_1</p></td><td><p>Broker_1 is server</p></td><td><p>Generates <code>contextId_1</code> and <code>taskId_1</code> for the client.</p></td></tr><tr><td><p>Agent A → Broker_2</p></td><td><p>Broker_2 is server</p></td><td><p>Generates <code>contextId_2</code> and <code>taskId_2</code> for Broker_1.</p></td></tr><tr><td><p>Network broker</p></td><td><p>Broker_1</p></td><td><p>Broker_1 maps <code>contextId_1</code> and <code>taskId_1</code> to <code>contextId_2</code> and <code>taskId_2</code>.</p></td></tr></tbody></table>

For more information, see
[Life of a Task - Group Related Interactions](https://a2a-protocol.org/v0.3.0/topics/life-of-a-task/#group-related-interactions).

> [!NOTE] Agent networks don’t support streaming with Server-Sent Events (SSE).

## See Also

- [Get Started with Agent Networks](https://docs.mulesoft.com/agent-network/1.0/af-get-started)

<!-- document id=b79f8bdffe01f0e120dea95597e6e5f052c3e794719d4490147d014493b670dc url=/mulesoft/current/en-us/agent-network/latest/af-agent-networks.md -->

---
product: Building Agent Networks
version: 2.0
is-latest-version: true
---

# Building Agent Networks for Agent Fabric

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

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, MuleSoft provides 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 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.

## The Guided Determinism Pattern

Brokers in agent network 2.0 architecture use a guided 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 after 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 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 LLMs. 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 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.

Agent assets must be A2A-compliant.

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.

## 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 [Agent Network 2.0 Project File Reference](https://docs.mulesoft.com/agent-network/latest/af-project-files).

> [!NOTE] For a complete, working example you can use as a starting point for your own agent network
> project, see [Example: Building an IT Investigation Broker](https://docs.mulesoft.com/agent-network/latest/af-example-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

This diagram shows an agent network deployed to a shared space in CloudHub 2.0 using a single Omni
Gateway for ingress and egress. The network includes agents and MCP servers and is observed in
Anypoint Monitoring.

![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](/mulesoft/current/en-us/agent-network/latest/_images/agent-fabric-architecture-v2-shared-space.png)

<table><tbody><tr><td><i data-value="1"></i><b>1</b></td><td>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.</td></tr><tr><td><i data-value="2"></i><b>2</b></td><td>Deploy the agentic assets to CloudHub 2.0 (managed in Runtime Manager).</td></tr><tr><td><i data-value="3"></i><b>3</b></td><td>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.<div><div data-type="NOTE">In a private space using a two-gateway configuration, policies, traffic, and data are handled by separate ingress and egress Omni Gateways.</div></div></td></tr><tr><td><i data-value="4"></i><b>4</b></td><td>Collect logs, metrics, and traces from Omni Gateway and runtimes in Anypoint Monitoring.</td></tr></tbody></table>

## Agent Network Assets in Anypoint Exchange

Agent network projects support these asset types 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
[Agent Network YAML and Agent Script](#yaml-and-agent-script) or
[Agent Network 2.0 Project File Reference](https://docs.mulesoft.com/agent-network/latest/af-project-files).

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 [various LLMs](#llm-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`.

## Large Language Models

Agent network brokers support the latest models from OpenAI, Azure OpenAI, Bedrock OpenAI, and
Gemini, as well as LLM Proxies.

- [OpenAI](https://developers.openai.com/api/docs/models)

- [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models)

- [Bedrock OpenAI](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html)

  > [!NOTE] Bedrock OpenAI uses the `openai.` prefix for model names (for example,
  > `openai.gpt-5.5`), which differs from the model names used with OpenAI and Azure OpenAI.

- [Gemini](https://ai.google.dev/gemini-api/docs/models)

- LLM Proxy

  Agent network brokers only support access to OpenAI and Gemini through
  [Omni Gateway LLM Proxy](https://docs.mulesoft.com/general/model-proxy). Transcoding other models to OpenAI format to
  use in agent networks is not supported.

This table details requirements and recommended models.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th><strong>Model Provider</strong></th><th><strong>Required Endpoint</strong></th><th><strong>Required Capabilities</strong></th><th><strong>Suggested Models</strong></th></tr></thead><tbody><tr><td><p>OpenAI</p></td><td><p><code>/responses</code></p></td><td><div><div><ul><li><p>Reasoning</p></li><li><p>Native structured output</p></li><li><p>Function and custom tool calling</p></li></ul></div></div></td><td><div><div><ul><li><p>For lower latency: GPT-5-mini</p></li><li><p>For complex reasoning: Evaluate models</p></li></ul></div></div></td></tr><tr><td><p>Gemini</p></td><td><p><code>/generateContent</code> (Native API)</p></td><td><div><div><ul><li><p>Native Thinking (via thinkingBudget and thinkingLevel)</p></li><li><p>Native structured output (responseSchema)</p></li><li><p>Function and custom tool calling</p></li></ul></div></div></td><td><div><div><ul><li><p>For lower latency: Gemini 2.5 Flash, Gemini 2.5 Flash-Lite</p></li><li><p>For complex reasoning: Gemini 3 Pro (Deep Think capabilities)</p></li></ul></div></div></td></tr></tbody></table>

Agent networks support text-based messages and responses. Image and binary message types aren’t
supported.

For configuration options, see the [LLM Section](https://docs.mulesoft.com/agent-network/latest/af-agent-script-reference#llm-section) of the Agent
Script file reference.

## A2A Protocol in Agent Networks

The Agent2Agent (A2A) Protocol governs agent-to-agent communication and powers orchestration,
observability, and governance features in agent networks. For more information, see
[Using A2A Protocol in Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-a2a-agent-network).

## See Also

- [Getting Started with Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-get-started)

- [Creating Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-create-agent-network)

- [Agent Network 2.0 Project File Reference](https://docs.mulesoft.com/agent-network/latest/af-project-files)

- [Agent Fabric Overview](https://docs.mulesoft.com/general/agent-fabric-overview)

[Agent Network Use Cases](https://docs.mulesoft.com/agent-network/latest/af-use-case-orchestration)

<!-- document id=ec215d820806ec9f9dc6c7a23b2a2f6707ab4cbc9a491fadce8396474cc52817 url=/mulesoft/current/en-us/agent-network/1.0/af-create-agent-network.md -->

---
product: Building Agent Networks
version: 1.0
---

# Create Agent Networks

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Whether you want to use MuleSoft Vibes or the UI, Anypoint Code Builder includes all the agent
network functionality you need to get started.

## Before You Begin

Make sure you review the [prerequisites](https://docs.mulesoft.com/agent-network/1.0/af-get-started#before-you-begin).

## Create a Network Using MuleSoft Vibes

MuleSoft Vibes can help you create your project. For more information, see
[MuleSoft Vibes Overview](https://docs.mulesoft.com/anypoint-code-builder/mulesoft-vibes).

1.  In the Anypoint Code Builder activity bar, click the agent icon
    ![](/mulesoft/current/en-us/agent-network/1.0/_images/af-acb-dev-agent-icon.png).

2.  Describe your agent network, including the brokers, agents, MCP servers, and LLMs you want to
    connect. MuleSoft Vibes does the rest.

To get started, try one of these suggested messages.

- Create a new agent network project called "Employee Onboarding." Add HR agent and CRM agent.

- Build a travel planner broker that plans multi-city trips and generate a new agent network.

- Generate an agent network project for incident management. Include a broker that coordinates the
  resolution of incidents reported by customers.

## Create a Network Using Anypoint Code Builder

1.  If you’re not logged in, log in to your Anypoint Platform account.

2.  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**.

3.  Enter a name for the project and select the location to create the project.

4.  Select the business group associated with the target space you created in
    [Get Started with Agent Networks](https://docs.mulesoft.com/agent-network/1.0/af-get-started). The business group you select must be the
    same business group you selected when you created the target space.

5.  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
[Agent Network Project File Reference](https://docs.mulesoft.com/agent-network/1.0/af-project-files).

- `agent-network.yaml`

  Specifies brokers, agents, MCP servers, LLMs, policies, and authentication in your agent network.

- `exchange.json`

  Specifies Anypoint Exchange assets that are referenced in your agent network, as well as the
  variables to use in your agent network. Each asset has an asset ID that you use in the
  `agent-network.yaml` file.

The canvas shows a visual, read-only representation of your YAML file. Select any component to show
the associated code in the code editor.

![Anypoint Code Builder canvas showing two different brokers with their respective agents and MCP servers](/mulesoft/current/en-us/agent-network/1.0/_images/af-acb-canvas.png)

## 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
[Build Agent Networks in a CI/CD Environment](https://docs.mulesoft.com/agent-network/1.0/af-build-agent-networks-in-a-ci-cd-environment).

## See Also

- [Define Your Agent Network Specification](https://docs.mulesoft.com/agent-network/1.0/af-define-your-agent-network-specification)

- [Working with Workspaces](https://docs.mulesoft.com/anypoint-code-builder/start-workspaces)

<!-- document id=32dd2a03ece70d258ddd06b57adcab82b9a81ac894301468dfa3389153fd8718 url=/mulesoft/current/en-us/agent-network/latest/af-create-agent-network.md -->

---
product: Building Agent Networks
version: 2.0
is-latest-version: true
---

# Creating Agent Networks

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Create an agent network to connect brokers, agents, MCP servers, and LLMs into a coordinated
workflow. Choose from MuleSoft Vibes, the visual canvas and code editor in Anypoint Code Builder, or
the Anypoint CLI for CI/CD environments.

## Before You Begin

Make sure you review the [prerequisites](https://docs.mulesoft.com/agent-network/latest/af-get-started#before-you-begin).

## Create a Network Using MuleSoft Vibes

Details

Use natural language prompts in MuleSoft Vibes to create your project. For more information, see
[MuleSoft Vibes Overview](https://docs.mulesoft.com/anypoint-code-builder/mulesoft-vibes).

1.  In the Anypoint Code Builder activity bar, click the agent icon
    ![](/mulesoft/current/en-us/agent-network/latest/_images/af-acb-dev-agent-icon.png).

2.  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 a Network Using a Coding Agent

Details

Use a coding agent of your choice, like Claude or Cursor, with these publicly available MuleSoft
skills on [MuleSoft Developer Hub](https://dev-portal.mulesoft.com/index.html?filter=skill).

- [Build an agent broker project](https://dev-portal.mulesoft.com/skills/build-agent-broker-project.html).

- [Translate an agent network](https://dev-portal.mulesoft.com/skills/translate-agent-broker-old-to-new-project.html)
  1.0 project to an agent network 2.0 project.

## Create a Network Using Anypoint Code Builder

Details

If you prefer not to use MuleSoft Vibes, create a new agent network project directly from the
Anypoint Code Builder UI.

1.  If you’re not logged in, log in to your Anypoint Platform account.

2.  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**.

3.  Enter a name for the project and select the location to create the project.

4.  Select the business group associated with the target space you created in
    [Get Started with Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-get-started). The business group you select must be the
    same business group you selected when you created the target space.

5.  Select **Create Project**.

When the project opens, the `agent-network.yaml` file opens in the code view editor. Open the graph
canvas from the action bar. For more information, see
[Define Your Agent Network](https://docs.mulesoft.com/agent-network/latest/af-define-your-agent-network-specification).

## Convert an Agent Network 1.0 Project to a 2.0 Project

If you have an existing agent network 1.0 project, use natural language prompts in MuleSoft Vibes to
convert it to a 2.0 project. Agent network 2.0 projects use guided determinism to separate workflow
steps requiring probabilistic LLM reasoning from those requiring deterministic control-flow logic.

To get started, try this suggested prompts:

- Help me convert my V1 agent network project in this folder to a new V2 agent network project as
  one orchestrator node.

## Agent Network Project Files

Anypoint Code Builder creates these 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
[Agent Network Project File Reference](https://docs.mulesoft.com/agent-network/latest/af-project-files).

/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 in this file.

- `/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 [Example: Building an IT Investigation Broker](https://docs.mulesoft.com/agent-network/latest/af-example-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 a Network Using the Anypoint CLI

If you run operations within a CI/CD environment, use Anypoint CLI’s plugin to set up, create,
build, publish, and deploy agent networks. For more information, see
[Build Agent Networks in a CI/CD Environment](https://docs.mulesoft.com/agent-network/latest/af-build-agent-networks-in-a-ci-cd-environment).

## What’s Next?

- [Defining Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-define-your-agent-network-specification)

[Getting Started with Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-get-started)
[Defining Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-define-your-agent-network-specification)

<!-- document id=24083f4257fb0ca0fbc578a183df914c98bc32fac7350b0402599ed2a60511fb url=/mulesoft/current/en-us/agent-network/1.0/af-define-your-agent-network-specification.md -->

---
product: Building Agent Networks
version: 1.0
---

# Define Your Agent Network Specification

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

After you create your agent network project, configure `agent-network.yaml` and `exchange.json` to
reflect the structure of your network.

## Before You Begin

Make sure you review the [prerequisites](https://docs.mulesoft.com/agent-network/1.0/af-get-started#before-you-begin).

> [!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 a Network Using MuleSoft Vibes

MuleSoft Vibes can help you configure your agent network specification. For more information, see
[Creating API Specs with MuleSoft Vibes](https://docs.mulesoft.com/anypoint-code-builder/vibes-api-ai-create-spec).

1.  In the Anypoint Code Builder activity bar, click the agent icon
    ![](/mulesoft/current/en-us/agent-network/1.0/_images/af-acb-dev-agent-icon.png).

2.  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 a Network Using Anypoint Code Builder or Your 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
[Agent Network Project File Reference](https://docs.mulesoft.com/agent-network/1.0/af-project-files). 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
[Add Exchange Assets to Your Agent Network Project](#add-exchange-assets).

Use auto-completion menus in Anypoint Code Builder to speed your development. For more information,
see [Use Auto-Completion Menus](https://docs.mulesoft.com/anypoint-code-builder/start-discover-ui#use-autocomplete).

## 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
[Example: Reference an Exchange Asset from Your Agent Network](#exchange-assets-example).

### Add Assets Using MuleSoft Vibes

1.  In the Anypoint Code Builder activity bar, click the agent icon
    ![](/mulesoft/current/en-us/agent-network/1.0/_images/af-acb-dev-agent-icon.png).

2.  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 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).

1.  If you’re not logged in already, log in to your Anypoint Platform account.

2.  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**.

3.  In Add Exchange Assets to Project, enter information about the assets to add.

4.  Select **Add to Project**.

    Assets are added to the `dependencies` attribute in the `exchange.json` file in your project.

5.  Edit the `agent-network.yaml` file to indicate which brokers use those assets:

    1.  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`.

    2.  Reference the connection from one or more brokers (for example, from a broker’s `llm`,
        `links`, or `tools` section).

    3.  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.

### 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`.

```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.

```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`.

<!-- document id=61d4c4dc6abafe30a50a707e24f9567cc78f371c4395952eb971b3c59ab10b05 url=/mulesoft/current/en-us/agent-network/latest/af-define-your-agent-network-specification.md -->

---
product: Building Agent Networks
version: 2.0
is-latest-version: true
---

# Defining Agent Networks

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

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

Review the [prerequisites](https://docs.mulesoft.com/agent-network/latest/af-get-started#before-you-begin) and make sure that you’ve created an
agent network project. See [Create Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-create-agent-network).

> [!NOTE] For a complete, working example you can use as a starting point for your own agent network
> project, see [Example: Building an IT Investigation Broker](https://docs.mulesoft.com/agent-network/latest/af-example-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 an Agent Network Using MuleSoft Vibes

Details

Use natural language prompts in MuleSoft Vibes to configure your agent network specification. For
more information, see
[Creating API Specs with MuleSoft Vibes](https://docs.mulesoft.com/anypoint-code-builder/vibes-api-ai-create-spec).

1.  In the Anypoint Code Builder activity bar, click the agent icon
    ![](/mulesoft/current/en-us/agent-network/latest/_images/af-acb-dev-agent-icon.png).

2.  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 Your Network in Anypoint Code Builder

Details

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. 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, 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
> [Use Auto-Completion Menus](https://docs.mulesoft.com/anypoint-code-builder/start-discover-ui#use-autocomplete).

![Anypoint Code Builder canvas showing the executor node highlighted in the code view editor](/mulesoft/current/en-us/agent-network/latest/_images/af-acb-canvas-v2.png)

### Open Your Project

Open your agent network project in Anypoint Code Builder and display the canvas alongside the code
editor.

1.  In Anypoint Code Builder, open your agent network project. By default, `agent-network.yaml`
    opens in the editor.

2.  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.

1.  Edit `agent-network.yaml` to declare assets in the **registry** section and to define
    connections and policies in the **context** section.

2.  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
    [Agent Network Project File Reference](https://docs.mulesoft.com/agent-network/latest/af-project-files).

3.  Update `exchange.json` to manage Anypoint Exchange dependencies by using the **Add Exchange
    Assets** action rather than editing it by hand. See
    [Add Exchange Assets to Your Agent Network Project](#add-exchange-assets).

### Navigate Between Canvas and Code View

Use the navigation shortcuts on the canvas to jump straight to the lines you need to edit.

1.  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.

2.  To open the full Agent Script for a broker, click the **Open in code view** button in that
    broker’s graph header.

3.  To zoom into a specific graph, click the graph name in the **Project Palette**.

4.  To switch the canvas to the Project Assets view, use the toggle at the top of the Project
    Palette.

#### Adjust the Canvas View

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

The **Project Assets** view lists every asset (agent, LLM, MCP server, or policy) you declared in
the **registry** section of `agent-network.yaml`. Use this view to manage those assets or add new
dependencies from Anypoint Exchange.

1.  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.

2.  Use the **search** and **filter** controls at the top of the Project Assets view to find assets
    across both sections.

3.  To open a locally defined asset’s definition in `agent-network.yaml`, click the asset card.

4.  To open an imported asset’s page in Anypoint Exchange, click the asset card.

## 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

Details

Use natural language prompts in MuleSoft Vibes to add Exchange assets to your project.

1.  In the Anypoint Code Builder activity bar, click the agent icon
    ![](/mulesoft/current/en-us/agent-network/latest/_images/af-acb-dev-agent-icon.png).

2.  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

Details

Use the **Project Assets** view to search Anypoint Exchange and add assets directly from the canvas.

1.  In the Project Palette, open the **Project Assets** view.

2.  Click **Add Exchange Assets**.

    The **Add Exchange Assets to Project** UI opens with the Exchange search and listing experience.

3.  Search for the asset you want to add, select it, and choose the version to import.

4.  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 Project Assets.

5.  Edit `agent-network.yaml` to add a connection entry in the `context.connections` section that
    references the new asset, and edit the relevant `.agent` files in `/brokers` to use the
    connection 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 from the Command Palette

Details

You can also start the **Add Exchange Assets** flow without opening the canvas:

1.  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**.

2.  In **Add Exchange Assets to Project**, search for and select the asset.

3.  Click **Add to Project**.

After you add dependencies, their asset names are 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.

## Use an LLM Proxy in Your Agent Network

You can use an [Omni Gateway LLM Proxy](https://docs.mulesoft.com/general/model-proxy) as the LLM connection for your
agent broker. The LLM Proxy must use the OpenAI or Gemini format. For supported models, see
[Large Language Models](https://docs.mulesoft.com/agent-network/latest/af-agent-networks#llm-support).

### Create and Activate the LLM Model Proxy

Create an LLM Model Proxy in Omni Gateway and verify that it is active in Anypoint Exchange before
adding it to your agent network.

1.  [Create an LLM Model Proxy in Omni Gateway](https://docs.mulesoft.com/general/model-proxy-create-model-proxy). The
    proxy format must be OpenAI or Gemini.

2.  [Request access to the LLM Model Proxy asset](https://docs.mulesoft.com/exchange/to-request-access) in Anypoint
    Exchange and verify that the proxy status is **Active**.

3.  Note the client ID and client secret, as you need these to authenticate with the proxy when you
    deploy your agent network.

### Add the LLM Proxy to Your Agent Network

Add the LLM Proxy Exchange asset to your project and configure the connection in
`agent-network.yaml` and your broker’s `.agent` file.

1.  Add the LLM Proxy Exchange asset to your agent network project by using one of the following
    methods:

    - [Add Exchange Assets from the Project Assets or the Command Palette](#add-exchange-assets)

    - [Use MuleSoft Vibes](#define-dev-agent)

2.  In the Explorer, open `exchange.json` and copy the `assetId` for the LLM Proxy dependency.

3.  Open `agent-network.yaml` and add a connection entry in the `context.connections` section:

    1.  Set `kind` to `llm`.

    2.  Set `ref.name` to the `assetId` value you copied from `exchange.json`.

    3.  Set `url` to the consumer endpoint URL for the LLM Proxy. You can find this URL on the **LLM
        Proxy** page in the Anypoint Platform UI.

        You don’t need to add the LLM Proxy to the `registry` section of `agent-network.yaml`.

4.  In the `/brokers` directory, open the `.agent` file for the broker that uses this LLM and set
    the `target` of the LLM node to the connection name you defined in `agent-network.yaml`.

### Provide Authentication Credentials at Deployment

When you deploy your agent network, provide an `apiKey` to authenticate with the LLM Proxy. LLM
Proxy authenticates with a `client_id` and `client_secret`. Provide the value in this format:

`<client_id>:<client_secret>`

### Troubleshoot Version Mismatches

If you reuse an existing LLM Proxy Exchange asset in your agent network, ensure that the
`apiVersion` in the `exchange.json` dependency matches the version group name in your LLM Proxy
asset. To verify, open the Exchange asset page for your LLM Proxy and confirm that the version group
name matches the `apiVersion` value in `exchange.json`.

## See Also

- [Create Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-create-agent-network)

- [Agent Network Project File Reference](https://docs.mulesoft.com/agent-network/latest/af-project-files)

- [Agent Script Reference](https://docs.mulesoft.com/agent-network/latest/af-agent-script-reference)

[Creating Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-create-agent-network)
[Publishing Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-publish-agent-network-assets)

<!-- document id=362dcf6fd8089a64b4f6c2b8c2f1547f1c6c3a920e2e94f5e9d0917720c45ac1 url=/mulesoft/current/en-us/agent-network/1.0/af-deploy-agent-network-targets.md -->

---
product: Building Agent Networks
version: 1.0
---

# Deploy Agent Network Instances

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

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.

<table><colgroup><col> <col></colgroup><thead><tr><th>Agent Type</th><th>Policy</th></tr></thead><tbody><tr><td><p>Broker</p></td><td><div><div><ul><li><p>A2A Agent Card policy</p></li><li><p>Tracing policy</p></li><li><p>Agent Connection Telemetry policy</p></li></ul></div></div></td></tr><tr><td><p>Agent</p><p>(ingress and egress)</p></td><td><div><div><ul><li><p>A2A Agent Card policy</p></li><li><p>Tracing policy</p></li><li><p>Agent Connection Telemetry policy</p></li></ul></div></div></td></tr><tr><td><p>MCP Server</p><p>(ingress and egress)</p></td><td><div><div><ul><li><p>MCP Support policy</p></li><li><p>Tracing policy</p></li><li><p>Agent Connection Telemetry policy</p></li></ul></div></div></td></tr></tbody></table>

## Before You Begin

Make sure you review the [prerequisites](https://docs.mulesoft.com/agent-network/1.0/af-get-started#before-you-begin).

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.

> [!IMPORTANT] You can’t deploy existing agent network projects to a CloudHub shared space. If you
> want to deploy to a shared space, switch to an agent network 2.0 project.

## Deploy Your Network Using MuleSoft Vibes

MuleSoft Vibes can help you deploy your agent network instances. For more information, see
[Creating API Specs with MuleSoft Vibes](https://docs.mulesoft.com/anypoint-code-builder/vibes-api-ai-create-spec).

1.  In the Anypoint Code Builder activity bar, click the agent icon
    ![](/mulesoft/current/en-us/agent-network/1.0/_images/af-acb-dev-agent-icon.png).

2.  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 Your Network Using Anypoint Code Builder

1.  If you’re not logged in already, log in to your Anypoint Platform account.

2.  In Anypoint Code Builder, choose one of the following:

3.  In Explorer, right-click a project file and select **Deploy Agent Network**.

4.  From the Command Palette, run this command: **MuleSoft: Deploy Agent Network**.

5.  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
    [Get Started with Agent Networks](https://docs.mulesoft.com/agent-network/1.0/af-get-started).

6.  Select **Deploy**.

7.  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 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
[Build Agent Networks in a CI/CD Environment](https://docs.mulesoft.com/agent-network/1.0/af-build-agent-networks-in-a-ci-cd-environment).

<!-- document id=5417e136241a302c3f89f794ae28e5a83ad89a59b54d27f173bdcfa6f4ec729e url=/mulesoft/current/en-us/agent-network/latest/af-local-deploy-and-test.md -->

---
product: Building Agent Networks
version: 2.0
is-latest-version: true
---

# Deploy and Test Agent Networks Locally (BETA)

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Deploy your agent network locally and test each broker through an Agent-to-Agent (A2A) chat
interface directly from Anypoint Code Builder. Local deployments let you iterate quickly on your
agent network without publishing or deploying it.

When you deploy locally, Anypoint Code Builder deploys the entire project, including all brokers.
You can then chat with each broker, inspect request and response details, and debug issues before
deploying to a remote target.

## Before You Begin

1.  Install [Docker](https://docs.docker.com/desktop/) on the machine from which you want to run
    local deployments and tests.

2.  To load the local deploy and test feature, ensure you are signed into to Anypoint Code Builder,
    and then restart VSCode.

## Deploy Your Agent Network Locally

Trigger a local deployment from the activity bar, the context menu, or the Command Palette.

> [!NOTE] If your workspace contains multiple agent network projects, the context menu action
> deploys the last active project instead of the one you right-clicked. To deploy a specific
> project, use the **Run** button in the graph or run the command from the Command Palette.

1.  In Anypoint Code Builder, choose one of the following:

    - In the activity bar, click the **Deploy and test locally** icon.

    - In Explorer, right-click your agent network project and select **Deploy and Test Locally**.

    - From the Command Palette, run the command: **MuleSoft: Deploy and Test Locally**.

2.  Review the local deploy and test terms and conditions, and click **Accept**.

3.  On the first run, the terminal prompts you to enter values for the variables defined in your
    `exchange.json` file.

    > [!NOTE] Variables and secrets are stored in plain text on your local machine.

4.  Enter your variable values in the terminal and confirm to start the deployment, or select
    **Cancel** to close without deploying.

    On subsequent runs, your saved variable values are reused automatically and you are not prompted
    again.

### Deployment Results

- **Success**: The Local Deployment and Testing panel opens side-by-side, and a success notification
  appears.

- **Failure**: An error notification appears with a **Try again** button. Check the error details
  and retry. For more information, see
  [Troubleshoot Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-troubleshoot-agent-networks).

## Test Your Brokers

After a successful local deployment, use the testing panel to chat with your brokers using the A2A
protocol.

1.  Use the inline dropdown in the panel header to select a broker. If your project contains
    multiple brokers, you can switch between them without stopping the deployment. Each broker’s
    chat history is preserved while the runtime is running.

2.  View the agent card, which includes:

    - Name and version

    - Protocol and capability tags

    - Description and skills

    - Localhost endpoint URL (with a copy action)

      The agent card collapses to a header strip after you send the first message.

3.  Type a message in the composer to send a request to the selected broker. The broker processes
    the request and returns a response in the chat view.

Each chat session uses a single context ID. To start a fresh session, click **New Chat** in the
panel header.

### Inspect Response Details

Expand any response by clicking **Details** to view:

- State

- Time Used

- Timestamp

- Message ID

- Context ID

- Task ID

- Request (raw JSON, collapsible)

- Response (raw JSON, collapsible)

For multi-part responses, each part appears individually in raw JSON.

## Panel Actions

The testing panel header provides these actions:

<table><colgroup><col> <col></colgroup><thead><tr><th>Action</th><th>Description</th></tr></thead><tbody><tr><td><p><strong>New Chat</strong></p></td><td><div><div><p>Starts a fresh chat session with a new context ID. Clears the current conversation.</p></div></div></td></tr><tr><td><p><strong>Redeploy</strong></p></td><td><div><div><p>Restarts the local deployment and clears all chat history.</p></div></div></td></tr><tr><td><p><strong>Stop</strong></p></td><td><div><div><p>Stops the local runtime. Chat history remains visible, but you can’t send messages until the next run.</p></div></div></td></tr><tr><td><p><strong>…​</strong> (overflow menu)</p></td><td><div><div><p>Contains <strong>Export logs</strong> and <strong>Stop</strong>.</p></div></div></td></tr></tbody></table>

## View Runtime Logs

Runtime logs stream to the standard VS Code Output panel and Debug Console, attached to the run
configuration. Use these logs to debug issues with your brokers, agents, and MCP servers during
local testing.

## See Also

- [Publishing Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-publish-agent-network-assets)

- [Deploying Agent Network Instances](https://docs.mulesoft.com/agent-network/latest/af-deploy-agent-network-targets)

[Publishing Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-publish-agent-network-assets)
[Deploying Agent Network Instances](https://docs.mulesoft.com/agent-network/latest/af-deploy-agent-network-targets)

<!-- document id=35364676a730e8e4cd82557ab59793052a16368fc91de135a1cf68defbae4148 url=/mulesoft/current/en-us/agent-network/latest/af-deploy-agent-network-targets.md -->

---
product: Building Agent Networks
version: 2.0
is-latest-version: true
---

# Deploying Agent Network Instances

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Deploy your agent network instance to a CloudHub 2.0 shared space, a CloudHub 2.0 private space, or
to a Runtime Fabric target. Agent network deployments are available on US Cloud and EU Cloud hosts
only. For more information, see
[Control Plane Hosting Options](https://docs.mulesoft.com/hosting-home/#control-plane-hosting-options).

Additionally, agent brokers follow the same monthly patching cadence as CloudHub 2.0. For the update
schedule, see
[MuleSoft Commercial Cloud Schedule](https://docs.mulesoft.com/release-notes/cloudhub-2/cloudhub-2-runtimes-release-notes#mulesoft-commercial-cloud-schedule).

## Agent Network Deployments and Omni Gateway

When you deploy, Omni Gateway secures inbound traffic to your agent network and outbound traffic
from your brokers, agents, and MCP servers.

Omni Gateway applies these policies automatically at deployment.

<table><colgroup><col> <col></colgroup><thead><tr><th>Agent Type</th><th>Policy</th></tr></thead><tbody><tr><td><p>Broker</p></td><td><div><div><ul><li><p>A2A Agent Card policy</p></li><li><p>Tracing policy</p></li><li><p>Agent Connection Telemetry policy</p></li></ul></div></div></td></tr><tr><td><p>Agent</p><p>(ingress and egress)</p></td><td><div><div><ul><li><p>A2A Agent Card policy</p></li><li><p>Tracing policy</p></li><li><p>Agent Connection Telemetry policy</p></li></ul></div></div></td></tr><tr><td><p>MCP Server</p><p>(ingress and egress)</p></td><td><div><div><ul><li><p>MCP Support policy</p></li><li><p>Tracing policy</p></li><li><p>Agent Connection Telemetry policy</p></li></ul></div></div></td></tr></tbody></table>

### Last-Mile Security Considerations for Agent Networks

Agent networks in version 2.0 don’t support Last-Mile Security for outbound (egress) traffic on the
Omni Gateway. If you have enabled Last-Mile Security, the agent network deploys and the broker can
answer general questions, but it can’t route requests to downstream agents or MCP servers.

Agent networks route outbound traffic through the egress gateway (on port 8082, cluster endpoint).
Last-Mile Security enforces TLS on the ingress-gateway-to-pod hop. The outbound path bypasses this
hop, so the connections can’t be established.

If your deployment requires Last-Mile Security for other applications, deploy your agent network to
a separate egress gateway that has Last-Mile Security disabled.

The broker’s `egressgw.url` resolving to the cluster endpoint is expected behavior, regardless of
the Last-Mile Security setting.

## Before You Begin

Make sure you review the
[prerequisites for setting up agent network gateways and deployment targets](https://docs.mulesoft.com/agent-network/latest/af-get-started#before-you-begin).

> [!IMPORTANT] Redeploying an agent network to a different target or gateway (for example, switching
> between a shared space and a private space, or changing to a different gateway) is not supported
> and fails with a Runtime Manager error. To deploy to a different target or gateway, first manually
> delete the existing Runtime Manager application, then redeploy.

When you deploy your agent network, the system deploys one instance for each connection defined in
your agent network. If your agent network contains brokers, the system deploys one instance per
broker.

## Deploy Your Network Using MuleSoft Vibes

Details

Use MuleSoft Vibes to deploy your agent network instances. For more information, see
[Creating API Specs with MuleSoft Vibes](https://docs.mulesoft.com/anypoint-code-builder/vibes-api-ai-create-spec).

1.  In the Anypoint Code Builder activity bar, click the agent icon
    ![](/mulesoft/current/en-us/agent-network/latest/_images/af-acb-dev-agent-icon.png).

2.  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 Your Network Using Anypoint Code Builder

Details

Deploy your agent network instance to a CloudHub 2.0 space or Runtime Fabric target directly from
Anypoint Code Builder.

1.  If you’re not logged in already, log in to your Anypoint Platform account.

2.  In Anypoint Code Builder, choose one of the following:

3.  In Explorer, right-click a project file and select **Deploy Agent Network**.

4.  From the Command Palette, run this command: **MuleSoft: Deploy Agent Network**.

5.  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
    [Get Started with Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-get-started).

6.  Select **Deploy**.

7.  Your instances are now deployed and ready to test. The system deploys one instance for each
    connection defined in your agent network. If your agent network contains brokers, the system
    deploys one instance 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.

## Undeploy Your Network Using MuleSoft Vibes

Use MuleSoft Vibes to undeploy your agent network instances. For more information, see
[Creating API Specs with MuleSoft Vibes](https://docs.mulesoft.com/anypoint-code-builder/vibes-api-ai-create-spec).

1.  In the Anypoint Code Builder activity bar, click the agent icon
    ![](/mulesoft/current/en-us/agent-network/latest/_images/af-acb-dev-agent-icon.png).

2.  Tell MuleSoft Vibes that you want to undeploy your agent network. MuleSoft Vibes does the rest.

To get started, try one of these suggested messages.

- Undeploy my agent network project from the production environment.

- Undeploy the \[project-name\] project from staging.

- Undeploy agent network project at /path/to/project from dev environment.

## Undeploy Your Network Using Anypoint Code Builder

Details

Undeploy your agent network instances directly from Anypoint Code Builder. When you undeploy, all
API instances and applications in the agent network are stopped and runtime resources are removed.

1.  If you’re not logged in already, log in to your Anypoint Platform account.

2.  In Anypoint Code Builder, choose one of the following:

3.  In the Explorer view, right-click a project file and select **Undeploy Agent Network**.

4.  From the Command Palette, run this command: **MuleSoft: Undeploy Agent Network**.

5.  In the confirmation dialog, select **Undeploy**.

6.  Anypoint Code Builder removes all deployed runtime resources. For details, check the Agent
    Fabric CLI output logs.

## Deploy or Undeploy a Network Using the Anypoint CLI

Details

If you run operations within a CI/CD environment, use Anypoint CLI plugin to set up, create, build,
publish, unpublish, deploy, and undeploy agent networks. For more information, see
[Build Agent Networks in a CI/CD Environment](https://docs.mulesoft.com/agent-network/latest/af-build-agent-networks-in-a-ci-cd-environment).

## Configure CPU and Memory Resources for an Agent Broker

Configure CPU and memory resources for brokers when you deploy an agent network with Anypoint CLI.
By default, brokers reserve `20m` of CPU and `700Mi` of memory, with limits of `2000m` CPU and
`700Mi` memory.

Specify the resource settings in a deployment configuration file or directly in the deploy command.
Don’t use both methods in the same command.

To specify the settings in a deployment configuration file:

1.  Create a `deployment-config.yaml` file with the resource settings:

    ```yaml
    brokers:
      resources.cpu.reserved: 20m
      resources.cpu.limit: 2000m
      resources.memory.reserved: 700Mi
      resources.memory.limit: 700Mi
    ```

2.  Pass the file to the deploy command with `--deployment-properties-file`:

    \--deployment-properties-file=/path/to/deployment-config.yaml

To specify a resource setting directly in the deploy command, use `--deployment-property` with the
broker scope, resource property, and value. For example, to reserve `50m` of CPU:

\--deployment-property brokers:resources:cpu:reserved:50m

## Resolve Agent Network Deployment Errors in Anypoint Code Builder

If you try to deploy an agent network project and see errors related to CLI version, install the
latest Anypoint Code Builder version (1.24.1 or later) and then rebuild, republish, and deploy your
project.

If you try to deploy an agent network project and see errors related to invalid API metadata, use
API Manager to delete existing API instances that were created with previous a Anypoint Code Builder
version. Then rebuild, republish, and deploy your project.

## See Also

- [Agent Network 2.0 Project File Reference](https://docs.mulesoft.com/agent-network/latest/af-project-files)

- [Agent Fabric Overview](https://docs.mulesoft.com/general/agent-fabric-overview)

- [Managed Omni Gateway in Shared Spaces with Unified Traffic Control](https://blogs.mulesoft.com/news/managed-omni-gateway-in-shared-spaces-with-unified-traffic-control/)

[Troubleshoot Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-troubleshoot-agent-networks)

<!-- document id=6708fe3fff4188249d6b26ec6afb45cf1b14d2ad73a29cac53843185463e6784 url=/mulesoft/current/en-us/agent-network/latest/af-example-it-investigation-broker.md -->

---
product: Building Agent Networks
version: 2.0
is-latest-version: true
---

# Example: Building an IT Investigation Broker

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

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.

## Get Hands On

To follow along and try this example yourself, download the
[complete project from GitHub](https://github.com/MuleSoft-AI-Chain-Project/example-mule-apps/blob/master/agent-network-2.0-examples/it-investigation-broker-example).
The repository includes mock endpoints so that you can deploy and test the full agent network. You
need your LLM provider credentials and your Anypoint Platform organization ID.

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 reads incoming ticket descriptions (received via
an A2A message with a Jira ticket ID), classifies severity (High, Low, or too vague to classify)
using an LLM’s judgment, and then takes the correct action. If the ticket is too vague, the agent
first asks the user for clarification.

High-severity tickets are 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. 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 (for example, `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.

<table><colgroup><col> <col> <col> <col> <col> <col></colgroup><thead><tr><th>Node</th><th>Type</th><th>Assets</th><th>LLM</th><th>Total Assets</th><th>Notes</th></tr></thead><tbody><tr><td><p><code>classifySeverity</code></p></td><td><p>generator</p></td><td><p>(none)</p></td><td><p>Gemini 2.5 Flash (default)</p></td><td><p>0</p></td><td><p>Pure LLM classification (needs deep reasoning to classify ambiguous tickets). Constraint: Can only read the ticket and classify, has no actions.</p></td></tr><tr><td><p><code>crossPlatformTriage</code></p></td><td><p>orchestrator</p></td><td><p>Help Center A2A, License Procurement A2A, Jira MCP</p></td><td><p>OpenAI GPT 5.4</p></td><td><p>3</p></td><td><p>Coordinates multi-agent investigation (needs deep reasoning). Constraint: Can investigate and update tickets, but cannot escalate.</p></td></tr><tr><td><p><code>helpSummary</code></p></td><td><p>generator</p></td><td><p> — </p></td><td><p>Gemini 2.5 Flash (default)</p></td><td><p> — </p></td><td><p>One-shot summary generation.</p></td></tr><tr><td><p><code>licenseSummary</code></p></td><td><p>generator</p></td><td><p> — </p></td><td><p>Gemini 2.5 Flash (default)</p></td><td><p> — </p></td><td><p>One-shot summary generation.</p></td></tr><tr><td><p><code>escalateTicket</code></p></td><td><p>executor</p></td><td><p>Escalation MCP</p></td><td><p> — </p></td><td><p>1</p></td><td><p>Deterministic action call (no LLM). Constraint: Can only escalate, not investigate or resolve.</p></td></tr><tr><td><p><code>escalateUnresolved</code></p></td><td><p>executor</p></td><td><p>Escalation MCP</p></td><td><p> — </p></td><td><p>1</p></td><td><p>Deterministic escalation for unresolved tickets (no LLM). Constraint: Can only escalate unresolved tickets after investigation has been exhausted.</p></td></tr><tr><td><p><code>All echo nodes</code></p></td><td><p>echo</p></td><td><p> — </p></td><td><p> — </p></td><td><p> — </p></td><td><p>Deterministic response formatting (no LLM).</p></td></tr></tbody></table>

## 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 produces:
`help_given` or `license_given`. MuleSoft Vibes runs a rigorous contradiction test to make sure that
no node’s instructions accidentally override the deterministic routing logic defined in the graph.
MuleSoft Vibes verifies all instructions against the overall graph structure and 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

This diagram shows the workflow.

![Visual canvas showing the IT agent broker showing severity classification branching into escalation](/mulesoft/current/en-us/agent-network/latest/_images/af-it-broker-escalation-flow.png)

## IT Agent Project Reference

These are the project files for the IT agent.

**Project structure**

it-help-network/ agent-network.yaml brokers/ it-help-investigation.agent exchange.json

**agent-network.yaml**

```yaml
agentNetwork: 2.0.0
info:
  label: "IT Help Investigation Agent Network"
  version: v1
registry:
  agents:
    helpCenterAgent:
      info:
        label: Help Center Agent
      metadata:
        platform: Other
        interfaces:
          a2a_v03:
            card:
              name: Help Center Agent
              description:
                Searches the IT knowledge base for answers to common issues. Returns relevant
                articles with step-by-step instructions.
              url: ${helpCenterAgent.url}
              protocolVersion: 0.3.0
              version: 1.0.0
              capabilities:
                pushNotifications: false
              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:
        platform: Other
        interfaces:
          a2a_v03:
            card:
              name: License Procurement Agent
              description:
                Checks software license availability and provisions licenses for employees.
              url: ${licenseProcurementAgent.url}
              protocolVersion: 0.3.0
              version: 1.0.0
              capabilities:
                pushNotifications: false
              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:
    openAiMini:
      info:
        label: GPT Mini
      metadata:
        platform: OpenAI
context:
  connections:
    help_center_agent_connection:
      kind: a2a
      ref:
        name: helpCenterAgent
      url: ${helpCenterAgent.url}
    license_procurement_agent_connection:
      kind: a2a
      ref:
        name: licenseProcurementAgent
      url: ${licenseProcurementAgent.url}
      authentication:
        kind: oauth2-client-credentials
        clientId: ${licenseProcurementAgent.clientId}
        clientSecret: ${licenseProcurementAgent.clientSecret}
        token:
          url: ${licenseProcurementAgent.tokenUrl}
    escalation_mcp_connection:
      kind: mcp
      ref:
        name: escalationMcp
      url: ${escalationMcp.url}
      authentication:
        kind: apiKey
        apiKey: ${escalationMcp.apiKey}
    jira_mcp_connection:
      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}
    openai_mini_connection:
      kind: llm
      ref:
        name: openAiMini
      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.
          version: 1.0.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:**

```yaml
# @dialect: AGENTFABRIC=1.0
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.openai_mini

llm:
  openai_mini:
    target: "llm://openai_mini_connection"
    kind: "OpenAI"
    model: "gpt-5-mini"

# -- ACTION DEFINITIONS -------------------------------------------------------
actions:
  help_center_agent:
    target: "a2a://help_center_agent_connection"
    kind: "a2a:send_message"

  license_procurement_agent:
    target: "a2a://license_procurement_agent_connection"
    kind: "a2a:send_message"

  escalate:
    target: "mcp://escalation_mcp_connection"
    kind: "mcp:tool"
    tool_name: "escalate"

  updateIssue:
    target: "mcp://jira_mcp_connection"
    kind: "mcp:tool"
    tool_name: "updateIssue"

# -- 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"
  llm: @llm.openai_mini
  system:
    instructions: |
      Classify the severity of the incoming IT support ticket and extract the Jira ticket ID.

      Classify as HIGH:
      - System outages affecting multiple users (e.g. "VPN is down for the entire office", "Nobody in Building 3 can connect")
      - Security incidents involving unauthorized access or suspicious activity (e.g. "unauthorized login attempts from an IP in another country")
      - Any blocking issue impacting a team, building, or department

      Classify as LOW:
      - Password resets or connectivity help (e.g. "I forgot my VPN password")
      - Software license or access requests (e.g. "rate limited on my Figma MCP server", "I need access to Tableau")
      - Single-user issues with a clear description

      The ticket_id must always be a string value.
      If no Jira ticket ID is provided in the input, default ticket_id to "JIRA001".
  prompt: ->
    | {!@request.payload.message.parts[0].text}
  outputs:
    properties:
      ticket_id:
        type: "string"
        description: "The Jira ticket ID extracted from the input (e.g. '001' from 'Jira ticket ID 001')"
      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
  on_exit: ->
    transition to @echo.escalationResponse

echo escalationResponse:
  kind: "a2a:status_update_event"
  state: "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)]})

# -- LOW: CROSS-PLATFORM TRIAGE -----------------------------------------------
orchestrator crossPlatformTriage:
  description: "Investigates the ticket using Help Center and License Procurement agents."
  label: "Cross-Platform Triage"
  llm: @llm.openai_mini
  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.updateIssue
        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:status_update_event"
  state: "TASK_STATE_COMPLETED"
  message: a2a.message({messageId: uuid(), parts: [a2a.textPart(@generator.helpSummary.output)]})

# -- 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:status_update_event"
  state: "TASK_STATE_COMPLETED"
  message: a2a.message({messageId: uuid(), parts: [a2a.textPart(@generator.licenseSummary.output)]})

# -- UNRESOLVED PATH -----------------------------------------------------------
executor escalateUnresolved:
  description: "Escalates an unresolved low-severity ticket to a human agent."
  do: ->
    run @actions.escalate
  on_exit: ->
    transition to @echo.unresolvedResponse

echo unresolvedResponse:
  kind: "a2a:status_update_event"
  state: "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)]})
```

**exchange.json**

```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",
  "descriptorVersion": "1.0.0",
  "apiVersion": "v1.0",
  "description": "Triages IT support tickets, escalates critical issues, and resolves common problems through cross-platform investigation with Help Center and License Procurement agents.",
  "tags": [],
  "dependencies": [],
  "metadata": {
    "variables": {
      "helpCenterAgent": {
        "url": {
          "description": "Help Center Agent A2A URL",
          "default": "",
          "secret": false
        }
      },
      "licenseProcurementAgent": {
        "url": {
          "description": "License Procurement Agent A2A URL",
          "default": "",
          "secret": false
        },
        "tokenUrl": {
          "description": "OAuth2 token endpoint for the License Procurement agent (client credentials grant)",
          "default": "",
          "secret": false
        },
        "clientId": {
          "description": "OAuth2 client ID the broker presents to the License Procurement agent",
          "default": "",
          "secret": false
        },
        "clientSecret": {
          "description": "OAuth2 client secret -- inject at deploy time via --property, never commit a default value",
          "default": "",
          "secret": true
        }
      },
      "escalationMcp": {
        "url": {
          "description": "Escalation MCP Server URL",
          "default": "",
          "secret": false
        },
        "apiKey": {
          "description": "API key for the Escalation MCP server -- inject at deploy time, never commit a default value",
          "default": "",
          "secret": true
        }
      },
      "jiraMcp": {
        "url": {
          "description": "Jira MCP Server URL (called on-behalf-of the inbound user)",
          "default": "",
          "secret": false
        },
        "tokenUrl": {
          "description": "OAuth2 token endpoint Jira accepts for the OBO token exchange",
          "default": "",
          "secret": false
        },
        "clientId": {
          "description": "OAuth2 client ID the broker uses to perform the OBO exchange with Jira",
          "default": "",
          "secret": false
        },
        "clientSecret": {
          "description": "OAuth2 client secret for the Jira OBO exchange -- inject at deploy time, never commit a default value",
          "default": "",
          "secret": true
        }
      },
      "openai": {
        "apiKey": {
          "description": "OpenAI API key -- inject at deploy time, never commit a default value",
          "default": "",
          "secret": true
        }
      }
    }
  }
}
```

## See Also

- [Getting Started with Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-get-started)

- [Creating Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-create-agent-network)

- [Agent Network 2.0 Project File Reference](https://docs.mulesoft.com/agent-network/latest/af-project-files)

<!-- document id=9dffe4b22be1ebd2d92996459656b88cdbf1a7c9fd897ce4326ec3d6fc3be316 url=/mulesoft/current/en-us/agent-network/1.0/af-get-started.md -->

---
product: Building Agent Networks
version: 1.0
---

# Get Started with Agent Networks

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

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 get started, review these prerequisites.

### Anypoint Platform Requirements and Permissions

<table><colgroup><col> <col></colgroup><thead><tr><th>Anypoint Platform Component</th><th>Required Permissions</th></tr></thead><tbody><tr><td><p>Runtime Manager</p></td><td><div><div><ul><li><p>Manage Servers</p></li><li><p>Create Applications</p></li><li><p>Read Servers</p></li></ul></div></div></td></tr><tr><td><p>Anypoint Code Builder</p></td><td><div><div><ul><li><p>Anypoint Code Builder</p></li><li><p>Mule Developer Generative AI User</p></li></ul></div></div></td></tr><tr><td><p>Anypoint Design Center</p></td><td><p>Design Center Developer</p></td></tr><tr><td><p>API Manager</p></td><td><div><div><ul><li><p>Deploy API Proxies</p></li><li><p>Manage Policies</p></li></ul></div></div></td></tr><tr><td><p>Exchange</p></td><td><p>Exchange Contributor</p></td></tr><tr><td><p>Usage</p></td><td><p>Usage Viewer</p></td></tr><tr><td><p>CloudHub 2.0 or Runtime Fabric</p></td><td><p><a href="https://docs.mulesoft.com/runtime-fabric/latest/limitations-self">Runtime Fabric permissions</a> <a href="https://docs.mulesoft.com/cloudhub-2/ps-assign-permissions">CloudHub 2.0 permissions</a></p></td></tr></tbody></table>

See [Permissions by Product in Anypoint Platform](https://docs.mulesoft.com/access-management/permissions-by-product)
for a list of all Anypoint Platform permissions.

### Additional Requirements

To complete these tasks, you also need:

- Your Anypoint Platform credentials

- [Anypoint Code Builder](https://docs.mulesoft.com/anypoint-code-builder/start-acb)

  Allowlist Anypoint Code Builder URLs. For more information, see
  [Allow URLs and Antivirus Exclusions for Anypoint Code Builder](https://docs.mulesoft.com/anypoint-code-builder/urls-to-allow).

- [Omni Gateway Ingress and Egress gateways](https://docs.mulesoft.com/gateway/latest/gateway-managed-ingress-egress)

### MuleSoft Vibes Requirements (Optional)

If you plan to use MuleSoft Vibes to create agent network projects, make sure you meet
[the requirements](https://docs.mulesoft.com/anypoint-code-builder/mulesoft-vibes#before-you-begin-vibes).

### 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 [Nodejs.org](https://nodejs.org/en).

- Java 17 or later. Set the `JAVA_HOME` environment variable.

- [Anypoint CLI Fabric Plugin](https://docs.mulesoft.com/agent-network/1.0/af-build-agent-networks-in-a-ci-cd-environment)

## Task Overview

### Step 1: Set Up Your Agent Network

1.  Use Anypoint Runtime Manager to set up a space in CloudHub 2.0 or deployment target in Runtime
    Fabric.

    See [Set Up the Space or Deployment Target for Your Environment](#setup-space).

2.  Set up Omni Gateways for the space or deployment target.

    - If using Anypoint Code Builder, see
      [Set Up Agent Network Gateways for the Space or Deployment Target](#setup-gateways).

    - If using the Anypoint CLI, see the
      [setup gateways command reference](https://docs.mulesoft.com/agent-network/1.0/af-build-agent-networks-in-a-ci-cd-environment#agent-network-setup-gateways).

### Step 2: Create a Project

Now you’re ready to create an agent network project. Choose one of these methods.

- [Create a Network Using MuleSoft Vibes](https://docs.mulesoft.com/agent-network/1.0/af-create-agent-network#create-dev-agent)

- [Create a Network Using Anypoint Code Builder](https://docs.mulesoft.com/agent-network/1.0/af-create-agent-network#create-acb)

- [Create a Network Using the Anypoint CLI](https://docs.mulesoft.com/agent-network/1.0/af-create-agent-network#create-cli)

### 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.

- [Define a Network Using MuleSoft Vibes](https://docs.mulesoft.com/agent-network/1.0/af-define-your-agent-network-specification#define-dev-agent)

- [Define a Network Using Anypoint Code Builder or Your IDE](https://docs.mulesoft.com/agent-network/1.0/af-define-your-agent-network-specification#define-acb-ide)

### 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.

- [Publish Your Network Using MuleSoft Vibes](https://docs.mulesoft.com/agent-network/1.0/af-publish-agent-network-assets#publish-dev-agent)

- [Publish Your Network Using Anypoint Code Builder](https://docs.mulesoft.com/agent-network/1.0/af-publish-agent-network-assets#publish-acb)

- [Publish Your Network Using the Anypoint CLI](https://docs.mulesoft.com/agent-network/1.0/af-build-agent-networks-in-a-ci-cd-environment#agent-network-project-publish)

### Step 5: Deploy Your Agent Network Instances

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.

- [Deploy Your Network Using MuleSoft Vibes](https://docs.mulesoft.com/agent-network/1.0/af-deploy-agent-network-targets#deploy-dev-agent)

- [Deploy Your Network Using Anypoint Code Builder](https://docs.mulesoft.com/agent-network/1.0/af-deploy-agent-network-targets#deploy-acb)

- [Deploy Your Network Using the Anypoint CLI](https://docs.mulesoft.com/agent-network/1.0/af-build-agent-networks-in-a-ci-cd-environment#agent-network-project-deploy)

## 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:

  1.  Create a private space in CloudHub 2.0 or verify that you can access an existing private
      space.

      To create a private space, see
      [Creating Private Spaces](https://docs.mulesoft.com/cloudhub-2/ps-create-configure). We recommend naming the
      private space `agent-network-space`.

  2.  [Associate the new or existing private space with the business groups and environments](https://docs.mulesoft.com/cloudhub-2/ps-config-env)
      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
  [Managed Omni Gateway on Runtime Fabric](https://docs.mulesoft.com/gateway/latest/gateway-managed-set-up#rtf).

## 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
[Omni Gateway Deployment Models](https://docs.mulesoft.com/gateway/latest/gateway-architecture-basic-deployments).

For more information about Runtime Fabric deployments, see
[Managed Omni Gateway on Runtime Fabric](https://docs.mulesoft.com/gateway/latest/gateway-managed-set-up#rtf).

1.  In Anypoint Code Builder, from the Command Palette, run the command **MuleSoft: Set Up Agent
    Network Gateways**.

2.  If you’re not logged in, log in to your Anypoint Platform account.

3.  Select the business group and environment.

4.  Select the deployment target:

    - **Shared Space**: 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): Creates one gateway named `agent-network-gw` that handles
        both ingress and egress traffic.

      - **Separate Ingress & Egress**: Creates two gateways:

        - `agent-network-ingress-gw` (with public and internal endpoints)

        - `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

- [Create Agent Networks](https://docs.mulesoft.com/agent-network/1.0/af-create-agent-network)

<!-- document id=8f75f0401df6240ae1d69eb30f77e616e5d0743278710a2ac2af5d4fe55c441a url=/mulesoft/current/en-us/agent-network/latest/af-get-started.md -->

---
product: Building Agent Networks
version: 2.0
is-latest-version: true
---

# Getting Started with Agent Networks

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

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 get started, review these prerequisites.

### Anypoint Platform Requirements and Permissions

<table><colgroup><col> <col></colgroup><thead><tr><th>Anypoint Platform Component</th><th>Required Permissions</th></tr></thead><tbody><tr><td><p>Runtime Manager</p></td><td><div><div><ul><li><p>Manage Servers</p></li><li><p>Create Applications</p></li><li><p>Read Servers</p></li></ul></div></div></td></tr><tr><td><p>Anypoint Code Builder</p></td><td><div><div><ul><li><p>Anypoint Code Builder</p></li><li><p>Mule Developer Generative AI User</p></li></ul></div></div></td></tr><tr><td><p>Anypoint Design Center</p></td><td><p>Design Center Developer</p></td></tr><tr><td><p>API Manager</p></td><td><div><div><ul><li><p>Deploy API Proxies</p></li><li><p>Manage Policies</p></li></ul></div></div></td></tr><tr><td><p>Exchange</p></td><td><p>Exchange Contributor</p></td></tr><tr><td><p>Usage</p></td><td><p>Usage Viewer</p></td></tr><tr><td><p>CloudHub 2.0 or Runtime Fabric</p></td><td><p><a href="https://docs.mulesoft.com/runtime-fabric/latest/limitations-self">Runtime Fabric permissions</a> or <a href="https://docs.mulesoft.com/cloudhub-2/ps-assign-permissions">CloudHub 2.0 permissions</a></p></td></tr></tbody></table>

See [Permissions by Product in Anypoint Platform](https://docs.mulesoft.com/access-management/permissions-by-product)
for a list of all Anypoint Platform permissions.

### Additional Requirements

To complete these tasks, you also need:

- Your Anypoint Platform credentials

- [Anypoint Code Builder](https://docs.mulesoft.com/anypoint-code-builder/start-acb)

  Allowlist Anypoint Code Builder URLs. For more information, see
  [Allow URLs and Antivirus Exclusions for Anypoint Code Builder](https://docs.mulesoft.com/anypoint-code-builder/urls-to-allow).

- [Omni Gateway Ingress and Egress gateways](https://docs.mulesoft.com/gateway/latest/gateway-managed-ingress-egress)

### MuleSoft Vibes Requirements (Optional)

If you plan to use MuleSoft Vibes to create agent network projects, make sure you meet
[the requirements](https://docs.mulesoft.com/anypoint-code-builder/mulesoft-vibes#before-you-begin-vibes).

### 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 [Nodejs.org](https://nodejs.org/en).

- Java 17 or later. Set the `JAVA_HOME` environment variable.

- [Anypoint CLI Agent Fabric Plugin](https://www.npmjs.com/package/mulesoft-anypoint-cli-agent-fabric-plugin)

## Task Overview

### Step 1: Set Up Your Agent Network

1.  Use Anypoint Runtime Manager to set up a space in CloudHub 2.0 or deployment target in Runtime
    Fabric.

    See [Set Up the Space or Deployment Target for Your Environment](#setup-space).

2.  Set up Omni Gateways for the space or deployment target.

    - If using Anypoint Code Builder, see
      [Set Up Agent Network Gateways for the Space or Deployment Target](#setup-gateways).

    - If using the Anypoint CLI, see the
      [setup gateways command reference](https://docs.mulesoft.com/agent-network/latest/af-build-agent-networks-in-a-ci-cd-environment#agent-network-setup-gateways).

### Step 2: Create a Project

Now you’re ready to create an agent network project. Choose one of these methods.

- [Create a Network Using MuleSoft Vibes](https://docs.mulesoft.com/agent-network/latest/af-create-agent-network#create-dev-agent)

- [Create a Network Using Anypoint Code Builder](https://docs.mulesoft.com/agent-network/latest/af-create-agent-network#create-acb)

- [Create a Network Using the Anypoint CLI](https://docs.mulesoft.com/agent-network/latest/af-create-agent-network#create-cli)

### 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.

- [Define a Network Using MuleSoft Vibes](https://docs.mulesoft.com/agent-network/latest/af-define-your-agent-network-specification#define-dev-agent)

- [Define Your Network in Anypoint Code Builder](https://docs.mulesoft.com/agent-network/latest/af-define-your-agent-network-specification#define-acb-ide)

### 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.

- [Publish Your Network Using MuleSoft Vibes](https://docs.mulesoft.com/agent-network/latest/af-publish-agent-network-assets#publish-dev-agent)

- [Publish Your Network Using Anypoint Code Builder](https://docs.mulesoft.com/agent-network/latest/af-publish-agent-network-assets#publish-acb)

- [Publish Your Network Using the Anypoint CLI](https://docs.mulesoft.com/agent-network/latest/af-build-agent-networks-in-a-ci-cd-environment#agent-network-project-publish)

### Step 5: Deploy Your Agent Network Instances

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 target.

- [Deploy Your Network Using MuleSoft Vibes](https://docs.mulesoft.com/agent-network/latest/af-deploy-agent-network-targets#deploy-dev-agent)

- [Deploy Your Network Using Anypoint Code Builder](https://docs.mulesoft.com/agent-network/latest/af-deploy-agent-network-targets#deploy-acb)

- [Deploy Your Network Using the Anypoint CLI](https://docs.mulesoft.com/agent-network/latest/af-build-agent-networks-in-a-ci-cd-environment#agent-network-project-deploy)

## 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. CloudHub 2.0 supports shared spaces and private spaces.

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:

  1.  Create a private space in CloudHub 2.0 or verify that you can access an existing private
      space.

      To create a private space, see
      [Creating Private Spaces](https://docs.mulesoft.com/cloudhub-2/ps-create-configure). We recommend naming the
      private space `agent-network-space`.

  2.  [Associate the new or existing private space with the business groups and environments](https://docs.mulesoft.com/cloudhub-2/ps-config-env)
      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 deployment target for Runtime Fabric.

  For information about Runtime Fabric deployments, see
  [Managed Omni Gateway on Runtime Fabric](https://docs.mulesoft.com/gateway/latest/gateway-managed-set-up#rtf).

  Agent networks on Runtime Fabric use Object Store in one of two modes:

  - **Non-persistent** (default): No additional setup required.

  - **Persistent**: Requires a persistence gateway. For setup instructions, see
    [Persistence Gateway](https://docs.mulesoft.com/runtime-fabric/latest/persistence-gateway).

## Set Up Agent Network Gateways for the Space or Deployment Target

After you set up 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. A single gateway
simplifies operations by providing unified policy enforcement, centralized observability, and one
deployment to manage and scale. This configuration also reduces the cost of using multiple gateways.

If needed, you can use separate gateways for ingress and egress traffic in a private space.

For more information about gateways, see
[Omni Gateway Deployment Models](https://docs.mulesoft.com/gateway/latest/gateway-architecture-basic-deployments).

For more information about Runtime Fabric deployments, see
[Managed Omni Gateway on Runtime Fabric](https://docs.mulesoft.com/gateway/latest/gateway-managed-set-up#rtf).

> [!IMPORTANT] For Runtime Fabric deployments, you must register an external ingress domain on your
> Managed Omni Gateway in Runtime Manager before you deploy an agent network. Running a gateway
> without inbound transport is a valid configuration, but agent network broker deployment requires
> an inbound ingress endpoint.
>
> To add an ingress endpoint, see the instructions for
> [deploying a Managed Omni Gateway](https://docs.mulesoft.com/gateway/latest/gateway-managed-set-up#deploy-a-managed-omni-gateway).

1.  In Anypoint Code Builder, from the Command Palette, run the command **MuleSoft: Set Up Agent
    Network Gateways**.

2.  If you’re not logged in, log in to your Anypoint Platform account.

3.  Select the business group and environment.

4.  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.

> [!IMPORTANT] After you deploy an agent network, you cannot redeploy it to a different target or
> gateway (for example, switching between a shared space and a private space, or changing to a
> different gateway). Attempting to do so fails with a Runtime Manager error. To deploy to a
> different target or gateway, first manually delete the existing Runtime Manager application, then
> redeploy.

## See Also

- [Creating Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-create-agent-network)

[Agent Network Use Cases](https://docs.mulesoft.com/agent-network/latest/af-use-case-orchestration)
[Creating Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-create-agent-network)

<!-- document id=558523634931d1096142563ef05a4d40d3b1c38fb67e1e14d59f62fb4be74106 url=/mulesoft/current/en-us/agent-network/latest/af-use-case-orchestration.md -->

---
product: Building Agent Networks
version: 2.0
is-latest-version: true
---

# Orchestrating Multi-Agent Processes with Agent Networks

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Agent brokers and agent networks coordinate task delegation across specialized agents with guided
determinism. This coordination produces reliable, predictable outcomes from complex business
processes. You define broker routing logic in Agent Script and configure the network composition in
`agent-network.yaml`. This file brings agents, LLMs, and MCP servers together in a single
coordinated system. Use this approach when a single agent can’t handle the process and your business
process requires multiple specialized agents working in sequence or in parallel.

## The Problem

A single agent can handle straightforward tasks, but complex business processes expose the limits of
working with one agent in isolation:

- Specialization gaps: One agent can’t excel at research, financial analysis, regulatory review, and
  customer communication simultaneously.

- No intelligent routing: Without a broker, there’s no component to match an incoming request to the
  right specialist agent based on context.

- Process reliability: Multi-step processes that involve multiple agents and systems are difficult
  to make reliable and predictable without explicit coordination.

- Opaque execution: When something goes wrong in a multi-agent process, it’s hard to know which
  agent failed, why, and what state the process was in.

- Duplication: Teams that build similar multi-agent processes independently create inconsistent
  behavior and duplicated effort.

Making a single agent smarter doesn’t solve these challenges. They require a coordination layer—an
agent network with a broker.

## The Solution

Agent Fabric’s agent brokers and agent networks provide a coordination layer for multi-agent
processes:

- Agent networks: A YAML-configured composition of agents, brokers, LLMs, and MCP servers that
  defines the structure of your agentic solution.

- Agent brokers: Intelligent routing services, defined in Agent Script, that delegate tasks to the
  right A2A-compliant agent based on context.

- Guided determinism: Graph-based broker logic makes sure that tasks follow defined paths, handling
  both expected outcomes and error conditions.

- Anypoint Exchange integration: Published agent networks and brokers appear in Exchange for
  discovery and reuse across your organization.

- Integrated observability: Agent Visualizer displays the network topology, real-time request flows,
  and performance metrics for the entire network.

Key benefits of agent networks and brokers include:

- Reliable outcomes from complex processes: Graph-based routing runs operations in the correct order
  with defined paths for both expected outcomes and error conditions, so multi-step processes behave
  predictably instead of drifting.

- Better results by using the right specialist: Route each task to the agent best suited to handle
  it, instead of stretching one agent to do everything and accepting weaker output on every task.

- Build once, reuse across teams: Publish brokers and agent networks to Exchange so other teams
  compose them into their own networks rather than rebuilding the same process.

- Know exactly where a process failed: Monitor broker routing decisions, agent performance, and
  request flows with Agent Visualizer, so a failure points to the agent and step that caused it.

- Start small, scale when ready: Begin with a simple agent network and add brokers as complexity
  grows. You don’t need a broker to get started, so there’s no upfront coordination cost.

## How Agent Brokers Work

When a request arrives at a broker, it follows this path:

1.  A request arrives at the broker, either from an external caller or from another broker higher in
    the network.

2.  The broker evaluates the request against its routing logic, defined as a graph of nodes in Agent
    Script.

3.  The broker generates a context ID and task ID to track state across the interaction.

4.  The broker delegates the task to the A2A-compliant agent or sub-broker best suited to handle it.

5.  The assigned agent processes the task, calling LLMs and MCP servers as needed.

6.  Results return to the broker, which continues routing through the graph until the process is
    complete.

7.  The broker returns the final result to the original caller.

## Who This Is For

Agent brokers and agent networks are for:

- Teams building multi-agent solutions where tasks are routed across specialized agents based on
  context

- Companies that need reliable, predictable outcomes from complex processes spanning multiple agents
  and systems

- Architects designing reusable agentic components that other teams can discover and compose

- Teams that need end-to-end visibility into how multi-agent processes execute and where failures
  occur

## Example Scenarios

### Scenario 1: Order Processing

**Challenge:** Processing customer orders involves checking inventory, routing to fulfillment,
handling payment, and sending confirmation. Each step is handled by a specialized agent. Without
coordination, the process is fragile and hard to monitor.

Agent brokers and agent networks provide reliable coordination with clear routing logic:

1.  Define an agent network in `agent-network.yaml` that registers a broker, an inventory agent, a
    payment agent, and a fulfillment agent.

2.  Define the broker in Agent Script with nodes for each step and explicit routing logic for
    inventory shortfalls, payment failures, and partial fulfillment.

3.  Deploy the agent network to CloudHub 2.0.

4.  Monitor execution in Agent Visualizer to trace each step and identify where issues occur.

**Result:** Orders move through inventory, payment, and fulfillment on defined paths, with explicit
handling for shortfalls and payment failures instead of silent breakage. When a step fails, Agent
Visualizer shows which agent and which state, so recovery is fast rather than a guessing game.

### Scenario 2: Multi-Discipline Research

**Challenge:** Answering a strategic research question requires market analysis, competitive
intelligence, technical feasibility assessment, and financial modeling — capabilities that belong in
separate specialized agents.

With an agent network, a broker decomposes the request and coordinates the specialists:

1.  Define an agent network that registers market, competitive, technical, and financial analysis
    agents alongside a synthesis agent.

2.  Define a broker in Agent Script that routes each research sub-task to the appropriate specialist
    agent, then routes all results to the synthesis agent.

3.  The synthesis agent produces the final report from the aggregated specialist outputs.

4.  Agent Visualizer shows the routing path, which agents were called, and where time was spent.

**Result:** A strategic question is answered by four specialists working in parallel and synthesized
into one report. The report is faster and higher-quality than a single general-purpose agent, with a
visible trail of which analysis contributed what.

### Scenario 3: Document Processing Pipeline

**Challenge:** Processing incoming documents requires classification, data extraction, quality
validation, and routing for human review — in sequence, with defined rules for what happens when
quality thresholds aren’t met.

With guided determinism in Agent Script:

1.  Define an agent network that includes a classification agent, an extraction agent, and a review
    routing agent.

2.  Define a broker with nodes for each processing stage and explicit paths for low-confidence
    extractions that require human review.

3.  Deploy the network and monitor processing quality and throughput in Agent Visualizer.

**Result:** Documents flow through classification, extraction, and validation automatically, and
only low-confidence cases route to a human. Staff review the exceptions instead of every document,
and quality thresholds are enforced by the graph rather than left to chance.

### Scenario 4: Customer Support Triage

**Challenge:** Incoming support requests range from simple account questions to complex technical
issues and billing disputes. Each type requires a different specialized agent, and misrouting wastes
time.

With a broker handling intelligent triage:

1.  Define a broker in Agent Script that classifies the incoming request and routes it to the
    appropriate specialist: account agent, technical agent, or billing agent.

2.  Each specialist agent calls the relevant MCP servers to retrieve customer data, account history,
    or billing records.

3.  The broker consolidates the specialist’s response and returns it to the caller.

4.  Publish the agent network to Exchange so other teams can reuse the triage broker.

**Result:** Requests reach the right specialist on the first hop, so account, technical, and billing
issues stop bouncing between the wrong agents. Publishing the triage broker to Exchange lets other
teams adopt the same routing instead of rebuilding it.

## Implementation Steps

### Step 1: Map the Process

1.  List the steps in the process and identify which require specialized capabilities.

2.  Document decision points such as where the process branches based on outcomes or data.

3.  Identify which steps can run in parallel and which must be sequential.

4.  Determine what backend systems each agent needs to call, and whether MCP servers already expose
    those systems.

### Step 2: Design the Agent Network

1.  Identify which agents exist and which to build.

2.  Determine whether a broker is needed. If the process involves multiple specialists that are
    routed dynamically, add a broker.

3.  Sketch the broker graph: nodes represent steps, edges represent routing logic between them.

4.  Identify which LLMs agents use for reasoning and which MCP servers provide backend access.

### Step 3: Configure agent-network.yaml

1.  In Anypoint Code Builder, create a new agent network project.

2.  Configure `agent-network.yaml` to declare the registry (agents and MCP servers), context
    (connections), and brokers.

3.  For each broker, create an Agent Script file (`.agent`) that defines the routing graph and node
    behavior.

For more information, see
[Define Your Agent Network Specification](https://docs.mulesoft.com/agent-network/latest/af-define-your-agent-network-specification).

### Step 4: Deploy and Test

1.  Deploy the agent network to CloudHub 2.0.

2.  Send test requests that exercise each routing path in the broker graph.

3.  Verify that each agent receives the tasks it is responsible for.

4.  Test failure paths.

### Step 5: Monitor with Agent Visualizer

1.  Open Agent Visualizer to view the network topology and confirm that agents, brokers, and MCP
    servers are connected as expected.

2.  Send live requests and watch routing decisions in real time.

3.  Use performance metrics to identify latency, error rates, and bottlenecks.

4.  Review historical analysis to identify patterns and optimize routing logic.

For more information, see
[monitoring agent networks with Agent Visualizer](https://docs.mulesoft.com/agent-visualizer/troubleshoot-agent-network).

### Step 6: Publish for Reuse

1.  After validating the agent network, publish it to Exchange.

2.  Other teams can discover the published broker and reuse it as a component in their own agent
    networks.

3.  Apply Omni Gateway policies to the broker endpoint to enforce authentication, rate limiting, and
    audit logging.

## Broker Design Patterns

These patterns represent common approaches to structuring broker routing logic in Agent Script.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Pattern</th><th>Description</th><th>When to Use</th></tr></thead><tbody><tr><td><p>Sequential Routing</p></td><td><p>Route a request through a fixed sequence of specialist agents, where each agent’s output is the input for the next.</p></td><td><p>Steps must run in order and each step depends on the previous result.</p></td></tr><tr><td><p>Parallel Dispatch</p></td><td><p>Dispatch a request to multiple specialist agents simultaneously and aggregate the results.</p></td><td><p>Sub-tasks are independent and can run concurrently for faster completion.</p></td></tr><tr><td><p>Conditional Routing</p></td><td><p>Route a request to different agents based on the content or classification of the request.</p></td><td><p>The right specialist depends on context that isn’t known until the request arrives.</p></td></tr><tr><td><p>Hierarchical Delegation</p></td><td><p>A broker delegates to another broker, which in turn delegates to specialist agents.</p></td><td><p>Complex processes can be decomposed into distinct sub-processes, each managed by its own broker.</p></td></tr></tbody></table>

## Security Considerations

When deploying agent networks and brokers in production:

- Apply Omni Gateway policies to broker endpoints to enforce authentication, rate limiting, and
  audit logging.

- Make sure that each specialist agent’s MCP server connections use appropriate authentication.

- Review which agents have access to which backend systems and apply the principle of least
  privilege to MCP tool selection.

- Use Agent Visualizer to monitor for unexpected routing paths or anomalous agent behavior.

## Next Steps

Get started with your first agent network, from setting up your environment through deploying it to
a target.

1.  [Get started with agent networks](https://docs.mulesoft.com/agent-network/latest/af-get-started).

2.  [Create an agent network project](https://docs.mulesoft.com/agent-network/latest/af-create-agent-network).

3.  [Define your agent network](https://docs.mulesoft.com/agent-network/latest/af-define-your-agent-network-specification).

4.  [Publish your agent network](https://docs.mulesoft.com/agent-network/latest/af-publish-agent-network-assets).

5.  [Deploy an agent network instance](https://docs.mulesoft.com/agent-network/latest/af-deploy-agent-network-targets).

[Getting Started with Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-get-started)

<!-- document id=8cfbc19e5a7417d37599c43146810502732df98e59742174c0afafb87a80a17e url=/mulesoft/current/en-us/agent-network/1.0/af-publish-agent-network-assets.md -->

---
product: Building Agent Networks
version: 1.0
---

# Publish Agent Network Assets

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

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

Make sure you review the [prerequisites](https://docs.mulesoft.com/agent-network/1.0/af-get-started#before-you-begin).

If you want to publish your project assets to a different business group, update the relevant
`groupId` in `exchange.json`.

> [!IMPORTANT] Agent networks use an automatic versioning system for Anypoint Exchange assets. If
> you make changes to your existing agent network project assets and re-publish them, Exchange
> triggers a major semantic version upgrade (for example, 1.x.x to 2.x.x).

## Publish Your Network Using MuleSoft Vibes

MuleSoft Vibes can help you publish your agent network specification to Anypoint Exchange. For more
information, see
[Creating API Specs with MuleSoft Vibes](https://docs.mulesoft.com/anypoint-code-builder/vibes-api-ai-create-spec).

1.  In the Anypoint Code Builder activity bar, click the agent icon
    ![](/mulesoft/current/en-us/agent-network/1.0/_images/af-acb-dev-agent-icon.png).

2.  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 Your Network Using Anypoint Code Builder

1.  If you’re not logged in already, log in to your Anypoint Platform account.

2.  In your Anypoint Code Builder project, choose one of the following:

3.  In Explorer, right-click a project file and select **Publish Agent Network Assets**.

4.  In the Command Palette, run this command: **MuleSoft: Publish Agent Network Assets**.

5.  In **Publish Agent Network Project Assets**, enter a version 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`.

6.  Select **Publish**.

7.  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 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
[Build Agent Networks in a CI/CD Environment](https://docs.mulesoft.com/agent-network/1.0/af-build-agent-networks-in-a-ci-cd-environment).

## See Also

- [Deploy Agent Network Instances](https://docs.mulesoft.com/agent-network/1.0/af-deploy-agent-network-targets)

<!-- document id=5d46d2645f9f50e66f73ee85268571e041e2caedeff3de918be15bf71308ddd4 url=/mulesoft/current/en-us/agent-network/latest/af-publish-agent-network-assets.md -->

---
product: Building Agent Networks
version: 2.0
is-latest-version: true
---

# Publishing Agent Networks

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Build and publish your agent network project as Anypoint Exchange assets. When you publish, Exchange
creates an asset for each broker, agent, and MCP server 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 named `badging-agent` in `agent-network.yaml`. After you
publish, the Exchange `assetId` is `badging-agent`.

> [!IMPORTANT] Asset names must be unique across all projects in your organization. If another
> project already uses an asset name, the publish command fails. Use unique, descriptive names for
> each asset in `agent-network.yaml`. For more information, see
> [Troubleshoot Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-troubleshoot-agent-networks#asset-belongs-to-another-project-error-2006).

## Before You Begin

Make sure you review the [prerequisites](https://docs.mulesoft.com/agent-network/latest/af-get-started#before-you-begin).

To publish your project assets to a different business group, update the relevant `groupId` in
`exchange.json`.

## Version Assets

Don’t 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. If you specify a
different version group, then Exchange triggers a major semantic version upgrade (for example,
`1.x.x` to `2.x.x`) for all associated assets.

The `apiVersion` field in `exchange.json` is the version group shown when you publish an agent
network to Exchange. The `apiVersion` field has these behaviors:

- The version group name only changes when you explicitly rename `apiVersion`. Changing `apiVersion`
  automatically increments the major version (`x.0.0`).

- The version group name doesn’t need to follow a `v#` pattern. You can can use any string.

- Any other change unrelated to `apiVersion` automatically increments only the patch version.

- You can’t manually increment the minor version. Exchange handles minor version increments.

## Publish Your Network Using MuleSoft Vibes

Details

Use MuleSoft Vibes to publish your agent network specification to Anypoint Exchange. For more
information, see
[Creating API Specs with MuleSoft Vibes](https://docs.mulesoft.com/anypoint-code-builder/vibes-api-ai-create-spec).

1.  In the Anypoint Code Builder activity bar, click the agent icon
    ![](/mulesoft/current/en-us/agent-network/latest/_images/af-acb-dev-agent-icon.png).

2.  Tell MuleSoft Vibes 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 \[project-name\] project to Exchange.

- Publish agent network project at /path/to/project with version 2.1.0.

## Publish Your Network Using Anypoint Code Builder

Details

Use Anypoint Code Builder to publish your agent network assets directly from your project to
Anypoint Exchange.

1.  If you’re not logged in already, log in to your Anypoint Platform account.

2.  In your Anypoint Code Builder project, choose one of the following:

3.  In Explorer, right-click a project file and select **Publish Agent Network Assets**.

4.  In the Command Palette, run this command: **MuleSoft: Publish Agent Network Assets**.

5.  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`.

6.  Select **Publish**.

7.  Anypoint Code Builder publishes your agents, MCP servers, and LLM provider definitions to
    Exchange and creates an asset 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.

## Unpublish Your Network Using MuleSoft Vibes

Details

Use MuleSoft Vibes to unpublish your agent network assets from Anypoint Exchange. For more
information, see
[Creating API Specs with MuleSoft Vibes](https://docs.mulesoft.com/anypoint-code-builder/vibes-api-ai-create-spec).

1.  In the Anypoint Code Builder activity bar, click the agent icon
    ![](/mulesoft/current/en-us/agent-network/latest/_images/af-acb-dev-agent-icon.png).

2.  Tell MuleSoft Vibes to unpublish your agent network. MuleSoft Vibes does the rest.

To get started, try one of these suggested messages.

- Unpublish my Employee Onboarding project from Exchange.

- Unpublish my agent network project.

- Unpublish the \[project-name\] project from Exchange.

## Unpublish Your Network Using Anypoint Code Builder

Details

Unpublish your agent network assets from Anypoint Exchange directly from Anypoint Code Builder. When
you unpublish, the asset versions are removed from Exchange. To prevent orphaned runtime references,
undeploy your agent network before unpublishing.

1.  If you’re not logged in already, log in to your Anypoint Platform account.

2.  In Anypoint Code Builder, choose one of the following:

3.  In the Explorer view, right-click a project file and select **Unpublish Agent Network**.

4.  From the Command Palette, run this command: **MuleSoft: Unpublish Agent Network**.

5.  In the confirmation dialog, select **Unpublish**.

6.  Anypoint Code Builder removes the asset versions from Exchange. For details, check the Agent
    Fabric CLI output logs.

## Unpublish Behavior in Exchange

When you unpublish an asset, Exchange performs a soft delete of the asset by default. Exchange waits
7 days before it permanently removes (hard deletes) the asset. If you republish an asset before the
hard delete, Exchange uses the next available patch version (for example, `1.0.x`).

## Publish or Unpublish a Network Using the Anypoint CLI

To set up, create, build, publish, unpublish, deploy, and undeploy agent networks in a CI/CD
environment, use the Anypoint CLI plugin. For more information, see
[Build Agent Networks in a CI/CD Environment](https://docs.mulesoft.com/agent-network/latest/af-build-agent-networks-in-a-ci-cd-environment).

## See Also

- [Deploying Agent Network Instances](https://docs.mulesoft.com/agent-network/latest/af-deploy-agent-network-targets)

[Defining Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-define-your-agent-network-specification)
[Deploy and Test Agent Networks Locally (BETA)](https://docs.mulesoft.com/agent-network/latest/af-local-deploy-and-test)

<!-- document id=e83d3d8f72d42787c029f455e040e3005b028f88c3e755d6fcd99e8e0aefb13e url=/mulesoft/current/en-us/agent-network/latest/af-troubleshoot-errors.md -->

---
product: Building Agent Networks
version: 2.0
is-latest-version: true
---

# Troubleshoot Agent Fabric CLI Errors

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

This guide helps you diagnose and resolve errors from the Anypoint CLI Agent Fabric plugin.

## CLI Error Code Reference

Error codes are grouped into ranges by area:

- **Code:** 1000–1999

  - **Area:** Build errors

  - [Build Errors](#build-errors)

- **Code:** 2000–2999

  - **Area:** Publish and unpublish errors

  - [Publish Errors](#publish-errors)

- **Code:** 3000–3999

  - **Area:** Deploy and undeploy errors

  - [Deploy Errors](#deploy-errors)

- **Code:** 4000–4999

  - **Area:** Gateway setup errors

  - [Gateway Setup Errors](#gateway-setup-errors)

- **Code:** 5000–5999

  - **Area:** Entitlement and org access errors

  - [Entitlement and Org Access Errors](#entitlement-and-org-access-errors)

- **Code:** 6000–6999

  - **Area:** Dependency manager errors

  - [Dependency Manager Errors](#dependency-manager-errors)

- **Code:** 7000–7999

  - **Area:** `create` command errors

  - [Create Command Errors](#create-command-errors)

- **Code:** 8001–8004

  - **Area:** Policy validation errors

  - [Policy Validation Errors](#policy-validation-errors)

- **Code:** 8500–8534

  - **Area:** Local run (`run-local`) errors

  - [Local Run Errors](#local-run-errors)

- **Code:** 10001

  - **Area:** Access management errors

  - [Access Management Errors](#access-management-errors)

- **Code:** 11001–11006

  - **Area:** Gateway flags and CLI arguments errors

  - [Gateway Flag and CLI-Argument Errors](#gateway-flag-and-cli-argument-errors)

### Build Errors

- **Code:** 1001

  - **Name:** `projectDescriptorNotFound`

  - **What it means:** `exchange.json` is missing for the project.

  - **How to fix:** Run the command from the project root and confirm that `exchange.json` exists.

- **Code:** 1002

  - **Name:** `invalidAgentNetworkProject`

  - **What it means:** The project failed validation.

  - **How to fix:** Check the validation output printed before the error. Fix the reported issue and
    rebuild.

- **Code:** 1003

  - **Name:** `buildAssetsError`

  - **What it means:** An asset failed to build.

  - **How to fix:** Read the nested `cause`. The cause is usually a malformed asset file in the
    assets directory.

- **Code:** 1004

  - **Name:** `variableNotFound`

  - **What it means:** A `${placeholder}` has no matching variable.

  - **How to fix:** Declare the variable under `metadata.variables` in `exchange.json`.

- **Code:** 1005

  - **Name:** `validatingAgentNetworkError`

  - **What it means:** Project validation exited with a non-zero status.

  - **How to fix:** Review the validator output for the specific failure.

- **Code:** 1006

  - **Name:** `buildingAgentNetworkError`

  - **What it means:** The build process exited with a non-zero status.

  - **How to fix:** Check the build logs printed before the error.

- **Code:** 1007

  - **Name:** `wrapperNotFoundError`

  - **What it means:** The Maven wrapper (`mvnw`/`mvnw.cmd`) is missing.

  - **How to fix:** Confirm that the project is a Maven project and that the wrapper is present and
    executable.

- **Code:** 1008

  - **Name:** `buildBrokersAppError`

  - **What it means:** The Brokers App failed to build.

  - **How to fix:** Check the logs. The cause is usually an AgentScript compile error.

- **Code:** 1009

  - **Name:** `variablesNotFound`

  - **What it means:** Multiple \`${placeholder}\`s are unresolved.

  - **How to fix:** Declare each listed variable under `metadata.variables` in `exchange.json`.

- **Code:** 1010

  - **Name:** `invalidVariablePath`

  - **What it means:** A variable resolves to an invalid nested path.

  - **How to fix:** Correct the variable path in `exchange.json`.

- **Code:** 1011

  - **Name:** `invalidPath`

  - **What it means:** A file or YAML path is invalid.

  - **How to fix:** Verify the referenced path exists and is well-formed.

- **Code:** 1012

  - **Name:** `invalidOrNotBuiltAgentNetworkProject`

  - **What it means:** A downstream command ran before the project was built.

  - **How to fix:** Run `agent-network project build` first.

- **Code:** 1013

  - **Name:** `unsupportedSchemaVersion`

  - **What it means:** The `schemaVersion` isn’t supported by this CLI.

  - **How to fix:** Use a supported version listed in the message or upgrade the CLI.

- **Code:** 1014

  - **Name:** `validationConnectionsError`

  - **What it means:** A connection references an undefined target or has the wrong kind.

  - **How to fix:** Fix the connection references in `agent-network.yaml` to match defined entities
    and kinds.

- **Code:** 1015

  - **Name:** `noBrokerForImplementation`

  - **What it means:** An AgentScript implementation has no matching broker entry.

  - **How to fix:** Add a broker for the implementation or remove the orphaned file.

- **Code:** 1016

  - **Name:** `unsupportedToolType`

  - **What it means:** An entity declares an unknown tool type.

  - **How to fix:** Use a supported tool type (listed in the message).

- **Code:** 1017

  - **Name:** `invalidAgentScriptPath`

  - **What it means:** An AgentScript path is invalid or its content is unsafe.

  - **How to fix:** Use a path inside the project and remove unsafe content.

- **Code:** 1018

  - **Name:** `errorParsingAgentFile`

  - **What it means:** An AgentScript file failed to parse.

  - **How to fix:** Fix the syntax error reported in the nested `cause`.

- **Code:** 1019

  - **Name:** `policyBindingNotFound`

  - **What it means:** A referenced policy binding doesn’t exist.

  - **How to fix:** Define the binding or correct the reference name.

- **Code:** 1020

  - **Name:** `brokerKindMismatch` **see note**

  - **What it means:** A broker’s kind doesn’t support the requested interface kind.

  - **How to fix:** Align the broker’s kind with the interface or use a compatible broker.

- **Code:** 1021

  - **Name:** `brokerIdMismatch` **see note**

  - **What it means:** The broker id in AgentScript doesn’t match the YAML.

  - **How to fix:** Make the broker id consistent between AgentScript and `agent-network.yaml`.

- **Code:** 1022

  - **Name:** `invalidAgentNetworkProjectDescriptor` **see note**

  - **What it means:** `exchange.json` descriptor is malformed.

  - **How to fix:** Fix the descriptor per the details in the message.

- **Code:** 1023

  - **Name:** `brokerSupportedInterfacesUrlMismatch` **see note**

  - **What it means:** A broker’s A2A supported interfaces use different base URLs.

  - **How to fix:** Use the same scheme, host, and port for all supported interfaces. Use different
    paths only.

- **Code:** 1024

  - **Name:** `brokerUnsupportedProtocolBinding` **see note**

  - **What it means:** A broker’s `protocolBinding` isn’t supported.

  - **How to fix:** Use a supported `protocolBinding` value (listed in the message).

- **Code:** 1020

  - **Name:** `mcpMainYamlNotFound` **see note**

  - **What it means:** MCP introspection can’t find the main YAML.

  - **How to fix:** Set the `main` field in `exchange.json` to the correct file.

- **Code:** 1021

  - **Name:** `mcpYamlParseError` **see note**

  - **What it means:** The MCP YAML failed to parse.

  - **How to fix:** Fix the YAML syntax error in the reported file.

- **Code:** 1022

  - **Name:** `mcpServerJsonNotFound` **see note**

  - **What it means:** `server.json` couldn’t be read.

  - **How to fix:** Confirm `server.json` exists and is readable.

- **Code:** 1023

  - **Name:** `mcpServerJsonInvalidJson` **see note**

  - **What it means:** `server.json` isn’t valid JSON.

  - **How to fix:** Fix the JSON syntax.

- **Code:** 1024

  - **Name:** `mcpServerJsonSchemaValidation` **see note**

  - **What it means:** `server.json` failed schema validation.

  - **How to fix:** Correct the fields listed in the message.

- **Code:** 1025

  - **Name:** `mcpServerJsonNoRemotes`

  - **What it means:** `server.json` defines no remotes.

  - **How to fix:** Add a remote entry. Only remote MCP servers are supported.

- **Code:** 1026

  - **Name:** `mcpServerJsonMultipleRemotes`

  - **What it means:** `server.json` defines multiple remotes.

  - **How to fix:** Pass `--transport` to select one.

- **Code:** 1027

  - **Name:** `mcpServerJsonRemoteNotFound`

  - **What it means:** The requested transport isn’t in `server.json`.

  - **How to fix:** Use one of the available transports listed in the message.

- **Code:** 1028

  - **Name:** `mcpInvalidRemoteProtocol`

  - **What it means:** The remote URL uses an unsupported scheme.

  - **How to fix:** Use `http:` or `https:`.

- **Code:** 1029

  - **Name:** `mcpInvalidRemoteUrl`

  - **What it means:** The remote URL failed to parse.

  - **How to fix:** Correct the URL in `server.json`.

- **Code:** 1030

  - **Name:** `mcpInvalidRegistryKey`

  - **What it means:** A registry key contains invalid characters.

  - **How to fix:** Use only lowercase letters, digits, and hyphens.

- **Code:** 1031

  - **Name:** `mcpCannotDeriveRegistryKey`

  - **What it means:** A registry key couldn’t be derived.

  - **How to fix:** Declare an explicit registry key.

- **Code:** 1032

  - **Name:** `assetIdTooLongForDeployment`

  - **What it means:** The project asset id exceeds the deployment-name length limit.

  - **How to fix:** Shorten the asset id and rebuild.

- **Code:** 1033

  - **Name:** `invalidExchangeJson`

  - **What it means:** `exchange.json` isn’t valid JSON.

  - **How to fix:** Fix the JSON syntax.

- **Code:** 1034

  - **Name:** `invalidExchangeJsonField`

  - **What it means:** An `exchange.json` field has the wrong type.

  - **How to fix:** Set the reported field to the expected type (a string).

> [!NOTE] **Code collision (1020–1024) — known defect.** Codes 1020 through 1024 are each assigned
> to **two** different errors: a broker-interface error and an MCP-introspection error. The
> `errorMessage` text identifies the error as either a broker-interface error or a `server.json` or
> MCP YAML error. Match the message instead of the number alone.

### Publish Errors

- **Code:** 2001

  - **Name:** `organizationAccessError`

  - **What it means:** You lack access to the project’s `groupId`.

  - **How to fix:** Switch to an org that owns the `groupId` or request access.

- **Code:** 2002

  - **Name:** `projectNotBuiltError`

  - **What it means:** Publish ran before build.

  - **How to fix:** Run `agent-network project build` first.

- **Code:** 2003

  - **Name:** `publishError`

  - **What it means:** An asset failed to publish.

  - **How to fix:** Read the nested `cause`. See [Exchange](#exchange).

- **Code:** 2004

  - **Name:** `assetNotFoundError`

  - **What it means:** An Exchange asset lookup failed.

  - **How to fix:** Verify the GAV, confirm that the asset exists, and check org access.

- **Code:** 2005

  - **Name:** `assetTypeMismatchError`

  - **What it means:** An asset already exists in Exchange with a different type.

  - **How to fix:** Use a new asset id or version, or reconcile the existing asset’s type.

- **Code:** 2006

  - **Name:** `ownershipConflictsError`

  - **What it means:** The asset id is already owned by another project.

  - **How to fix:** Choose a different asset id or publish from the owning project.

- **Code:** 2007

  - **Name:** `deployedResourcesExistOnUnpublish`

  - **What it means:** Unpublish is blocked because deployed resources still reference the assets.

  - **How to fix:** Run `agent-network project undeploy` first, then retry unpublish.

- **Code:** 2010

  - **Name:** `unpublishError`

  - **What it means:** Reports a failure that occurred during the unpublish stage.

  - **How to fix:** Read the nested `cause` for the specific reason. See [Exchange](#exchange) for
    the known 403 issue.

- **Code:** 2011

  - **Name:** `incompatibleTargetVersionPublish`

  - **What it means:** The `target/` artifact was built with an incompatible CLI version.

  - **How to fix:** Rebuild with the current CLI version, then publish.

- **Code:** 2012

  - **Name:** `projectNotBuiltPublish`

  - **What it means:** No build artifact was found at publish time.

  - **How to fix:** Run `agent-network project build` first.

- **Code:** 2013

  - **Name:** `publicationAggregateFailure`

  - **What it means:** One or more publish tasks failed. This error consolidates the failures.

  - **How to fix:** Read the logs for each sub-failure. Each sub-failure maps to an error-code or
    dependent-service entry on this page.

- **Code:** 2014

  - **Name:** `unrecognizedComponentKindForPublicationOrder`

  - **What it means:** **Internal:** a component kind wasn’t recognized when ordering publication.

  - **How to fix:** Rebuild the project. If the error persists, then report it with the `requestId`.

- **Code:** 2015

  - **Name:** `metadataPatchParseFailed`

  - **What it means:** **Internal:** a serialized metadata file couldn’t be parsed for version
    patching.

  - **How to fix:** Rebuild the project. If the error persists, then report it with the `requestId`.

### Deploy Errors

- **Code:** 3001

  - **Name:** `createApiError`

  - **What it means:** Creating an API instance in API Manager failed.

  - **How to fix:** A 409 often means that an instance with this name already exists. See
    [API Manager](#api-manager).

- **Code:** 3004

  - **Name:** `deployError`

  - **What it means:** Deploying an API into a gateway failed.

  - **How to fix:** Read the nested `cause`. See
    [Runtime Fabric / AMC](#runtime-fabric-application-manager-amc).

- **Code:** 3005

  - **Name:** `connectionNotFoundError`

  - **What it means:** A connection couldn’t be resolved.

  - **How to fix:** Verify the connection is published and its name matches the reference.

- **Code:** 3006

  - **Name:** `gettingEgressConnectionError`

  - **What it means:** Fetching the egress connection failed.

  - **How to fix:** Check the egress gateway and target. See [Gateway Manager](#gateway-manager).

- **Code:** 3007

  - **Name:** `deployAPIError`

  - **What it means:** A generic API deploy failure.

  - **How to fix:** Read the nested `cause`.

- **Code:** 3008

  - **Name:** `brokerGroupDeploymentError`

  - **What it means:** Broker group (Agent Graph) deployment failed.

  - **How to fix:** Check the logs. See
    [Runtime Fabric / AMC](#runtime-fabric-application-manager-amc).

- **Code:** 3009

  - **Name:** `unableToResolve`

  - **What it means:** A GAV couldn’t be resolved at deploy time.

  - **How to fix:** Build and publish the project before deploying.

- **Code:** 3010

  - **Name:** `createPatchApiError`

  - **What it means:** Updating an existing API instance failed.

  - **How to fix:** Read the nested `cause`. See [API Manager](#api-manager).

- **Code:** 3012

  - **Name:** `noTranscodingFoundFor`

  - **What it means:** An expected transcoding policy is missing.

  - **How to fix:** Verify that the transcoding policy is published and referenced correctly.

- **Code:** 3015

  - **Name:** `gatewayTargetSpaceError`

  - **What it means:** The ingress and egress gateways don’t match the runtime target space.

  - **How to fix:** Choose gateways whose target space matches your runtime target.

- **Code:** 3016

  - **Name:** `createApiSpecNotFound`

  - **What it means:** The API spec asset isn’t in Exchange.

  - **How to fix:** Publish the Agent Network before deploying.

- **Code:** 3017

  - **Name:** `requestTimeout`

  - **What it means:** A single HTTP request timed out.

  - **How to fix:** Retry the request. If the error persists, then increase `--request-timeout`. See
    [retry engine](#the-retry-and-timeout-engine).

- **Code:** 3018

  - **Name:** `commandTimeout`

  - **What it means:** The overall command exceeded its timeout budget.

  - **How to fix:** Review org resource limits and increase `--process-timeout`. Check `steps` for
    the command’s progress.

- **Code:** 3019

  - **Name:** `findingAssetsError`

  - **What it means:** Discovering assets to deploy failed.

  - **How to fix:** Retry the request. If the error persists, then read the nested `cause`.

- **Code:** 3020

  - **Name:** `nonPublishedAssetsFoundError`

  - **What it means:** One or more assets aren’t published in Exchange.

  - **How to fix:** Publish the listed assets, then deploy.

- **Code:** 3021

  - **Name:** `noGatewayFoundForInstance`

  - **What it means:** No gateway resolvable for an API instance.

  - **How to fix:** Verify that a gateway is configured for the instance’s protection direction.

- **Code:** 3022

  - **Name:** `assetNotFoundForInstance`

  - **What it means:** An API instance’s backing asset is missing from Exchange.

  - **How to fix:** Publish the asset before deploying.

- **Code:** 3023

  - **Name:** `assetNotFoundForConnection`

  - **What it means:** A connection’s backing asset is missing from Exchange.

  - **How to fix:** Publish the asset before deploying.

- **Code:** 3024

  - **Name:** `missingRequiredUpstreamUrl`

  - **What it means:** A required upstream URL wasn’t resolved.

  - **How to fix:** Provide the upstream URL variable at deploy time (`--property`).

- **Code:** 3025

  - **Name:** `dependencyFailure`

  - **What it means:** A stage was skipped because a dependency’s stage failed.

  - **How to fix:** Fix the upstream failure reported elsewhere in the output.

- **Code:** 3026

  - **Name:** `apiBelongsToAnotherProject`

  - **What it means:** An instance name collides with another project’s instance.

  - **How to fix:** Choose a different name or reuse the existing instance.

- **Code:** 3027

  - **Name:** `invalidSourceValue`

  - **What it means:** An invalid `source` value was supplied.

  - **How to fix:** Set `source` to a supported value (listed in the message).

- **Code:** 3028

  - **Name:** `agentGraphDeploymentError`

  - **What it means:** Agent Graph provisioning failed.

  - **How to fix:** Check the logs. See
    [Runtime Fabric / AMC](#runtime-fabric-application-manager-amc).

- **Code:** 3029

  - **Name:** `connectionRefNotFoundError`

  - **What it means:** A `connection.ref.name` didn’t resolve.

  - **How to fix:** Verify the connection is published and the ref name matches.

- **Code:** 3030

  - **Name:** `undeployError`

  - **What it means:** Reports a failure that occurred during the undeploy stage (fail-closed).

  - **How to fix:** Read the nested `cause` for the specific reason. See
    [Dependent Services: Status Codes and Common Issues](#dependent-services-status-codes-and-common-issues).

- **Code:** 3031

  - **Name:** `invalidPolicy`

  - **What it means:** A policy metadata response was empty or invalid.

  - **How to fix:** Verify the policy GAV (`groupId:assetId:version` coordinate) and retry the
    request. The error can be transient. See [API Manager](#api-manager).

- **Code:** 3032

  - **Name:** `missingGatewayForSharedSpace`

  - **What it means:** A shared-space deploy needs a gateway but none was given.

  - **How to fix:** Provide a gateway with `--gateway`.

- **Code:** 3033

  - **Name:** `invalidGAVFormat`

  - **What it means:** A GAV argument couldn’t be parsed.

  - **How to fix:** Use `groupId:assetId:version`.

- **Code:** 3034

  - **Name:** `parentAssetNotFound`

  - **What it means:** A parent asset lookup failed.

  - **How to fix:** Verify the parent asset exists in Exchange.

- **Code:** 3036

  - **Name:** `invalidAgentProtocol`

  - **What it means:** Agent metadata declares no protocol for a connection.

  - **How to fix:** Declare a protocol for the connection in agent metadata.

- **Code:** 3037

  - **Name:** `unsupportedAgentProtocol`

  - **What it means:** An agent exposes a non-A2A protocol only.

  - **How to fix:** Connect only A2A (Agent2Agent) agents that use `a2a` or `a2a_v1`.

- **Code:** 3045

  - **Name:** `incompatibleTargetVersionDeploy`

  - **What it means:** The `target/` artifact was built with an incompatible CLI version.

  - **How to fix:** Rebuild with the current CLI, republish, then deploy.

- **Code:** 3046

  - **Name:** `projectNotBuiltDeploy`

  - **What it means:** Deploy ran before build.

  - **How to fix:** Run `agent-network project build` first.

- **Code:** 3047

  - **Name:** `bulkApplyPolicyError`

  - **What it means:** Applying policies in API Manager failed.

  - **How to fix:** Check policy GAV resolution and org entitlements. See
    [API Manager](#api-manager).

- **Code:** 3048

  - **Name:** `brokerAuthorizationPolicyConflict`

  - **What it means:** An explicit `user-context-propagation` policy conflicts with the broker’s
    `authorization` section.

  - **How to fix:** Align or remove the conflicting policy field, per the message.

- **Code:** 3049

  - **Name:** `deploymentSettingsFlagsMutuallyExclusive`

  - **What it means:** `--deployment-properties-file` and `--deployment-property` were both passed.

  - **How to fix:** Use one or the other, not both.

- **Code:** 3050

  - **Name:** `deploymentFileReadError`

  - **What it means:** The deployment settings file couldn’t be read.

  - **How to fix:** Verify the file path and permissions.

- **Code:** 3051

  - **Name:** `deploymentSettingsMalformedEntry`

  - **What it means:** A `--deployment-property` entry is malformed.

  - **How to fix:** Use `<scope>:<name>:<value>` (for example `brokers:vCores:0.1`).

- **Code:** 3052

  - **Name:** `deploymentSettingsInvalid`

  - **What it means:** Deployment settings failed semantic validation.

  - **How to fix:** Fix the reported setting.

- **Code:** 3053

  - **Name:** `runtimeVersionNotFound`

  - **What it means:** The requested runtime version isn’t available.

  - **How to fix:** Use one of the available versions listed in the message.

- **Code:** 3054

  - **Name:** `mixedRuntimeTypesInDeploy`

  - **What it means:** The deploy set mixes Mule apps and Agent Graphs.

  - **How to fix:** Split into separate deploys.

- **Code:** 3055

  - **Name:** `deploymentAggregateFailure`

  - **What it means:** One or more deploy tasks failed. This error consolidates the failures.

  - **How to fix:** Read the logs for each sub-failure. Each sub-failure maps to an error-code or
    dependent-service entry on this page.

- **Code:** 3056

  - **Name:** `runtimeVersionNotResolved`

  - **What it means:** **Internal:** runtime version wasn’t resolved before deployment.

  - **How to fix:** Rebuild and redeploy. If the error persists, then report it with the
    `requestId`.

- **Code:** 3057

  - **Name:** `undeployEnvironmentIdRequired`

  - **What it means:** `--gav` undeploy is missing the environment id.

  - **How to fix:** Pass `--environment`.

- **Code:** 3058

  - **Name:** `undeployEnvironmentRequired`

  - **What it means:** No environment was selected for undeploy.

  - **How to fix:** Pass `--environment`.

- **Code:** 3059

  - **Name:** `publicationBeforeDeploymentFailed`

  - **What it means:** The auto-publish step before deploy failed, so deploy aborted.

  - **How to fix:** Fix the publish failure. See the embedded cause and
    [Publish Errors](#publish-errors).

### Gateway Setup Errors

- **Code:** 4001

  - **Name:** `noDomainsFound`

  - **What it means:** No private-network domains for the target space.

  - **How to fix:** Create a private network in the target space first.

- **Code:** 4002

  - **Name:** `setupIngressGatewayError`

  - **What it means:** Ingress gateway setup threw.

  - **How to fix:** Read the nested `cause`. See [Gateway Manager](#gateway-manager).

- **Code:** 4003

  - **Name:** `setupIngressGatewayFail`

  - **What it means:** Ingress gateway setup returned a non-success status.

  - **How to fix:** Check the `status` and response in the message. See
    [Gateway Manager](#gateway-manager).

- **Code:** 4004

  - **Name:** `setupEgressGatewayError`

  - **What it means:** Egress gateway setup threw.

  - **How to fix:** Read the nested `cause`. See [Gateway Manager](#gateway-manager).

- **Code:** 4005

  - **Name:** `setupEgressGatewayFail`

  - **What it means:** Egress gateway setup returned a non-success status.

  - **How to fix:** Check the `status` and response. See [Gateway Manager](#gateway-manager).

- **Code:** 4006

  - **Name:** `gatewayNotFoundError`

  - **What it means:** A named gateway isn’t in the environment.

  - **How to fix:** Use one of the available gateways listed in the message.

- **Code:** 4007

  - **Name:** `runtimeTargetNotFoundError`

  - **What it means:** A named runtime target space isn’t in the environment.

  - **How to fix:** Use an available space or create one
    ([CloudHub 2 docs](https://docs.mulesoft.com/cloudhub-2/ps-create-configure)).

- **Code:** 4008

  - **Name:** `unableToRetrieveTargetSpaceMetadata`

  - **What it means:** Fetching target space metadata failed.

  - **How to fix:** Retry the request. See [Gateway Manager](#gateway-manager).

- **Code:** 4009

  - **Name:** `unableToRetrieveGateways`

  - **What it means:** Fetching the gateway list failed.

  - **How to fix:** Retry the request and check org and environment access.

- **Code:** 4010

  - **Name:** `unableToRetrieveGatewayVersions`

  - **What it means:** Fetching gateway versions failed.

  - **How to fix:** Retry the request. See [Gateway Manager](#gateway-manager).

- **Code:** 4011

  - **Name:** `gatewayChannelNotFoundError`

  - **What it means:** The requested update channel doesn’t exist.

  - **How to fix:** Use one of the available channels listed in the message.

- **Code:** 4012

  - **Name:** `noGatewayVersionsFoundError`

  - **What it means:** The channel has no versions.

  - **How to fix:** Choose a different channel.

- **Code:** 4013

  - **Name:** `gatewayAlreadyExists`

  - **What it means:** A gateway with this name already exists in the environment.

  - **How to fix:** Choose a different name because gateway names are unique per environment.

- **Code:** 4014

  - **Name:** `setupGatewayInsufficientResourcesError`

  - **What it means:** The org’s gateway quota is exhausted.

  - **How to fix:** Delete an unused gateway or increase your org limits.

- **Code:** 4015

  - **Name:** `missingDomainsResponse`

  - **What it means:** Domains are required for a non-shared target but none were returned.

  - **How to fix:** Confirm a private network exists for the target.

- **Code:** 4016

  - **Name:** `gatewayUpdateFailedError`

  - **What it means:** Updating the gateway runtime version failed.

  - **How to fix:** Check the `status` in the message and retry the request.

- **Code:** 4017

  - **Name:** `gatewayUpdateTimedOutError`

  - **What it means:** The gateway update didn’t finish within the timeout.

  - **How to fix:** Check the gateway status in Runtime Manager. Retry when the gateway is stable.

### Entitlement and Org Access Errors

- **Code:** 5001

  - **Name:** `noEntitlementForOrganization`

  - **What it means:** Retrieving org entitlements failed.

  - **How to fix:** Check the `status` in the message and verify org access. See
    [Access Management](#access-management).

- **Code:** 5002

  - **Name:** `organizationAccessDenied`

  - **What it means:** You lack access to the org.

  - **How to fix:** Switch orgs or request access.

- **Code:** 5003

  - **Name:** `selectedOrganizationMismatch`

  - **What it means:** The `groupId` doesn’t match the selected org.

  - **How to fix:** Switch to the org that owns the assets.

### Dependency Manager Errors

- **Code:** 6001

  - **Name:** `downloadFileError`

  - **What it means:** A dependency download failed.

  - **How to fix:** Check network access and retry the request.

- **Code:** 6002

  - **Name:** `couldNotFindVersion`

  - **What it means:** No resolvable version in `maven-metadata.xml`.

  - **How to fix:** Confirm the dependency exists in the repository and that you have network access
    to it.

- **Code:** 6003

  - **Name:** `invalidStrategyVersion`

  - **What it means:** A dependency strategy or version config is invalid.

  - **How to fix:** Correct the strategy or version in the descriptor.

- **Code:** 6004

  - **Name:** `invalidMetadataFile`

  - **What it means:** A dependency metadata file is invalid.

  - **How to fix:** Rerun setup to refresh the cached dependency.

- **Code:** 6005

  - **Name:** `runtimeDependenciesFileNotFound`

  - **What it means:** The runtime dependency manifest is missing.

  - **How to fix:** Run `agent-network setup dependencies`.

- **Code:** 6006

  - **Name:** `invalidDependencyVersion`

  - **What it means:** A dependency version isn’t valid SemVer.

  - **How to fix:** Use SemVer (for example `2.1.3`).

### Create Command Errors

- **Code:** 7001

  - **Name:** `projectAlreadyExists`

  - **What it means:** The target project or directory already exists.

  - **How to fix:** Use a new name or directory.

- **Code:** 7002

  - **Name:** `invalidAssetVersion`

  - **What it means:** The asset version isn’t valid SemVer.

  - **How to fix:** Use SemVer (for example `0.0.0`).

- **Code:** 7003

  - **Name:** `invalidGroupId`

  - **What it means:** The `group-id` wasn’t found.

  - **How to fix:** Use a `group-id` for an org that you belong to, as listed in the message.

- **Code:** 7004

  - **Name:** `invalidProjectName`

  - **What it means:** The project name has no alphanumeric character.

  - **How to fix:** Include at least one alphanumeric character.

- **Code:** 7005

  - **Name:** `invalidAssetId`

  - **What it means:** The asset id has invalid characters.

  - **How to fix:** Use only `A-Z`, `a-z`, `0-9`, `_`, `-`.

- **Code:** 7006

  - **Name:** `missingAssetIdWithInvalidProjectName`

  - **What it means:** The project name has no alphanumerics and no asset id was given.

  - **How to fix:** Provide an explicit asset id.

- **Code:** 7007

  - **Name:** `brokerAlreadyExists`

  - **What it means:** A broker with this name already exists.

  - **How to fix:** Choose a different broker name.

- **Code:** 7008

  - **Name:** `invalidBrokerTemplate`

  - **What it means:** The broker scaffold template is missing.

  - **How to fix:** Reinstall the plugin. The installation can be corrupted.

- **Code:** 7009

  - **Name:** `unsupportedAgentNetworkVersion`

  - **What it means:** The command requires a V2 project.

  - **How to fix:** Use a V2 Agent Network project.

- **Code:** 7010

  - **Name:** `invalidAgentNetworkYaml`

  - **What it means:** `agent-network.yaml` failed to parse.

  - **How to fix:** Fix the YAML syntax error reported in the message.

- **Code:** 7011

  - **Name:** `invalidEmptyBrokerName`

  - **What it means:** The broker name has no alphanumeric character.

  - **How to fix:** Include at least one alphanumeric character.

- **Code:** 7012

  - **Name:** `invalidBrokerName`

  - **What it means:** The broker id violates the naming pattern.

  - **How to fix:** Start and end with a letter or digit. In the middle, use only letters, digits,
    `_`, `.`, or `-`.

- **Code:** 7013

  - **Name:** `invalidBrokersSection`

  - **What it means:** The `brokers` YAML section isn’t a mapping.

  - **How to fix:** Make `brokers:` a mapping of names to definitions.

- **Code:** 7014

  - **Name:** `brokerNameTooLong`

  - **What it means:** The broker id exceeds the deployment-name length limit.

  - **How to fix:** Shorten the name of the broker.

### Policy Validation Errors

- **Code:** 8001

  - **Name:** `policyVersionError`

  - **What it means:** Looking up a policy version failed.

  - **How to fix:** Verify the policy GAV. See [Exchange](#exchange).

- **Code:** 8002

  - **Name:** `policyValidationFailed`

  - **What it means:** One or more policy bindings failed validation.

  - **How to fix:** Fix the validation errors listed in the nested `cause`.

- **Code:** 8003

  - **Name:** `schemaNotFoundForAsset`

  - **What it means:** A policy config schema file is missing.

  - **How to fix:** Verify the policy asset includes its schema.

- **Code:** 8004

  - **Name:** `dependencyVersionNotFound`

  - **What it means:** A dependency version is absent from the descriptor.

  - **How to fix:** Add the dependency version to `exchange.json`.

### Local Run Errors

These errors come from `agent-network project run-local` in a local Docker Compose environment.

- **Code:** 8500

  - **Name:** `v1NotSupportedForLocalRun`

  - **What it means:** `run-local` was invoked on a V1 project.

  - **How to fix:** Only V2 projects can run locally.

- **Code:** 8501

  - **Name:** `dockerNotInstalled`

  - **What it means:** Docker isn’t installed.

  - **How to fix:** Install [Docker Desktop](https://www.docker.com/products/docker-desktop/).

- **Code:** 8502

  - **Name:** `dockerDaemonNotRunning`

  - **What it means:** The Docker daemon isn’t running.

  - **How to fix:** Start Docker Desktop and retry.

- **Code:** 8503

  - **Name:** `dockerSignInRequired`

  - **What it means:** Docker requires sign-in.

  - **How to fix:** Run `docker login` or sign in via Docker Desktop.

- **Code:** 8504

  - **Name:** `dockerImagePullFailed`

  - **What it means:** A required image failed to pull.

  - **How to fix:** Confirm that you’re signed in and have network access.

- **Code:** 8505

  - **Name:** `exchangeJsonMissingMain`

  - **What it means:** `exchange.json` has no `main` field.

  - **How to fix:** Set the `main` field to the network YAML file.

- **Code:** 8506

  - **Name:** `flexRegistrationFailed`

  - **What it means:** Flex Gateway registration generation failed.

  - **How to fix:** Read the detail in the message and retry the request.

- **Code:** 8507

  - **Name:** `policyImplementationNotFound`

  - **What it means:** No Flex implementation exists for a policy.

  - **How to fix:** Use a policy with a Flex Gateway implementation.

- **Code:** 8508

  - **Name:** `policyImplementationResolveFailed`

  - **What it means:** Resolving a policy’s Flex implementation failed.

  - **How to fix:** Read the detail and verify the policy GAV.

- **Code:** 8509

  - **Name:** `policyFetchFailed`

  - **What it means:** Fetching a policy asset failed.

  - **How to fix:** Check network and Exchange access, and then retry the request.

- **Code:** 8510

  - **Name:** `policyAssetCorrupt`

  - **What it means:** A cached policy asset is missing `exchange.json`.

  - **How to fix:** Clear the cache and fetch the asset again.

- **Code:** 8511

  - **Name:** `policyMainFileMissing`

  - **What it means:** A policy asset’s declared main file is absent.

  - **How to fix:** Verify the policy asset is complete.

- **Code:** 8512

  - **Name:** `policyDependencyMissing`

  - **What it means:** A policy dependency isn’t cached.

  - **How to fix:** Rerun the command to fetch dependencies.

- **Code:** 8513

  - **Name:** `noAvailablePort`

  - **What it means:** No free port in the scan range.

  - **How to fix:** Free a port or pass `--port` explicitly.

- **Code:** 8514

  - **Name:** `invalidPort`

  - **What it means:** The `--port` value is invalid.

  - **How to fix:** Use an integer between 1 and 65535.

- **Code:** 8515

  - **Name:** `agentGraphServiceNameCollision`

  - **What it means:** Two asset ids trim to the same Docker service name.

  - **How to fix:** Rename one asset to avoid the DNS-label collision.

- **Code:** 8516

  - **Name:** `localSecretRetrievalFailed`

  - **What it means:** A stored secret couldn’t be retrieved.

  - **How to fix:** Rerun the command without a cached value and reenter the secret.

- **Code:** 8517

  - **Name:** `unknownLlmPlatformForApiKey`

  - **What it means:** An LLM platform isn’t recognized for API-key selection.

  - **How to fix:** Use a supported platform (listed in the message).

- **Code:** 8518

  - **Name:** `undeclaredVariables`

  - **What it means:** A `${…​}` placeholder is used but not declared.

  - **How to fix:** Declare each variable under `metadata.variables` in `exchange.json`.

- **Code:** 8519

  - **Name:** `dockerAgentGraphImageMissing`

  - **What it means:** The Agent Graph image isn’t published yet.

  - **How to fix:** Use `--build-only`, which doesn’t require the image. Local deploy is unavailable
    without the image.

- **Code:** 8520

  - **Name:** `localEnvironmentNotRendered`

  - **What it means:** A local-deploy command ran before `run-local`.

  - **How to fix:** Run `agent-network project run-local` first.

- **Code:** 8521

  - **Name:** `secretEnvVarNameCollision`

  - **What it means:** Two secret variables normalize to the same environment variable name.

  - **How to fix:** Rename one to avoid the collision.

- **Code:** 8522

  - **Name:** `secretRouteSegment`

  - **What it means:** A secret variable is used in a route path segment.

  - **How to fix:** Use a non-secret variable for the path.

- **Code:** 8523

  - **Name:** `secretUpstreamAddress`

  - **What it means:** A secret variable is used in an upstream URL.

  - **How to fix:** Use a non-secret variable, or supply the credential via a policy.

- **Code:** 8524

  - **Name:** `flexCrdNameCollision`

  - **What it means:** Two Flex Gateway CRD (Custom Resource Definition) ids collapse to the same
    filename.

  - **How to fix:** Rename one of the colliding ids.

- **Code:** 8525

  - **Name:** `connectionPolicyResolverRequired`

  - **What it means:** **Internal:** local render lacks a connection policy resolver.

  - **How to fix:** Rebuild and rerun. If the error persists, then report it with the `requestId`.

- **Code:** 8526

  - **Name:** `apiInstancePolicyResolverRequired`

  - **What it means:** **Internal:** local render lacks an API-instance policy resolver.

  - **How to fix:** Rebuild and rerun. If the error persists, then report it with the `requestId`.

- **Code:** 8527

  - **Name:** `localExchangeDestinationUnsafe`

  - **What it means:** A local Exchange asset has an empty or unsafe destination.

  - **How to fix:** Rename the asset or dependency to a safe id.

- **Code:** 8528

  - **Name:** `localExchangeDestinationCollision`

  - **What it means:** Two local Exchange assets map to the same destination.

  - **How to fix:** Rename an asset or use a distinct dependency.

- **Code:** 8529

  - **Name:** `malformedBuildOutputAssetKeyMismatch`

  - **What it means:** **Internal:** build-output asset map key mismatch.

  - **How to fix:** Rebuild the project. If the error persists, then report it with the `requestId`.

- **Code:** 8530

  - **Name:** `malformedBuildOutputMissingComponentVersion`

  - **What it means:** **Internal:** an owned asset has no component version.

  - **How to fix:** Rebuild the project. If the error persists, then report it with the `requestId`.

- **Code:** 8531

  - **Name:** `malformedBuildOutputDuplicateAssetIdentity`

  - **What it means:** **Internal:** duplicate owned-asset identity.

  - **How to fix:** Rebuild the project. If the error persists, then report it with the `requestId`.

- **Code:** 8532

  - **Name:** `malformedBuildOutputEmptyDestination`

  - **What it means:** **Internal:** an owned asset has an empty destination.

  - **How to fix:** Rename the asset and rebuild.

- **Code:** 8533

  - **Name:** `malformedBuildOutputDestinationCollision`

  - **What it means:** **Internal:** two owned assets map to the same destination.

  - **How to fix:** Rename an asset and rebuild.

- **Code:** 8534

  - **Name:** `localRenderAggregateFailure`

  - **What it means:** One or more local-render tasks failed. This error consolidates the failures.

  - **How to fix:** Read the logs for each sub-failure.

### Access Management Errors

- **Code:** 10001

  - **Name:** `credentialsValidationsError`

  - **What it means:** Credential validation failed.

  - **How to fix:** Reauthenticate and verify your credentials. See
    [Access Management](#access-management).

### Gateway Flag and CLI-Argument Errors

- **Code:** 11001

  - **Name:** `gatewayFlagsMutuallyExclusive`

  - **What it means:** `--gateway` was combined with `--ingress-gw`/`--egress-gw`.

  - **How to fix:** Use `--gateway` alone, or `--ingress-gw [--egress-gw]`.

- **Code:** 11002

  - **Name:** `egressGwRequiresIngress`

  - **What it means:** `--egress-gw` was passed without `--ingress-gw`.

  - **How to fix:** Pass both, or use `--gateway`.

- **Code:** 11003

  - **Name:** `gatewayFlagRequired`

  - **What it means:** No gateway flag was supplied.

  - **How to fix:** Pass `--gateway` or `--ingress-gw [--egress-gw]`.

- **Code:** 11004

  - **Name:** `separateGatewayModeNotSupportedInSharedSpace`

  - **What it means:** Separate-gateway mode was used with a Shared Space.

  - **How to fix:** Use `--gateway`, or pass a Private Space to `--target-space`.

- **Code:** 11005

  - **Name:** `singleGatewayTargetSpaceMismatch`

  - **What it means:** `--target-space` conflicts with the gateway’s target space.

  - **How to fix:** Omit `--target-space`, or make it match the gateway.

- **Code:** 11006

  - **Name:** `forceFlagRequiredWithJson`

  - **What it means:** `--json` was used without `--force`.

  - **How to fix:** Add `--force` to skip interactive prompts.

## Dependent Services: Status Codes and Common Issues

The CLI orchestrates several Anypoint Platform services. When one of them returns an HTTP error, it
surfaces in the `cause.response.status` field in the CLI error output. This part explains the common
failures per service.

### The Retry and Timeout Engine

Before diagnosing a transient-looking failure, know that the CLI already retries automatically:

- **Retries:** Every HTTP `429` and `5xx` response, plus network errors (`ECONNRESET`, `ETIMEDOUT`,
  `ENETUNREACH`, `EAI_AGAIN`).

- **Attempts:** Up to two, with a 30-second backoff. The CLI honors the server’s `Retry-After`
  header and limits the backoff to 30 seconds.

- **Deletes:** a `404` on a retry is treated as success (the resource was already deleted).

- **Non-idempotent writes:** The CLI also retries `POST`, `PUT`, and `PATCH` requests after `5xx` or
  `429` responses. A retry can create a duplicate resource on a non-idempotent endpoint.

- **Timeouts:** Each request defaults to 60 seconds (`--request-timeout`). The whole command
  defaults to 15 minutes (`--process-timeout`).

If a command still fails after these retries, treat the failure as deterministic rather than
transient unless a service entry says otherwise.

### Exchange

Backs `publish`, `unpublish`, and asset lookups during build and deploy operations.

- **Operation:** Publish asset

  - **Status / symptom:** `409`, asset already exists

  - **Likely cause:** An asset with this id exists with a different type or owner.

  - **Fix:** See codes 2005 and 2006. Use a new id or version, or reconcile ownership.

- **Operation:** Delete an asset during unpublish or undeploy

  - **Status / symptom:** **`403 Forbidden` (surfaces as code 2010)**

  - **Likely cause:** A known Exchange platform issue.

  - **Fix:** Retry later. If the error persists, then open a support case with your `requestId`.
    This known platform issue can’t be resolved locally.

- **Operation:** Delete asset version

  - **Status / symptom:** `404`

  - **Likely cause:** The asset is already gone.

  - **Fix:** No action. The CLI treats the response as a success.

- **Operation:** Fetch policy or asset

  - **Status / symptom:** `5xx` or `429`

  - **Likely cause:** Transient platform load.

  - **Fix:** The CLI retries automatically. If the error persists, then retry later.

- **Operation:** Fetch policy Flex bundle

  - **Status / symptom:** Missing zip classifier (`run-local` only)

  - **Likely cause:** Some policy versions (for example
    `user-context-propagation-policy-flex@1.0.0`) were published without a zip classifier.

  - **Fix:** This policy version is missing a required file in Exchange. Open a support case to
    request that MuleSoft republish it with a zip classifier. Production `deploy` is unaffected.

### API Manager

Backs API-instance and connection creation or patching, policy application, and instance deletion
during deploy and undeploy operations.

- **Operation:** Create API instance or connection

  - **Status or symptom:** **`409 Conflict` (code 3001)**

  - **Likely cause:** A stale or orphaned instance from a prior partial deploy, or a name collision.

  - **Fix:** Check API Manager for an existing instance with that name. Delete or reuse the
    instance, and then redeploy.

- **Operation:** Patch API instance

  - **Status or symptom:** non-2xx (code 3010)

  - **Likely cause:** The target instance changed or was removed.

  - **Fix:** Read the `cause` and verify that the instance still exists.

- **Operation:** Apply policies

  - **Status or symptom:** failure (code 3047)

  - **Likely cause:** A policy GAV resolution or org entitlement problem.

  - **Fix:** Verify the policy GAV and confirm that your org is entitled to the policy.

- **Operation:** Fetch policy metadata

  - **Status or symptom:** empty or invalid (code 3031)

  - **Likely cause:** A transient error or a bad policy GAV.

  - **Fix:** Retry the request. If the error persists, then verify the policy GAV.

- **Operation:** Delete instance (undeploy)

  - **Status or symptom:** `404`

  - **Likely cause:** The instance was already removed.

  - **Fix:** No action. The CLI treats the response as a success.

### Runtime Fabric and Application Manager

Backs Mule application and agent network deployments and undeployments.

- **Operation:** Poll deployment status

  - **Status or symptom:** "Deployment status request returned status N"

  - **Likely cause:** A non-retryable HTTP error, or retries exhausted.

  - **Fix:** Read the status and check the deployment in Runtime Manager.

- **Operation:** Deploy request

  - **Status or symptom:** request timeout (code 3017)

  - **Likely cause:** The request exceeded `--request-timeout`.

  - **Fix:** Retry the request and increase `--request-timeout`.

- **Operation:** Whole command

  - **Status or symptom:** command timeout (code 3018)

  - **Likely cause:** The org can lack sufficient resources, or the deploy can be slow.

  - **Fix:** Review org resource allocation and increase `--process-timeout`. Check `steps` for
    progress.

- **Operation:** Deploy broker group or Agent Graph

  - **Status or symptom:** failure (codes 3008 and 3028)

  - **Likely cause:** Underlying AMC error.

  - **Fix:** Read the logs and nested `cause`.

- **Operation:** Undeploy by name

  - **Status or symptom:** `404`

  - **Likely cause:** Already removed.

  - **Fix:** No action. The CLI treats the response as a success.

### Gateway Manager

Backs `agent-network setup gateways` for ingress and egress Flex Gateway provisioning.

- **Operation:** Create gateway

  - **Status or symptom:** name collision (code 4013)

  - **Likely cause:** The environment already contains a gateway with this name.

  - **Fix:** Choose a different name.

- **Operation:** Create gateway

  - **Status or symptom:** insufficient resources (code 4014)

  - **Likely cause:** The org’s gateway quota is exhausted.

  - **Fix:** Delete an unused gateway or increase org limits.

- **Operation:** Resolve domains

  - **Status or symptom:** no domains (codes 4001 and 4015)

  - **Likely cause:** No private network in the target space.

  - **Fix:** Create a private network for the target space first.

- **Operation:** Set up ingress or egress

  - **Status or symptom:** non-success status (codes 4003 and 4005)

  - **Likely cause:** Downstream gateway or API Manager error.

  - **Fix:** Read the `status` and response in the message, and then retry the request.

- **Operation:** List gateways, versions, or metadata

  - **Status or symptom:** non-2xx (codes 4008–4010)

  - **Likely cause:** A transient or access issue.

  - **Fix:** Retry the request and verify org and environment access.

### Access Management

Backs org, entitlement, and credential validation during build, publish, and deploy operations.

- **Operation:** Retrieve entitlements

  - **Status or symptom:** non-2xx (code 5001)

  - **Likely cause:** A transient error or a missing org entitlement.

  - **Fix:** Retry the request and verify that the org is entitled to Agent Fabric.

- **Operation:** Org access check

  - **Status or symptom:** denied (code 5002)

  - **Likely cause:** You lack access to the org that owns the `groupId`.

  - **Fix:** Switch orgs or request access.

- **Operation:** Selected org check

  - **Status or symptom:** mismatch (code 5003)

  - **Likely cause:** The `groupId` doesn’t match your selected org or business group.

  - **Fix:** Switch to the org that owns the assets.

- **Operation:** Credential validation

  - **Status or symptom:** failure (code 10001)

  - **Likely cause:** Expired or invalid credentials.

  - **Fix:** Reauthenticate.

### Known Platform Issues Versus Plugin Issues

- **Item:** Exchange unpublish or undeploy `403`

  - **Status or code:** 403 → code 2010

  - **Classification:** **Known Exchange platform issue.** Retry later. If the error persists, then
    open a support case with your `requestId`.

- **Item:** `user-context-propagation-policy-flex@1.0.0` missing zip classifier

  - **Status or code:** `run-local` fetch failure

  - **Classification:** **Missing file in Exchange.** Open a support case to request a republish.
    Production `deploy` is unaffected.

- **Item:** Agent Graph Docker image not published

  - **Status or code:** code 8519

  - **Classification:** **External blocker.** Use `--build-only` because the image isn’t published.

- **Item:** `409` when creating an API instance or connection

  - **Status or code:** 409 → code 3001

  - **Classification:** **Environment state.** The cause is usually an orphaned instance. Check API
    Manager and delete or reuse the instance.

- **Item:** API Manager or AMC `5xx`, `429`, or timeouts

  - **Status or code:** 429, 5xx

  - **Classification:** **Transient platform load.** The CLI already retries the request.

- **Item:** Gateway setup non-2xx relays

  - **Status or code:** codes 4003–4010

  - **Classification:** **Downstream relay.** The CLI passes through the status that the gateway or
    API Manager service returns.

<!-- document id=8b286ad32bf0b3b6542e163fd010dc8c45d28b6241cc54c7703752e6d22e7fb4 url=/mulesoft/current/en-us/agent-network/1.0/af-troubleshoot-agent-networks.md -->

---
product: Building Agent Networks
version: 1.0
---

# Troubleshoot Agent Networks

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

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
> [view metrics, logs, and traces](https://docs.mulesoft.com/agent-visualizer/troubleshoot-agent-network) 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:

1.  In Runtime Manager, navigate to the application for the agent broker.

2.  Choose one of these options to configure logging:

    - [CloudHub 2.0](https://docs.mulesoft.com/cloudhub-2/ch2-manage-app-logs#configure-log-levels-and-categories)

    - [Runtime Fabric](https://docs.mulesoft.com/runtime-fabric/latest/deploy-to-runtime-fabric#configure-logging-and-log-levels)

3.  Set the log level to Debug for these classes:

    - `com.mulesoft.modules.agent.broker` (For agent broker)

    - `INSECURE-LOGGING` (For content that can potentially contain sensitive information, such as
      LLM reasoning, and inputs and outputs from agents and assets defined in `tools` and `links`)

> [!IMPORTANT] `INSECURE-LOGGING` is very likely to contain sensitive information, such as
> personally identifiable information (PII). Make sure to disable it after troubleshooting is
> completed.

## Enable Message Logging Policy

Edit `agent-network.yaml` to set message logging for MCP servers and agents.

Message logging uses the
[Omni Gateway Message Logging policy](https://docs.mulesoft.com/gateway/latest/policies-included-message-logging). In
the `connection` section of the agent or MCP server instance you want to log, add the following
logging policy inside `policies`:

```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 [Get Started with Agent Networks](https://docs.mulesoft.com/agent-network/1.0/af-get-started).

### 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,
[enable the message logging policy](#enable-message-logging) on the LLM instance, and then review
the logs to determine the cause of the error.

### Error: "HTTP error 404: Agent card not found at /.well-known/agent-card.json"

You can encounter this error in two different scenarios:

1.  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](https://ping-id-agent-url/pingid/.well-known/agent-card.json)`.

2.  The A2A agent is not configured to use A2A protocol version 0.3.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 0.3.0.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=46bea95214c84b45ccf2997a3c110afb81486165b6eb8261ab12456aa1d0e009 url=/mulesoft/current/en-us/agent-network/latest/af-troubleshoot-agent-networks.md -->

---
product: Building Agent Networks
version: 2.0
is-latest-version: true
---

# Troubleshoot Agent Networks

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

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.

For Anypoint CLI Agent Fabric plugin errors, see
[Troubleshoot Agent Fabric CLI Errors](https://docs.mulesoft.com/agent-network/latest/af-troubleshoot-errors).

> [!NOTE] Use Agent Visualizer to
> [view metrics, logs, and traces](https://docs.mulesoft.com/agent-visualizer/troubleshoot-agent-network) 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.

Agent brokers provide two levels of logging detail:

- **INFO**: Logs node transitions, MCP tool discovery, agent card retrieval, and related operational
  events. INFO-level logs don’t use the `INSECURE-LOGGING` level.

- **DEBUG**: Logs LLM reasoning, LLM input and output, tools invoked, and all external calls made by
  the broker. All DEBUG-level logs use the `INSECURE-LOGGING` level.

To enable logging:

1.  In Runtime Manager, navigate to the application for the agent broker.

2.  Choose one of these options to configure logging:

    - [CloudHub 2.0](https://docs.mulesoft.com/cloudhub-2/ch2-manage-app-logs#configure-log-levels-and-categories)

    - [Runtime Fabric](https://docs.mulesoft.com/runtime-fabric/latest/deploy-to-runtime-fabric#configure-logging-and-log-levels)

3.  To view operational logs, set the log level to `INFO`.

4.  To view detailed LLM and tool execution logs, set the log level for `INSECURE-LOGGING` to
    `DEBUG`.

> [!IMPORTANT] `INSECURE-LOGGING` logs content that can contain sensitive information, such as LLM
> reasoning, and inputs and outputs from agents and assets defined in your agent network. This
> content is very likely to contain personally identifiable information (PII). Disable
> `INSECURE-LOGGING` after you finish troubleshooting.

## Enable Message Logging Policy

Edit `agent-network.yaml` to set message logging for MCP servers and agents.

Message logging uses the
[Omni Gateway Message Logging policy](https://docs.mulesoft.com/gateway/latest/policies-included-message-logging). In
the `connection` section of the agent or MCP server instance you want to log, add this logging
policy inside `policies`:

```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: Linting Errors in Agent Script File

If you see linting errors in your `.agent` file in VS Code, you likely have the Agentforce DX
extension pack installed, and it’s conflicting with Anypoint Code Builder. This extension pack
includes a dependency on the Agent Script extension that conflicts with the Agent Script extension
built into Anypoint Code Builder.

To resolve this conflict, uninstall the Agentforce DX extension pack from VS Code and restart the
IDE. Anypoint Code Builder already includes all Agent Script functionality, so you don’t need a
separate extension.

### 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 [Get Started with Agent Networks](https://docs.mulesoft.com/agent-network/latest/af-get-started).

### 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:

1.  Build

2.  Publish

3.  Deploy

### Error: "Asset belongs to another project" (Error 2006)

If the publish command fails with this error (code `2006`), an asset in your project has the same
name as an asset that belongs to a different project in the same organization. Asset names must be
unique across all projects in an org, and you can’t reuse an asset name that another project already
owns.

To resolve this conflict:

- In `agent-network.yaml`, rename the conflicting asset to a unique name.

- Check the other project referenced in the error to verify which assets it owns. If you own the
  conflicting project, remove or rename the asset in that project before you republish.

### 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.

### Issue: Broker Cannot Reach Downstream Agents (Last-Mile Security Enabled)

If your broker deploys successfully and answers general questions, but fails whenever it routes a
request to a downstream agent or MCP server, check if **Last-Mile Security** is enabled on the Omni
Gateway used for outbound (egress) traffic.

Agent networks route outbound traffic directly to the pod through the egress gateway (port 8082),
which bypasses the ingress-to-pod hop that Last-Mile Security protects. As a result, agent networks
are not compatible with Last-Mile Security on the egress gateway.

To resolve:

- In Runtime Manager, go to **Omni Gateways** > <the gateway in use> > **Settings**, and disable
  **Last-Mile Security**.

- If Last-Mile Security is required for other applications on that gateway, deploy your agent
  network to a separate egress gateway that has Last-Mile Security disabled.

> [!NOTE] This is a behavior change from Agent Network version 1.0, which routed outbound traffic
> through the CloudHub ingress gateway (port 8081) and was therefore unaffected by Last-Mile
> Security. A gateway that worked under version 1.0 with Last-Mile Security enabled will fail under
> version 2.0.

### 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,
[enable the message logging policy](#enable-message-logging) 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 the LLM 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: Runtime System Limit Exceeded

If your agent network encounters errors related to exceeding iteration limits, tool call limits, or
state size limits, you can configure runtime system limits in your `exchange.json` file. These
variables control graph execution behavior and help prevent infinite loops or excessive resource
usage.

Common limit-related errors include:

- Maximum handoff iterations exceeded

- Maximum reasoning iterations exceeded

- Maximum tool call count exceeded

- State size limit exceeded

To adjust these limits, add runtime system limit variables to the `metadata.variables` section of
your `exchange.json` file. For detailed information about configuring these limits, see
[Runtime System Limits Configuration](https://docs.mulesoft.com/agent-network/latest/af-agent-network-yaml-reference#runtime-system-limits).

### Error: "HTTP error 404: Agent card not found at /.well-known/agent-card.json"

You can encounter this error in two different scenarios:

1.  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](https://ping-id-agent-url/pingid/.well-known/agent-card.json)`.

2.  The A2A agent doesn’t 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.

### Error: "401 Unauthorized" When a Broker Calls an Agent

If the broker returns **401 Unauthorized** error when it routes a request to a downstream A2A agent,
the A2A protocol version declared for that agent in `agent-network.yaml` might not match the agent’s
actual runtime protocol version.

When the declared version doesn’t match the real version, the platform applies the wrong A2A Agent
Card policy. That policy doesn’t rewrite the agent card’s `url` field to the egress proxy URL, so
the A2A SDK posts `send_message` directly to the external gateway URL and bypasses the egress proxy.
Because the egress proxy is what injects the `client_id` and `client_secret` headers required by the
Client-ID-Enforcement policy, the request arrives without credentials and is rejected with a `401`
error.

To resolve this error:

1.  Confirm the agent’s real A2A protocol version. Request the agent card in a browser or Postman by
    appending `.well-known/agent-card.json` to the connection URL, and check the `protocolVersion`
    field.

2.  Update the connection definition in `agent-network.yaml` so the declared protocol version
    matches the agent’s real version.

3.  Rebuild, republish, and redeploy the agent network.

> [!NOTE] A protocol version mismatch surfaces as an authentication (401) error, not as a version
> error. Verify the protocol version whenever a downstream agent call fails with `401` even if
> you’ve correctly configured the the egress auth policy.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)

<!-- document id=a4a80850d1dedf02bb91b3ea41026c5ab8b0d476469dce8ef11e1f8e6969fd7d url=/mulesoft/current/en-us/agent-network/latest/af-a2a-agent-network.md -->

---
product: Building Agent Networks
version: 2.0
is-latest-version: true
---

# Using A2A Protocol in Agent Networks

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

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](https://a2a-protocol.org/latest).

Review the following about using A2A interactions in agent networks.

## Context and Task ID Scoping

In a multi-broker network, each broker generates its own `contextId` and `taskId` for the requests
it receives. 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`.

When a client sends a request to Broker\_1, 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] Non-broker agents don’t have 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 maintains a mapping between its own upstream `taskId` (used to respond to its client)
  and the downstream `taskId` it tracks with Broker\_2.

- If Broker\_2 requires more information (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.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Relationship</th><th>Role</th><th>Logic</th></tr></thead><tbody><tr><td><p>Client → Broker_1</p></td><td><p>Broker_1 is server</p></td><td><p>Generates <code>contextId_1</code> and <code>taskId_1</code> for the client.</p></td></tr><tr><td><p>Agent A → Broker_2</p></td><td><p>Broker_2 is server</p></td><td><p>Generates <code>contextId_2</code> and <code>taskId_2</code> for Broker_1.</p></td></tr><tr><td><p>Network broker</p></td><td><p>Broker_1</p></td><td><p>Broker_1 maps <code>contextId_1</code> and <code>taskId_1</code> to <code>contextId_2</code> and <code>taskId_2</code>.</p></td></tr></tbody></table>

For more information, see
[Life of a Task - Group Related Interactions](https://a2a-protocol.org/latest/topics/life-of-a-task/).

## Streaming with Server-Sent Events (SSE)

Agent network brokers support serving streaming responses to clients using Server-Sent Events (SSE).
A client can call a broker with streaming enabled and receive incremental updates as the broker
processes the request.

However, brokers don’t use streaming when communicating with downstream brokers or agents. Outbound
requests from a broker to other brokers or agents use standard non-streaming communication.

## How Agent Brokers Handle Concurrent Requests

In an agent network, most of a request's time is spent waiting on an LLM, an MCP tool, or another
agent to respond. Rather than holding a thread idle during that wait, agent brokers use a
non-blocking execution engine that frees the broker to make progress on other in-flight requests.
Each request resumes as soon as its response arrives. As a result, a broker processes many requests
concurrently rather than one at a time.

## Creating Conversational Memory with `contextId`

Configure your broker to remember earlier turns in a conversation by reusing a `contextId` across
requests. When a caller reuses a `contextId`, the broker seeds each new task with the prior
conversation history so the agent remembers what was said earlier.

To enable conversational memory, you need an agent network with: \* A broker configured with an
ingress authentication policy that resolves a stable user identity \* A client that supports the A2A
v1.0 wire contract

### How `contextId` Works

A `contextId` identifies one logical conversation. A `taskId` identifies one turn within that
conversation. Every turn produces a new `taskId`, but all turns that share a `contextId` belong to
the same conversation.

Request 1 (no contextId) ──► broker mints contextId=C, taskId=T1 ──► returns C Request 2
(contextId=C) ──► new taskId=T2, seeded with T1's conversation Request 3 (contextId=C) ──► new
taskId=T3, seeded with T1+T2

> [!IMPORTANT] Reuse the `contextId`, not the `taskId`. The prior task is already in a terminal
> state (`TASK_STATE_COMPLETED`). Sending a message to a completed `taskId` returns an error.

### Requirements

All three requirements must be met for conversational memory to work.

1.  The broker resolves a stable user identity for the caller.

2.  The caller reuses the `contextId` across turns.

3.  The caller sends the correct A2A wire contract.

#### User Identity

Conversational memory is scoped to a user identity derived from authentication at the broker’s
ingress. Configure the broker with an ingress authentication policy that yields this identity.
Without this policy, tasks are created without an owner and memory doesn’t engage.

The same authenticated caller must be present on every request in a conversation. That identity is
the key the broker’s memory is stored under.

##### Example: Client ID Enforcement with User Context Propagation

A common way to produce this identity is a pair of inbound API Manager policies applied to the
broker:

1.  Client ID enforcement authenticates the caller’s `client_id` and `client_secret`.

2.  User context propagation derives the user identity from the authenticated client, using the
    expression `#[authentication.clientId]`.

Apply client ID enforcement before user context propagation. User context propagation reads
`#[authentication.clientId]`, which is populated only after Client ID enforcement authenticates the
request. If the policies are reversed, the identity resolves empty, tasks are created without an
owner, and conversational memory does not engage. No error is returned to the caller; a `ListTasks`
request for the context returns an empty result. Use reorder policies on the broker’s inbound policy
list to set the order.

Other authentication schemes can supply the user identity as well. This ordering requirement is
specific to the Client ID enforcement and user context propagation pairing.

### A2A Wire Contract

The following values must be exact in every request:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Requirement</th><th>Value</th><th>Error if incorrect</th></tr></thead><tbody><tr><td><p>Version header</p></td><td><p><code>A2A-Version: 1.0</code></p></td><td><p><code>-32009 Unsupported A2A version: missing</code></p></td></tr><tr><td><p>Method</p></td><td><p><code>SendMessage</code></p></td><td><p><code>-32601 Method not found</code></p></td></tr><tr><td><p>Role</p></td><td><p><code>ROLE_USER</code> (enum, not <code>"user"</code>)</p></td><td><p><code>-32602 Invalid enum value user</code></p></td></tr></tbody></table>

### Starting a Conversation

To start a new conversation, send a request without a `contextId`. The broker generates and returns
a `contextId` in the response.

```bash
curl -s -X POST "https://<host>/<broker-path>/" \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 1.0" \
  <auth headers for your ingress policy> \
  -d '{
    "jsonrpc": "2.0", "id": "1", "method": "SendMessage",
    "params": { "message": {
      "role": "ROLE_USER",
      "parts": [{ "text": "My favorite fruit is DRAGONFRUIT and my order number is ORD-4521. Please remember both." }],
      "messageId": "g1"
    }}
  }'
```

The response includes a `contextId` in `result.task.contextId`. Save this value for subsequent
requests:

```json
{
  "result": {
    "task": {
      "id": "…T1…",
      "contextId": "c740ccdf-b70a-4e81-b9e4-395845b4c6ab",
      "status": {
        "state": "TASK_STATE_COMPLETED",
        "message": {
          "parts": [
            {
              "text": "Acknowledged — I have recorded your favorite fruit (DRAGONFRUIT) and your order number (ORD-4521)…"
            }
          ]
        }
      }
    }
  }
}
```

### Continuing a Conversation

To continue an existing conversation, include the `contextId` from the first turn in subsequent
requests:

```bash
curl -s -X POST "https://<host>/<broker-path>/" \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 1.0" \
  <auth headers for your ingress policy> \
  -d '{
    "jsonrpc": "2.0", "id": "2", "method": "SendMessage",
    "params": { "message": {
      "role": "ROLE_USER",
      "contextId": "c740ccdf-b70a-4e81-b9e4-395845b4c6ab",
      "parts": [{ "text": "What is my favorite fruit and my order number?" }],
      "messageId": "g2"
    }}
  }'
```

The broker recalls facts from prior turns:

```json
{
  "result": {
    "task": {
      "contextId": "c740ccdf-b70a-4e81-b9e4-395845b4c6ab",
      "status": {
        "message": { "parts": [{ "text": "Favorite fruit: DRAGONFRUIT. Order number: ORD-4521." }] }
      }
    }
  }
}
```

### Referencing Work from Another Conversation

Reusing `contextId` handles continuity within one conversation. To bring in work from a different
conversation, add `referenceTaskIds` to the message. This field accepts a list of prior task IDs
whose conversation is seeded into the current turn.

```json
{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "SendMessage",
  "params": {
    "message": {
      "role": "ROLE_USER",
      "contextId": "<this-conversation>",
      "referenceTaskIds": ["<task-id-from-another-conversation>"],
      "parts": [{ "text": "Reuse the itinerary from my earlier booking." }],
      "messageId": "g3"
    }
  }
}
```

When using `referenceTaskIds`:

- Each referenced task must belong to the same authenticated user (`userId`). If a referenced task
  is missing or owned by another user, the request is rejected.

- Referencing a task already part of the current conversation doesn’t duplicate its content.

- Use `referenceTaskIds` only to cross conversation boundaries. Same-conversation continuity comes
  from reusing the `contextId`.

### Memory Scope and Limits

Conversational memory includes user and assistant messages (the text exchanged between the user and
the agent)

Conversational memory does not include tool calls and tool results. The agent remembers what was
discussed, not the intermediate tool invocations it made.

Additional limits include:

- Memory is capped at approximately the most recent 200 messages per conversation. Older turns roll
  off.

- Retention is bounded by the configured TTL. After the TTL expires, recall stops.

- Memory is shared across broker instances. Continuity does not depend on requests landing on the
  same replica, so sticky sessions or session affinity on your load balancer are not required.

#### Orchestrator Brokers

If a broker calls downstream A2A agents while handling a conversation, it keeps those downstream
conversations continuous automatically. For a given inbound `contextId`, the broker reuses the same
downstream conversation with each child agent across turns so the downstream agents recover their
own context on follow-ups. No extra caller action is required beyond reusing the inbound
`contextId`.

### Configuring Memory Retention

Set the following variable in `exchange.json` under `metadata.variables` to control how long
conversational memory persists:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Variable</th><th>Description</th><th>Default</th><th>Notes</th></tr></thead><tbody><tr><td><p><code>OBJECT_STORE_DEFAULT_TTL_MS</code></p></td><td><p>How long a <code>contextId</code> memory persists</p></td><td><p>24 hours (<code>86400000</code>)</p></td><td><p>Maximum 30 days (<code>2592000000</code>). After the TTL expires, recall stops.</p></td></tr></tbody></table>

### Verifying Your Setup

To confirm the ingress policy is active, send an unauthenticated request. A `401` response confirms
that identity is required:

```bash
curl -s -o /dev/null -w "%{http_code}\n" -X POST "https://<host>/<broker-path>/" \
  -H "Content-Type: application/json" -H "A2A-Version: 1.0" \
  -d '{"jsonrpc":"2.0","id":"0","method":"SendMessage","params":{"message":{"role":"ROLE_USER","parts":[{"text":"ping"}],"messageId":"p0"}}}'
```

After completing your first turn, use `ListTasks` to verify that memory is active. An empty result
means no user identity was resolved. If you use Client ID enforcement with user context propagation,
confirm that the policies are applied in that order:

```bash
curl -s -X POST "https://<host>/<broker-path>/" \
  -H "Content-Type: application/json" -H "A2A-Version: 1.0" \
  <auth headers for your ingress policy> \
  -d '{"jsonrpc":"2.0","id":"l","method":"ListTasks","params":{"contextId":"<contextId>"}}'
```

## See Also

- [Building Agent Networks for Agent Fabric](https://docs.mulesoft.com/agent-network/latest/af-agent-networks)

- [Agent Network 2.0 Project File Reference](https://docs.mulesoft.com/agent-network/latest/af-project-files)

- [A2A Protocol Specification](https://a2a-protocol.org/latest)