> ## Documentation Index
> Fetch the complete documentation index at: https://handler.alduncanson.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Messages, tasks, and sessions

> Send messages, stream responses, manage tasks, and reuse saved conversation state from the Handler CLI.

# 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:

```bash theme={null}
handler card get --server demo
```

Validate the configured server's card:

```bash theme={null}
handler card validate --server demo
```

Validate a saved agent card file:

```bash theme={null}
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:

```bash theme={null}
handler message send --server demo --text "Hello"
```

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

```bash theme={null}
handler message send --url http://localhost:8000 --text "Hello"
```

## Stream the response

Stream task events and response text from a configured server:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
handler message send --server demo --text "Start a task"
```

Continue using Handler's saved context and task IDs:

```bash theme={null}
handler message send --server demo --text "Continue that task" --continue
```

Inspect the saved session for a configured server:

```bash theme={null}
handler session show --server demo
```

If you already know the IDs you want, you can pass them explicitly:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
handler task get --server demo --task task-123
```

Include recent message history with the task response:

```bash theme={null}
handler task get --server demo --task task-123 --history-length 10
```

Cancel a running task:

```bash theme={null}
handler task cancel --server demo --task task-123
```

Reconnect to a task's SSE stream after interruption:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
handler task notification get --server demo --task task-123
```

For a local receiver you can run the bundled webhook server described in
[Local servers](./local-servers).

## Manage saved sessions

Handler stores session metadata locally so repeated CLI calls can reuse
conversation state.

List all saved sessions:

```bash theme={null}
handler session list
```

Show the saved session for a configured server:

```bash theme={null}
handler session show --server demo
```

Clear the saved session for one configured server:

```bash theme={null}
handler session clear --server demo
```

Clear all saved sessions:

```bash theme={null}
handler session clear --all
```

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