# ACP to A2A Module Rename and Symbol Standardization

> **Introduced in:** v3.6.0
> **Architectural decision:** [ADR-047 - A2A Standard Adoption](../adr/ADR-047-acp-standard-adoption.md)
> **Module path:** `cleveragents.a2a` (commit `449c33b7`)

---

## Overview

In v3.6.0 the internal **ACP (Agent Client Protocol)** module was renamed to
**A2A (Agent-to-Agent Protocol)** and all public symbols were standardized to
align with the external [A2A open standard](https://a2a-protocol.org) (Linux
Foundation, Apache 2.0).

This was not merely a rename - it was an architectural shift from a bespoke
JSON envelope protocol to the industry-standard A2A wire format built on
**JSON-RPC 2.0**. The change eliminates the proprietary ACP envelope, replaces
custom REST routing with JSON-RPC 2.0 method dispatch, and introduces
**Agent Card** discovery (`/.well-known/agent.json`).

---

## What Changed

### 1. Module Path

| Before (ACP) | After (A2A) |
|---|---|
| `cleveragents.acp` | `cleveragents.a2a` |
| `from cleveragents.acp import ...` | `from cleveragents.a2a import ...` |

### 2. Class and Symbol Names

All public symbols were renamed from `Acp*` to `A2a*`:

| Old Symbol (ACP) | New Symbol (A2A) | Notes |
|---|---|---|
| `AcpRequest` | `A2aRequest` | Wire format changed - see section 3 |
| `AcpResponse` | `A2aResponse` | Wire format changed - see section 3 |
| `AcpError` | `A2aError` | Base exception |
| `AcpNotAvailableError` | `A2aNotAvailableError` | Server-mode guard |
| `AcpOperationNotFoundError` | `A2aOperationNotFoundError` | Unknown method |
| `AcpVersionMismatchError` | `A2aVersionMismatchError` | Protocol version guard |
| `AcpLocalFacade` | `A2aLocalFacade` | Local-mode dispatcher |
| `AcpHttpTransport` | `A2aHttpTransport` | Server-mode transport stub |
| `AcpEventQueue` | `A2aEventQueue` | In-process event delivery |
| `AcpVersionNegotiator` | `A2aVersionNegotiator` | Version negotiation |
| `AcpVersion` | `A2aVersion` | Version constants |
| `AcpEvent` | `A2aEvent` | SSE event envelope |
| `AcpErrorDetail` | `A2aErrorDetail` | JSON-RPC error object |

### 3. Request and Response Field Names

`A2aRequest` and `A2aResponse` now use **JSON-RPC 2.0** field names instead of
the proprietary ACP envelope fields. These models are defined in
`cleveragents.a2a.models` (commit `449c33b7`):

| Old Field (ACP) | New Field (A2A / JSON-RPC 2.0) | Type |
|---|---|---|
| `a2a_version` | `jsonrpc` (always `"2.0"`) | `str` |
| `request_id` | `id` | `str` |
| `operation` | `method` | `str` |
| `payload` | `params` | `dict[str, Any]` |
| `data` (success path) | `result` | `dict[str, Any] or None` |
| `error_detail` | `error` | `A2aErrorDetail or None` |

**Before (ACP):**
```python
from cleveragents.acp import AcpRequest, AcpLocalFacade

request = AcpRequest(
    a2a_version="1.0",
    request_id="req-001",
    operation="plan.status",
    payload={"plan_id": "01HXRCF1..."},
)
response = facade.dispatch(request)
if response.data:
    print(response.data["phase"])
```

**After (A2A):**
```python
from cleveragents.a2a import A2aRequest, A2aLocalFacade

request = A2aRequest(
    jsonrpc="2.0",
    id="req-001",
    method="_cleveragents/plan/status",
    params={"plan_id": "01HXRCF1..."},
)
response = facade.dispatch(request)
if response.result:
    print(response.result["phase"])
```

### 4. Operation Names

The ACP proprietary operation names were replaced with the A2A standard
`_cleveragents/` extension method namespace. The legacy names are still
accepted by `A2aLocalFacade.dispatch()` in `cleveragents.a2a.facade`
(commit `449c33b7`) for backward compatibility but are **deprecated** and
will be removed in a future major version.

| Old Operation (ACP / deprecated) | New Operation (A2A) |
|---|---|
| `session.create` | `_cleveragents/session/create` (via `message/send`) |
| `session.close` | `_cleveragents/session/close` |
| `plan.create` | `_cleveragents/plan/use` |
| `plan.execute` | `_cleveragents/plan/execute` |
| `plan.status` | `_cleveragents/plan/status` |
| `plan.diff` | `_cleveragents/plan/diff` |
| `plan.apply` | `_cleveragents/plan/apply` |
| `registry.list_tools` | `_cleveragents/registry/tool/list` |
| `registry.list_resources` | `_cleveragents/registry/resource/list` |
| `context.get` | `_cleveragents/context/show` |
| `event.subscribe` | (event delivery via SSE `message/stream`) |

