From 897687c415759c138b269b0b6fe658bc93a381f6 Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Thu, 18 Dec 2025 11:05:48 -0800 Subject: [PATCH 01/10] Add A2A Protocol details and non-supported features to af-agent-networks.adoc --- modules/ROOT/pages/af-agent-networks.adoc | 39 ++++++++++++++++++++--- 1 file changed, 34 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/af-agent-networks.adoc b/modules/ROOT/pages/af-agent-networks.adoc index 1a2c12506..b6ff6b733 100644 --- a/modules/ROOT/pages/af-agent-networks.adoc +++ b/modules/ROOT/pages/af-agent-networks.adoc @@ -60,6 +60,40 @@ These servers will be published to Exchange. The asset might also be published to Exchange. . An asset that has been added to this agent network project from Exchange. +== A2A Protocol + +Agent networks use the A2A specification 0.3.0. Brokers use the A2A protocol to accept requests to reach other agents. + +=== Context and Task ID Scoping in Agent Networks + +In the A2A protocol, the server (the agent receiving the request) always generates the `contextId` and `taskId`. These IDs define the state and scope of a specific conversation between two agents. + +When an agent acts as a broker, IDs do not pass through from the upstream client. Each "hop" in a multi-agent network establishes its own unique session. + +Consider a network with a client and two agents (A and B). + +* The IDs used between the client and Agent A are independent of the IDs used between Agent A and Agent B. +* When Agent A delegates a task to Agent B, Agent B (acting as aserver) generates its own `contextId` and `taskId`. +* Agent A is responsible for maintaining a mapping between its own upstream `taskId` (used to respond to its client) and the downstream `taskId` it is tracking with Agent B. +* If Agent B requires more information (if it returns `status: input-required`), Agent B provides a `contextId` and `taskId` to Agent A. Agent A uses these IDs to provide the requested input to Agent B. The client never sees Agent B's internal IDs. + +[cols="1,1,1", options="header"] +|=== +| Relationship | Role | Logic +| Client -> Agent A | Agent A is server | Generates `contextID_1` and `taskID_1` for the client. +| Agent A -> Agent B | Agent B is server | Generates `contextID_2` and `taskID_2` for Agent A. +| Network broker | Agent A | Agent A maps `contextID_1` and `taskID_1` to `contextID_2` and `taskID_2`. +|=== + +For more information, see https://a2a-protocol.org/v0.3.0/topics/life-of-a-task/#group-related-interactions[Life of a Task - Group Related Interactions]. + +=== Non-Supported Features + +Agent network doesn't support the following features in the A2A protocol. +* Task History +* Push Notifications Config +* Streaming + == Considerations Agent networks have these considerations. @@ -69,11 +103,6 @@ Agent networks have these considerations. ** Basic ** Client Credentials ** Anypoint Client Credentials -* A2A specification 0.3.0 is supported. Brokers use the A2A protocol to accept requests to reach other agents. -* These A2A features aren't available. -** Task History -** Push Notifications Config -** Streaming * Text-based prompts and responses are supported. Image and binary message/artifact types aren't supported. * All LLM models in your agent network project must support structured responses in JSON format. For example, a `gpt4.1` model is supported; a `gpt4` model isn't. * These LLMs are supported. From 76d9f34acb6297b5f527676792630a6b95c50561 Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Thu, 18 Dec 2025 11:08:54 -0800 Subject: [PATCH 02/10] Enhance documentation in af-project-files.adoc by adding a reference to A2A protocol details for agents, improving clarity and providing additional context for users. --- modules/ROOT/pages/af-project-files.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/af-project-files.adoc b/modules/ROOT/pages/af-project-files.adoc index c1b97a017..89453bd82 100644 --- a/modules/ROOT/pages/af-project-files.adoc +++ b/modules/ROOT/pages/af-project-files.adoc @@ -494,7 +494,7 @@ Use these properties to handle error scenarios. Define these properties within t `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. +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 xref:af-agent-networks.adoc#a2a-protocol[] Example From ee952917742eeda0a124e159a2385dcc318a4c10 Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Thu, 18 Dec 2025 11:12:58 -0800 Subject: [PATCH 03/10] Fix typo in af-agent-networks.adoc by correcting "as aserver" to "as a server" for improved clarity. --- modules/ROOT/pages/af-agent-networks.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/af-agent-networks.adoc b/modules/ROOT/pages/af-agent-networks.adoc index b6ff6b733..3e0855620 100644 --- a/modules/ROOT/pages/af-agent-networks.adoc +++ b/modules/ROOT/pages/af-agent-networks.adoc @@ -73,7 +73,7 @@ When an agent acts as a broker, IDs do not pass through from the upstream client Consider a network with a client and two agents (A and B). * The IDs used between the client and Agent A are independent of the IDs used between Agent A and Agent B. -* When Agent A delegates a task to Agent B, Agent B (acting as aserver) generates its own `contextId` and `taskId`. +* When Agent A delegates a task to Agent B, Agent B (acting as a server) generates its own `contextId` and `taskId`. * Agent A is responsible for maintaining a mapping between its own upstream `taskId` (used to respond to its client) and the downstream `taskId` it is tracking with Agent B. * If Agent B requires more information (if it returns `status: input-required`), Agent B provides a `contextId` and `taskId` to Agent A. Agent A uses these IDs to provide the requested input to Agent B. The client never sees Agent B's internal IDs. From 593be023d472687c81e3770070e9bfb77ab4d29c Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Mon, 5 Jan 2026 14:08:06 -0800 Subject: [PATCH 04/10] Update af-agent-networks.adoc to clarify A2A protocol usage by replacing "agents" with "brokers" and enhancing the explanation of context and task ID scoping in multi-agent networks. --- modules/ROOT/pages/af-agent-networks.adoc | 25 +++++++++++------------ 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/modules/ROOT/pages/af-agent-networks.adoc b/modules/ROOT/pages/af-agent-networks.adoc index 3e0855620..ab41dfa87 100644 --- a/modules/ROOT/pages/af-agent-networks.adoc +++ b/modules/ROOT/pages/af-agent-networks.adoc @@ -62,27 +62,27 @@ The asset might also be published to Exchange. == A2A Protocol -Agent networks use the A2A specification 0.3.0. Brokers use the A2A protocol to accept requests to reach other agents. +For orchestration, observability, and governance, agents use the A2A specification 0.3.0. === Context and Task ID Scoping in Agent Networks -In the A2A protocol, the server (the agent receiving the request) always generates the `contextId` and `taskId`. These IDs define the state and scope of a specific conversation between two agents. +In MuleSoft agent networks, the server (the agent or broker receiving the request) always generates the `contextId` and `taskId`. These IDs define the state and scope of a specific conversation between two agents. -When an agent acts as a broker, IDs do not pass through from the upstream client. Each "hop" in a multi-agent network establishes its own unique session. +In a multi-agent network, a client sends a request to a broker and the broker generates the necessary IDs. When the broker sends a request to the next broker in line, the broker doesn't send these same IDs. Instead, the broker establishes a unique `contextID` and `taskID` for the request to the next broker. -Consider a network with a client and two agents (A and B). +Consider a network with a client and two brokers (1 and 2). -* The IDs used between the client and Agent A are independent of the IDs used between Agent A and Agent B. -* When Agent A delegates a task to Agent B, Agent B (acting as a server) generates its own `contextId` and `taskId`. -* Agent A is responsible for maintaining a mapping between its own upstream `taskId` (used to respond to its client) and the downstream `taskId` it is tracking with Agent B. -* If Agent B requires more information (if it returns `status: input-required`), Agent B provides a `contextId` and `taskId` to Agent A. Agent A uses these IDs to provide the requested input to Agent B. The client never sees Agent B's internal IDs. +* 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 B (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 is tracking with Broker_2. +* If Broker_2 requires more information (if it returns `status: input-required`), it provides a `contextId` and `taskId` to Broker_1. Broker_1 uses these IDs to provide the requested input to Broker_2. The client never sees Broker_2's internal IDs. [cols="1,1,1", options="header"] |=== | Relationship | Role | Logic -| Client -> Agent A | Agent A is server | Generates `contextID_1` and `taskID_1` for the client. -| Agent A -> Agent B | Agent B is server | Generates `contextID_2` and `taskID_2` for Agent A. -| Network broker | Agent A | Agent A maps `contextID_1` and `taskID_1` to `contextID_2` and `taskID_2`. +| Client -> Broker_1 | Broker_1 is server | Generates `contextID_1` and `taskID_1` for the client. +| Agent A -> Broker_2 | Broker_2 is server | Generates `contextID_2` and `taskID_2` for Broker_1. +| Network broker | Broker_1 | Broker_1 maps `contextID_1` and `taskID_1` to `contextID_2` and `taskID_2`. |=== For more information, see https://a2a-protocol.org/v0.3.0/topics/life-of-a-task/#group-related-interactions[Life of a Task - Group Related Interactions]. @@ -90,8 +90,7 @@ For more information, see https://a2a-protocol.org/v0.3.0/topics/life-of-a-task/ === Non-Supported Features Agent network doesn't support the following features in the A2A protocol. -* Task History -* Push Notifications Config + * Streaming == Considerations From e07eca17812312c72695962b04271fde63ef5260 Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Tue, 6 Jan 2026 08:57:24 -0800 Subject: [PATCH 05/10] Apply suggestions from sme review --- modules/ROOT/pages/af-agent-networks.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/af-agent-networks.adoc b/modules/ROOT/pages/af-agent-networks.adoc index ab41dfa87..ccec02123 100644 --- a/modules/ROOT/pages/af-agent-networks.adoc +++ b/modules/ROOT/pages/af-agent-networks.adoc @@ -66,14 +66,14 @@ For orchestration, observability, and governance, agents use the A2A specificati === Context and Task ID Scoping in Agent Networks -In MuleSoft agent networks, the server (the agent or broker receiving the request) always generates the `contextId` and `taskId`. These IDs define the state and scope of a specific conversation between two agents. +In MuleSoft agent networks, the servers (the brokers receiving the request) always generate the `contextId` and `taskId`. These IDs define the state and scope of a specific conversation between two agents. -In a multi-agent network, a client sends a request to a broker and the broker generates the necessary IDs. When the broker sends a request to the next broker in line, the broker doesn't send these same IDs. Instead, the broker establishes a unique `contextID` and `taskID` for the request to the next broker. +In a multi-agent network, a client sends a request to a broker and the broker generates the necessary IDs. When that broker sends a request to the next broker in line, the broker doesn't send these same IDs. Instead, the broker establishes a unique `contextID` and `taskID` for the request to the next broker. 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 B (acting as a server) generates its own `contextId` and `taskId`. +* 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 is 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. From 2ed1ad31ae9946d4a16ab0c4604be6f68aa6793e Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Tue, 6 Jan 2026 09:14:50 -0800 Subject: [PATCH 06/10] edits from sme review --- modules/ROOT/pages/af-agent-networks.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/af-agent-networks.adoc b/modules/ROOT/pages/af-agent-networks.adoc index ccec02123..4089763ce 100644 --- a/modules/ROOT/pages/af-agent-networks.adoc +++ b/modules/ROOT/pages/af-agent-networks.adoc @@ -66,9 +66,9 @@ For orchestration, observability, and governance, agents use the A2A specificati === Context and Task ID Scoping in Agent Networks -In MuleSoft agent networks, the servers (the brokers receiving the request) always generate the `contextId` and `taskId`. These IDs define the state and scope of a specific conversation between two agents. +In MuleSoft agent networks, the servers (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 a broker and the broker generates the necessary IDs. When that broker sends a request to the next broker in line, the broker doesn't send these same IDs. Instead, the broker establishes a unique `contextID` and `taskID` for the request to the next broker. +In a multi-agent network, a client sends a request to Broker_1 and Broker_1 generates the necessary IDs. When Broker_1 sends a request to the next broker or non-broker agent in line, Broker_1 establishes a unique `contextID` and `taskID` for the request. However, it's not mandatory for brokers to generate a `contextId` and `taskId` when making requests to non-broker agents. Consider a network with a client and two brokers (1 and 2). From ad18bddcc24655cd07db2aa67957f52213a46891 Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Tue, 6 Jan 2026 09:21:40 -0800 Subject: [PATCH 07/10] Refine explanation in af-agent-networks.adoc regarding ID generation in multi-agent networks for improved clarity and consistency. --- modules/ROOT/pages/af-agent-networks.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/af-agent-networks.adoc b/modules/ROOT/pages/af-agent-networks.adoc index 4089763ce..91304ebb0 100644 --- a/modules/ROOT/pages/af-agent-networks.adoc +++ b/modules/ROOT/pages/af-agent-networks.adoc @@ -68,7 +68,7 @@ For orchestration, observability, and governance, agents use the A2A specificati In MuleSoft agent networks, the servers (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. When Broker_1 sends a request to the next broker or non-broker agent in line, Broker_1 establishes a unique `contextID` and `taskID` for the request. However, it's not mandatory for brokers to generate a `contextId` and `taskId` when making requests to non-broker agents. +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, Broker_1 establishes a unique `contextID` and `taskID` for that new request. (Note that it's not mandatory for brokers to generate a `contextId` and `taskId` when making requests to non-broker agents.) Consider a network with a client and two brokers (1 and 2). From 3ba19821cb527a9225db8501e50943e00df6b9f0 Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Tue, 6 Jan 2026 13:42:56 -0800 Subject: [PATCH 08/10] more edits from peer review --- modules/ROOT/pages/af-agent-networks.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/af-agent-networks.adoc b/modules/ROOT/pages/af-agent-networks.adoc index 91304ebb0..151871017 100644 --- a/modules/ROOT/pages/af-agent-networks.adoc +++ b/modules/ROOT/pages/af-agent-networks.adoc @@ -62,13 +62,13 @@ The asset might also be published to Exchange. == A2A Protocol -For orchestration, observability, and governance, agents use the A2A specification 0.3.0. +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 servers (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 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, Broker_1 establishes a unique `contextID` and `taskID` for that new request. (Note that it's not mandatory for brokers to generate a `contextId` and `taskId` when making requests to non-broker agents.) +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 that it's 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). @@ -89,7 +89,7 @@ For more information, see https://a2a-protocol.org/v0.3.0/topics/life-of-a-task/ === Non-Supported Features -Agent network doesn't support the following features in the A2A protocol. +Agent network doesn't support streaming with Server-Sent Events (SSE). * Streaming From 97dd4677ae4d5110125ffc032e5024b6ec9c9d62 Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Tue, 6 Jan 2026 15:23:14 -0800 Subject: [PATCH 09/10] Remove the streaming section from af-agent-networks.adoc to streamline the documentation and focus on key considerations for agent networks. --- modules/ROOT/pages/af-agent-networks.adoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/modules/ROOT/pages/af-agent-networks.adoc b/modules/ROOT/pages/af-agent-networks.adoc index 151871017..5d24edbcc 100644 --- a/modules/ROOT/pages/af-agent-networks.adoc +++ b/modules/ROOT/pages/af-agent-networks.adoc @@ -91,8 +91,6 @@ For more information, see https://a2a-protocol.org/v0.3.0/topics/life-of-a-task/ Agent network doesn't support streaming with Server-Sent Events (SSE). -* Streaming - == Considerations Agent networks have these considerations. From 05de5bed1cce2564ace405b409c99156db187ad8 Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Tue, 6 Jan 2026 16:04:14 -0800 Subject: [PATCH 10/10] Apply suggestions from peer review Co-authored-by: Valkyrie Hunter --- modules/ROOT/pages/af-agent-networks.adoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/af-agent-networks.adoc b/modules/ROOT/pages/af-agent-networks.adoc index 5d24edbcc..9cfed9ce8 100644 --- a/modules/ROOT/pages/af-agent-networks.adoc +++ b/modules/ROOT/pages/af-agent-networks.adoc @@ -68,13 +68,15 @@ The Agent2Agent (A2A) Protocol governs agent-to-agent communication. This protoc 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 that it's not mandatory for non-broker agents to generate a `contextId` and `taskId` when receiving requests from a client.) +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 is tracking with Broker_2. +* Broker_1 is responsible for maintaining a mapping between its own upstream `taskId` (used to respond to its client) and the downstream `taskId` it's tracking with Broker_2. * If Broker_2 requires more information (if it returns `status: input-required`), it provides a `contextId` and `taskId` to Broker_1. Broker_1 uses these IDs to provide the requested input to Broker_2. The client never sees Broker_2's internal IDs. [cols="1,1,1", options="header"]