Messages, tasks, and sessions

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

handler card get --server demo
handler card validate --server demo
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

handler message send --server demo --text "Hello"

You can target a URL directly instead of a named server:

handler message send --url http://localhost:8000 --text "Hello"

Stream the response live

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 connection is interrupted. The send command also accepts --stream when you want the same request shape but prefer one command form. 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 knobs 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"
handler message send --server demo --text "Continue that task" --continue
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 '{"message":{"role":"user","parts":[{"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

handler task get --server demo --task task-123
handler task get --server demo --task task-123 --history-length 10
handler task cancel --server demo --task task-123
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.

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.

handler session list
handler session show --server demo
handler session clear --server demo
handler session clear --all

Use session clear when you want a clean slate without deleting the server definition itself.

Documentation Index

​Messages, tasks, and sessions

​Inspect an agent card first

​Send a message

​Stream the response live

​Continue a saved conversation

​Send custom payloads or headers

​Work with tasks directly

​Configure push notifications for tasks

​Manage saved sessions