[ISSUE #5202,#5204]Implement A2A (Agent-to-Agent) protocol

[qqeasonchen]

1. Overview

The EventMesh A2A (Agent-to-Agent) Protocol is a specialized, high-performance protocol plugin designed to enable asynchronous communication, collaboration, and task coordination between autonomous agents.

With the release of v2.0, A2A adopts the MCP (Model Context Protocol) architecture, transforming EventMesh into a robust Agent Collaboration Bus. It bridges the gap between synchronous LLM-based tool calls (JSON-RPC 2.0) and asynchronous Event-Driven Architectures (EDA), enabling scalable, distributed, and decoupled agent systems.

2. Core Philosophy

The architecture adheres to the principles outlined in the broader agent community (e.g., A2A Project, FIPA-ACL, and CloudEvents):

1. JSON-RPC 2.0 as Lingua Franca: Uses standard JSON-RPC for payload semantics, ensuring compatibility with modern LLM ecosystems (LangChain, AutoGen).
2. Transport Agnostic: Encapsulates all messages within CloudEvents, allowing transport over any EventMesh-supported protocol (HTTP, TCP, gRPC, Kafka).
3. Async by Default: Maps synchronous Request/Response patterns to asynchronous Event streams using correlation IDs.
4. Native Pub/Sub Semantics: Supports O(1) broadcast complexity, temporal decoupling (Late Join), and backpressure isolation, solving the scalability limits of traditional P2P webhook callbacks.

2.1 Native Pub/Sub Semantics

Traditional A2A implementations often rely on HTTP Webhooks (POST /inbox) for asynchronous callbacks. While functional, this Point-to-Point (P2P) model suffers from significant scaling issues:

• Insufficient Fan-Out: A publisher must send $N$ requests to reach $N$ subscribers, leading to $O(N)$ complexity.
• Temporal Coupling: Consumers must be online at the exact moment of publication.
• Backpressure Propagation: A slow subscriber can block the publisher.

EventMesh A2A solves this by introducing Native Pub/Sub capabilities:

flowchart LR
    Publisher["Publisher Agent"] -->|1. Publish Once| Bus["EventMesh Bus"]
    
    subgraph FanoutLayer ["EventMesh Fanout Layer"]
        Queue["Topic Queue"]
    end
    
    Bus --> Queue
    
    Queue -->|"Push"| Sub1["Subscriber 1"]
    Queue -->|"Push"| Sub2["Subscriber 2"]
    Queue -->|"Push"| Sub3["Subscriber 3"]
    
    style Bus fill:#f9f,stroke:#333
    style FanoutLayer fill:#ccf,stroke:#333

Loading

2.1 Hybrid Protocol Support (JSON-RPC & CloudEvents)

A2A Protocol introduces a unique Hybrid Architecture that bridges the gap between the AI ecosystem (which prefers simple JSON) and the Cloud Native ecosystem (which prefers structured CloudEvents).

Feature	JSON-RPC 2.0 Mode	Native CloudEvents Mode
Primary Audience	LLMs, Scripts (Python/JS), LangChain	EventMesh Apps, Knative, Java SDK
Philosophy	"Battery Included"	"Power User"
Usage	Send raw JSON ({"method":...})	Send CloudEvent object
Complexity	Low (No SDK required)	Medium (Requires CE SDK)
Mechanism	Adaptor automatically wraps JSON in CE	Adaptor passes through the event

Benefits:

• Zero-Barrier Entry: Developers can interact with the mesh using just curl or simple JSON libraries.
• Full Flexibility: Advanced users retain full control over CloudEvent attributes (Source, Type, Extensions) for complex routing or tracing scenarios.

3. Architecture Design

3.1 System Context

graph TD
    Client["Client Agent / LLM"] -- "JSON-RPC Request" --> EM["EventMesh Runtime"]
    EM -- "CloudEvent (Request)" --> Server["Server Agent / Tool"]
    Server -- "CloudEvent (Response)" --> EM
    EM -- "JSON-RPC Response" --> Client
    
    subgraph Runtime ["EventMesh Runtime"]
        Plugin["A2A Protocol Plugin"]
    end
    
    style EM fill:#f9f,stroke:#333,stroke-width:4px
    style Plugin fill:#ccf,stroke:#333,stroke-width:2px

Loading

3.2 Component Design (eventmesh-protocol-a2a)

The core logic resides in the eventmesh-protocol-plugin module.

• EnhancedA2AProtocolAdaptor: The central brain of the protocol.
  • Intelligent Parsing: Automatically detects message format (MCP vs. Raw CloudEvent).
  • Protocol Delegation: Delegates to CloudEvents or HTTP adaptors when necessary.
  • Semantic Mapping: Transforms JSON-RPC methods and IDs into CloudEvent attributes.
• A2AProtocolConstants: Defines standard operations like task/get, message/sendStream.
• JsonRpc* Models: Strictly typed POJOs for JSON-RPC 2.0 compliance.

3.3 Asynchronous RPC Mapping ( The "Async Bridge" )

To support MCP on an Event Bus, synchronous RPC concepts are mapped to asynchronous events:

Concept	MCP / JSON-RPC	CloudEvent Mapping
Action	method (e.g., tools/call)	Type: org.apache.eventmesh.a2a.tools.call.req Extension: a2amethod
Correlation	id (e.g., req-123)	Extension: collaborationid (on Response) ID: Preserved on Request
Direction	Implicit (Request vs Result)	Extension: mcptype (request or response)
P2P Routing	params._agentId	Extension: targetagent
Pub/Sub Topic	params._topic	Subject: The topic value (e.g. market.btc)
Streaming Seq	params._seq	Extension: seq

4. Functional Specification

4.1 Message Processing Flow

1. Ingestion: The adaptor receives a ProtocolTransportObject (byte array/string).
2. Detection: Checks for jsonrpc: "2.0".
3. Transformation (MCP Mode):
   • Request: Parses method.
     • If message/sendStream, sets type suffix to .stream and extracts _seq.
     • If _topic present, sets subject (Pub/Sub).
     • If _agentId present, sets targetagent (P2P).
   • Response: Parses result/error. Sets collaborationid = id.
4. Batch Processing: Splits JSON Array into a List<CloudEvent>.

4.2 Key Features

A. Intelligent Routing Support

• Mechanism: Promotes _agentId or _topic from JSON body to CloudEvent attributes.
• Benefit: Enables EventMesh Router to perform content-based routing (CBR) efficiently.

B. Batching

• Benefit: Significantly increases throughput for high-frequency interactions.

C. Streaming Support

• Operation: message/sendStream
• Mechanism: Maps to .stream event type and preserves sequence order via seq extension attribute.

5. Usage Examples

5.1 JSON-RPC 2.0 (MCP) Mode

This mode is ideal for LLMs, scripts, and simple integrations where you want to send raw JSON without worrying about CloudEvent headers.

5.1.1 Sending a Tool Call (RPC Request)

Client Sends (Raw JSON):

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "weather",
    "city": "Shanghai",
    "_agentId": "weather-agent"
  },
  "id": "req-101"
}

