Playbooks

This section collects end-to-end recipes. Each one walks the same arc — init → configure → validate → start → smoke — using only real mono-agent.config.json keys and the mono-agent CLI, so you can copy a playbook, adapt the placeholders, and have a working agent in minutes.

Every recipe ends with a concrete smoke test (a Telegram message, a curl, a cron tick, or a recorded-run assertion) so you can prove the agent works before you ship it.

How to use these

1. Pick a recipe from the selector or the full table below.
2. Run mono-agent init with the suggested --model (and --memory / repeated canonical --fallback routes where shown).
3. Edit mono-agent.config.json per the recipe — keys are cross-checked against the config blueprint and feature registry.
4. Run mono-agent validate (catches missing tokens, unreachable providers, un-pulled local models and consolidation cadence), then mono-agent start.
5. Run the recipe’s smoke test and inspect the JSONL run artifact under artifacts.dir.

Note

mono-agent init, validate, and start are cli coverage; most knobs below are config. Recipes that compose responders in TypeScript (multi-agent and some A2A) are code-only — see Programmatic.

Pick a recipe

Choose along three axes, in order: channel (how messages reach the agent), then memory tier, then deployment shape.

1. By channel

You want the agent reachable via…	Start with
Telegram (long-polling)	Personal Telegram Assistant
Slack (Socket Mode, mention-triggered)	Slack Team Bot · Cron Digest → Slack
An OpenAI-compatible /v1 endpoint (Open WebUI, SDKs)	OpenAI Endpoint for Open WebUI
Plain HTTP (sync + async jobs)	Webhook Automation
Another agent over A2A	A2A Provider + Consumer
A scheduled prompt (no inbound channel)	Cron Digest
A local-model agent	Local-Only Ollama Agent · Local-Only LM Studio Agent · Local-first Web Research

See Channels for the full per-channel reference.

2. By memory tier

Memory need	Tier	Recipe
Remember every turn, scheduled consolidation, semantic recall	bujo	Telegram Assistant with BuJo
Durable notes + semantic recall, no scheduled consolidation	journal	Local-Only Ollama · Sandboxed Code Agent · Cron Digest
Stateless / no long-term memory	—	Webhook · OpenAI Endpoint · A2A

Memory tiers, writeMode, embeddings, and consolidation are covered in Memory and Consolidation.

3. By deployment shape

Shape	Recipe
Single agent, one channel	most recipes above
Fully local / air-gapped (no cloud, no outbound network)	Local-Only Ollama · Local-Only LM Studio
Reliability-hardened (ordered model fallback)	Multi-Model Fallback Chain
Composed / multi-agent (delegation)	Multi-Agent Orchestration · A2A Pair

All recipes

Recipe	Who it’s for	Goal
Personal Telegram Assistant with BuJo Memory	Individual power user wanting a private assistant that remembers	Telegram long-polling bot that captures every turn into BuJo memory, consolidates it automatically, and recalls past notes semantically.
Slack Team Bot with MCP Tools	DevOps engineer running a shared team bot	Slack Socket Mode bot, mention-triggered in allowed channels, with a custom MCP tool plus Read/Grep and SlackSendMessage for proactive posts.
Fully Local Ollama Agent (No Cloud)	Privacy-focused user with no cloud API budget	Agent running entirely on local Ollama via the Pi runtime, with journal memory on local embeddings and no outbound network.
Fully Local LM Studio Agent (No Cloud)	Privacy-focused user who prefers LM Studio’s GUI over Ollama’s CLI	Agent running entirely on a local LM Studio provider via the Pi runtime, with lite-tier FTS memory and no outbound network (optional journal-tier upgrade using LM Studio’s own embeddings).
OpenAI-Compatible Endpoint for Open WebUI	AI infra engineer fronting the agent with a chat UI	Expose the agent as an OpenAI-compatible /v1 endpoint so Open WebUI can stream responses and keep multi-turn state.
Webhook Automation with Sync + Async Endpoints	Backend developer integrating the agent into a pipeline	Accept fast sync HTTP calls and long-running async jobs (202 + status polling) across multiple named endpoints, some defined as markdown.
Cron Digest with Native Notify	Data analyst wanting a scheduled briefing pushed to a chat	Timezone-aware cron job that builds a daily digest with shared history and delivers the final answer through native Telegram, Slack, or web-console notification.
A2A Provider + Consumer Pair	Platform integrator connecting two agents over A2A	Publish agent A as an A2A provider (Agent Card discovery, bearer) and configure agent B to discover and call it.
Multi-Agent Orchestration (AskCollaborator)	Workflow designer composing specialist agents	One orchestrator delegates subtasks to named collaborator responders via the loopback AskCollaborator MCP tool.
Sandboxed Code Agent (Loopback Only, Deny .env)	Security team deploying an internal code assistant	Agent that reads repos and runs Bash inside the native sandbox with loopback-only network access and protected secrets, recalling local context.
Local-first Web Research Agent	Researcher wanting explicit search-provider selection and bounded public-page extraction	Pi agent using explicit Ollama or loopback SearXNG, ChatGPT-subscription Codex search, deterministic keyless fallback policy, local extraction, and optional isolated browser rendering.
Multi-Model Fallback Chain with Transcript Resume	Reliability-minded builder who can’t afford a single-provider outage	Primary cloud model with ordered backups the failover router tries on retryable failures, resuming from the transcript tail.
Interactive Agent with Long Jobs & Large Media	Builder whose agent must ask before acting, run multi-minute tools, and exchange large files	Telegram agent that blocks on AskUser for context, streams progress from a long transcription tool (keep-alive past 120s), accepts recordings over 20 MB via a self-hosted Bot API server, and returns a generated document.

Tip

Always run mono-agent validate before start. It is the single fastest way to catch a missing botToken, an un-pulled Ollama model, or a duplicate webhook path before they bite you at runtime.