Playbooks & FAQs

Reusable knowledge bundles attached to agents.

Two complementary primitives for giving agents context without ballooning the system prompt.

Playbooks

A playbook is a prompt fragment + a list of tool names. Think of it as a self-contained capability: “I know how to book appointments, and to do that I need these three tools available.”

{
  "id": "uuid",
  "name": "appointments",
  "display_name": "Appointment booking",
  "category": "scheduling",
  "description": "Books, reschedules, and cancels appointments.",
  "tool_names": ["check_availability", "book_appointment", "cancel_appointment"],
  "tags": ["calendar"]
}

When an agent has a playbook attached, the playbook’s prompt body gets merged into the agent’s system prompt at runtime, and the agent becomes aware of the listed tools.

Why bundle tools and prompt?

Because the prompt and the tool list have to agree. A “book an appointment” prompt is useless if the book_appointment tool isn’t available. Wrapping them together as a playbook prevents the “prompt mentions a tool that doesn’t exist” bug and makes capabilities composable.

Built-in vs custom

Same model as tools: is_default = true for shipped playbooks, custom ones can be created, updated, and deleted.

FAQs

A FAQ is one question + answer + category. Surfaced to the agent as quick-lookup knowledge for common questions.

{
  "id": "uuid",
  "name": "shipping-times",
  "category": "logistics",
  "title": "How long does shipping take?",
  "summary": "2–5 business days domestic.",
  "content": "Standard shipping arrives within 2–5 business days...",
  "tags": ["shipping", "logistics"]
}

FAQs are simpler than playbooks — no tool dependencies, no prompt fragment. Just attached knowledge.

Operations

Operation	Playbooks	FAQs
List	GET /api/playbooks	GET /api/faqs
Get (by UUID or name)	GET /api/playbooks/{id}	GET /api/faqs/{id}
Create	POST /api/playbooks	POST /api/faqs
Update	PUT /api/playbooks/{id}	PUT /api/faqs/{id}
Delete custom	DELETE /api/playbooks/{id}	DELETE /api/faqs/{id}
Attach to agent	POST /api/agents/{id}/playbooks	POST /api/agents/{id}/faqs
Detach from agent	DELETE /api/agents/{id}/playbooks/{pbId}	DELETE /api/agents/{id}/faqs/{faqId}

When to use which

If you want…	Use
Reusable capability across many agents (with its tools)	Playbook
Static Q&A entries the agent can quote	FAQ
Per-agent config that no one else will touch	Inline it in the agent’s system_prompt