# Agent Playbooks

An **Agent Playbook** is a reusable instruction set (an SOP) that steers how a customer-facing [Agent](/docs/concepts/agents) handles a specific task. A playbook bundles instructions plus optional tools, record types, custom tools, and connected-account configs. You then assign it to one or more agents so they can execute it at runtime.

These are **not** [Max Playbooks](/docs/concepts/max/playbooks), which steer the user's personal Max assistant.

All playbook endpoints require a USER API key.

## Identity

| Field | Type | Notes |
|  --- | --- | --- |
| `id` | number | Use as `playbookId`. |
| `name` | string | 1–100 characters. |
| `description` | string | When to use this playbook. 10–750 characters. |
| `instructions` | string | The SOP the agent follows. 10–10,000 characters. |
| `isActive` | boolean | Default `true`. Inactive playbooks stay assigned but are not used at runtime. |
| `visibility` | enum | `ACCOUNT` (shared with the whole account) · `PRIVATE` (only the creator). Default `ACCOUNT`. |
| `tools` | array | System tool names the playbook may use (max 20). |
| `selectedRecordTypes` | array? | Record-type tool settings. |
| `selectedCustomTools` | array? | Custom-tool settings. |
| `playbookConnectedAccounts` | array? | Connected-account tool configs (`connectedAccountId`, `useAllTools`, `selectedToolSlugs`). |
| `createdByUserId` | number? | Creator. Only the creator (or an OWNER/ADMIN) can update; only the creator can delete. |
| `createdAt` | string | ISO timestamp. |
| `updatedAt` | string | ISO timestamp. |


## Assigning playbooks to an agent

Playbooks are account-scoped resources. Assigning them to an agent is a separate step:

- `GET /agents/{agentId}/playbooks` — which playbooks that agent currently has.
- `PUT /agents/{agentId}/playbooks` — **replaces** the full assignment set. Send `{ "playbookIds": [1, 2] }` to set it, or `{ "playbookIds": [] }` to unassign all.


You also wire playbooks through `PUT /agents/{agentId}/agent-setting` (the agent's brain). The dedicated assign endpoint is the one to use when you only want to change which playbooks are attached.

## Operations

| Verb | Path | Purpose |
|  --- | --- | --- |
| `GET` | `/public/v1/playbooks` | List (filters: `filterText`, `visibility`, `isActive`) |
| `POST` | `/public/v1/playbooks` | Create (USER key) |
| `GET` | `/public/v1/playbooks/{playbookId}` | Detail |
| `PUT` | `/public/v1/playbooks/{playbookId}` | Update (creator or OWNER/ADMIN) |
| `DELETE` | `/public/v1/playbooks/{playbookId}` | Delete (creator only) |
| `GET` | `/public/v1/agents/{agentId}/playbooks` | List assigned to an agent |
| `PUT` | `/public/v1/agents/{agentId}/playbooks` | Replace the assignment set |


Full list in the **[API Reference](/reference/openapi)** under the `Agent Playbooks` tag.

## CLI

```bash
frontline playbooks list --table
frontline playbooks create \
  --name "Refund flow" \
  --description "How to process a customer refund request" \
  --instructions "1. Verify the order number. 2. Confirm the refund window. 3. ..."
frontline playbooks assign --agent-id <agentId> --playbook-ids '[1,2]'
frontline playbooks assigned --agent-id <agentId> --table
```