AMCP v1.5 Technical Specification

1. Core Principles

• Event-Driven Asynchrony: Communication is primarily through asynchronous event publication, minimizing blocking and maximizing throughput, enabling **10K+ messages/sec** per context.
• Agent Mobility (Strong Mobility): Agents are not bound to a single process; they can be serialized and moved between remote **AgentContexts** (`dispatch()`) or cloned (`clone()`) for workload distribution and resilience.
• Loosely Coupled Mesh: Agents communicate via the **EventBroker** without needing prior knowledge of recipient location or state, enabling dynamic topology.
• Contextual Isolation: Each agent operates within a secure **AgentContext**, ensuring isolation of state, credentials, and resources.
• Protocol Bridge: Native support for bridging to other protocols like Google **A2A (Agent-to-Agent)** and **MCP (Model Context Protocol)**.

2. Architecture Components

2.1. Agent & AgentContext

The **Agent** is the fundamental unit of computation, embodying logic, state, and a unique identifier. The **AgentContext** serves as the agent's runtime environment, providing resources and enforcing boundaries.

// Java Interface Example
public interface Agent {
    UUID getId();
    String getType();
    void setContext(AgentContext context);
    void handleEvent(Event event);
    // Lifecycle methods required for mobility
    byte[] serializeState();
    void deserializeState(byte[] state);
}

// Pseudocode for Agent Context
AgentContext {
    AgentRegistry registry;
    EventBroker broker;
    SecurityManager security;
    
    // Public endpoint for communication/mobility
    Endpoint getEndpoint(); 
    
    // Method to inject and start a new agent
    void injectAgent(Agent agent, UUID callerId, SecurityToken token); 
}

2.2. EventBroker

The **EventBroker** is the central communication bus, abstracting the underlying messaging technology (Kafka, NATS, Solace). It handles topic-based routing, QoS, and guaranteed delivery.

• **Topic Structure:** Events are routed based on well-defined topics, e.g., amcp.agent.{agentId} for direct messaging, or amcp.domain.{type} for pub/sub.
• **Topic Naming:** Must be hierarchical and adhere to security policies for access control.

3. Protocol & Data Model

3.1. AMCP Event (CloudEvents)

All communication is encapsulated in the **AMCP Event**, which adheres strictly to the CloudEvents v1.0 specification for interoperability.

3.2. Message Exchange Types

• **Publish/Subscribe:** Agent publishes event to a **topic** (e.g., amcp.domain.weather). All subscribed agents receive it.
• **Point-to-Point (P2P):** Agent publishes event to a **direct agent topic** (e.g., amcp.agent.b03a4...). Only the target agent receives it.
• **Request/Reply (via Correlation):** The initiator publishes an event with a **Correlation ID** and a **Reply-To Topic**. The responder replies to the unique Reply-To topic, enabling asynchronous R/R over the event mesh.

4. Agent Mobility Mechanism (Strong Mobility)

Agent Mobility is a core feature, allowing agents to move their execution state (Strong Mobility) between different **AgentContexts**. This is critical for load balancing, fault tolerance, and moving computation closer to data.

4.1. The dispatch() Process

The dispatch(AgentID, TargetContextURL) operation is performed as a transaction over the EventBroker and HTTP/HTTPS.

// Pseudocode for Agent Mobility Dispatch
function dispatch(agentId, targetUrl, token):
    // Step 1: Suspend Agent & Capture State (Serialization)
    agent = AgentRegistry.lookup(agentId);
    agent.suspend(); 
    serializedState = agent.serializeState(); // Capture execution state and object graph
    
    // Step 2: Prepare Mobility Payload
    payload = {
        "agentId": agentId,
        "agentType": agent.getType(),
        "serializedState": serializedState,
        "sourceContext": AgentContext.getEndpoint()
    };
    
    // Step 3: Secure Transfer (HTTPS)
    response = HTTP.post(targetUrl + "/inject", payload, Headers: {"Authorization": "Bearer " + token});
    
    if response.status == 200:
        // Step 4: Finalize Source Context Cleanup
        AgentRegistry.remove(agentId);
        EventBroker.publish(
            Event(type="amcp.mobility.dispatched", source=agentId, data={...})
        );
        return Success;
    else:
        // Step 5: Rollback
        agent.resume(); 
        return Failure(response.error);

• **Clone:** A clone() operation follows the same transfer steps but skips Step 4 (Cleanup), allowing the original agent to continue execution.
• **Retract:** A retract() operation is essentially a dispatch() where the target is the agent's originating context, often triggered by a timeout or failure signal.

5. Security Model

The AMCP security model is layered, leveraging established standards for identity and transport security.

• **Transport Security:** **Mutual TLS (mTLS)** is the mandatory baseline for communication between all **AgentContexts** (inter-context communication).
• **Agent Authentication:** Agents are authenticated using **JSON Web Tokens (JWT)**. These tokens are issued by the **SecurityManager** of the AgentContext upon creation or injection and are attached to every outgoing event or mobility request.
• **Authorization (Topic-Level):** Access to EventBroker topics (e.g., publish, subscribe) is governed by **ACLs (Access Control Lists)** bound to the JWT claims (AgentID, ContextID, Roles).
• **Agent State Verification:** Mobility operations include a digital signature of the serialized state to prevent unauthorized state tampering during transfer.

6. Deployment & Integration

6.1. Event Broker Integration

AMCP is agnostic to the underlying broker, requiring only a compliant EventBroker implementation. Enterprise solutions are provided for:

6.2. Kubernetes Deployment

AgentContexts are designed to be deployed as stateless (or near-stateless) microservices within a **Kubernetes** cluster.

• **Containerization:** Each AgentContext instance is a container (Docker, JVM-based) exposing a minimal set of ports (e.g., 8080/HTTP for mobility injection, 9090/Metrics).
• **Liveness/Readiness Probes:** Standard Kubernetes probes are implemented at /health and /ready endpoints to ensure proper lifecycle management.
• **Horizontal Scaling:** Scaling the number of AgentContext pods allows for elastic scaling of the agent mesh. The EventBroker ensures load balancing of topic subscriptions across all replicas.

6.3. Performance Tuning (JVM Reference)

For Java implementations, the following JVM flags are recommended for enterprise-grade performance, focusing on minimizing garbage collection latency.

JAVA_OPTS="
  -Xms4g -Xmx8g               // Initial/Maximum Heap Size
  -XX:+UseG1GC                // Use the Garbage First Collector
  -XX:MaxGCPauseMillis=200    // Target max pause time
  -XX:ParallelGCThreads=8     // Parallel threads for GC
  -XX:ConcGCThreads=2         // Concurrent threads for GC
  -XX:InitiatingHeapOccupancyPercent=45 // Start GC earlier
  -XX:+UseStringDeduplication // Save memory by deduplicating strings
"