A2A Protocol Implementation

Overview

The Aitana platform implements the A2A (Agent-to-Agent) protocol, enabling interoperability with other AI agents that follow the A2A standard. The implementation is fully compliant with the A2A protocol specifications as defined at https://a2a-protocol.org/.

Compliance Status ✅

Your A2A implementation is compliant with the protocol specifications:

✅ Required Endpoints Implemented

/.well-known/agent.json - Agent discovery endpoint
/a2a/tasks/send - Standard message transmission
/a2a/tasks/sendSubscribe - Streaming message operations
/a2a/tasks/get - Task status retrieval
/a2a/tasks/cancel - Task cancellation
/a2a/tasks/pushNotification/set - Push notification configuration

✅ Protocol Requirements Met

JSON-RPC Communication: Uses JSON for all message exchanges
HTTPS Security: Supports secure communication
Authentication: Supports JWT tokens and OpenID Connect
Streaming: Implements Server-Sent Events (SSE) for streaming responses
Agent Card: Provides comprehensive agent capabilities discovery

Architecture

Backend Implementation (Port 1956)

The backend FastAPI application (backend/app_fastapi.py) has A2A support enabled:

app, vac_routes = VACRoutesFastAPI.create_app_with_mcp(
    enable_a2a_agent=True,  # A2A protocol enabled
    # ... other configuration
)

Frontend Proxy (Port 3000)

The frontend Next.js application provides web-accessible A2A endpoints through proxy routes:

General A2A Proxy: /api/a2a/[...path]/route.ts
- Proxies all A2A protocol endpoints
- Handles authentication headers (JWT, Authorization)
- Supports streaming responses
- Adds CORS headers for cross-origin access
Agent Card Endpoint: /.well-known/agent.json/route.ts
- Serves the agent discovery document
- Updates URLs to use frontend proxy endpoints
- Adds CORS configuration

Available Endpoints

Public Web Access (Through Frontend Proxy)

https://your-domain.com/.well-known/agent.json
https://your-domain.com/api/a2a/a2a/tasks/send
https://your-domain.com/api/a2a/a2a/tasks/sendSubscribe
https://your-domain.com/api/a2a/a2a/tasks/get
https://your-domain.com/api/a2a/a2a/tasks/cancel
https://your-domain.com/api/a2a/a2a/tasks/pushNotification/set

Direct Backend Access (Internal)

http://localhost:1956/.well-known/agent.json
http://localhost:1956/a2a/tasks/send
http://localhost:1956/a2a/tasks/sendSubscribe
http://localhost:1956/a2a/tasks/get
http://localhost:1956/a2a/tasks/cancel
http://localhost:1956/a2a/tasks/pushNotification/set

Agent Capabilities

The agent card exposes multiple VACs (Virtual Assistant Configurations) with various capabilities:

Task Management: Handle complex, multi-step operations
Streaming: Real-time response streaming via SSE
Conversation: Multi-turn dialogue support
Document Retrieval: Access to knowledge bases
Memory Search: Query agent memory and knowledge

Security Features

Authentication Methods

JWT Tokens: Via X-JWT-Token header
OAuth 2.0: Via Authorization header
OpenID Connect: For identity verification

CORS Configuration

Allows cross-origin requests
Configurable allowed origins
Supports preflight requests

Testing the Implementation

1. Check Agent Card

# Through frontend proxy (public)
curl https://your-domain.com/.well-known/agent.json

# Direct backend
curl http://localhost:1956/.well-known/agent.json

2. Send a Message

curl -X POST https://your-domain.com/api/a2a/a2a/tasks/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "query": "Hello, agent!",
    "context": {}
  }'

3. Stream a Response

curl -X POST https://your-domain.com/api/a2a/a2a/tasks/sendSubscribe \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "query": "Tell me a story",
    "stream_settings": {
      "wait_time": 7,
      "timeout": 120
    }
  }'

Integration with Other A2A Agents

To integrate with another A2A-compliant agent:

Discover their capabilities: Fetch their /.well-known/agent.json
Authenticate: Use their specified authentication method
Send messages: Use their /a2a/tasks/send endpoint
Handle responses: Process JSON-RPC formatted responses

Development Setup

Local Testing

# Start backend
cd backend
uv run app.py

# Start frontend (in another terminal)
npm run dev

# Test A2A endpoints
curl http://localhost:3000/.well-known/agent.json

Production Deployment

The A2A endpoints are automatically exposed when deploying to production:

Frontend proxy handles public-facing requests
Backend processes A2A protocol operations
Google Cloud Run provides automatic HTTPS

Monitoring and Debugging

Request Tracking

All A2A requests include an X-Request-ID header for tracing:

Frontend proxy logs: [A2A Proxy][request-id]
Backend logs: Check logs/backend.log

Common Issues

CORS Errors: The proxy adds appropriate CORS headers automatically
Authentication Failures: Ensure JWT tokens are properly forwarded
Timeout Issues: Default timeout is 120 seconds for long-running operations
Streaming Interruptions: Check network stability and SSE support

Future Enhancements

Add webhook support for async task completion
Implement rate limiting per agent
Add agent reputation/trust scoring
Support for batch message processing
Enhanced error recovery for streaming

Aitana Documentation