diff --git a/README.md b/README.md index 9a178df..a93acc2 100644 --- a/README.md +++ b/README.md @@ -4,75 +4,78 @@ [![A2A Protocol](https://img.shields.io/badge/A2A_Protocol-v0.3.0-blue)](https://a2a-protocol.org/latest/) [![PyPI version](https://img.shields.io/pypi/v/a2a-handler)](https://pypi.org/project/a2a-handler/) [![PyPI - Status](https://img.shields.io/pypi/status/a2a-handler)](https://pypi.org/project/a2a-handler/) -[![PyPI monthly downloads](https://img.shields.io/pypi/dm/a2a-handler)](https://pypi.org/project/a2a-handler/) [![Pepy total downloads](https://img.shields.io/pepy/dt/a2a-handler?label=total%20downloads)](https://pepy.tech/projects/a2a-handler) [![GitHub stars](https://img.shields.io/github/stars/alDuncanson/handler)](https://github.com/alDuncanson/handler/stargazers) -![Handler TUI](https://github.com/alDuncanson/Handler/blob/main/assets/handler-tui.png?raw=true) +Handler is an open-source [A2A protocol](https://github.com/a2aproject/A2A) +client for software engineers building, testing, and operating agentic systems. +It provides an interactive TUI, a scriptable CLI with structured output, and an +MCP server that lets other agents integrate with A2A services directly. Handler +also supports global and repo-scoped A2A server configuration with bearer, +API key, mTLS, and OAuth2 client credentials auth. -Handler is an open-source [A2A protocol](https://github.com/a2aproject/A2A) client for your terminal. - -Use the TUI or CLI to send messages, manage tasks, and inspect agent cards. -An included MCP server lets your AI assistant talk to A2A agents too. +![Handler TUI connected to the built-in Handler Agent, showing the agent card and a completed assistant response](https://raw.githubusercontent.com/alDuncanson/Handler/73915875903b60dad6e4e404aa7ed91b6d94559f/assets/tui.png) ## Install +Install Handler from the [PyPI package](https://pypi.org/project/a2a-handler/) as a `uv` tool: + ```bash uv tool install a2a-handler ``` -Or with [pipx](https://pipx.pypa.io/) / pip: +Or with [pipx](https://pipx.pypa.io/): ```bash -pipx install a2a-handler # or: pip install a2a-handler +pipx install a2a-handler ``` -## Quick Start +Or with pip: ```bash -handler tui # launch the interactive TUI -handler message send URL "hello" # send a message from the CLI -handler card get URL # fetch an agent card -handler mcp # start the MCP server -handler server run agent # run the bundled embedded agent -handler docs # open the hosted documentation -handler update # upgrade Handler to the latest release +pip install a2a-handler ``` -## Run Without Installing +## Quick Start + +Open the interactive terminal UI: ```bash -uvx --from a2a-handler handler # or: pipx run a2a-handler +handler tui ``` -## Servers +Inspect an A2A server's agent card: + +```bash +handler card get --url http://localhost:8000 +``` -Handler supports named servers in `$XDG_CONFIG_HOME/handler/servers.toml` -(global) and `.handler/servers.toml` (repo-local). +Send a message from the CLI: -```toml -version = 1 +```bash +handler message send --url URL --text "hello" +``` -[servers.local] -url = "http://localhost:8000" +Open the full documentation: -[servers.local.auth] -type = "bearer" -env = "HANDLER_LOCAL_TOKEN" +```bash +handler docs ``` -See [docs/](docs) for the full auth reference covering bearer, API key, mTLS, -and OAuth2. +## Run Without Installing + +Run Handler with `uvx`: -## Development +```bash +uvx --from a2a-handler handler +``` -A [hermetic](https://zero-to-nix.com/concepts/hermeticity/) dev environment -is available via [Nix](https://zero-to-nix.com/concepts/nix/): +Run Handler with `pipx`: ```bash -nix develop +pipx run a2a-handler ``` -The Mintlify docs source lives in `docs/`. +## Documentation -See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. +Read the documentation at . diff --git a/assets/handler-tui.png b/assets/handler-tui.png deleted file mode 100644 index 24050b7..0000000 Binary files a/assets/handler-tui.png and /dev/null differ diff --git a/assets/tui.png b/assets/tui.png new file mode 100644 index 0000000..6a8e7fc Binary files /dev/null and b/assets/tui.png differ diff --git a/docs/docs.json b/docs/docs.json index 4d9b09c..29b2ee4 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -23,7 +23,7 @@ "navigation": { "tabs": [ { - "tab": "Docs", + "tab": "Get started", "groups": [ { "group": "Getting started", @@ -31,21 +31,39 @@ "index", "quickstart" ] - }, + } + ] + }, + { + "tab": "Guides", + "groups": [ { - "group": "Workflows", + "group": "Core workflows", "pages": [ "guides/tui", "guides/messages-tasks", + "guides/servers", + "guides/authentication" + ] + }, + { + "group": "Agent and MCP workflows", + "pages": [ "guides/mcp", + "guides/agent-docs-mcp", + "guides/enterprise-a2a", "guides/local-servers" ] - }, + } + ] + }, + { + "tab": "Reference", + "groups": [ { - "group": "Configuration", + "group": "CLI", "pages": [ - "guides/servers", - "guides/authentication" + "reference/cli" ] } ] diff --git a/docs/guides/agent-docs-mcp.mdx b/docs/guides/agent-docs-mcp.mdx new file mode 100644 index 0000000..4eccc0f --- /dev/null +++ b/docs/guides/agent-docs-mcp.mdx @@ -0,0 +1,78 @@ +--- +title: "Documentation MCP" +description: "Use Handler's hosted documentation MCP server so agents can discover Handler commands and structured CLI workflows." +--- + +# Give agents current Handler docs + +Handler's documentation is available through a hosted MCP server at: + +```text +https://handler.alduncanson.com/mcp +``` + +Connect an agent to this MCP endpoint when you want it to use Handler reliably +instead of guessing command names or output shapes from model memory. + +## When this is useful + +- an AI coding assistant needs to call A2A agents from a shell +- an internal agent should generate `handler --output json ...` commands +- a workflow needs up-to-date examples for sessions, tasks, and server configuration +- you want agents to discover Handler docs through MCP rather than a web browser + +## Recommended agent instruction + +Give the agent a short, operational instruction like this: + +```text +Use Handler to send A2A protocol messages, inspect agent cards, and manage A2A +tasks. Prefer structured output with `handler --output json` or +`handler --output ndjson` when another program or agent will consume the result. +``` + +## Agent-friendly CLI pattern + +For single responses, prefer JSON: + +```bash +handler --output json message send \ + --server production-agent \ + --text "Summarize the current task state" +``` + +For streaming responses, prefer newline-delimited JSON: + +```bash +handler --output ndjson message stream \ + --server production-agent \ + --text "Run the long workflow and stream progress" +``` + +## Discover commands programmatically + +Handler also exposes its own CLI shape for agents and automation: + +```bash +handler --output json schema +``` + +```bash +handler --output json describe message send +``` + +```bash +handler --output json describe task get +``` + +Use these commands when an agent needs to construct invocations dynamically. +They are also useful for validating wrapper tools, command palettes, and +generated documentation. + +## Built-in local agent behavior + +The bundled local agent uses the same hosted docs MCP endpoint by default: + +```bash +handler server run agent +``` diff --git a/docs/guides/authentication.mdx b/docs/guides/authentication.mdx index 36f354e..e1faf19 100644 --- a/docs/guides/authentication.mdx +++ b/docs/guides/authentication.mdx @@ -3,9 +3,9 @@ title: "Authentication" description: "Configure bearer, API key, mTLS, and OAuth2 client credentials authentication for Handler servers." --- -# Authentication +# Configure server authentication -Handler supports four auth types for named servers: +Handler supports four auth types for configured servers: - bearer tokens - API keys @@ -98,7 +98,7 @@ key = "/path/to/client.key" ca_cert = "/path/to/ca.crt" ``` -Handler checks that the certificate and key files exist before use, and it also +Handler checks that the certificate and key files exist before use, and verifies private key permissions. ## OAuth2 client credentials diff --git a/docs/guides/enterprise-a2a.mdx b/docs/guides/enterprise-a2a.mdx new file mode 100644 index 0000000..21bbcd4 --- /dev/null +++ b/docs/guides/enterprise-a2a.mdx @@ -0,0 +1,109 @@ +--- +title: "Enterprise A2A setup" +description: "Configure Handler for OAuth-authenticated, gateway-fronted, and team-shared A2A services." +--- + +# Connect to production A2A services + +Handler is designed to work with production A2A services, including agents +behind API gateways, OAuth2 token endpoints, private clusters, and internal +developer platforms. + +## Recommended production pattern + +Use repo-scoped server configuration for shared server shape and +environment variables for secrets: + +```toml +version = 1 + +[servers.apigee-gke-agent] +url = "https://agents.example.com/a2a/my-agent" + +[servers.apigee-gke-agent.auth] +type = "oauth2" +token_url = "https://login.example.com/oauth2/token" +client_id_env = "HANDLER_APIGEE_CLIENT_ID" +client_secret_env = "HANDLER_APIGEE_CLIENT_SECRET" +scopes = ["a2a.invoke"] +``` + +Commit `.handler/servers.toml` if the URL and auth shape are safe to share. +Keep client IDs, client secrets, bearer tokens, API keys, and certificate paths +in each developer or CI environment. + +## Validate before sending traffic + +Validate server configuration and auth references first: + +```bash +handler server validate +``` + +```bash +handler card validate --server apigee-gke-agent +``` + +```bash +handler card get --server apigee-gke-agent +``` + +This catches invalid TOML, missing environment variables, auth file problems, +and agent-card issues before you debug task execution. + +## Use structured output in automation + +Human-readable text is best in a terminal. JSON is better for CI, scripts, and +other agents: + +```bash +handler --output json message send \ + --server apigee-gke-agent \ + --text "Run the readiness check" +``` + +For long-running tasks, stream newline-delimited JSON: + +```bash +handler --output ndjson message stream \ + --server apigee-gke-agent \ + --text "Execute the deployment analysis" +``` + +## Tune network timeouts for gateway-fronted services + +Long-running A2A tasks may sit behind proxies, service meshes, or load +balancers. Handler exposes timeout controls as global flags and environment +variables: + +```bash +handler \ + --connect-timeout 120 \ + --read-timeout 120 \ + --write-timeout 120 \ + --pool-timeout 120 \ + --stream-read-timeout none \ + message stream --server apigee-gke-agent --text "Run the workflow" +``` + +The streaming read timeout defaults to `none` so idle gaps between server-sent +events do not abort long tasks. + +## Production-readiness checklist + +- Use configured servers instead of hard-coded URLs in scripts. +- Store secrets in environment variables, not TOML files. +- Prefer OAuth2 client credentials, bearer tokens, API keys, or mTLS according + to your gateway policy. +- Validate agent cards and server configuration during onboarding and CI checks. +- Use `--output json` or `--output ndjson` when another system consumes results. +- Use `handler task resubscribe` for recoverable streaming interruptions. +- Run the local webhook receiver before integrating push notifications with a + real webhook consumer. + +## Current gaps to plan around + +Handler is production-ready as a terminal and MCP client, but it intentionally +does not replace enterprise platform controls. Plan to provide external secret +management, audit logging, network policy, and centralized distribution through +your existing infrastructure. diff --git a/docs/guides/local-servers.mdx b/docs/guides/local-servers.mdx index 475d359..ad7a378 100644 --- a/docs/guides/local-servers.mdx +++ b/docs/guides/local-servers.mdx @@ -3,7 +3,7 @@ title: "Local servers" description: "Run Handler's embedded A2A agent and local webhook server for development, demos, and integration testing." --- -# Local servers +# Run local A2A servers Handler ships with two useful local servers for development work: @@ -12,6 +12,8 @@ Handler ships with two useful local servers for development work: ## Run the embedded agent +Start Handler's bundled local A2A agent: + ```bash handler server run agent ``` @@ -28,21 +30,6 @@ Handler's hosted documentation MCP server at Handler CLI, TUI, MCP bridge, authentication, local servers, and common A2A workflows from the current docs instead of only relying on model memory. -You can point it at another compatible documentation MCP endpoint when testing -docs locally: - -```bash -export HANDLER_DOCS_MCP_URL=http://localhost:3000/mcp -handler server run agent -``` - -For fully offline runs, disable the docs toolset: - -```bash -export HANDLER_DOCS_MCP_ENABLED=false -handler server run agent -``` - ## Choose a model The built-in agent uses Google ADK with LiteLLM against an Ollama-compatible @@ -58,7 +45,13 @@ Or set environment variables: ```bash export OLLAMA_MODEL=gemma4:e2b +``` + +```bash export OLLAMA_API_BASE=http://localhost:11434 +``` + +```bash handler server run agent ``` @@ -67,8 +60,13 @@ If you do not override it, Handler defaults to `gemma4:e2b` and ## Protect the local agent with an API key +Require API key auth with a generated key: + ```bash handler server run agent --auth +``` + +```bash handler server run agent --auth --api-key my-secret ``` @@ -81,8 +79,13 @@ still discover the server. ## Run the push notification receiver +Start the local webhook receiver on the default port: + ```bash handler server run push +``` + +```bash handler server run push --port 9001 ``` diff --git a/docs/guides/mcp.mdx b/docs/guides/mcp.mdx index 96ff91a..57f0204 100644 --- a/docs/guides/mcp.mdx +++ b/docs/guides/mcp.mdx @@ -1,27 +1,62 @@ --- title: "MCP server" -description: "Expose Handler's A2A capabilities through a local MCP server for Claude Desktop, Cursor, and other MCP-compatible clients." +description: "Expose Handler's A2A capabilities through a local MCP server for Amp, Pi, and other MCP-compatible agent harnesses." --- -# MCP server +# Expose A2A tools through MCP -Handler can expose its A2A features as an MCP server so other tools can call the -same card, message, task, session, and auth operations. +Handler can expose A2A protocol operations through an MCP server so other tools +can call the same card, message, task, session, and auth operations. -## Start the MCP server +## Configure your agent harness + +Most users do not start `handler mcp` manually. Instead, add it to your agent's +MCP server configuration so the agent harness launches Handler when it needs the +tools. + +## Amp or Pi example + +Use the same command shape for Amp, Pi, or any MCP client that supports stdio +servers: + +```json +{ + "mcpServers": { + "handler": { + "command": "handler", + "args": ["mcp"] + } + } +} +``` + +## Run it manually for debugging + +For local debugging, you can start the stdio server yourself: ```bash handler mcp ``` -The default transport is `stdio`, which is usually what desktop MCP clients -expect. +The default transport is `stdio`, which is what most local MCP clients expect. ## Available transports +Start the MCP server with the default stdio transport: + ```bash handler mcp --transport stdio +``` + +Start the MCP server with Server-Sent Events transport: + +```bash handler mcp --transport sse +``` + +Start the MCP server with streamable HTTP transport: + +```bash handler mcp --transport streamable-http ``` @@ -40,27 +75,12 @@ The server provides tools across five areas: That makes it useful as a bridge layer between MCP clients and A2A agents. -## Claude Desktop example - -Add Handler to `claude_desktop_config.json`: - -```json -{ - "mcpServers": { - "handler": { - "command": "handler", - "args": ["mcp"] - } - } -} -``` - ## Typical workflow One common pattern is: -1. Save one or more named servers in Handler. -2. Start `handler mcp`. +1. Configure one or more A2A servers in Handler. +2. Add `handler mcp` to your agent harness MCP config. 3. Connect your MCP client. 4. Use MCP tools to inspect cards, send messages, and manage tasks against those agents. @@ -69,5 +89,5 @@ the fastest way to stabilize that setup first. ## When to use this instead of the CLI -Use MCP mode when another tool should drive Handler for you. Use the CLI when -you want direct shell control or automation in scripts. +Use the MCP server when another tool should drive Handler for you. Use the CLI +when you want direct shell control or automation in scripts. diff --git a/docs/guides/messages-tasks.mdx b/docs/guides/messages-tasks.mdx index 4657bc6..d1a9506 100644 --- a/docs/guides/messages-tasks.mdx +++ b/docs/guides/messages-tasks.mdx @@ -3,7 +3,7 @@ title: "Messages, tasks, and sessions" description: "Send messages, stream responses, manage tasks, and reuse saved conversation state from the Handler CLI." --- -# Messages, tasks, and sessions +# Use the CLI for A2A workflows Message responses and errors default to readable text for interactive use. Pass `--output json` for full protocol responses, or `--output ndjson` before @@ -13,9 +13,21 @@ JSON in the default mode. ## Inspect an agent card first +Fetch the card for a configured server: + ```bash handler card get --server demo +``` + +Validate the configured server's card: + +```bash handler card validate --server demo +``` + +Validate a saved agent card file: + +```bash handler card validate --file ./agent-card.json ``` @@ -24,17 +36,21 @@ agent itself is advertising a valid card. ## Send a message +Send a basic message to a configured server: + ```bash handler message send --server demo --text "Hello" ``` -You can target a URL directly instead of a named server: +You can target a URL directly instead of a configured server: ```bash handler message send --url http://localhost:8000 --text "Hello" ``` -## Stream the response live +## Stream the response + +Stream task events and response text from a configured server: ```bash handler message stream --server demo --text "Summarize your capabilities" @@ -44,11 +60,12 @@ In text mode, streaming prints lightweight `event:` summaries for task state changes, tool calls, tool results, data/file parts, and response text before the final answer content. That makes it clear when the agent is still working even if the model's text arrives in one larger chunk. Handler also prints the full -task ID once when the stream starts so you can resubscribe if the connection is -interrupted. +task ID once when the stream starts so you can resubscribe if the server +connection is interrupted. -The `send` command also accepts `--stream` when you want the same request shape -but prefer one command form. +If you already use `message send` in scripts, adding `--stream` switches that +same command to streaming mode. Otherwise, prefer the more explicit +`message stream` command in examples and documentation. Use newline-delimited JSON when you want structured stream events: @@ -70,7 +87,7 @@ handler \ message stream --server demo --text "Summarize your capabilities" ``` -The same knobs are available as `HANDLER_CONNECT_TIMEOUT`, +The same timeout settings are available as `HANDLER_CONNECT_TIMEOUT`, `HANDLER_READ_TIMEOUT`, `HANDLER_WRITE_TIMEOUT`, `HANDLER_POOL_TIMEOUT`, and `HANDLER_STREAM_READ_TIMEOUT`, including from a workspace `.env` file. Streaming disables the read timeout by default so long-running tasks are not aborted during @@ -82,7 +99,17 @@ Handler persists conversation identifiers locally so you can continue later: ```bash handler message send --server demo --text "Start a task" +``` + +Continue using Handler's saved context and task IDs: + +```bash handler message send --server demo --text "Continue that task" --continue +``` + +Inspect the saved session for a configured server: + +```bash handler session show --server demo ``` @@ -104,7 +131,7 @@ input, structured output, and repeatable header flags: ```bash handler --output json message send \ --server demo \ - --json '{"message":{"role":"user","parts":[{"text":"hello"}]}}' \ + --json '{"text":"hello"}' \ --header 'X-Trace-Id: local-test' ``` @@ -112,15 +139,32 @@ You can also override saved auth with `--bearer-env` or `--api-key-env`. ## Work with tasks directly +Fetch the latest task status: + ```bash handler task get --server demo --task task-123 +``` + +Include recent message history with the task response: + +```bash handler task get --server demo --task task-123 --history-length 10 +``` + +Cancel a running task: + +```bash handler task cancel --server demo --task task-123 +``` + +Reconnect to a task's SSE stream after interruption: + +```bash handler task resubscribe --server demo --task task-123 ``` `resubscribe` is useful when a task uses streaming events and you need to attach -again after a dropped connection. +again after a dropped server connection. ## Configure push notifications for tasks @@ -148,10 +192,27 @@ For a local receiver you can run the bundled webhook server described in Handler stores session metadata locally so repeated CLI calls can reuse conversation state. +List all saved sessions: + ```bash handler session list +``` + +Show the saved session for a configured server: + +```bash handler session show --server demo +``` + +Clear the saved session for one configured server: + +```bash handler session clear --server demo +``` + +Clear all saved sessions: + +```bash handler session clear --all ``` diff --git a/docs/guides/servers.mdx b/docs/guides/servers.mdx index 838f71d..3565516 100644 --- a/docs/guides/servers.mdx +++ b/docs/guides/servers.mdx @@ -1,22 +1,24 @@ --- title: "Servers" -description: "Configure reusable global or repository-local server definitions for Handler." +description: "Configure global or repo-scoped A2A server definitions for Handler." --- -# Servers +# Configure A2A servers -Handler can load named server definitions from two places: +Handler can load configured A2A server definitions from two places: - global config at `$XDG_CONFIG_HOME/handler/servers.toml` -- repository-local config at `.handler/servers.toml` +- repo-scoped config at `.handler/servers.toml` Handler also includes a built-in global entry named `Handler Agent` at `http://localhost:8000`. It appears in the TUI server picker even before you create a `servers.toml` file, so new users can connect to Handler's bundled -embedded agent immediately. If you define your own server with the same name or -URL, Handler uses your entry instead of adding the built-in one. +embedded agent immediately. Handler does not add the built-in entry when a +configured server already uses the `Handler Agent` name or the +`http://localhost:8000` URL. When the TUI auto-starts the embedded agent and +port `8000` is already occupied, it tries the next available local port. -Repository-local config is useful when a project should travel with a shared +Repo-scoped config is useful when a project should travel with a shared agent URL or auth shape, while secrets continue to come from environment variables on each developer machine. @@ -31,7 +33,7 @@ url = "http://localhost:8000" Each server entry needs a `url`. Auth is optional. -## Global vs repository-local +## Global vs repo-scoped Use global config by default: @@ -39,7 +41,7 @@ Use global config by default: handler server add demo --url http://localhost:8000 ``` -Use repository-local config when the server definition belongs with the repo: +Use repo-scoped config when the server definition belongs with the repo: ```bash handler server add demo --url http://localhost:8000 --repository @@ -50,11 +52,23 @@ handler server add demo --url http://localhost:8000 --repository Handler validates server files when it loads them and skips only the invalid entries instead of failing the whole file. -These commands help you inspect what is available: +Use these commands to inspect what is available. + +List every configured server Handler can load: ```bash handler server list +``` + +Show one server's resolved configuration: + +```bash handler server show demo +``` + +Validate configured servers and auth references: + +```bash handler server validate ``` diff --git a/docs/guides/tui.mdx b/docs/guides/tui.mdx index 4a60e24..3c49713 100644 --- a/docs/guides/tui.mdx +++ b/docs/guides/tui.mdx @@ -1,52 +1,67 @@ --- title: "TUI and web UI" -description: "Use Handler's interactive terminal interface to connect to agents, manage auth, inspect cards, and keep conversations moving." +description: "Use Handler's interactive terminal interface to connect to A2A servers, manage auth, inspect cards, and send messages." --- -# TUI and web UI +# Use the interactive UI The TUI is the fastest way to explore an A2A agent when you want a live, interactive workflow instead of one command at a time. ## Start the TUI +Open the interactive terminal UI: + ```bash handler tui ``` -You can also pre-connect on startup: +You can also open servers automatically on startup. + +Open a configured server by name: ```bash handler tui --server demo +``` + +Open multiple configured servers in tabs: + +```bash handler tui --server demo --server staging +``` + +Open a server by URL without saving it first: + +```bash handler tui --url http://localhost:8000 +``` + +Override auth with a bearer token from the environment: + +```bash handler tui --bearer-env HANDLER_TOKEN ``` -## What the TUI is good at +## What you can do with the TUI -- switching between multiple agent connections in tabs +- switching between multiple A2A servers in tabs - inspecting agent cards and supported capabilities -- sending messages and watching streaming responses -- editing auth, custom headers, and connection details interactively +- sending messages and inspecting task responses +- editing auth, custom headers, and server details interactively - keeping recent sessions close at hand while testing agents repeatedly - viewing logs without leaving the interface -## Useful keyboard shortcuts +## Footer shortcuts -The default footer exposes the most important controls: +The footer shows the shortcuts that are always worth keeping close: - `Ctrl+P` opens the command palette -- `Ctrl+N` opens a new server tab -- `Ctrl+W` closes the active server tab -- `Ctrl+B` switches to the previous server tab -- `Ctrl+T` switches to the next server tab -- `Ctrl+M` maximizes the focused panel - `Ctrl+Q` quits the application +- `?` opens the keybindings panel -## Connecting with saved servers +## Connecting with configured servers -If you already defined named servers in `servers.toml`, the TUI can open them +If you already defined servers in `servers.toml`, the TUI can open them directly from the picker or from the command line with `--server`. This is usually the easiest way to work with mTLS or OAuth2 because the server @@ -63,8 +78,8 @@ The auth panel supports the same major flows as the CLI: - mTLS certificate paths - OAuth2 client credentials -That makes the TUI useful for debugging an agent before you turn the same setup -into a reusable named server. +That makes the TUI useful for debugging an agent before you save the same setup +as server configuration. ## Browser-hosted mode @@ -72,6 +87,9 @@ If you want the same interface in a browser tab, serve it as a web app: ```bash handler web +``` + +```bash handler web --port 9000 ``` diff --git a/docs/index.mdx b/docs/index.mdx index 0f528cd..dab9ab3 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -1,53 +1,78 @@ --- -title: "Introduction" -description: "Install Handler and use the TUI, CLI, or MCP server to work with A2A agents from your terminal." +title: "Overview" +description: "Handler is a terminal-first A2A client with a TUI, scriptable CLI, MCP bridge, and server configuration for production auth." --- -# Handler +# What is Handler? Handler is an open-source [A2A protocol](https://github.com/a2aproject/A2A) -client for the terminal. +client for software engineers building, testing, and operating agentic systems. +It gives you a terminal-native control surface for A2A services: an interactive +TUI for exploration, a scriptable CLI with structured output for automation, +and an MCP server so other agents can call A2A services through Handler. -Use it when you want to: +Use Handler when you need to: -- send messages to A2A agents from a CLI -- manage conversations and tasks in a terminal UI -- inspect agent cards -- expose an MCP server so your AI tooling can talk to A2A agents -- save reusable server definitions with bearer, API key, mTLS, or OAuth2 auth +- inspect and validate agent cards before debugging deeper protocol issues +- send messages, stream events, and manage tasks from shell scripts or CI +- configure global or repo-scoped A2A servers with bearer, API key, mTLS, + or OAuth2 client credentials auth +- expose A2A operations as MCP tools for agent harnesses such as Amp or Pi ## Install +Install Handler from the [PyPI package](https://pypi.org/project/a2a-handler/) as a `uv` tool: + ```bash uv tool install a2a-handler ``` -Or with `pipx` or `pip`: +Or with `pipx`: ```bash pipx install a2a-handler -# or +``` + +Or with `pip`: + +```bash pip install a2a-handler ``` ## First commands +Open the interactive terminal UI: + ```bash handler tui -handler message send URL "hello" -handler card get URL -handler mcp -handler server run agent +``` + +Inspect an A2A server's agent card: + +```bash +handler card get --url http://localhost:8000 +``` + +Send a message from the CLI: + +```bash +handler message send --url http://localhost:8000 --text "hello" +``` + +Open the full documentation: + +```bash handler docs -handler update ``` -## What to read next +If you want another agent to use Handler through MCP, add `handler mcp` to that +agent's MCP server configuration. See [MCP server](./guides/mcp). + +## Choose your path -- [Quickstart](./quickstart) for the fastest path from install to first message -- [TUI and web UI](./guides/tui) for the interactive workflow -- [Messages, tasks, and sessions](./guides/messages-tasks) for the main CLI flow -- [MCP server](./guides/mcp) to expose Handler to MCP-compatible tools -- [Local servers](./guides/local-servers) for the bundled test agent and webhook receiver -- [Servers](./guides/servers) for reusable server definitions -- [Authentication](./guides/authentication) for bearer, API key, mTLS, and OAuth2 examples +- [Quickstart](./quickstart) walks through install, first message, and configured servers. +- [TUI and web UI](./guides/tui) covers the interactive workflow. +- [Messages, tasks, and sessions](./guides/messages-tasks) explains CLI automation and structured output. +- [Configured servers](./guides/servers) and [authentication](./guides/authentication) cover production connection configuration. +- [MCP server](./guides/mcp) shows how to let MCP clients call A2A agents through Handler. +- [CLI reference](./reference/cli) lists commands, flags, and machine-readable schema helpers. diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index bfad0df..71b1fab 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -1,79 +1,116 @@ --- title: "Quickstart" -description: "Get Handler running locally, send your first message, and save a reusable server definition." +description: "Install Handler, start a local A2A server, send your first message, and save a server configuration." --- -# Quickstart +# Get started with Handler ## Install Handler +Install Handler from the [PyPI package](https://pypi.org/project/a2a-handler/) as a `uv` tool: + ```bash uv tool install a2a-handler ``` -If you prefer not to install it globally, you can run it directly: +If you prefer not to install it globally, you can invoke Handler without installing: ```bash uvx --from a2a-handler handler --help ``` -To update an installed Handler later: +## 1. Start with the TUI + +Open the interactive terminal UI: ```bash -handler update -# or -handler upgrade +handler tui ``` -## Start with the TUI +The TUI is the easiest place to browse cards, inspect tasks, and manage auth for +an A2A server interactively. + +## 2. Try the CLI + +If you do not already have an A2A server available, start Handler's bundled +local agent in another terminal: ```bash -handler tui +handler server run agent ``` -The TUI is the easiest place to browse cards, inspect tasks, and manage auth for -a connection interactively. +Inspect the local A2A server's agent card: -## Try the CLI +```bash +handler card get --url http://localhost:8000 +``` + +Send your first message: ```bash -handler card get http://localhost:8000 -handler message send http://localhost:8000 "hello" +handler message send --url http://localhost:8000 --text "hello" ``` -## Save a named server +## 3. Configure an A2A server -Named servers let you reuse a URL and auth configuration instead of typing them -on every command. +Handler can store A2A server definitions as configuration for repeated +connections: the server URL, where the configuration lives, and any auth +settings needed for Handler to connect as an A2A client. + +Save a global server configuration: ```bash handler server add demo --url http://localhost:8000 ``` -To store a server in the repository instead of your global config: +Store the server configuration with the current repository instead of your global config: ```bash handler server add demo --url http://localhost:8000 --repository ``` -That creates or updates a `.handler/servers.toml` file at the git root. +That creates or updates `.handler/servers.toml` at the root of the repository. + +## 4. Inspect configured servers -## Inspect configured servers +List every configured server Handler can find: ```bash handler server list +``` + +Show the resolved details for one server: + +```bash handler server show demo +``` + +Validate configured servers and their auth references: + +```bash handler server validate ``` -## Keep the conversation going +## 5. Keep the conversation going -Once you have a live task or saved conversation, you can keep using the same -context from the CLI: +Once you have a live task or saved conversation, the CLI can continue from the +same context. + +Start or resume a conversation with the configured server: ```bash handler message send --server demo --text "Hello" +``` + +Continue from Handler's saved session state: + +```bash handler message send --server demo --text "Follow up" --continue +``` + +Inspect the saved session IDs: + +```bash handler session show --server demo ``` @@ -81,8 +118,9 @@ See [Messages, tasks, and sessions](./guides/messages-tasks) for the full flow. ## Bridge Handler into MCP clients -If you want Claude Desktop, Cursor, or another MCP client to use Handler's A2A -tools, start the MCP server: +If you want Amp, Pi, or another agent harness to use Handler's A2A tools, add +Handler to that tool's MCP server configuration. Most MCP clients launch the +server for you with this command: ```bash handler mcp @@ -90,22 +128,26 @@ handler mcp See [MCP server](./guides/mcp) for transport options and client setup. -## Preview these docs locally +## Open the docs from your terminal -To open the deployed docs in your browser from the CLI: +Open the hosted Handler docs in your browser: ```bash handler docs ``` -To preview local documentation changes, install the Mintlify CLI, then run the -preview server from the `docs/` directory where `docs.json` lives. +## Keep learning -```bash -npm i -g mint -cd docs -mint dev -``` +Ready to go deeper? Choose the path that matches what you want to do next. + + + + Learn Handler's TUI, CLI messaging, server configuration, authentication, MCP, + and enterprise A2A workflows. + -Once the Mintlify GitHub app is connected to this repository, pushes to `main` -deploy documentation changes automatically. + + Look up Handler commands, flags, output modes, and machine-readable schema + helpers for automation. + + diff --git a/docs/reference/cli.mdx b/docs/reference/cli.mdx new file mode 100644 index 0000000..0e1d9df --- /dev/null +++ b/docs/reference/cli.mdx @@ -0,0 +1,331 @@ +--- +title: "CLI reference" +description: "Complete reference for Handler commands, global options, structured output, and machine-readable CLI metadata." +--- + +# Look up Handler commands + +Handler's command line is optimized for both humans and agents. Use text output +interactively, JSON for scripts, and NDJSON for streaming event consumers. + +## Global options + +| Option | Description | +| --- | --- | +| `--version` | Show the version and exit. | +| `-v, --verbose` | Enable verbose logging. | +| `-d, --debug` | Enable debug logging. | +| `--output text/json/ndjson` | Select output format. Defaults to `text`. | +| `--quiet` | Suppress non-error output. | +| `--connect-timeout SECONDS/none` | HTTP connect timeout. Env: `HANDLER_CONNECT_TIMEOUT`. | +| `--read-timeout SECONDS/none` | HTTP read timeout for non-streaming calls. Env: `HANDLER_READ_TIMEOUT`. | +| `--write-timeout SECONDS/none` | HTTP write timeout. Env: `HANDLER_WRITE_TIMEOUT`. | +| `--pool-timeout SECONDS/none` | HTTP connection pool timeout. Env: `HANDLER_POOL_TIMEOUT`. | +| `--stream-read-timeout SECONDS/none` | HTTP read timeout for streaming calls. Defaults to `none`. Env: `HANDLER_STREAM_READ_TIMEOUT`. | + +## Machine-readable metadata + +Use these commands when generating wrappers, validating agent plans, or building +docs from the installed CLI: + +```bash +handler --output json schema +``` + +```bash +handler --output json describe message send +``` + +```bash +handler --output json describe task get +``` + +```bash +handler --output json describe server add +``` + +## Core commands + +### `handler card get` + +Retrieve an agent's card. + +```bash +handler card get --server my-agent +``` + +```bash +handler card get --url http://localhost:8000 +``` + +Options: `--url`, `-s, --server`, `-b, --bearer-env`, `-k, --api-key-env`. + +### `handler card validate` + +Validate an agent card from a URL, configured server, or local file. + +```bash +handler card validate --server my-agent +``` + +```bash +handler card validate --file ./agent-card.json +``` + +Options: `--url`, `--file`, `-s, --server`, `-b, --bearer-env`, `-k, --api-key-env`. + +### `handler message send` + +Send a message and receive a response. + +```bash +handler message send --server my-agent --text "Hello" +``` + +```bash +handler --output json message send --server my-agent --text "Hello" +``` + +Options: `--url`, `-s, --server`, `-t, --text`, `--stream`, `--json`, +`--context-id`, `--task-id`, `-C, --continue`, `--push-url`, `--push-token`, +`-b, --bearer-env`, `-k, --api-key-env`, `-H, --header`. + +### `handler message stream` + +Send a message and stream the response in real time. + +```bash +handler message stream --server my-agent --text "Run the workflow" +``` + +```bash +handler --output ndjson message stream --server my-agent --text "Run the workflow" +``` + +Options match `message send`, except `--text` is required and streaming is +always enabled. + +### `handler task get` + +Retrieve task status. + +```bash +handler task get --server my-agent --task task-123 +``` + +```bash +handler task get --server my-agent --task task-123 --history-length 10 +``` + +Options: `--url`, `-s, --server`, `--task`, `-n, --history-length`, `--params`, +`-b, --bearer-env`, `-k, --api-key-env`. + +### `handler task cancel` + +Request cancellation of a task. + +```bash +handler task cancel --server my-agent --task task-123 +``` + +### `handler task resubscribe` + +Resubscribe to a task's SSE stream after disconnection. + +```bash +handler task resubscribe --server my-agent --task task-123 +``` + +### `handler task notification get` + +Get the push notification configuration for a task. + +```bash +handler task notification get --server my-agent --task task-123 +``` + +Options: `--url`, `-s, --server`, `--task`, `-c, --config-id`, `-b, --bearer-env`, `-k, --api-key-env`. + +### `handler task notification set` + +Configure a push notification webhook for a task. + +```bash +handler task notification set \ + --server my-agent \ + --task task-123 \ + --webhook-url http://127.0.0.1:9000/webhook \ + --token local-secret +``` + +Options: `--url`, `-s, --server`, `--task`, `--webhook-url`, `-t, --token`, +`-b, --bearer-env`, `-k, --api-key-env`. + +## Session commands + +### `handler session list` + +List all saved conversation sessions. + +```bash +handler session list +``` + +### `handler session show` + +Display saved conversation state. + +```bash +handler session show --server my-agent +``` + +### `handler session clear` + +Clear saved conversation state for one agent. + +```bash +handler session clear --server my-agent +``` + +Clear all saved conversation state. + +```bash +handler session clear --all +``` + +## Server commands + +### `handler server add` + +Add a server to the global or repo-scoped configuration. + +```bash +handler server add demo --url http://localhost:8000 +``` + +```bash +handler server add prod --url https://agent.example.com --repository +``` + +Options include `--url`, `--bearer-env`, `--api-key-env`, `--api-key-header`, +`--cert`, `--key`, `--oauth2-token-url`, `--oauth2-client-id-env`, +`--oauth2-client-secret-env`, `--oauth2-scope`, `--global`, and `--repository`. + +### `handler server list` + +List configured global and repo-scoped servers. + +```bash +handler server list +``` + +### `handler server show` + +Show details for a configured server. + +```bash +handler server show NAME +``` + +```bash +handler server show NAME --source repository +``` + +Options: `--source repository/global`. + +### `handler server remove` + +Remove a server from the configuration. + +```bash +handler server remove NAME +``` + +```bash +handler server remove NAME --repository +``` + +Options: `--global`, `--repository`. + +### `handler server validate` + +Validate configured servers and default auth resolution. + +```bash +handler server validate +``` + +### `handler server run agent` + +Start Handler's local A2A agent server. + +```bash +handler server run agent +``` + +### `handler server run push` + +Start a local webhook server for push notifications. + +```bash +handler server run push +``` + +## Interface and integration commands + +### `handler mcp` + +Run a local MCP server exposing A2A protocol operations. Supports `stdio`, +`sse`, and `streamable-http`. + +```bash +handler mcp +``` + +### `handler tui` + +Launch the interactive terminal interface. + +```bash +handler tui +``` + +### `handler web` + +Serve the TUI as a web application. + +```bash +handler web +``` + +### `handler docs` + +Open the Handler documentation in your browser. + +```bash +handler docs +``` + +### `handler version` + +Display the current version. + +```bash +handler version +``` + +### `handler update` + +Update Handler to the latest published version. + +```bash +handler update +``` + +### `handler upgrade` + +Alias for `handler update`. + +```bash +handler upgrade +``` diff --git a/src/a2a_handler/cli/session.py b/src/a2a_handler/cli/session.py index 21b90c5..19c3a5c 100644 --- a/src/a2a_handler/cli/session.py +++ b/src/a2a_handler/cli/session.py @@ -32,15 +32,18 @@ def session_list() -> None: if not sessions: return + data: list[dict[str, object]] = [] for session_entry in sessions: - data: dict[str, object] = {"agent_url": session_entry.agent_url} + session_data: dict[str, object] = {"agent_url": session_entry.agent_url} if session_entry.context_id: - data["context_id"] = session_entry.context_id + session_data["context_id"] = session_entry.context_id if session_entry.task_id: - data["task_id"] = session_entry.task_id + session_data["task_id"] = session_entry.task_id if session_entry.last_used_at: - data["last_used_at"] = session_entry.last_used_at - output.json(data) + session_data["last_used_at"] = session_entry.last_used_at + data.append(session_data) + + output.json(data) @session.command("show")