---
schema_version: "1"
id: 50311bc5f362df123bc7699cd75f8d4d6057812bc3edf13b303b6b51c5e8fdb8
title: Upgrading and Migrating A2A Connector to Version 2.x
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/a2a-connector/latest/a2a-connector-upgrade-migrate.md
canonical_url: https://docs.mulesoft.com/a2a-connector/latest/a2a-connector-upgrade-migrate
source_site: docs.mulesoft.com
content_type: documentation
content_hash: a1162f42dd6dae98c1591783aaf2b1452d7ddb1bdb0ec8d186ad56efc910d699
description: MuleSoft Documentation Site
release: "2.0"
latest: true
---
---
product: A2A Connector
version: 2.0
is-latest-version: true
---

# Upgrading and Migrating A2A Connector to Version 2.x

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

Upgrade Anypoint Connector for Agent2Agent (A2A) (A2A Connector) to version 2.x.

## Supported Upgrade Paths

<table><colgroup><col> <col></colgroup><thead><tr><th>From Version</th><th>To Version</th></tr></thead><tbody><tr><td><div><div><p>1.x</p></div></div></td><td><div><div><p>2.x</p></div></div></td></tr></tbody></table>

## Changes in 2.0

A2A Connector 2.0 uplifts the connector from A2A protocol 0.3.0 to A2A protocol 1.0.0. This is a
breaking change: wire method names, transport configuration, client and listener elements, and the
error palette all change. Review the changes below and update your apps before upgrading.

### Protocol and Transports

- A2A Connector now uses A2A protocol 1.0.0 instead of 0.3.0. Wire JSON-RPC method names change from
  slash-form to PascalCase. For example, `message/send` becomes `SendMessage`, `message/stream`
  becomes `SendStreamingMessage`, `tasks/get` becomes `GetTask`, `tasks/cancel` becomes
  `CancelTask`, and `tasks/resubscribe` becomes `SubscribeToTask`. Clients written against 0.3.0
  must update their method strings.

- An A2A Server can expose the same agent over both the JSON-RPC and the new HTTP+JSON transport
  bindings on a single connection (gRPC is out of scope for this release).

- You can now send a non-blocking `SendMessage` request by setting `returnImmediately` to `true` in
  the request configuration. The A2A Server acknowledges the request with the initial `Task` and
  continues processing asynchronously, and the **A2A Server - On Async Request Listener** source
  authors that initial response.

- At most one active `SendMessage` request (blocking, non-blocking, or streaming) can run against a
  given `taskId` at a time. A duplicate concurrent submission is rejected with `A2A:INVALID_REQUEST`
  ("Another SendMessage is already in flight for taskId {id}; retry once it completes."), which
  preserves the ordering of a task’s message history under concurrency.

- Tasks in a terminal state (`TASK_STATE_COMPLETED`, `TASK_STATE_FAILED`, `TASK_STATE_CANCELED`, or
  `TASK_STATE_REJECTED`) are immutable. A `SendMessage` or `SendStreamingMessage` request against a
  terminal task is rejected with `A2A:UNSUPPORTED_OPERATION` ("Task has reached terminal state.").

- Task states now use the `TASK_STATE_*` constants (for example, `TASK_STATE_WORKING`,
  `TASK_STATE_COMPLETED`) instead of the lowercase 0.3.0 states.

- Streaming events use the A2A `StreamResponse` envelope shape with a single root key (`task`,
  `statusUpdate`, or `artifactUpdate`). There is no explicit `final` boolean. Finality is derived
  from `TaskStatus.state`.

### Server Configuration

- New required `<a2a:interfaces>` block on `<a2a:connection>`. One or more `<a2a:interface>` entries
  select the **Protocol** (`JSONRPC` or `HTTP_JSON`) and the **Path** segment appended to **Agent
  Path**. This is what enables multi-transport agents on a single connection.

- **Agent Path** on `<a2a:connection>` is now the base HTTP path for both the agent card (served at
  `{agentPath}/.well-known/agent-card.json`) and every configured interface
  (`{agentPath}{interface.path}`), rather than a single fixed agent endpoint.

- Startup validates a bijection between the configured `<a2a:interface>` entries and
  `agentCard.supportedInterfaces`. Mismatched `(protocol, path)` pairs fail initialization instead
  of surfacing as runtime 404s.

