A2A-MCP Java Bridge

Developers annotate standard Java methods with @Action, @Agent, and @ActionParameter decorators; the framework's PredictionLoader package scanner automatically introspects these annotations at startup and registers the same method as both an A2A Skill (discoverable at /.well-known/agent.json) and an MCP Tool (via tools/list endpoint). A unified AIProcessor orchestrates invocation through both protocols without code duplication, using protocol-specific controllers (DynamicTaskController for A2A, MCPToolsController for MCP) that delegate to the same underlying business logic.

The AIProcessor interface abstracts LLM invocation across Gemini, OpenAI, and Anthropic, with concrete implementations (GeminiV2ActionProcessor, OpenAiActionProcessor, AnthropicActionProcessor) that handle provider-specific request/response formatting, streaming, and tool-calling conventions. The framework selects the appropriate processor at runtime based on configuration, allowing a single @Action method to be invoked by different LLM providers without code changes. Integration with tools4ai library enables structured tool-calling across all providers.

The framework provides ActionCallback interface and custom callback implementations (SSEEmitterCallback, etc.) that allow developers to hook into action execution lifecycle (before, during, after) and extend protocol behavior. Callbacks receive execution context including action name, parameters, and results, enabling custom logging, monitoring, authorization, and result transformation. Protocol extensions can be implemented by subclassing controller classes and overriding request/response handling, allowing teams to add custom headers, authentication schemes, or result formatting without modifying core framework code.

The framework provides A2ATaskClientTest and regression test utilities that enable developers to test agent actions via both A2A and MCP protocols without deploying to a server. Test utilities include mock clients (A2AAgent, MCPAgent) that invoke actions directly, assertion helpers for validating results, and fixtures for common test scenarios. The testing framework integrates with Spring Boot Test, allowing agents to be tested in isolation with mocked LLM providers or real providers depending on test requirements.

The DynamicTaskController implements asynchronous task execution for long-running @Action methods, assigning unique task IDs and allowing clients to poll for completion status via REST endpoints. Task state is tracked in memory (or can be persisted to external storage), with endpoints for task creation (/task/create), status polling (/task/status/{taskId}), and result retrieval (/task/result/{taskId}). This enables non-blocking client interactions where clients submit tasks and check back later, rather than blocking on action execution. The controller integrates with SSEEmitterCallback for streaming intermediate results during task execution.

The SSEEmitterCallback and SseEmitter components enable Server-Sent Events streaming for long-running @Action methods, allowing clients to receive intermediate results and status updates without blocking. The framework wraps action execution in a streaming context that captures callbacks and pushes them to HTTP clients via Spring's SseEmitter, with protocol-aware formatting for both A2A and MCP consumers. This enables interactive agent experiences where users see progress in real-time rather than waiting for final results.

The AgenticMesh class implements multi-agent orchestration patterns where multiple @Agent instances are registered in an AgentCatalog, and incoming requests are routed to the most appropriate agent based on AI-powered selection logic. The framework uses the configured LLM provider to analyze request intent and select the best agent, then delegates execution to that agent's actions. This enables hierarchical agent systems where a coordinator agent can decompose tasks and route sub-tasks to specialist agents, with all routing decisions made by the LLM rather than hardcoded rules.

The DynamicTaskController implements the A2A (Agent-to-Agent) protocol task lifecycle, handling task creation, status polling, and result retrieval through REST endpoints. The framework automatically generates A2A Skill definitions from @Action annotations and exposes them at /.well-known/agent.json for discovery by A2A-compatible clients (e.g., Gemini agents). Task execution is tracked with unique task IDs, allowing asynchronous clients to poll for completion status and retrieve results without blocking, with support for long-running operations via SSE streaming.

The MCPToolsController and JSON-RPC Controller Gateway implement the MCP (Model Context Protocol) server specification, exposing @Action methods as MCP Tools via JSON-RPC 2.0 endpoints. The framework handles MCP tool listing (tools/list), tool invocation (tools/call), and result serialization, with automatic schema generation from @ActionParameter annotations. The JSON-RPC gateway routes incoming MCP requests to the appropriate controller, handling protocol-level concerns (request/response formatting, error handling) while delegating business logic to the unified AIProcessor.

The AgentCard class and DynamicAgentCardController automatically generate capability metadata from @Agent and @Action annotations, exposing agent descriptions, action names, parameter schemas, and return types. This metadata is used for agent discovery (in AgentCatalog), multi-agent routing (in AgenticMesh), and protocol-level schema generation (for A2A and MCP). The framework introspects Java method signatures and annotation values to build rich capability descriptions without manual metadata definition.

The A2UI Extension System provides component builders that generate UI schemas compatible with both A2A and MCP protocols, allowing @Action methods to specify rich UI hints (dropdowns, date pickers, text areas) that render correctly in both Gemini and Claude clients. The framework abstracts protocol-specific UI representation differences, translating a single A2UI component definition into both A2A and MCP UI schemas. This enables agent developers to define rich UIs once and have them work across multiple LLM platforms.

The framework provides native client libraries for Java (A2AAgent, MCPAgent), Node.js (stdio bridge via mcpserver.js), and Python (MCP client adapters) that enable applications in different languages to invoke A2A and MCP servers. The Java clients use the same annotation model as servers, allowing symmetric agent development. The Node.js and Python clients implement protocol-specific adapters that handle JSON-RPC marshaling and protocol state management, enabling polyglot agent systems where agents written in different languages can communicate via A2A or MCP.

The framework integrates deeply with Spring Boot via @EnableAgent annotation and properties-based configuration (application.properties or application.yml), allowing developers to configure AI providers, protocol settings, and agent behavior without code changes. Spring's component scanning automatically discovers @Agent and @Action classes, registers them as beans, and wires them into controllers. Properties like a2a.enabled, mcp.enabled, and ai.provider control which protocols and LLM providers are active, enabling environment-specific configuration (e.g., Gemini in production, OpenAI in development).