Retrofit, don’t rebuild: Agentic overlays for remodeling legacy enterprise providers

The opinions expressed on this submit are the authors’ views and never these of Cisco.

Enterprise architectures have lengthy been centered on REST APIs and microservices. These methods are secure, well-tested, and deeply embedded in manufacturing environments. They weren’t designed for Agent-to-Agent (A2A) communication, the rising commonplace for autonomous brokers that collaborate, motive, and coordinate by means of structured messaging. That labored within the absence of a standard agent protocol, nevertheless it means many current brokers now sit outdoors the rising A2A framework. The problem immediately is not solely including A2A to conventional providers. You additionally have to carry these REST-based brokers right into a standardized agent-to-agent world.

On this technical collaboration between AWS and the authors, we current a realistic resolution: agentic overlays. Agentic overlays are skinny wrapper layers that rework conventional REST-based providers into brokers able to collaborating in A2A interactions. In addition they expose REST APIs as instruments appropriate with the Mannequin Context Protocol (MCP). Collectively, they let enterprises add A2A capabilities to current REST providers with out rewriting enterprise logic, with out duplicating code, and with out working parallel infrastructures. This reduces agent sprawl within the infrastructure by reusing current providers as brokers. We offer reference architectures and pattern code that present how you can construct agentic overlays.

Background: REST vs. A2A

REST APIs are designed for deterministic, client-server integration. A consumer calls a well-defined endpoint, passes parameters, and receives a predictable response, usually in a stateless request-response stream ruled by HTTP semantics. This makes REST wonderful for exposing enterprise capabilities (resembling create, learn, replace, and delete) with clear contracts, robust compatibility, and operational simplicity.

A2A is designed for interoperability between autonomous brokers. Brokers uncover each other by means of metadata (resembling an agent card), negotiate capabilities, and trade structured messages (usually by means of JSON-RPC) to coordinate multi-step duties. The place REST optimizes for secure service interfaces and direct execution, A2A optimizes for reasoning-driven coordination, task-oriented messaging, and agent collaboration. The result’s methods that may plan, delegate, and compose actions throughout a number of providers slightly than invoking remoted endpoints.

Challenges with shifting in direction of agentic methods

REST APIs and agentic methods are primarily based on orthogonal paradigms, which makes it arduous for enterprises to maneuver current providers into standardized agentic communication. But enterprises want to make use of each with out a main overhaul. Though newer agent communication by means of A2A introduces coordination fashions for enterprise methods, adoption has been slowed by the necessity to deploy and function agentic infrastructures alongside current enterprise methods. This parallel operation will increase operational complexity and price, creating boundaries to adopting AI successfully.

Earlier than A2A was standardized, enterprises generally deployed brokers as REST-based or proprietary providers. They handled them as typical APIs with agent-specific logic embedded in request-response endpoints. In consequence, many current brokers immediately aren’t A2A-native, which creates a brand new migration problem: making these brokers interoperate utilizing standardized A2A protocols with out rewriting their core logic.

Fig 1: REST-based utility

The previous determine reveals a REST-based utility. The REST API stack is likely to be a monolith or a set of distributed endpoints. The REST API controller doesn’t should be an express dealer that delegates requests outdoors the appliance. It may be a part of the framework itself. For instance, in a Flask utility, the framework supplies the controller abstraction out of the field, as you usually see when utilizing @app.route() or Flask’s RESTful extensions. The concept right here is to seize the REST stack with a set of endpoints.

Answer approaches

On this part, we focus on the completely different approaches you possibly can take so as to add an agentic functionality to a legacy enterprise system. We evaluate them to the method of utilizing agentic overlays.

Keep separate REST and A2A stacks: One method is to develop and keep two parallel methods to reveal the identical capabilities. This might imply:

• Two units of endpoints: /api/v2/... and /a2a/....
• Two implementations of auth, validation, and error mapping (except fastidiously reused).
• Two deployment pipelines (construct, take a look at, launch, rollback).
• Double observability work: logs, metrics, and tracing for each paths.
• Larger danger of inconsistency. A2A could return a special output for a similar operation carried out by REST.
• Larger price and operational complexity over time.

Fig 2: Separate REST and A2A stacks

Separated stacks, however shared enterprise logic: Refactoring current endpoints means you modify your present REST API code construction (and typically habits) so it may be reused by a brand new interface resembling A2A. As an alternative of leaving REST endpoints as-is, you reorganize them, often by extracting enterprise logic into shared providers and updating controllers and handlers to name these providers. Even when the exterior REST paths stay the identical, refactoring can introduce regressions, habits drift, and a big take a look at burden.

