Contact Us 1-800-596-4880

Reference: Agent Network Project Files

Your agent network project contains two primary configuration files: agent-network.yaml and exchange.json.

Basic Concepts

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

Exchange.Json

All agent network projects also have an exchange.json file. This file contains asset metadata available in Anypoint Exchange after publishing your agent network assets.

File Elements

Exchange.Json Elements

Here’s an example file. These key-value pairs are important for your agent network configuration.

  • groupId: The ID of the Anypoint business group that owns your agent network and all of the assets derived from it.

  • assetId: Identifies the agent network project.

  • dependencies: Existing assets that this network needs to reference.

  • variables: Nested in the metadata section, it defines all the variables whose values shouldn’t be hardcoded in the agent network YAML file. The user must be prompted for those 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 of the assets derived from it share the same groupId (business group) defined in exchange.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
        }
      }
    }
  }
}

Relationship to the Ref Element in Agent-Network.Yaml

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 (agent, MCP server, LLM provider, etc.). 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.

Let’s see an example:

     links:
        - agent:
            ref:
              name: hr-agent

The above snippet 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.

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

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

Agent-Network.Yaml Elements

Brokers

The brokers 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 leverage to accomplish tasks. The broker name is used as the assetId in exchange.json. The groupId defaults to the associated business group value used in exchange.json.

Card

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

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

The spec 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 the agent network is defined.

spec:
  llm:                            # LLM provider reference
  instructions:                   # Custom instructions
  maxNumberOfLoops: 25            # Max task steps (default: 25)
  maxConsecutiveErrors: 3         # Max recovery attempts
  tools: [...]                    # Available tools, including MCP servers
  links: [...]                    # Connected agents
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.

When specifying an LLM model, it must support structured responses in JSON format. For example, a gpt4.1 model is supported; a gpt4 model isn’t.

  llm:                              # LLM provider reference
    ref:
      name: my-openAI               # Exchange asset ID of this LLM provider. 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.
    configuration:
      model: gpt-5-mini
Instructions (optional)

Provide optional instructions that are specific to this broker. These instructions often focus on business-oriented concerns. For example, here’s instructions for an employee onboarding broker.

Example 1

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.
  - Since this a long running task, send a Slack update using tool SlackMcpServer.send_status_update to communicate the status of actions taken so far. It should be a human-readable summary. For example: {
  {
  "message": "HR and CRM onboarding completed. Working on next steps...",
  "contextId": "<fetch-the-context-id-from-input>"
  }
  - Request employee laptop: Submit a laptop request in Zendesk.
  - Request employee badge: Initiate the employee badge request.
  - Send a Slack update using tool SlackMcpServer.send_status_update to communicate the status of actions taken so far. It should be a human-readable summary. For example: {
  {
  "message": "Zendesk laptop and badge onboarding completed. Working on next steps...",
  "contextId": "<fetch-the-context-id-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, not just the final step. Format it in 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.

Example 2

     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 need to provide instructions like "split the prompt into tasks", or "select the best tool". The broker does that on its own. These instructions are only necessary for describing specific business processes.

While the instructions section is optional, it improves broker outcomes if you include as much detail about your business process as possible.

This section is the most important part of the entire specification. The links section defines the agents that are available to this broker. Essentially, the links section is where the agent network is defined. 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.

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.
  - 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 leads to drops in agent network accuracy and determinism.

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

Links Example

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
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 (Model Context Protocol) server.

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
  - mcp:
      ref:
        name: slack-mcp
      allowed:
        - SlackMcpServer.send_status_update

By default, the broker has access to all the tools available on the MCP server. However, the 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.

Policies

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

Policies can be applied at the broker or at the connection. Reference the policy definition and apply the configuration that wants to be set.

When you add governance policies to your project, those policies persist between deployments. However, if you add governance policies at run-time, those policies won’t persist.

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
Error Handling

Error scenarios can be handled through these attributes.

Name

Description

Type

Default value

maxNumberOfLoops

The maximum number of steps that a task can take. Useful for keeping orchestrations from running too long and consuming too many tokens.

Integer

25

maxConsecutiveErrors

The maximum number of errors that the broker attempts to recover from before returning a failed status.

Integer

3

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.

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

McpServers

This section lists the MCP servers in your agent network. These servers can be used to obtain context relevant to the information and generate notifications. If you want to apply governance to an MCP server, it must be in your agent network or published to Anypoint Exchange as an asset.

MCP StreamableHttp and SSE transports are supported. StreamableHttp is recommended.

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 whole, filtering at the group level.

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

LlmProviders

Configure the LLMs the brokers use for reasoning. For supported LLMs, see Building Agent Networks for Agent Fabric.

llmProviders:
  my-openAI:                            # Provider reference name
    label: OpenAI Provider
    description: OpenAI LLM provider for incident management
    metadata:
	    platform: OpenAI

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.

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: ${}
      configuration:
        apiKey: ${openai.apiKey}

  talent-pool-mcp:
    kind: mcp
    ref:
      name: talent-pool-mcp
    spec:
      url: https://talent-pool-mcp-server-inkbh1.paga8m.usa-w1.cloudhub.io/

  slack-mcp:
    kind: mcp
    ref:
      name: slack-mcp
    spec:
      url: https://slack-mcp-server-inkbh1.paga8m.usa-w1.cloudhub.io/
Connection Resolution

Connection resolution is done at deployment time. The connection reference can be done explicitly or implicitly.

Explicit

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

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

      - agent:

           ref:

             name: weather-agent

Authentication Types

Authentication is always expressed in accordance with Open API authentication methods. For supported authentication types, see Building Agent Networks for Agent Fabric.

These examples show how to define each type in YAML.

Basic Authentication

authentication:
  type: basic
  username: "username"
  password: "password"

OAuth 2.0 Client Credentials

authentication:
  type: oauth2-client-credentials
  clientId: "client_id"
  clientSecret: "client_secret"
  tokenUrl: "https://oauth.provider.com/token"
  scopes: ["read", "write"]             # Optional

Anypoint Client Credentials

authentication:
  type: apikey-client-credentials
  clientId: "client_id"
  clientSecret: "client_secret"