The full list of supported A2A extension methods is documented in
[`docs/reference/a2a.md`](../reference/a2a.md#extension-methods).

### 5. YAML and Configuration Files

If you have YAML configuration files, actor definitions, or skill files that
reference the old ACP module path or operation names, update them as follows:

**Actor YAML - protocol binding:**
```yaml
# Before (ACP)
protocol:
  type: acp
  version: "1.0"

# After (A2A)
protocol:
  type: a2a
  version: "2.0"
```

**Skill YAML - operation references:**
```yaml
# Before (ACP)
operations:
  - operation: plan.create
  - operation: plan.execute

# After (A2A)
operations:
  - method: _cleveragents/plan/use
  - method: _cleveragents/plan/execute
```

**Server connection config:**
```yaml
# Before (ACP)
server:
  protocol: acp
  endpoint: https://my-server.example.com/acp

# After (A2A)
server:
  protocol: a2a
  endpoint: https://my-server.example.com/a2a
```

---

## Migration Steps

Follow these steps when upgrading from a codebase that used the ACP module:

### Step 1 - Update imports

Replace all `cleveragents.acp` imports with `cleveragents.a2a`:

```bash
# Find all files that import from the old ACP module
grep -r "from cleveragents.acp" src/ tests/
grep -r "import cleveragents.acp" src/ tests/
```

Then update each import:
```python
# Before
from cleveragents.acp import AcpLocalFacade, AcpRequest, AcpResponse

# After
from cleveragents.a2a import A2aLocalFacade, A2aRequest, A2aResponse
```

### Step 2 - Rename symbol references

Use your editor's find-and-replace to rename all `Acp*` symbols to `A2a*`
(see the complete symbol table in section 2 above).

### Step 3 - Update request field names

Update all `AcpRequest` and `AcpResponse` constructor calls and field accesses
to use the new JSON-RPC 2.0 field names (see section 3 above).

### Step 4 - Update operation names

Replace deprecated ACP operation strings with the new `_cleveragents/`
extension method names (see section 4 above). The legacy names still work but
emit deprecation warnings.

### Step 5 - Update YAML files

Search for any YAML files that reference `acp` in protocol type fields or
operation names and update them (see section 5 above).

### Step 6 - Verify

Run the full test suite to confirm no regressions:

```bash
nox -s unit_tests
nox -s integration_tests
```

---

## Backward Compatibility

The `A2aLocalFacade.dispatch()` method in `cleveragents.a2a.facade.A2aLocalFacade`
(commit `449c33b7`) continues to accept the legacy ACP operation names
(`session.create`, `plan.create`, etc.) via the `_LEGACY_OPERATIONS` list.
This backward compatibility shim will be removed in the next major version.

The `A2aVersion` class in `cleveragents.a2a.models.A2aVersion` (commit
`449c33b7`) retains the `CURRENT` and `SUPPORTED` constants for backward
compatibility, though the wire format now uses the `jsonrpc` field rather than
a proprietary `a2a_version` field.

---

## Architectural Rationale

The rename was driven by the adoption of the external A2A open standard
([a2a-protocol.org](https://a2a-protocol.org)), which supersedes the bespoke
ACP protocol. Key reasons for the change:

- **Ecosystem alignment**: A2A is governed by the Linux Foundation with 22k+
  GitHub stars and SDKs in Python, Go, JavaScript, Java, and .NET.
- **Agent Card discovery**: The standard introduces `/.well-known/agent.json`
  for dynamic capability advertisement.
- **JSON-RPC 2.0**: Replaces the proprietary envelope with a mature, widely-
  tooled standard.
- **Extensibility**: The `_cleveragents/` extension namespace cleanly separates
  platform-specific operations from standard agent interactions.

See [ADR-047](../adr/ADR-047-acp-standard-adoption.md) for the full
architectural rationale and decision record.

---

## Related Documentation

- [A2A Reference](../reference/a2a.md) - complete API reference for the `cleveragents.a2a` module
- [A2A API](../api/a2a.md) - class-level API documentation
- [ADR-026 - Agent-to-Agent Protocol](../adr/ADR-026-agent-client-protocol.md) - protocol boundary design
- [ADR-047 - A2A Standard Adoption](../adr/ADR-047-acp-standard-adoption.md) - rationale for adopting the external standard
- [ADR-048 - Server Application Architecture](../adr/ADR-048-server-application-architecture.md) - server implementation using A2A
