A2a Server

SKILL.md

---
name: a2a-server
description: 'Run an A2A inbound task listener that lets this OpenClaw instance receive tasks from other agents via the A2A API Gateway. Use when: (1) starting/stopping the A2A listener service, (2) receiving inbound A2A tasks from other agents, (3) checking if the listener is running. NOT for: sending tasks outbound (use a2a-client), registering this agent (use a2a-register).'
metadata: {"clawdbot":{"emoji":"📡","requires":{"anyBins":["python3"]},"os":["linux","darwin"]}}
---

# A2A Server — Inbound Task Listener

Run an A2A protocol listener that allows this OpenClaw instance to receive tasks routed from the A2A API Gateway. The listener runs as a background HTTP service.

## Sidecar Principle

This skill is strictly an **OpenClaw sidecar** — it receives tasks FROM the A2A API Gateway in whatever format the gateway sends them. The gateway's A2A protocol is the contract; OpenClaw's listener just speaks it. Never assume what the sending system looks like — it could be any agent that routes tasks through the gateway. The listener implements the gateway's expected endpoints as-is.

## Configuration

The listener reads configuration from a shared `a2a.conf` file (located in the `a2a-client` skill directory), with auto-detection fallbacks for local settings.

**Priority order:** CLI flags → env vars → `a2a.conf` → auto-detected defaults

| Setting | Auto-detected Default | Description |
|---------|-----------------------|-------------|
| Port | `8100` | Listen port (`LISTENER_PORT`) |
| Bind Address | Tailscale IP or first NIC | Local bind address (`BIND_ADDR`) |
| Agent Slug | `hostname -s` (lowercase) | Agent identifier (`AGENT_SLUG`) |
| Agent Name | Slug (capitalized) | Display name (`AGENT_NAME`) |
| Agent URL | `http://{bind_addr}:{port}` | Agent endpoint (`AGENT_URL`) |
| Capabilities | `chat,code,research` | Comma-separated (`AGENT_CAPABILITIES`) |
| Auth Type | `bearer` | Auth method (`AGENT_AUTH_TYPE`) |
| API Key | *empty* | Bearer token — **if empty, auth checks are disabled** (`A2A_GATEWAY_API_KEY`) |
| OpenClaw Command | *auto* | Shell command template; `{message}` and `{session_id}` placeholders (`A2A_OPENCLAW_COMMAND`) |
| OpenClaw URL | *empty* | HTTP API URL for chat completions (`A2A_OPENCLAW_URL`) |
| OpenClaw URL API Key | *empty* | Bearer token for HTTP API (`A2A_OPENCLAW_URL_API_KEY`) |
| OpenClaw Timeout | `60` | Max seconds to wait for response (`A2A_OPENCLAW_TIMEOUT`) |

Run `a2a-register/a2a-setup.sh` to configure interactively, or set env vars / create `a2a-client/a2a.conf`.

## When to Use

- **Start the listener** — When this OpenClaw instance needs to receive inbound A2A tasks
- **Stop the listener** — When shutting down or pausing inbound task reception
- **Check listener status** — When verifying the A2A service is running

## Endpoints

The listener (`a2a-listener.py`) handles these routes:

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/health` | Health check — returns `{"status": "ok", "agent": "<slug>"}` |
| `GET` | `/v1/a2a/agents/{slug}` | Returns the agent card for this OpenClaw instance |
| `POST` | `/v1/a2a/tasks/send` | Receives an inbound A2A task (requires Bearer auth if API key is set) |

## Auth

Inbound tasks (`POST /v1/a2a/tasks/send`) require a Bearer token matching the configured `A2A_GATEWAY_API_KEY`. If no API key is configured, auth checks are disabled (with a warning at startup). Health checks and agent card lookups are unauthenticated.

## Tools

### start.sh — Start the Listener

```bash
./start.sh [--port PORT] [--bind ADDR]
```

Starts the A2A listener in the background. All other settings are read from `a2a.conf` or env vars.

```bash
# Start with defaults (from a2a.conf or auto-detected)
./start.sh

# Custom port and bind address
./start.sh --port 8200 --bind 0.0.0.0
```

Saves the PID to `a2a-listener.pid` for management. Logs to `a2a-listener.log`.

### stop.sh — Stop the Listener

```bash
./stop.sh
```

Gracefully stops the A2A listener using the PID file.

### a2a-listener.py — The Listener Process

Python HTTP server that implements the A2A protocol endpoints. Started by `start.sh`. Can also be run directly:

```bash
# Run directly (foreground)
python3 a2a-listener.py

# With custom settings via env vars
LISTENER_PORT=8200 BIND_ADDR=0.0.0.0 A2A_GATEWAY_API_KEY=your-key python3 a2a-listener.py
```

All configuration is loaded from `a2a.conf`, env vars, or auto-detected — no hardcoded values.

## OpenClaw Invocation — Real Responses

When an inbound task arrives, the listener invokes the local OpenClaw instance to produce a real response. The invocation method is configurable, with automatic fallback:

**Priority:** `A2A_OPENCLAW_COMMAND` → `A2A_OPENCLAW_URL` → auto-detect `openclaw` CLI → error

| Env Var | Description | Example |
|---------|-------------|--------|
| `A2A_OPENCLAW_COMMAND` | Shell command template; `{message}` and `{session_id}` are replaced | `openclaw agent -m "{message}" --session-id {session_id} --json` |
| `A2A_OPENCLAW_URL` | HTTP API URL to POST the task to | (any HTTP chat/completions endpoint) |
| `A2A_OPENCLAW_URL_API_KEY` | Bearer token for the HTTP URL | (optional, only used with `A2A_OPENCLAW_URL`) |
| `A2A_OPENCLAW_TIMEOUT` | Max seconds to wait for a response | `60` (default) |

### Auto-Detection

If neither `A2A_OPENCLAW_COMMAND` nor `A2A_OPENCLAW_URL` is set, the listener checks if the `openclaw` CLI is on `PATH`. If found, it runs:

```bash
openclaw agent -m "<message>" --session-id <session_id> --json
```

This uses OpenClaw's built-in agent runtime and returns real AI responses. The `--session-id` flag ensures continuity within a conversation thread.

### Response Format

On success:
```json
{"id": "task-123", "status": "completed", "result": {"kind": "text", "content": "<actual AI response>"}}
```

On failure (invocation error, timeout, etc.):
```json
{"id": "task-123", "status": "failed", "result": {"kind": "text", "content": "<error message>"}}
```

### Configuration Error

If no invocation method is available at all, the task response will have `status: "failed"` with a message explaining how to configure OpenClaw access.

## Typical Workflow

1. **Configure** → Run `a2a-register/a2a-setup.sh` or create `a2a.conf`
2. **Register** → Use the `a2a-register` skill to register this instance in the A2A API Gateway
3. **Start** → `./start.sh` to begin listening for inbound tasks
4. **Verify** → `curl http://YOUR_IP:8100/health` to confirm it's running
5. **Receive** — The gateway routes tasks to this listener automatically
6. **Stop** → `./stop.sh` when done