EventMesh Converts to:

• Type: org.apache.eventmesh.a2a.tools.call.req
• Extension (targetagent): weather-agent
• Extension (mcptype): request

5.1.2 Pub/Sub Broadcast (Notification)

Client Sends (Raw JSON):

{
  "jsonrpc": "2.0",
  "method": "notifications/alert",
  "params": {
    "message": "System Maintenance in 10 mins",
    "_topic": "system.alerts"
  }
}

EventMesh Converts to:

• Type: org.apache.eventmesh.a2a.notifications.alert
• Subject: system.alerts
• Extension (mcptype): notification

5.1.3 Java SDK Example (MCP Mode)

// See eventmesh-examples/src/main/java/org/apache/eventmesh/a2a/demo/mcp/McpCaller.java

Map<String, Object> request = new HashMap<>();
request.put("jsonrpc", "2.0");
request.put("method", "tools/call");
request.put("params", Map.of("name", "weather", "_agentId", "weather-agent"));
request.put("id", UUID.randomUUID().toString());

CloudEvent event = CloudEventBuilder.v1()
    .withType("org.apache.eventmesh.a2a.tools.call.req")
    .withData(JsonUtils.toJSONString(request).getBytes())
    .withExtension("protocol", "A2A") // Critical to trigger A2A adaptor
    .build();

producer.publish(event);

5.2 Native CloudEvents Mode

This mode provides full control over all CloudEvent attributes and is recommended for robust, typed applications using the EventMesh SDK.

5.2.1 Native RPC Request

Client Sends (CloudEvent):

{
  "specversion": "1.0",
  "type": "com.example.rpc.request",
  "source": "my-app",
  "id": "evt-123",
  "data": "...",
  "protocol": "A2A",
  "targetagent": "target-agent-001"
}

Java SDK Example:

// See eventmesh-examples/src/main/java/org/apache/eventmesh/a2a/demo/ce/CloudEventsCaller.java

CloudEvent event = CloudEventBuilder.v1()
    .withId(UUID.randomUUID().toString())
    .withSource(URI.create("ce-client"))
    .withType("com.example.rpc.request")
    .withData("application/text", "RPC Payload".getBytes())
    .withExtension("protocol", "A2A")
    .withExtension("targetagent", "target-agent-001") // Explicit routing
    .build();

producer.publish(event);

5.2.2 Native Pub/Sub

Client Sends (CloudEvent):

{
  "specversion": "1.0",
  "type": "com.example.notification",
  "source": "my-app",
  "subject": "broadcast.topic",
  "protocol": "A2A"
}

5.2.3 Native Streaming

Client Sends (CloudEvent):

