Skip to main content

​
Run local A2A servers

Handler ships with two useful local servers for development work:
  • a documentation-aware embedded A2A agent for local testing and Handler help
  • a webhook receiver for task push notifications

​
Run the embedded agent

Start Handler’s bundled local A2A agent: 
handler server run agent
By default it binds to 0.0.0.0:8000. In the TUI, Handler includes this local agent as the built-in Handler Agent server. Selecting it and pressing CONNECT auto-starts the embedded agent if nothing is already listening at http://localhost:8000. The embedded agent is Handler-aware: it uses Google ADK tools to connect to Handler’s hosted documentation MCP server at https://handler.alduncanson.com/mcp. That lets it answer questions about the Handler CLI, TUI, MCP bridge, authentication, local servers, and common A2A workflows from the current docs instead of only relying on model memory.

​
Choose a model

The built-in agent uses Google ADK with LiteLLM against an Ollama-compatible endpoint. You can override the model directly: 
handler server run agent --model gemma4:e4b
Or set environment variables: 
export OLLAMA_MODEL=gemma4:e2b

export OLLAMA_API_BASE=http://localhost:11434

handler server run agent
If you do not override it, Handler defaults to gemma4:e2b and http://localhost:11434.

​
Protect the local agent with an API key

Require API key auth with a generated key: 
handler server run agent --auth

handler server run agent --auth --api-key my-secret
When auth is enabled, Handler protects the A2A request endpoints with an API key. If you do not provide one explicitly, Handler generates a random key for you. The agent card and health endpoints stay readable without auth so clients can still discover the server.

​
Run the push notification receiver

Start the local webhook receiver on the default port: 
handler server run push

handler server run push --port 9001
By default it binds to 127.0.0.1:9000 and exposes these endpoints:
  • POST /webhook receives task notifications
  • GET /webhook returns a simple validation response
  • GET /notifications lists received notifications
  • POST /notifications/clear clears stored notifications

​
End-to-end push notification test

  1. Start the webhook receiver with handler server run push.
  2. Start or connect to an agent.
  3. Send a message that creates a long-running task.
  4. Point that task at http://127.0.0.1:9000/webhook with handler task notification set.
  5. Inspect received events at http://127.0.0.1:9000/notifications.
This is a simple way to verify that an agent’s push flow works before wiring it into a real webhook consumer.