Playbooks

A playbook is a saved prompt + a schedule + execution config. The orchestrator fires the prompt at the scheduled time, runs the agent autonomously, and (optionally) notifies you when it’s done.

Use cases:

Morning briefings (Gmail summary, calendar digest)
Daily/weekly finance recaps (Teller transactions, spend categorization)
Bill payment guidance (cron daily, check what’s due in the next 5 days, suggest payment)
Periodic data hygiene (clean up old artifacts, archive stale chats)

Anatomy

Field	Meaning
`id`	`pb_<nanoid>`.
`name`, `description`	Human-readable.
`prompt`	The task text. Plain text. This is what the agent sees as the initial user message.
`schedule`	Cron expression in UTC. `0 14 * * *` = 10am EDT daily.
`trigger_type`	`cron` or `webhook`. Webhook gives you a per-playbook URL to POST to.
`enabled`	Toggle off without deleting.
`notify_on`	`none` / `completion` / `failure` / `always`. Controls platform auto-notification on run end.
`notification_channels`	Where platform sends the notification: `slack`, `email`, `webhook`, or `telegram:<integration_id>` for a specific bot.
`chain_config`	Multi-chain execution (rare): `max_chains`, `budget_cap_usd`, `max_turns_per_chain`, `decision_*`.

Authoring tips

A good playbook prompt:

Specifies the schedule context in the first line (“Scheduled run (daily, 8am EDT)”) so the agent knows it’s an automated fire, not an interactive turn.
Includes early-exit logic (“If reminders_sent already has a row for today, output ‘skipping’ and stop.”).
Tells the agent exactly which MCP tools to use (teller_list_transactions, not “fetch transactions”).
Specifies the output format (a Telegram-formatted message, a Slack block, etc.).
Ends with a delivery step (call mcp_notify__notify_user explicitly) — see notify MCP.

Notify-on vs agent-side delivery

Two ways to deliver a playbook’s result:

Approach	When to use
Platform auto-notify (`notify_on: completion`)	Simple “run done, here’s the summary” pings. Agent’s final assistant text becomes the message body.
Agent-side delivery (`notify_on: none` + agent calls `mcp_notify__notify_user`)	When you need control over channel routing, message formatting (Telegram inline keyboards for thread-claim), conditional skipping, or multi-message output.

For anything non-trivial, agent-side delivery wins. The platform’s auto-notify is fine for “build succeeded” / “report generated” kinds of pings.

Multi-chain execution

For long-running work (e.g. “process every account, one at a time”), chain_config.max_chains > 1 lets the agent loop with budget tracking. Between chains it emits a StructuredOutput decision (CONTINUE / DONE) and the orchestrator dispatches the next chain. Budget cap and turn-per-chain limits bound the runaway risk.

API surface

Endpoint	Purpose
`GET /v1/playbooks`	List playbooks for a profile.
`POST /v1/playbooks`	Create.
`GET /v1/playbooks/:id`	One playbook (full prompt included).
`PATCH /v1/playbooks/:id`	Update.
`DELETE /v1/playbooks/:id`	Delete.
`POST /v1/playbooks/:id/run`	Fire immediately, out of schedule. `202 Accepted`.
`GET /v1/playbooks/:id/runs`	Historical runs.

Webhook trigger

When trigger_type=webhook, the platform exposes POST /webhook/playbooks/:secret — anyone with the secret can fire the playbook. The agent’s prompt receives the inbound POST body as a parameter. Use for integrations with external schedulers, Zapier, CI hooks, GitHub Actions.

Playbook workspaces

Each run creates a workspace with a pb-… session id. By default these are hidden from your chat list (no one wants 100 daily-briefing workspaces cluttering it). They appear once you claim a Telegram thread on them — see Telegram integration.