{
  "specversion": "1.0",
  "type": "com.example.stream",
  "source": "my-app",
  "subject": "stream-topic",
  "protocol": "A2A",
  "sessionid": "session-555",
  "seq": "1"
}

6. Future Roadmap

• Schema Registry: Implement dynamic discovery of Agent capabilities via methods/list.
• Sidecar Injection: Fully integrate the adaptor into the EventMesh Sidecar.%

[Copilot]

Pull Request Overview

This PR implements a complete A2A (Agent-to-Agent) communication protocol for EventMesh that transforms simple point-to-point messaging into a comprehensive EventMesh-native publish/subscribe platform. The implementation provides intelligent multi-agent collaboration through topic-based routing and leverages EventMesh's existing infrastructure while adding enhanced protocol management capabilities.

Key Changes:

• Complete A2A publish/subscribe service implementation using EventMesh Producer/Consumer
• Enhanced protocol plugin factory with caching, routing, and performance monitoring
• CloudEvents 1.0 compliant protocol adapters with delegation pattern support
• Agent lifecycle management with capability-based routing and automatic load balancing

Reviewed Changes

Copilot reviewed 39 out of 39 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
settings.gradle	Adds A2A protocol plugin to build configuration
examples/a2a-agent-client/	Complete example implementation with Docker support and comprehensive documentation
eventmesh-runtime/.../a2a/pubsub/	Core publish/subscribe service implementation with EventMesh integration
eventmesh-runtime/.../a2a/processor/	HTTP processor for A2A-specific endpoints
eventmesh-runtime/.../a2a/service/	gRPC service integration for A2A communication
eventmesh-protocol-plugin/eventmesh-protocol-a2a/	Basic and enhanced A2A protocol adapters
eventmesh-protocol-plugin/eventmesh-protocol-api/	Enhanced protocol factory, router, and metrics system
eventmesh-runtime/conf/	A2A protocol configuration template
docs/a2a-protocol/	Comprehensive documentation and test results

Comments suppressed due to low confidence (1)

examples/a2a-agent-client/src/main/java/org/apache/eventmesh/examples/a2a/A2AProtocolExample.java:1

• References to A2AProtocolAdaptor.A2AMessage and A2AProtocolAdaptor.AgentInfo will cause compilation errors since these are not defined as inner classes in the A2AProtocolAdaptor. These should reference the correct classes or the inner classes need to be properly defined.

package org.apache.eventmesh.examples.a2a;

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

These imports reference classes that don't exist in the codebase. The A2AProtocolAdaptor class in the diff doesn't contain inner classes A2AMessage, AgentInfo, or MessageMetadata, which will cause compilation errors.

Suggested change

	import org.apache.eventmesh.runtime.core.protocol.a2a.A2AProtocolAdaptor.A2AMessage;
	import org.apache.eventmesh.runtime.core.protocol.a2a.A2AProtocolAdaptor.AgentInfo;
	import org.apache.eventmesh.runtime.core.protocol.a2a.A2AProtocolAdaptor.MessageMetadata;

[Copilot]

The A2AMessage class is referenced but not imported or defined in this file. This will cause compilation errors. The class needs to be properly imported or referenced.

[Copilot]

The variable messageRouter is referenced but not declared or initialized in this class. This will cause a compilation error.

[Copilot]

[nitpick] The AgentInfo class is defined as a nested class within A2AProtocolAdaptor, but it's also referenced in the runtime package. Consider extracting this as a shared class in a common package to avoid circular dependencies and improve maintainability.

Suggested change

	*/
	public static class AgentInfo {
	private String agentId;
	private String agentType;
	private String[] capabilities;
	private Map<String, Object> metadata;
	public String getAgentId() {
	return agentId;
	}
	public void setAgentId(String agentId) {
	this.agentId = agentId;
	}
	public String getAgentType() {
	return agentType;
	}
	public void setAgentType(String agentType) {
	this.agentType = agentType;
	}
	public String[] getCapabilities() {
	return capabilities;
	}
	public void setCapabilities(String[] capabilities) {
	this.capabilities = capabilities;
	}
	public Map<String, Object> getMetadata() {
	return metadata;
	}
	public void setMetadata(Map<String, Object> metadata) {
	this.metadata = metadata;
	}
	}
	* @deprecated Moved to org.apache.eventmesh.common.AgentInfo
	*/
	// public static class AgentInfo { ... } // Removed. Use org.apache.eventmesh.common.AgentInfo instead.

[github-actions]

It has been 60 days since the last activity on this pull request. I am reaching out here to gently remind you that the Apache EventMesh community values every pull request, and please feel free to get in touch with the reviewers at any time. They are available to assist you in advancing the progress of your pull request and offering the latest feedback.

If you encounter any challenges during development, seeking support within the community is encouraged. We sincerely appreciate your contributions to Apache EventMesh.

[xwm1992]

LGTM