GitHub - hemanth/A2A-XKCD: A minimal A2A (Agent-to-Agent) compatible agent that fetches and displays XKCD comics.

XKCD Agent for A2A

A minimal A2A (Agent-to-Agent) compatible agent that fetches and displays XKCD comics.

Features

• Latest, random, and specific comic retrieval
• Smart search through comic titles and alt text
• Full A2A protocol compliance
• Agent discovery via well-known path

Data Flow

flowchart TD
    A[Client Request] --> B[A2AServer]
    B --> C[Authentication]
    C --> D[JSON-RPC Handler]
    D --> E[XKCDAgent]
    E --> F[XKCD API]
    F --> G[Comic Data]
    G --> E
    E --> H[TaskUpdater]
    H --> I[EventQueue]
    I --> J[Response to Client]
    
    style A fill:#e1f5fe
    style J fill:#e8f5e8
    style F fill:#fff3e0
    style G fill:#fff3e0

Quick Start

1. Install dependencies:

   pip install -r requirements.txt

2. Start the A2A server:

3. Test the server (in another terminal):

   # Check health
   curl http://localhost:8080/health
   
   # Get agent card
   curl http://localhost:8080/.well-known/agent.json
   
   # Authenticate to get JWT token
   curl -X POST http://localhost:8080/auth \
     -H "Content-Type: application/json" \
     -d '{
       "username": "demo_user",
       "password": "demo_pass",
       "client_id": "test_client"
     }'
   
   # Send JSON-RPC request (use token from auth response)
   curl -X POST http://localhost:8080/agent \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN_HERE" \
     -d '{
       "jsonrpc": "2.0",
       "method": "tasks/send",
       "params": {
         "id": "test-123",
         "message": {
           "role": "user",
           "parts": [{"root": {"text": "latest"}}]
         }
       },
       "id": "req-1"
     }'

A2A Endpoints

JSON-RPC Methods

• tasks/send - Execute a task
• tasks/get - Get task status
• tasks/cancel - Cancel a task
• tasks/sendSubscribe - Execute with streaming

Authentication

The server implements secure credential-based authentication with the following features:

Authentication Methods

• Bearer Token: JWT-based authentication with username/password validation
• None: Optional no-auth mode (configurable in agent card)

Security Features

• Secure password hashing using HMAC-SHA256
• Rate limiting: 5 failed attempts per IP address in 5 minutes
• Comprehensive input validation and error handling
• 24-hour JWT token expiration

Available Test Accounts

Authentication Request Format

{
  "username": "demo_user",
  "password": "demo_pass",
  "client_id": "optional_client_id"
}

Authentication Response

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "agent:execute"
}

Files

├── agent_card.json        # A2A agent card
├── .well-known/
│   └── agent.json         # Agent discovery endpoint
├── xkcd_agent.py          # Core agent implementation  
├── a2a_server.py          # A2A server implementation
├── requirements.txt       # Dependencies
└── README.md              # This file

Dependencies

• a2a-sdk - A2A framework
• aiohttp - HTTP server
• aiohttp-cors - CORS support
• PyJWT - JWT authentication

License

MIT