Fig 3: Separated stacks, shared enterprise logic

The core thought: Agentic overlays

An agentic overlay is a skinny wrapper layer that lets REST-based providers take part in A2A communication. The overlay:

• Transforms an agentic message right into a REST payload, and the reverse.
• Exposes REST endpoints as agent duties or instruments.

Most significantly, A2A isn’t a brand new API. It’s a brand new interface to an current API. The underlying REST service stays unchanged.

Including an agentic overlay inside the utility

On this method, you have got two units of endpoints, /api/v2/... and /a2a/... (REST vs. A2A), as proven within the following diagram, however a single deployment pipeline for construct, take a look at, launch, and rollback. With this sample, conventional REST API endpoints could be remodeled into agentic endpoints with out rewriting the core enterprise logic. The deployment course of doesn’t change for the service. For a similar host and similar port, you add new routes, though the methods may should be scaled to deal with elevated site visitors.

You may apply the agent abilities themselves for routing. An MCP server can be utilized to invoke exterior providers, however agent abilities can route requests inside the agent scope instantly with out importing APIs into an MCP server as abilities. No matter endpoints you have got could be uncovered as agent abilities without having a separate MCP server.

Fig 4: Agentic overlay inside an utility

This method reduces agent sprawl within the infrastructure by reusing current providers as brokers. This design sample works nicely for supervisor brokers that want each REST-based and agentic capabilities with restricted useful scope, resembling intent classification and routing.

Agentic overlay instance implementation

As a proof of idea, this part reveals how you can port an instance legacy REST-based calculator service that makes use of Flask into an agentic system utilizing an overlay. For the overlay, we add the usual A2A elements (or routes), resembling a well known agent card, agent message endpoint, capabilities, abilities, and well being. We additionally introduce a message transformation design sample that converts agentic messages to REST API messages, then points REST invocation calls from the agent. The A2A message translation workflow is as follows:

1. Receives JSON-RPC 2.0 requests.
2. Maps A2A duties to REST endpoints.
3. Forwards authentication headers.
4. Calls REST endpoints internally.
5. Interprets REST responses to JSON-RPC format.

Step 0: Request-response format

This part compares the request-response format for the REST and A2A protocols, utilizing the calculator instance demonstrated within the following sections.

REST vs. A2A enter request:

REST vs. A2A output response:

Step 1: Arrange the agent

On this step, you create the calculator agent instance with a well known agent card and agent abilities loaded. The build_agent_card perform builds the agent card dynamically.

"""
A2A Request Translator - Calculator Instance.

This module implements the Request Translator Sample to offer A2A
(JSON-RPC 2.0) compatibility over the prevailing Calculator REST API.

A2A Spec 0.3 Compliance:
- Agent Card: GET /.well-known/agent-card.json
- JSON-RPC endpoint: POST /a2a
- Strategies: SendMessage, SendStreamingMessage
- Message format: { "message": { "components": [{ "kind": "data", "data": {...} }] } }
"""

# Default A2A API URL (override through build_agent_card(url) if wanted)
A2A_API_URL = "http://localhost:5000/a2a"

EXECUTE_TIMEOUT_SECONDS = 30

# Load abilities from JSON file
_SKILLS_FILE = Path(__file__).father or mother / "abilities.json"
_SKILLS_CACHE: Elective[List[Dict[str, Any]]] = None

def _load_skills() -> Listing[Dict[str, Any]]:
    """
    Load abilities from the abilities.json file.
    Abilities are cached after first load to keep away from repeated file reads.
    """
    international _SKILLS_CACHE
    if _SKILLS_CACHE shouldn't be None:
        return _SKILLS_CACHE
    strive:
        with open(_SKILLS_FILE) as f:
            _SKILLS_CACHE = json.load(f)
            return _SKILLS_CACHE
    besides FileNotFoundError:
        logger.error(f"Abilities file not discovered: {_SKILLS_FILE}")
        return []
    besides json.JSONDecodeError as e:
        logger.error(f"Invalid JSON in abilities file: {e}")
        return []

