docs: add automation guide
This commit is contained in:
chengyongru
Xubin Ren
+4
-1
@@ -42,6 +42,7 @@ full reference first.
|
||||
| Use a browser AI agent WebUI | [`guides/ai-agent-webui.md`](./guides/ai-agent-webui.md) |
|
||||
| Connect an AI agent to chat apps | [`guides/chat-app-ai-agent.md`](./guides/chat-app-ai-agent.md) |
|
||||
| Run long-running agent tasks | [`guides/long-running-ai-agent.md`](./guides/long-running-ai-agent.md) |
|
||||
| Schedule or trigger agent turns | [`automations.md`](./automations.md) |
|
||||
| Add long-term agent memory | [`guides/ai-agent-memory.md`](./guides/ai-agent-memory.md) |
|
||||
| Add MCP tools to an agent | [`guides/mcp-tools-for-ai-agents.md`](./guides/mcp-tools-for-ai-agents.md) |
|
||||
| Run an agent from Python | [`guides/python-ai-agent-sdk.md`](./guides/python-ai-agent-sdk.md) |
|
||||
@@ -89,7 +90,8 @@ If a local `nanobot agent` session can already answer normally, you can also ask
|
||||
|---|---|---|
|
||||
| Open the bundled browser UI | [`webui.md`](./webui.md) | `nanobot webui`, chat workspace, Apps, Skills, Automations, and settings |
|
||||
| Connect Telegram, Discord, WeChat, Slack, Email, Mattermost, or another chat app | [`chat-apps.md`](./chat-apps.md) | A gateway-backed chat channel with access control |
|
||||
| Use slash commands and automations | [`chat-commands.md`](./chat-commands.md) | Pairing, model presets, local triggers, heartbeat tasks, and chat-side controls |
|
||||
| Use automations | [`automations.md`](./automations.md) | Scheduled automations, local triggers, heartbeat, WebUI management, and delivery behavior |
|
||||
| Use slash commands | [`chat-commands.md`](./chat-commands.md) | Pairing, model presets, local triggers, heartbeat tasks, and chat-side controls |
|
||||
| Generate images | [`image-generation.md`](./image-generation.md) | Image provider config, WebUI image mode, and artifact behavior |
|
||||
| Run several isolated bots | [`multiple-instances.md`](./multiple-instances.md) | Separate configs, workspaces, ports, and sessions |
|
||||
| Deploy outside a terminal | [`deployment.md`](./deployment.md) | Docker, systemd user services, and macOS LaunchAgent setup |
|
||||
@@ -121,6 +123,7 @@ If a local `nanobot agent` session can already answer normally, you can also ask
|
||||
| WebSocket/WebUI protocol details | [`websocket.md`](./websocket.md) |
|
||||
| OpenAI-compatible API usage | [`openai-api.md`](./openai-api.md) |
|
||||
| Python SDK usage | [`python-sdk.md`](./python-sdk.md) |
|
||||
| Scheduled automations and local triggers | [`automations.md`](./automations.md) |
|
||||
| Multiple configs, workspaces, and ports | [`multiple-instances.md`](./multiple-instances.md) |
|
||||
| Security, sandboxing, and SSRF controls | [`configuration.md#security`](./configuration.md#security) |
|
||||
| Channel plugin development | [`channel-plugin-guide.md`](./channel-plugin-guide.md) |
|
||||
|
||||
@@ -0,0 +1,201 @@
|
||||
# Automations
|
||||
|
||||
<!-- Meta description: Create, run, and manage nanobot scheduled automations, local triggers, and heartbeat-backed background checks. -->
|
||||
|
||||
Automations are agent turns that run later in a linked chat/session. Use them
|
||||
when nanobot should do work without someone actively typing: reminders,
|
||||
recurring checks, nightly summaries, CI follow-ups, local script reports, or
|
||||
webhook-driven events.
|
||||
|
||||
Create automations from the chat, channel, or WebUI session where the result
|
||||
should appear. That lets nanobot keep the right session history, workspace, and
|
||||
reply target.
|
||||
|
||||
## Choose an Automation Type
|
||||
|
||||
| Type | Starts from | Best for | Created with |
|
||||
|---|---|---|---|
|
||||
| Scheduled automation | Time, interval, or cron expression | Recurring reminders, scheduled summaries, one-time future tasks | Ask nanobot in the target session to schedule it with the `cron` tool |
|
||||
| Local trigger | A local `nanobot trigger ...` command | CI jobs, webhooks, shell scripts, generated reports | `/trigger <name>` in the target session |
|
||||
| Heartbeat | Protected system schedule | Quiet recurring checks that should only report useful results | Edit `<workspace>/HEARTBEAT.md` |
|
||||
|
||||
The two user-created automation types are scheduled automations and local
|
||||
triggers. Heartbeat uses the same background service but is system-managed and
|
||||
protected from normal automation edits.
|
||||
|
||||
## Before You Create One
|
||||
|
||||
Keep `nanobot gateway` running. The gateway owns background delivery for chat
|
||||
apps, WebUI sessions, scheduled automations, local triggers, heartbeat, and
|
||||
Dream jobs.
|
||||
|
||||
Use the same workspace and config for the gateway and any process that sends
|
||||
local trigger messages. If you run multiple nanobot instances, pass the matching
|
||||
`--config` or `--workspace` option to `nanobot trigger`.
|
||||
|
||||
Create each automation from the target session. An automation without a linked
|
||||
chat/session cannot be enabled or run from the WebUI because nanobot would not
|
||||
know where to deliver the turn.
|
||||
|
||||
## Scheduled Automations
|
||||
|
||||
Scheduled automations are created by the agent's `cron` tool. In practice, ask
|
||||
nanobot from the target chat or WebUI session:
|
||||
|
||||
```text
|
||||
Every weekday at 9am, check open pull requests and summarize blockers here.
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```text
|
||||
Tomorrow at 4pm, remind me to send the release notes.
|
||||
```
|
||||
|
||||
The cron tool supports interval schedules, cron expressions, and one-time
|
||||
scheduled tasks. Cron expressions can include an IANA timezone such as
|
||||
`America/Vancouver`; otherwise nanobot uses the runtime default timezone.
|
||||
|
||||
Scheduled automations normally deliver the result back to the session where they
|
||||
were created. Use them for work that should run on a predictable schedule and
|
||||
report each run.
|
||||
|
||||
For background checks that should stay quiet unless there is something useful to
|
||||
report, use heartbeat instead of a user-created scheduled automation.
|
||||
|
||||
## Local Triggers
|
||||
|
||||
Local triggers let a local script or external service send a message into a
|
||||
specific nanobot session later.
|
||||
|
||||
Create the trigger from the chat or WebUI session where future messages should
|
||||
arrive:
|
||||
|
||||
```text
|
||||
/trigger PR review
|
||||
```
|
||||
|
||||
nanobot replies with a trigger ID and a command shaped like:
|
||||
|
||||
```bash
|
||||
nanobot trigger trg_8K4P2Q9X "Review PR #4502"
|
||||
```
|
||||
|
||||
Replace the quoted text with the message nanobot should receive. For generated
|
||||
or longer content, pipe stdin:
|
||||
|
||||
```bash
|
||||
generate-report | nanobot trigger trg_8K4P2Q9X
|
||||
```
|
||||
|
||||
For multiple instances, use the same config or workspace selector as the
|
||||
gateway:
|
||||
|
||||
```bash
|
||||
nanobot trigger --config ./bot-a/config.json trg_8K4P2Q9X "Nightly report"
|
||||
nanobot trigger --workspace ./bot-a/workspace trg_8K4P2Q9X "Nightly report"
|
||||
```
|
||||
|
||||
nanobot does not provide a built-in public webhook receiver for local triggers.
|
||||
If GitHub, CI, or another external system should wake nanobot, run your own
|
||||
small webhook service and have it call `nanobot trigger` after it builds the
|
||||
final message.
|
||||
|
||||
## Heartbeat
|
||||
|
||||
Heartbeat is for recurring workspace checks that should usually stay quiet. It
|
||||
reads `<workspace>/HEARTBEAT.md`, executes active tasks, and sends only useful or
|
||||
actionable results to the most recently active chat target.
|
||||
|
||||
Use heartbeat for checks such as "watch this repo for important failures" or
|
||||
"periodically inspect this workspace and only tell me when action is needed." Use
|
||||
a scheduled automation instead when every run should produce a visible reminder
|
||||
or report.
|
||||
|
||||
Heartbeat is enabled by default when `nanobot gateway` starts. Configure it in
|
||||
[`configuration.md#gateway-heartbeat`](./configuration.md#gateway-heartbeat).
|
||||
|
||||
## Manage Automations
|
||||
|
||||
Use the WebUI Automations view to:
|
||||
|
||||
- filter by all, active, paused, needs-attention, or system jobs;
|
||||
- search by task name, message, trigger command, linked chat, schedule, or
|
||||
status;
|
||||
- sort by next run, last run, updated time, or name;
|
||||
- run scheduled automations now;
|
||||
- pause or resume, rename, or delete user-created automations;
|
||||
- copy the CLI command for local triggers;
|
||||
- inspect protected system automations without changing them.
|
||||
|
||||
Local triggers do not have a WebUI "Run now" action because each run needs a
|
||||
message. Copy the `nanobot trigger ...` command from the WebUI and replace
|
||||
`"message"` with the content that should be delivered.
|
||||
|
||||
## Delivery and Reliability
|
||||
|
||||
Automation delivery is workspace-local. Scheduled jobs and local trigger
|
||||
deliveries use the same workspace as the gateway.
|
||||
|
||||
Local trigger messages are written to a durable queue. If the gateway is not
|
||||
running yet, the message waits in that workspace. If the linked session is
|
||||
already running a turn, the trigger waits until the session becomes idle instead
|
||||
of being injected into the active turn.
|
||||
|
||||
The local trigger queue is at-least-once, not exactly-once. If the gateway exits
|
||||
after claiming a delivery but before the linked turn completes, the next gateway
|
||||
start requeues that delivery. External scripts should make repeated trigger
|
||||
messages safe. If the delivery reaches the agent and the turn fails, the
|
||||
delivery is marked failed instead of retrying forever.
|
||||
|
||||
Each local trigger delivery writes an audit record under
|
||||
`<workspace>/triggers/runs`. Run one gateway consumer per workspace; the local
|
||||
queue is not a distributed multi-consumer queue.
|
||||
|
||||
## Common Patterns
|
||||
|
||||
For a nightly report, ask from the target session:
|
||||
|
||||
```text
|
||||
Every night at 9pm, review today's workspace changes and summarize anything I should handle tomorrow.
|
||||
```
|
||||
|
||||
For a CI follow-up, create a trigger once:
|
||||
|
||||
```text
|
||||
/trigger CI follow-up
|
||||
```
|
||||
|
||||
Then have your CI or webhook adapter call:
|
||||
|
||||
```bash
|
||||
nanobot trigger <trigger-id> "Build failed on main. Inspect the logs and suggest the next fix."
|
||||
```
|
||||
|
||||
For a local report script:
|
||||
|
||||
```bash
|
||||
generate-report | nanobot trigger <trigger-id>
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If an automation does not run, check that `nanobot gateway` is running, the
|
||||
automation is enabled, and it was created from a linked chat/session.
|
||||
|
||||
If a local trigger waits forever, confirm the command uses the same workspace or
|
||||
config as the gateway.
|
||||
|
||||
If a trigger message appears twice after a restart, treat it as expected
|
||||
at-least-once delivery and make the external message idempotent.
|
||||
|
||||
If you need to edit, pause, resume, rename, delete, or inspect automations, use
|
||||
the WebUI Automations view.
|
||||
|
||||
## Related Docs
|
||||
|
||||
- [`webui.md#automations`](./webui.md#automations) for the browser management view
|
||||
- [`chat-commands.md#local-triggers`](./chat-commands.md#local-triggers) for `/trigger`
|
||||
- [`cli-reference.md#local-triggers`](./cli-reference.md#local-triggers) for `nanobot trigger`
|
||||
- [`configuration.md#gateway-heartbeat`](./configuration.md#gateway-heartbeat) for heartbeat settings
|
||||
- [`guides/long-running-ai-agent.md`](./guides/long-running-ai-agent.md) for long-running agent work
|
||||
@@ -118,6 +118,9 @@ Manage triggers from the WebUI Automations view. You can search, pause/resume,
|
||||
rename, delete, and copy the trigger command there. A session may have multiple
|
||||
triggers, just like it may have multiple scheduled automations.
|
||||
|
||||
See [Automations](./automations.md) for how local triggers fit with scheduled
|
||||
automations, heartbeat, and gateway delivery.
|
||||
|
||||
## Periodic Tasks
|
||||
|
||||
Periodic background checks are driven by `HEARTBEAT.md` in your workspace (`~/.nanobot/workspace/HEARTBEAT.md`). When `nanobot gateway` starts, it registers a protected heartbeat cron job by default. Every 30 minutes, that job checks the file; if it finds tasks under `## Active Tasks`, the agent executes them and delivers only results that pass the notification gate to your most recently active chat channel. If there are no active tasks, or the result is routine with nothing useful to report, the heartbeat is skipped silently.
|
||||
|
||||
@@ -188,6 +188,9 @@ rename, delete, search, and copy the command for each trigger.
|
||||
For webhooks or other external systems, run your own small service and have it
|
||||
call this CLI after it decides what message nanobot should receive.
|
||||
|
||||
See [Automations](./automations.md) for the broader automation model, WebUI
|
||||
management, and delivery behavior.
|
||||
|
||||
## OpenAI-Compatible API
|
||||
|
||||
| Command | Description |
|
||||
|
||||
@@ -66,6 +66,7 @@ so nanobot can link it to the correct session and workspace.
|
||||
|
||||
## Related nanobot docs
|
||||
|
||||
- [Automations](../automations.md)
|
||||
- [WebUI Automations](../webui.md#automations)
|
||||
- [Chat Commands](../chat-commands.md)
|
||||
- [Memory](../memory.md)
|
||||
|
||||
+3
-13
@@ -150,6 +150,9 @@ be created from the chat, channel, or session where they are supposed to run so
|
||||
nanobot keeps the correct target context. When an automation runs, it normally
|
||||
delivers the result back to that linked chat.
|
||||
|
||||
For the full automation model, creation flow, trigger CLI usage, and delivery
|
||||
semantics, see [`automations.md`](./automations.md).
|
||||
|
||||
There are two user-facing automation types:
|
||||
|
||||
- Scheduled automations, created by the agent's cron tool, run at a time,
|
||||
@@ -157,19 +160,6 @@ There are two user-facing automation types:
|
||||
- Local triggers, created with `/trigger <name>`, run when you call a local
|
||||
command such as `nanobot trigger trg_8K4P2Q9X "Review PR #4502"`.
|
||||
|
||||
If a GitHub webhook, CI system, or another service should wake nanobot up, keep
|
||||
that webhook/service outside nanobot and have it call the trigger command with
|
||||
the final message.
|
||||
|
||||
Trigger deliveries use the same workspace as the gateway. They survive gateway
|
||||
restarts and are requeued if the process exits before the linked turn completes.
|
||||
If the linked session is already running a turn, the local trigger waits until
|
||||
that session is idle instead of being injected into the active turn. This is an
|
||||
at-least-once local queue, so repeated delivery is possible after an interrupted
|
||||
process. A delivered trigger is recorded as an automation turn in the linked
|
||||
session; if the agent receives it but the turn fails, Automations marks the run
|
||||
failed instead of retrying indefinitely.
|
||||
|
||||
For recurring background checks that should stay quiet unless there is something
|
||||
useful to report, use the protected heartbeat job by editing `HEARTBEAT.md`
|
||||
instead of creating a chat automation.
|
||||
|
||||
Reference in New Issue
Block a user