Recipes — common tasks, 1 click to the answer

Each recipe is a task you actually want to do mapped to the canonical chapter(s) where the pattern lives. If your task isn't here, the full table of contents probably has it.

I want to…

…expose my business API as an agent tool

→ 5.1 Custom Tools — Tool subclass with name / description / parameters / execute; production template at the end. TL;DR: return a JSON string, set requires_confirmation=True for side effects, write the description as if for the LLM.

…choose between Tool, Skill, MCP, Permission, and Hook

→ Part 5 · Extend Agent Behavior — start with the "Read by task" table: business APIs use Tools, LLM-side conventions use Skills / AGENTAO.md, existing external services use MCP, safety boundaries use Permissions, lifecycle interception / audit / continuation use Hooks.

…audit, intercept, or continue at lifecycle points

→ 5.7 Plugin Hooks — hooks.json rules, 8 events, command vs. prompt, StopHookResult, and the matched_rule_count == 0 silent rule. Event payload reference lives in 4.2 AgentEvent.

…stream agent output to a browser

→ 4.4 Streaming UI — SSE and WebSocket templates, thread / event-loop bridge with loop.call_soon_threadsafe, keep-alive frames. Pair with 2.7 FastAPI / Flask for a copy-paste production endpoint.

…add a "Stop" button that cancels mid-chat

→ 2.6 Cancellation & Timeouts — CancellationToken, wiring to client-disconnect events, hard wall-clock with asyncio.wait_for. chat() returns "[Cancelled: <reason>]" — don't catch an exception.

…show a tool-confirmation modal in my web UI

→ 4.5 Tool Confirmation UI — sync→async bridge with asyncio.run_coroutine_threadsafe, web modal pattern, "allow once" vs "always allow" UX. Pair with 5.4 Permission Engine so 90% of safe calls bypass the modal.

…pool agents per (tenant_id, session_id)

→ 2.3 Lifecycle for the lock + thread pattern; 6.7 Resource Governance for TTL + LRU eviction; 7.1 SaaS Assistant for the integrated FastAPI example.

…persist a conversation across pod restarts

→ 2.4 Session State & Persistence — what's on the instance, what to serialize (agent.messages), how to restore via add_message(role, content) before the next chat().

…switch model at runtime (cheap vs. expensive routing)

→ 2.5 Runtime LLM Switch — set_provider / set_model; routing patterns for cheap-then-expensive, primary-with-fallback, A/B.

…give each tenant their own credentials or MCP token

→ 2.2 Constructor: extra_mcp_servers for per-session MCP injection. 6.4 Multi-Tenant & Filesystem for the tenant isolation rules. 7.1 SaaS Assistant ties them together.

…block SSRF or lock down web_fetch

→ 6.3 Network & SSRF Defense — default blocklist coverage, the .github.com (suffix) vs github.com (exact) rule, redirect-disabling pattern. Don't disable the default blocklist — extend it.

…drive Agentao from Node / Go / Rust / IDE

→ Part 3 · ACP Protocol — start with 3.1 Quick Try for a 60-second taste, then 3.3 Host as ACP Client for the full client architecture (TS + Go skeletons).

…keep memory tenant-isolated

→ 5.5 Memory System for scopes (project + user) and graceful degradation. 6.4 Multi-Tenant & Filesystem for the cross-tenant pitfalls. Either disable user-scope or key entries by tenant_id+user_id.

…deploy via Docker without bloating runtime

→ 6.8 Deployment — multi-stage Dockerfile (build with uv, ship only the venv), StatefulSet + PVC + sessionAffinity for sticky sessions, canary by dimension.

…keep my host code working across Agentao releases (audit pipeline / observability)

→ 4.7 Embedded Harness Contract — the agentao.host package is the stable, schema-snapshotted host API. Use agent.events() (async pull iterator) for audit / SIEM / billing, and agent.active_permissions() for policy-snapshot UIs. Don't touch internal AgentEvent from production code.

Two runnable starting points: examples/host_events.py (~50 lines, prints to stdout) and examples/host_audit_pipeline.py (full SQLite audit loop).

…embed Agentao in a Jupyter notebook

→ examples/jupyter-session/ — one Agentao per kernel; agent.events() drives IPython.display. Includes a session.ipynb you can open immediately and a passing test suite. Pair with 1.3 Integration Modes for the in-process SDK background.

…build a Slack or WeChat bot

→ examples/slack-bot/ uses slack-bolt app_mention → one turn, with channel-scoped permissions. examples/wechat-bot/ is the WeChat polling-daemon equivalent with contact-scoped permissions. Both are minimum-shape (offline smoke, no API key).

…get hermetic pytest fixtures for Agentao

→ examples/pytest-fixture/ ships drop-in agent / agent_with_reply / fake_llm_client fixtures. Hermetic, no OPENAI_API_KEY needed. Pair with Appendix F.8 for the assertion patterns.

…replace Agentao's IO surfaces (FS / shell / MCP / memory) with my own backend

→ 2.2 Capability protocols lists all four host→Agentao injection slots (filesystem / shell / mcp_registry / memory_manager) and how each is bound. TL;DR: import the Protocols from agentao.host.protocols, pass implementations into the Agentao(...) constructor — None falls back to local defaults, not "disabled". Runnable end-to-end shape: examples/protocol-injection/ replaces all four slots with small adapters and asserts each one is consulted (6 smoke tests, no API key).

Don't see your task?

• All runnable examples — examples/README.md lists every sample with stack, run command, and what it shows.
• By role: see the "Pick your starting point" table on the home page.
• By search: VitePress search (top-right) is local + full-text.
• Stuck: Appendix F · FAQ & Troubleshooting is organized by symptom.