def build_agent_card(api_url: Elective[str] = None) -> Dict[str, Any]:
    """Construct the A2A Agent Card (v0.3.0 format) with configurable API URL."""
    if api_url is None:
        api_url = A2A_API_URL
    return {
        "identify": "Calculator Agent",
        "description": "Easy calculator supporting fundamental arithmetic operations",
        "supportedInterfaces": [
            {"url": api_url, "protocolBinding": "JSONRPC", "protocolVersion": "0.3"},
        ],
        "supplier": {
            "group": "Instance Group",
            "url": "",
        },
        "model": "1.0.0",
        "capabilities": {
            "streaming": False,
            "pushNotifications": False,
            "extendedAgentCard": False,
        },
        "defaultInputModes": ["text/plain", "application/json"],
        "defaultOutputModes": ["text/plain", "application/json"],
        "abilities": _load_skills(),
    }

# Agent Card constructed dynamically
AGENT_CARD = build_agent_card()

Step 2: Implement the interior REST caller

def invoke_rest_endpoint(
    endpoint: str,
    json_data: Elective[Dict] = None,
    http_method: str = "POST"
) -> Tuple[Optional[Dict], int]:
    """
    Name inside REST endpoint through actual HTTP request.

    Makes use of requests.submit/get to name the working server. This ensures
    any middleware, decorators, and headers are correctly exercised.

    Args:
        endpoint: REST endpoint path (e.g. "/api/v1/calculate")
        json_data: Request physique for POST/PUT
        http_method: HTTP technique (GET, POST, and so forth.)

    Returns:
        Tuple of (response_data, status_code)
    """
    strive:
        base_url = request.host_url.rstrip("/")
        url = f"{base_url}{endpoint}"

        headers = {"Content material-Kind": "utility/json"}
        auth_header = request.headers.get("Authorization")
        if auth_header:
            headers["Authorization"] = auth_header

        logger.information(f"Adapter: Delegating to REST {http_method} {url}")

        if http_method.higher() == "POST":
            response = http_requests.submit(
                url, json=json_data, headers=headers,
                timeout=EXECUTE_TIMEOUT_SECONDS
            )
        elif http_method.higher() == "GET":
            response = http_requests.get(
                url, headers=headers,
                timeout=EXECUTE_TIMEOUT_SECONDS
            )
        else:
            response = http_requests.request(
                http_method, url, json=json_data, headers=headers,
                timeout=EXECUTE_TIMEOUT_SECONDS
            )

        logger.information(f"Adapter: REST returned {response.status_code}")
        return response.json(), response.status_code

    besides http_requests.RequestException as e:
        logger.error(f"Adapter: Error calling REST endpoint: {e}", exc_info=True)
        return {"error": "Inner server error"}, 500

def extract_message_payload(message: Dict) -> Elective[Dict]:
    """
    Extract payload from A2A message components (Spec 0.3 format).

    Anticipated format:
    {
        "message": {
            "components": [{"kind": "data", "data": {"operation": "add", "operands": [5, 3]}}]
        }
    }

    Returns:
        Extracted information payload as dict, or None if not discovered
    """
    strive:
        components = message.get("components", [])
        for half in components:
            if isinstance(half, dict) and half.get("variety") == "information":
                return half.get("information")
        return None
    besides Exception as e:
        logger.error(f"Error extracting message payload: {e}")
        return None

def build_a2a_message(message_id: str, context_id: str, content material: Any) -> Dict:
    """
    Construct an A2A-compliant message object (A2A Spec 0.3).

    Response format:
    {
        "messageId": "uuid",
        "contextId": "uuid",
        "position": "agent",
        "components": [{"kind": "data", "data": {...}}],
        "variety": "message",
        "metadata": {}
    }
    """
    if isinstance(content material, dict):
        components = [{"kind": "data", "data": content}]
    else:
        components = [{"kind": "text", "text": str(content)}]

    return {
        "messageId": message_id,
        "contextId": context_id,
        "position": "agent",
        "components": components,
        "variety": "message",
        "metadata": {}
    }

Word on Server-Despatched Occasions (SSE) for streaming:

The previous extract_message_payload() perform works the identical approach for each SendMessage and SendStreamingMessage.

For operations which are prompt (like our calculator), each strategies return a single outcome. For long-running operations (for instance, report era or information evaluation), SSE streaming permits the server to push incremental updates.

Step 4: Implement JSON-RPC response builders

# The error codes outlined as per JSON-RPC 2.0 specification
class JsonRpcError:
    PARSE_ERROR = -32700
    INVALID_REQUEST = -32600
    METHOD_NOT_FOUND = -32601
    INVALID_PARAMS = -32602
    INTERNAL_ERROR = -32603

