Content
# 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
```mermaid
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**:
```bash
pip install -r requirements.txt
```
2. **Start the A2A server**:
```bash
python a2a_server.py
```
3. **Test the server** (in another terminal):
```bash
# 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
| Endpoint | Method | Purpose |
|----------|---------|---------|
| `/.well-known/agent.json` | GET | Agent discovery |
| `/auth` | POST | Authentication (optional) |
| `/agent` | POST | JSON-RPC task execution |
| `/health` | GET | Health check |
## 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
| 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
```json
{
"username": "demo_user",
"password": "demo_pass",
"client_id": "optional_client_id"
}
```
### Authentication Response
```json
{
"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
