From 2154dc51d0b0c20befe3d44cb764f89e52a8c766 Mon Sep 17 00:00:00 2001 From: chengyongru Date: Fri, 10 Jul 2026 10:21:17 +0800 Subject: [PATCH] docs: add automation guide --- README.md | 1 + docs/README.md | 5 +- docs/automations.md | 201 +++++++++++++++++++++++++++ docs/chat-commands.md | 3 + docs/cli-reference.md | 3 + docs/guides/long-running-ai-agent.md | 1 + docs/webui.md | 16 +-- 7 files changed, 216 insertions(+), 14 deletions(-) create mode 100644 docs/automations.md diff --git a/README.md b/README.md index 56d800c6..59af4dc6 100644 --- a/README.md +++ b/README.md @@ -343,6 +343,7 @@ Browse the [repo docs](./docs/README.md) for the latest features and GitHub deve - Copy provider setup recipes: [Provider Cookbook](./docs/provider-cookbook.md) - Debug setup and runtime failures: [Troubleshooting](./docs/troubleshooting.md) - Talk to your nanobot with familiar chat apps: [Chat App AI Agent](./docs/guides/chat-app-ai-agent.md) · [Chat Apps](./docs/chat-apps.md) +- Schedule or trigger agent work: [Automations](./docs/automations.md) - Configure providers, web search, MCP, and runtime behavior: [Configuration](./docs/configuration.md) - Integrate nanobot with local tools and automations: [OpenAI-Compatible API](./docs/openai-api.md) · [Python SDK](./docs/python-sdk.md) - Run nanobot with Docker or as a Linux service: [Deployment](./docs/deployment.md) diff --git a/docs/README.md b/docs/README.md index 9eb2c32e..8306fdf7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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) | diff --git a/docs/automations.md b/docs/automations.md new file mode 100644 index 00000000..9ca0dedd --- /dev/null +++ b/docs/automations.md @@ -0,0 +1,201 @@ +# Automations + + + +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 ` in the target session | +| Heartbeat | Protected system schedule | Quiet recurring checks that should only report useful results | Edit `/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 `/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 +`/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 "Build failed on main. Inspect the logs and suggest the next fix." +``` + +For a local report script: + +```bash +generate-report | nanobot trigger +``` + +## 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 diff --git a/docs/chat-commands.md b/docs/chat-commands.md index 3ad5c116..31468f8e 100644 --- a/docs/chat-commands.md +++ b/docs/chat-commands.md @@ -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. diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 551fcb17..9d5279e5 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -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 | diff --git a/docs/guides/long-running-ai-agent.md b/docs/guides/long-running-ai-agent.md index dde41d39..4104cfef 100644 --- a/docs/guides/long-running-ai-agent.md +++ b/docs/guides/long-running-ai-agent.md @@ -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) diff --git a/docs/webui.md b/docs/webui.md index af066f33..f0b4a37c 100644 --- a/docs/webui.md +++ b/docs/webui.md @@ -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 `, 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.