def jsonrpc_error(code: int, message: str, information: Any = None, request_id: Any = None) -> Dict:
    """Construct a JSON-RPC 2.0 error response."""
    response = {
        "jsonrpc": "2.0",
        "error": {"code": code, "message": message},
        "id": request_id
    }
    if information shouldn't be None:
        response["error"]["data"] = information
    return response

def jsonrpc_success(outcome: Any, request_id: Any = None) -> Dict:
    """Construct a JSON-RPC 2.0 success response."""
    return {
        "jsonrpc": "2.0",
        "outcome": outcome,
        "id": request_id
    }

Step 5: SendMessage — A2A-to-REST delegation

def handle_send_message(information: Dict) -> Tuple[Any, int]:
    """
    Deal with SendMessage -- dumb pass-through to /api/v1/calculate.
    The adapter does NOT examine or route primarily based on payload contents.
    """
    request_id = information.get("id")
    params = information.get("params", {})
    message = params.get("message", {})
    context_id = message.get("contextId") or generate_id()
    message_id = generate_id()

    payload = extract_message_payload(message)
    if not payload:
        return jsonify(jsonrpc_error(
            JsonRpcError.INVALID_PARAMS,
            "Invalid params: No information present in message.components.",
            request_id=request_id
        )), 400

    # Move by means of payload as-is to the only REST endpoint
    rest_response, standing = invoke_rest_endpoint(
        endpoint="/api/v1/calculate",
        json_data=payload,
        http_method="POST"
    )

    if 200 <= standing < 300:
        a2a_message = build_a2a_message(message_id, context_id, rest_response)
        return jsonify(jsonrpc_success(a2a_message, request_id)), 200
    else:
        error_message = "Operation failed"
        if isinstance(rest_response, dict):
            error_message = (rest_response.get("error")
                             or rest_response.get("particulars")
                             or "Operation failed")
        error_code = (JsonRpcError.INVALID_PARAMS if 400 <= standing < 500
                      else JsonRpcError.INTERNAL_ERROR)
        return jsonify(jsonrpc_error(
            error_code, error_message,
            information=rest_response, request_id=request_id
        )), standing

# we have to explicitly add the routes because the a2a

def generate_id() -> str:
    """Generate a UUID for message/context IDs."""
    return str(uuid.uuid4())

Step 6: Arrange A2A routes (Spec 0.3)

The official A2A SDK supplies A2A libraries for FastAPI and Starlette purposes that summary away the complexity of including A2A-specific routes. Though A2A libraries are additionally accessible for Flask apps, we don’t use them in our pattern code. We wish to make it simple so that you can perceive what it takes to host an A2A overlay over a Flask app. The next code snippet provides the routes wanted for A2A.

def setup_a2a_routes(app: Flask) -> None:
    """Register A2A protocol v0.3 routes on the Flask utility."""
    app.add_url_rule("/.well-known/agent-card.json", "get_agent_card",
                     get_agent_card, strategies=["GET"])
    app.add_url_rule("/a2a/capabilities", "get_capabilities",
                     get_capabilities, strategies=["GET"])
    app.add_url_rule("/a2a/well being", "a2a_health",
                     a2a_health, strategies=["GET"])
    app.add_url_rule("/a2a", "a2a_jsonrpc",
                     _handle_jsonrpc, strategies=["POST"])
    logger.information("A2A Protocol v0.3 routes registered")

Step 7: Lastly, initialize in your utility

# app/predominant.py
from flask import Flask
from app.rest_api import rest_api
from app.a2a_adapter import setup_a2a_routes

def create_app():
    app = Flask(__name__)

    # Register current REST API
    app.register_blueprint(rest_api)

    # Add A2A Protocol assist (Request Translator Sample)
    setup_a2a_routes(app)
    app.logger.information("A2A Protocol enabled through Request Translator Sample")

    return app

Step 8: Run your utility

From the mission base listing, run the next instructions.

python -m venv venv
supply venv/bin/activate   # On Home windows: venvScriptsactivate
pip set up -r necessities.txt
python -m app.predominant

Including an agentic overlay utilizing Amazon Bedrock AgentCore Gateway

Amazon Bedrock AgentCore is a service for constructing, connecting, and optimizing brokers at scale with out managing infrastructure. As proven within the following diagram, AgentCore Gateway can decouple the agentic overlay from the appliance by serving as a single entry level for endpoints and providers. This separation lets one agentic overlay serve a number of providers or purposes, not just one. AgentCore Gateway helps as much as 10 targets per gateway, with native integration into current AWS providers and assist for OpenAPI endpoints.

