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

# Agent

# `fluffbuzz agent`

Run an agent turn via the Gateway (use `--local` for embedded).
Use `--agent <id>` to target a configured agent directly.

Pass at least one session selector:

* `--to <dest>`
* `--session-id <id>`
* `--agent <id>`

Related:

* Agent send tool: [Agent send](/tools/agent-send)

## Options

* `-m, --message <text>`: required message body
* `-t, --to <dest>`: recipient used to derive the session key
* `--session-id <id>`: explicit session id
* `--agent <id>`: agent id; overrides routing bindings
* `--thinking <level>`: agent thinking level (`off`, `minimal`, `low`, `medium`, `high`, plus provider-supported custom levels such as `xhigh`, `adaptive`, or `max`)
* `--verbose <on|off>`: persist verbose level for the session
* `--channel <channel>`: delivery channel; omit to use the main session channel
* `--reply-to <target>`: delivery target override
* `--reply-channel <channel>`: delivery channel override
* `--reply-account <id>`: delivery account override
* `--local`: run the embedded agent directly (after plugin registry preload)
* `--deliver`: send the reply back to the selected channel/target
* `--timeout <seconds>`: override agent timeout (default 600 or config value)
* `--json`: output JSON

## Examples

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fluffbuzz agent --to +15555550123 --message "status update" --deliver
fluffbuzz agent --agent ops --message "Summarize logs"
fluffbuzz agent --session-id 1234 --message "Summarize inbox" --thinking medium
fluffbuzz agent --to +15555550123 --message "Trace logs" --verbose on --json
fluffbuzz agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
fluffbuzz agent --agent ops --message "Run locally" --local
```

## Notes

* Gateway mode falls back to the embedded agent when the Gateway request fails. Use `--local` to force embedded execution up front.
* `--local` still preloads the plugin registry first, so plugin-provided providers, tools, and channels stay available during embedded runs.
* `--channel`, `--reply-channel`, and `--reply-account` affect reply delivery, not session routing.
* When this command triggers `models.json` regeneration, SecretRef-managed provider credentials are persisted as non-secret markers (for example env var names, `secretref-env:ENV_VAR_NAME`, or `secretref-managed`), not resolved secret plaintext.
* Marker writes are source-authoritative: FluffBuzz persists markers from the active source config snapshot, not from resolved runtime secret values.