A2A Server , Inbound Task Listener

intent

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 and responds to inbound task requests by invoking the local openclaw instance. use this skill when: (1) starting or stopping the a2a listener service on this agent, (2) receiving inbound a2a tasks from other agents through the gateway, or (3) checking if the listener is running and healthy. do not use this for sending tasks outbound (use a2a-client instead) or for registering this agent with the gateway (use a2a-register instead).

inputs

environment and configuration

• python3 binary on PATH (required to run a2a-listener.py)
• shared a2a.conf file in the a2a-client skill directory (optional; auto-detected defaults apply if missing)
• cli flags: --port PORT, --bind ADDR (optional overrides for start.sh)
• environment variables (override a2a.conf and auto-detected defaults):
  • LISTENER_PORT (default: 8100)
  • BIND_ADDR (default: tailscale ip or first network interface)
  • AGENT_SLUG (default: hostname lowercase)
  • AGENT_NAME (default: slug capitalized)
  • AGENT_URL (default: http://{bind_addr}:{port})
  • AGENT_CAPABILITIES (default: chat,code,research)
  • AGENT_AUTH_TYPE (default: bearer)
  • A2A_GATEWAY_API_KEY (default: empty; auth disabled if not set)
  • A2A_OPENCLAW_COMMAND (default: auto-detected)
  • A2A_OPENCLAW_URL (default: empty)
  • A2A_OPENCLAW_URL_API_KEY (default: empty)
  • A2A_OPENCLAW_TIMEOUT (default: 60 seconds)

external connections

• a2a api gateway (http endpoint that routes tasks to this listener; requires bearer token in A2A_GATEWAY_API_KEY if auth is enabled)
• local openclaw instance (invoked by listener to generate responses; accessible via cli command, http api, or auto-detected openclaw binary)
• tailscale network or local network interfaces (for bind address auto-detection)

configuration priority order cli flags (highest) → environment variables → a2a.conf file → auto-detected defaults (lowest)

procedure

step 1: verify prerequisites

input: system environment

• check that python3 is installed and on PATH: python3 --version
• verify the a2a-client skill directory exists or will be created during a2a-register setup

output: confirmation that prerequisites are met or error message if python3 is missing

step 2: configure the listener (optional if using defaults)

input: user choices for agent metadata and openclaw invocation

• run a2a-register/a2a-setup.sh to create or edit a2a.conf interactively, or
• set environment variables directly (e.g., export LISTENER_PORT=8100), or
• edit a2a-client/a2a.conf by hand with key=value pairs

output: a2a.conf file with configuration, or environment variables set in the current shell session

step 3: start the listener

input: listener port (from config or cli flag), bind address (from config or cli flag), all other settings from a2a.conf or env vars

• run ./start.sh [--port PORT] [--bind ADDR]
• start.sh sources a2a.conf, applies cli flag overrides, and launches a2a-listener.py in the background
• start.sh saves the listener process id (pid) to a2a-listener.pid
• start.sh logs listener output to a2a-listener.log

output: a2a-listener.pid file containing the running process id, a2a-listener.log file with startup logs, listener process running in background

step 4: verify listener is running

input: none (checking local state)

• run curl http://{BIND_ADDR}:{LISTENER_PORT}/health to test the health endpoint
• response should be {"status": "ok", "agent": "<agent_slug>"}
• alternatively, check if a2a-listener.pid exists and the process is still alive: kill -0 $(cat a2a-listener.pid) 2>/dev/null && echo "running" || echo "stopped"

output: http 200 response with health json, or error message if listener is not responding

step 5: register with the a2a api gateway (optional, done separately)

input: none (this step is part of the a2a-register skill workflow)

• use the a2a-register skill to POST this agent's metadata to the gateway
• the gateway will then route inbound tasks to the agent url configured in step 2

output: agent registered in the gateway; subsequent inbound tasks will be routed to this listener

step 6: receive and process inbound tasks (ongoing)

input: inbound http POST to /v1/a2a/tasks/send with json body containing task details and bearer token in authorization header

• listener validates the bearer token against A2A_GATEWAY_API_KEY if configured
• listener extracts message and session_id from the task json
• listener invokes openclaw using one of: a2a_openclaw_command (shell command), a2a_openclaw_url (http post), auto-detected openclaw cli, or returns error if none available
• listener waits up to A2A_OPENCLAW_TIMEOUT seconds for a response
• listener formats the response as {"id": "", "status": "completed" or "failed", "result": {"kind": "text", "content": ""}}
• listener sends http 200 with response json back to the gateway

output: http 200 response json with task result, or http 401 (auth failed), 400 (invalid request), 500 (invocation error)

step 7: stop the listener (when done)

input: none (uses a2a-listener.pid)

• run ./stop.sh
• stop.sh reads the pid from a2a-listener.pid, sends sigterm to the process, waits for graceful shutdown
• stop.sh deletes a2a-listener.pid after confirming the process has exited

output: listener process terminated, a2a-listener.pid file deleted, log message confirming shutdown

decision points

if api key is configured (a2a_gateway_api_key is set)

• listener requires bearer token in http authorization header for post /v1/a2a/tasks/send
• requests without the header or with an invalid token receive http 401
• health and agent card endpoints remain unauthenticated

else (a2a_gateway_api_key is empty)

• listener logs a warning at startup: "A2A_GATEWAY_API_KEY not set; authentication is disabled"
• all endpoints including /v1/a2a/tasks/send accept requests without auth
• use this mode only in fully trusted networks

for openclaw invocation, priority order is:

1. if A2A_OPENCLAW_COMMAND is set, use it as a shell command template (replace {message} and {session_id})
2. else if A2A_OPENCLAW_URL is set, http post the task json to that url (include bearer token from A2A_OPENCLAW_URL_API_KEY if set)
3. else if openclaw binary is found on PATH, run openclaw agent -m "<message>" --session-id <session_id> --json
4. else task response has status "failed" with error message: "no openclaw invocation method available"

if openclaw invocation times out (exceeds a2a_openclaw_timeout)

• task response has status "failed" with error message: "openclaw invocation timed out after N seconds"

if openclaw invocation returns non-zero exit code or http error

• task response has status "failed" with error message: "openclaw invocation failed: "

if the inbound task json is malformed (missing message, session_id, or id)

• listener responds with http 400 and error json

if a2a-listener.pid does not exist when running stop.sh

• stop.sh logs a warning and exits cleanly (no error)

if the bind address cannot be auto-detected (no tailscale, no network interfaces)

• listener defaults to 127.0.0.1
• listener logs a warning that only localhost tasks will be routed correctly

output contract

successful listener startup

• a2a-listener.pid file exists and contains a valid process id
• a2a-listener.log file exists with startup logs (no errors)
• curl to http://{BIND_ADDR}:{LISTENER_PORT}/health returns http 200 with {"status": "ok", "agent": ""}
• listener is bound to the configured port and listening for http requests

successful task processing

• listener receives inbound POST to /v1/a2a/tasks/send
• listener returns http 200 with json: {"id": "", "status": "completed", "result": {"kind": "text", "content": ""}}
• response content is the actual text output from the openclaw invocation

failed task processing

• listener returns http 200 with json: {"id": "", "status": "failed", "result": {"kind": "text", "content": ""}}
• error message describes the failure (timeout, auth failure, invocation error, malformed request, etc.)

successful listener shutdown

• stop.sh script completes without error
• a2a-listener.pid file is deleted
• process is no longer listed in ps output
• subsequent curl to /health endpoint times out or refuses connection

misconfiguration or missing dependencies

• if python3 is missing, start.sh fails with error message
• if a2a.conf is missing and all env vars are unset, listener uses auto-detected defaults and logs them to a2a-listener.log
• if A2A_GATEWAY_API_KEY is unset, listener logs warning at startup

outcome signal

• listener is running in background: run ps aux | grep a2a-listener.py and see the running process, or check that a2a-listener.pid exists and the pid is valid
• listener is healthy: run curl http://{BIND_ADDR}:{LISTENER_PORT}/health and receive http 200 with ok status
• listener is processing tasks: check a2a-listener.log for incoming POST requests and response logs, or send a test task from another agent via the a2a gateway and verify the response
• listener is stopped: run stop.sh, then verify a2a-listener.pid is deleted and curl to /health times out
• listener is misconfigured: check a2a-listener.log for error or warning messages at startup (missing python3, no openclaw method, unset api key, etc.)