- Multi-tenant support: A single connection can serve multiple tenants at the same
  `{agentPath}{interface.path}` surface. Each request’s tenant (the `params.tenant` field on the
  request body, or `?tenant=` on GET/DELETE) is validated against
  `agentCard.supportedInterfaces[].tenant` and surfaced to flows as `attributes.tenant`.

### Client Configuration

- The **Client Connection** provider is replaced by two transport-specific connection providers,
  **Jsonrpc Client Connection** and **Http Json Client Connection**, chosen via the **Connection**
  dropdown in Studio. The transport must match one of the entries in the target
  `agentCard.supportedInterfaces`.

- The **Server Url** connection parameter is renamed to **Agent Url**, the base URL of the target
  A2A agent that the connector discovers via `{agentUrl}/.well-known/agent-card.json`.

- Every outbound request now sends `A2A-Version: 1.0` as a default header unless you override it via
  `<a2a:default-headers>`. If overridden, the value is validated to be a `1.x` version. Agent-card
  discovery (both connect-time and the **A2A Client - Get Card** operation) is exempt from this
  header.

### Sources

- The **A2A Server - Task Listener** source is now a unified listener. The same flow serves blocking
  `SendMessage`, non-blocking `SendMessage` (`returnImmediately=true`), and `SendStreamingMessage`
  over both JSON-RPC and HTTP+JSON, with no DSL change to distinguish the modes. The standalone
  **A2A Server - On Task Stream Listener** source is removed.

- The new **A2A Server - On Async Request Listener** source lets the flow customize the initial
  `Task` response emitted for streaming and non-blocking `SendMessage` requests. The flow receives
  the incoming `MessageSendParams` as payload and must return a `Task` (or raise an error to reject
  the request, or return a terminal or interrupted-state `Task` to short-circuit and skip the **A2A
  Server - Task Listener** flow entirely).

- The **A2A Server - Authorization Listener** source is replaced by the **A2A Server - Task
  Authorizer Listener** source, which uses a per-operation authorization contract and exposes the
  current operation name on `attributes.operationName`.

- The **A2A Server - On Push Notification Set Listener** source output payload is now the resolved
  `TaskPushNotificationConfig` JSON rather than the raw request params.

- SSE streams now close on terminal states (`TASK_STATE_COMPLETED`, `TASK_STATE_FAILED`,
  `TASK_STATE_CANCELED`, `TASK_STATE_REJECTED`) and on the interrupted state
  `TASK_STATE_INPUT_REQUIRED`. `TASK_STATE_AUTH_REQUIRED` does not close the stream.

### Operations

- The new **A2A Client - List Tasks** operation is a client operation that returns the tasks from
  the target A2A server as a list (`Array of Any`) with a configurable streaming strategy,
  consumable from `<foreach>`.

- The new **A2A Server - Get Tasks** operation is a server-side batch read of stored tasks by ID.
  The flow supplies a **Task IDs** list and an optional **History Length** per task.

- The new **A2A Server - Get Tasks By Context** operation is a server-side read of every stored task
  that belongs to a **Context Id**, returned oldest first. The flow supplies a **Context Id** and an
  optional **History Length** per task.

