cleveragents-core/docs/development/acp-to-a2a-migration.md

ACP to A2A Module Rename and Symbol Standardization

Introduced in: v3.6.0 Architectural decision: ADR-047 - A2A Standard Adoption 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 (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):

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

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.

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:

# Before (ACP)
protocol:
  type: acp
  version: "1.0"

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

Skill YAML - operation references:

# Before (ACP)
operations:
  - operation: plan.create
  - operation: plan.execute

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

Server connection config:

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

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

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

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), 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 for the full architectural rationale and decision record.

---

Related Documentation

• A2A Reference - complete API reference for the cleveragents.a2a module
• A2A API - class-level API documentation
• ADR-026 - Agent-to-Agent Protocol - protocol boundary design
• ADR-047 - A2A Standard Adoption - rationale for adopting the external standard
• ADR-048 - Server Application Architecture - server implementation using A2A