Show HN: A2A Xkcd Agent as per the Spec

4 months ago 4

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

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

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

Install dependencies:

pip install -r requirements.txt
Start the A2A server:
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" }'

Endpoint Method Purpose

/.well-known/agent.json	GET	Agent discovery
/auth	POST	Authentication (optional)
/agent	POST	JSON-RPC task execution
/health	GET	Health check

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

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

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

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

Username Password Description

xkcd_user	xkcd_password_123	Primary XKCD agent user
agent_client	secure_client_key	Client application user
demo_user	demo_pass	Demo/testing user

Authentication Request Format

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

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

├── 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