- The new **A2A Server - Set Task Metadata** operation is a full-replace (no merge) of the persisted
  ``Task’s `metadata`` field. Pass `{}` to clear. It’s rejected for tasks in a terminal state.

- The **Task Resubscribe** operation is renamed to **A2A Client - Subscribe To Task**.

- The **A2A Client - Set Push Notification Config** operation is renamed to **A2A Client - Create
  Push Notification Config** (`<a2a:create-push-notification-config>`).

- The extended agent card is now fetched via a new **Use Extended Card** boolean parameter on the
  existing **A2A Client - Get Card** operation (defaults to `false`). No separate operation was
  added.

- The **A2A Client - List Push Notification Configs** operation now returns its results as a list
  (`Array of Any`) with a configurable streaming strategy, also consumable from `<foreach>`.

- The **A2A Server - Send Push Notification** operation now accepts a full
  `StreamingMessageResponse` payload (Task, Message, `TaskStatusUpdateEvent`, or
  `TaskArtifactUpdateEvent`).

- The **A2A Server - Update Task Status** and **A2A Server - Update Task Artifact** operations are
  uplifted to the A2A 1.0.0 event schemas, and each now declares only the concrete error types it
  raises.

### Errors

- Added: `A2A:CONTENT_TYPE_UNSUPPORTED`, `A2A:INVALID_AGENT_RESPONSE`,
  `A2A:EXTENDED_CARD_UNCONFIGURED`, `A2A:EXTENSION_SUPPORT_REQUIRED`, and `A2A:VERSION_UNSUPPORTED`.

- Updated: The `A2A:UNAUTHORIZED` JSON-RPC code moved from `-32005` to `-32099` (`-32005` is now the
  code for `CONTENT_TYPE_UNSUPPORTED`). Every error type now also carries a `google.rpc.ErrorInfo`
  reason string.

- Dropped: `A2A:JSON_RPC_ERROR` (the umbrella parent type), `A2A:METHOD_NOT_FOUND`, and
  `A2A:REQUEST_TIMEOUT`. Each operation now declares only the concrete error types it actually
  raises, so verify your error handling after upgrading.

## Requirements

Ensure your system meets the following compatibility requirements before you perform the upgrade:

<table><colgroup><col> <col></colgroup><thead><tr><th>Software</th><th>Version</th></tr></thead><tbody><tr><td><p>Mule</p></td><td><p>4.9.8 and later</p></td></tr><tr><td><p>OpenJDK</p></td><td><p>17</p></td></tr><tr><td><p>A2A protocol</p></td><td><p>1.0.0</p></td></tr></tbody></table>

A2A Connector requires Mule Maven Plugin 4.6.0 or later to support Server-Sent Events (SSE) for
streaming operations. See [A2A Connector XML and Maven Support](https://docs.mulesoft.com/a2a-connector/latest/a2a-connector-xml-maven).

## Upgrade Prerequisites

Before you perform the upgrade, create a backup of your files, data, and configuration in case you
need to restore to the previous version.

Because 2.0 is a breaking change, plan to update your Mule apps for the following before or
immediately after upgrading:

- Add the required `<a2a:interfaces>`/`<a2a:interface>` block and ensure **Agent Path** is set on
  every `<a2a:connection>`, and that your agent card’s `supportedInterfaces` matches it exactly.

- Replace the **Client Connection** provider with **Jsonrpc Client Connection** or **Http Json
  Client Connection**, and rename **Server Url** to **Agent Url**.

- Replace any **A2A Server - On Task Stream Listener** source with the unified **A2A Server - Task
  Listener** source.

- Replace the **A2A Server - Authorization Listener** source with the **A2A Server - Task Authorizer
  Listener** source.

- Update client method strings and event payloads to A2A 1.0.0 (PascalCase methods, `TASK_STATE_*`
  states, `StreamResponse` envelopes).

- Update error handling for the added, renamed, and dropped `A2A:` error types.

## Upgrade Steps

Follow these steps to perform the upgrade to version 2.x:

1.  In Anypoint Studio, create a Mule project.

2.  In the **Mule Palette** view, click **Search in Exchange**.

3.  In **Add Dependencies to Project**, enter `a2a` in the search field.

4.  In **Available modules**, select **A2A Connector** and click **Add**.

5.  Click **Finish**.

6.  Verify that the A2A Connector dependency version is 2.x in the `pom.xml` file in the Mule
    project.

Studio upgrades the connector automatically.

## Post-Upgrade Steps

After you install the latest version of the connector, verify that your app reflects the breaking
changes listed in [Upgrade Prerequisites](#upgrade-prerequisites): transport configuration, client
connection elements, unified task listener, authorizer listener, protocol 1.0.0 method names and
payloads, and the updated error palette.

## Verify the Upgrade

After you install the latest version of the connector, follow these steps to verify the upgrade:

1.  In Studio, verify that there are no errors in the **Problems** or **Console** views.

2.  Verify that there are no problems in the project `pom.xml` file.

3.  Confirm the app starts without an interface/agent-card bijection error.

4.  Test the connection to verify that the operations work.

## Revert the Upgrade

If it is necessary to revert to the previous version of A2A Connector, change the A2A Connector
dependency version in the project’s `pom.xml` file to the previous version.

You must update the project’s `pom.xml` file in Anypoint Studio.

## See Also

- [A2A Connector Reference](https://docs.mulesoft.com/a2a-connector/latest/a2a-connector-reference)

- [A2A Connector Examples](https://docs.mulesoft.com/a2a-connector/latest/a2a-connector-examples)

- [Introduction to Anypoint Connectors](https://docs.mulesoft.com/connectors/introduction/introduction-to-anypoint-connectors)

- [Salesforce Help](https://help.salesforce.com)