Agentic overlays: AWS guide to retrofit legacy REST services

AWS and the authors present agentic overlays, thin wrapper layers that transform REST-based services into agents capable of A2A (agent-to-agent) interactions while leaving underlying business logic unchanged. The pattern exposes REST endpoints as tools compatible with the Model Context Protocol and maps JSON-RPC A2A messages to existing REST calls.

What are agentic overlays?

An agentic overlay is a thin wrapper that transforms an agentic message into a REST payload, and the reverse, exposing REST endpoints as agent tasks or tools while keeping the underlying REST service unchanged. The overlay lets a REST-based service participate in A2A interactions by adding A2A routes and metadata such as an agent card, capabilities, skills, and a JSON-RPC message endpoint.

The source describes overlays as an alternative to running parallel A2A and REST stacks or refactoring code to share business logic. The overlay reuses the existing REST implementation and avoids duplicating business logic, deployment pipelines, and observability for separate stacks.

How do overlays work in practice?

An overlay sits alongside existing REST routes (for example "/api/v2/...") and adds A2A-specific routes (for example "/a2a/") on the same host and port, sharing a single deployment pipeline while translating between protocols. The document shows an in-application overlay pattern where agent skills can route requests and an MCP server is optional for invoking external services.

The A2A message translation workflow in the example calculator proof of concept is explicit: receive JSON-RPC 2.0 requests, map A2A tasks to REST endpoints, forward authentication headers, call REST endpoints internally, and translate REST responses back to JSON-RPC format. The example includes concrete values and configuration: the default A2A API URL is "http://localhost:5000/a2a" and EXECUTE_TIMEOUT_SECONDS is set to 30. The example agent card built dynamically sets the agent name to "Calculator Agent" and the version to "1.0.0" and loads skills from a skills.json file.

The source provides a direct request/response mapping using a calculator example. REST input { "operation": "add", "operands": [5, 3] } becomes the A2A JSON-RPC request { "jsonrpc": "2.0", "method": "SendMessage", "params": { "message": { "role": "user", "parts": [ { "kind": "data", "data": { "operation": "add", "operands": [5, 3] } } ] } }, "id": 1 } and the REST response {"result": 8} is represented in A2A as a JSON-RPC result containing the message with the data part {"result": 8}.

The code sample also targets A2A Spec 0.3 compliance, implementing endpoints and behaviors such as GET /.well-known/agent-card.json and POST /a2a and supporting methods SendMessage and SendStreamingMessage.

Why it matters

Separate REST and A2A stacks introduce operational overhead: two sets of endpoints, duplicate auth and validation logic, two deployment pipelines, and doubled observability work with higher risk of inconsistency. The source warns that refactoring REST endpoints to share business logic can introduce regressions, behavior drift, and a large test burden. Agentic overlays reduce agent sprawl by reusing existing services as agents and let supervisor agents combine REST-based and agentic capabilities without rewriting core services.

The authors sum the difference succinctly: "A2A isn’t a new API. It’s a new interface to an existing API." That framing directs teams to add an interface layer rather than rebuild internal services.

What to watch

Watch for whether teams adopt well-known agent cards and A2A routes in production and whether MCP servers are used primarily for external orchestration while agent skills handle internal routing. Also watch scaling: the pattern notes the same host and port can serve both REST and A2A routes but systems might need to be scaled to handle increased traffic.

The reference implementation items to monitor include adoption of the A2A Spec 0.3 patterns (/.well-known/agent-card.json, POST /a2a, SendMessage methods), how organizations manage skills.json-based capability declarations, and whether overlays reduce duplicated pipelines and observability work in practice.