Skip to main content

​
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 streaming commands when you need structured event output for automation or agent-driven workflows. Commands without a custom text formatter may still emit JSON in the default mode.

​
Inspect an agent card first

Fetch the card for a configured server: 
handler card get --server demo
Validate the configured server’s card: 
handler card validate --server demo
Validate a saved agent card file: 
handler card validate --file ./agent-card.json
Use card validation before deeper debugging when you’re not sure whether the agent itself is advertising a valid card.

​
Send a message

Send a basic message to a configured server: 
handler message send --server demo --text "Hello"
You can target a URL directly instead of a configured server: 
handler message send --url http://localhost:8000 --text "Hello"

​
Stream the response

Stream task events and response text from a configured server: 
handler message stream --server demo --text "Summarize your capabilities"
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 server connection is interrupted. 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: 
handler --output ndjson message stream --server demo --text "Summarize your capabilities"
If you need to tune networking behavior, Handler exposes global timeout flags and matching environment variables. Values are seconds, or none to disable a specific timeout: 
handler \
  --connect-timeout 120 \
  --read-timeout 120 \
  --write-timeout 120 \
  --pool-timeout 120 \
  --stream-read-timeout none \
  message stream --server demo --text "Summarize your capabilities"
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 idle gaps between SSE events.

​
Continue a saved conversation

Handler persists conversation identifiers locally so you can continue later: 
handler message send --server demo --text "Start a task"
Continue using Handler’s saved context and task IDs: 
handler message send --server demo --text "Continue that task" --continue
Inspect the saved session for a configured server: 
handler session show --server demo
If you already know the IDs you want, you can pass them explicitly: 
handler message send \
  --server demo \
  --text "Continue with explicit IDs" \
  --context-id ctx-123 \
  --task-id task-123

​
Send custom payloads or headers

For agent-friendly invocation and integration testing, Handler exposes raw JSON input, structured output, and repeatable header flags: 
handler --output json message send \
  --server demo \
  --json '{"text":"hello"}' \
  --header 'X-Trace-Id: local-test'
You can also override saved auth with --bearer-env or --api-key-env.

​
Work with tasks directly

Fetch the latest task status: 
handler task get --server demo --task task-123
Include recent message history with the task response: 
handler task get --server demo --task task-123 --history-length 10
Cancel a running task: 
handler task cancel --server demo --task task-123
Reconnect to a task’s SSE stream after interruption: 
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 server connection.

​
Configure push notifications for tasks

Point a task at a webhook receiver: 
handler task notification set \
  --server demo \
  --task task-123 \
  --webhook-url http://127.0.0.1:9000/webhook \
  --token local-secret
Inspect the current push config later: 
handler task notification get --server demo --task task-123
For a local receiver you can run the bundled webhook server described in Local servers.

​
Manage saved sessions

Handler stores session metadata locally so repeated CLI calls can reuse conversation state. List all saved sessions: 
handler session list
Show the saved session for a configured server: 
handler session show --server demo
Clear the saved session for one configured server: 
handler session clear --server demo
Clear all saved sessions: 
handler session clear --all
Use session clear when you want a clean slate without deleting the server definition itself.