Fig 5: Decoupling the agentic overlay utilizing Amazon Bedrock AgentCore Gateway

Enterprise-scale purposes usually orchestrate a number of providers to deal with complicated duties. For instance, a calculator utility processing “Calculate 2 * (3 + 4).” As proven within the following diagram, the system first queries an order-of-operations endpoint (resembling /api/order-of-ops/...) to find out the order of analysis. It then makes sequential calls to an endpoint (resembling /api/arithmetic/...) to calculate “3 + 4” adopted by “2 * 7.” Including an agentic overlay to every service would introduce its personal overhead. As an alternative, you’ll be able to tie each providers collectively right into a single agentic overlay that orchestrates the calls as wanted.

You may separate the agentic overlay out of your utility to arrange your agentic overlays primarily based on performance slightly than solely by utility. The agentic overlays act as an agentic solution to work together together with your purposes and your methods, an agentic solution to work together with performance.

Past AgentCore Gateway, extra AgentCore capabilities simplify monitoring, iteration, and deployment of your agentic overlay. AgentCore Id handles authentication for each agent and gateway elements, supporting OAuth 2.0 suppliers with managed integrations for Okta, GitHub, and Slack. AgentCore Observability displays agent efficiency by means of metrics, logs, and span visualizations. You may view high-level information resembling software calls and latency, or examine granular execution paths throughout elements, with native Amazon CloudWatch integration. AgentCore Runtime deploys fashions by means of a container picture, whether or not open-source, customized, or Amazon Bedrock LLMs resembling Nova and Anthropic Claude, with out requiring you to handle massive language mannequin (LLM) infrastructure.

Fig 6: Decoupling the agentic overlay utilizing Amazon Bedrock AgentCore capabilities — runtime, gateway, identification, and observability

Through the use of the completely different capabilities of AgentCore, you’ll be able to simplify the deployment of your agent and your agentic overlay, with simple integration into your current AWS stack. As a result of it’s a managed service, it additionally reduces the work wanted to implement your agentic overlay.

Partnering to speed up enterprise AI adoption

This agentic overlay sample represents a broader collaboration between the authors and AWS to assist enterprises bridge the hole between current infrastructure and rising AI capabilities. Profitable AI adoption requires pragmatic options that respect current investments and assist incremental transformation. Collectively, AWS and the authors are creating reference architectures, implementation patterns, and tooling that allow enterprises undertake A2A communication with out wholesale infrastructure substitute. The agentic overlay sample exemplifies this philosophy: protect what works, prolong the place wanted, and supply clear migration paths that reduce danger whereas maximizing worth.

Conclusion

Agentic overlays give enterprises a realistic path to undertake Agent-to-Agent communication with out abandoning their REST API investments. By including a skinny translation layer that converts A2A messages to REST payloads, organizations can take part within the rising agentic panorama whereas preserving secure, production-tested enterprise logic. The 2 implementation patterns provide flexibility to match organizational wants: within-application overlays for targeted use circumstances, and AgentCore Gateway for enterprise-scale deployments. Whether or not you’re enabling a single supervisor agent or orchestrating complicated multi-service workflows, agentic overlays scale back the operational overhead of parallel infrastructures and the regression danger of wholesale refactoring.

As enterprises navigate the transition from deterministic REST APIs to reasoning-driven agentic methods, the important thing perception stays: A2A isn’t a brand new API. It’s a brand new interface to your current API. This angle shifts the adoption problem from rebuilding every thing to retrofitting incrementally, so organizations can notice AI worth quicker whereas managing danger successfully. For organizations able to discover agentic overlays, the calculator instance supplies a concrete place to begin, and AgentCore affords infrastructure for manufacturing deployments.

Subsequent steps

1. Consider your structure – Audit REST providers for A2A enablement candidates. Inside-application overlays match single-service brokers. AgentCore Gateway suits multi-service workflows.
2. Evaluate the reference implementation – The Flask calculator instance demonstrates the interpretation sample with agent card setup, message extraction, REST invocation, and response constructing.
3. Discover Amazon Bedrock AgentCore – AgentCore Gateway, Id, and Observability present infrastructure for manufacturing agentic overlays.
4. Be part of the A2A neighborhood – The A2A Protocol specification and SDK documentation can be found at a2a-protocol.org, with libraries for Flask, FastAPI, and Starlette purposes.

The way forward for enterprise AI lies not in changing current methods, however in extending them with agentic capabilities. Agentic overlays make that future accessible immediately.

In regards to the authors