> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datalyr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ad playbooks

> How each ad account's ads are made: naming, structure, voice, claims, links and setup. The agent learns it on its first run, you confirm it, and every later run follows it.

An ad playbook says how one ad account's ads are made. The agent drafts it on its first
run on the account, and you confirm it. Every later run reads it first and follows it.

DATALYR saves one playbook per ad account in each workspace. Your teammates and every
agent app use the same one.

## What a playbook holds

| Section | Holds | Example |
| - | - | - |
| Naming | A pattern for campaign, ad set and ad names, and up to 10 real names that follow them | `CBO - {product} - {geo}`, `Broad - {angle} - {age}+`, `{n}{variant} - {hook}` |
| Structure | Budget on the campaign or on each ad set, angles per ad set, variants per angle (1–10 each), notes | Budget on the campaign, 3 angles, 2 variants |
| Voice | How the brand sounds, what to do, what to avoid, and up to 5 lines from the account's best ads | Avoid "game-changer" |
| Claims | Offers, prices and claims you approved. The agent never invents others. | `20% off first order` |
| Landing pages | Up to 30 pages, each with a label and a URL | Label `LP2`, URL `https://shop.example.com/lp2` |
| CTA | The default call to action | `LEARN_MORE` |
| Identity | The Facebook Page and Instagram account | |
| Sizes | The file shapes to make | `1:1 + 9:16 in one ad` |
| Placements | `automatic`, `exclude` a list, or `only` a list | |
| Attribution | `7d_click_1d_view`, `7d_click` or `1d_click` | |
| Notes | Anything else about the setup | |

| Not in a playbook | Where it is |
| - | - |
| AI enhancements | **Settings → Ad publishing**, set with `update_ad_publish_settings` |
| URL parameters | DATALYR adds tracking to every ad link. See [Links and tracking](/agent-ads/how-publishing-works#links-and-tracking). |
| Budgets | The agent asks you each time. It never saves a budget you didn't give. |

## The first run

When `get_ad_playbook` returns `playbook: null`, or `gaps` lists missing sections, the
agent sets the playbook up.

<Steps>
  <Step title="The agent reads the account">
    It reads campaign and ad set names, the account's own ads, which ads perform, and the enhancement defaults. See the table below.
  </Step>

  <Step title="The agent drafts the playbook">
    It drafts every section from what it read, not from guesses.
  </Step>

  <Step title="You correct it">
    The agent shows the draft in one message. It asks one short question for each thing it isn't sure of.
  </Step>

  <Step title="You pick the enhancements">
    The agent asks which AI enhancements to keep on, and saves them in the ad publishing settings.
  </Step>

  <Step title="The agent saves it">
    It calls `save_ad_playbook` with `confirmed: true`.
  </Step>
</Steps>

| Read | Tool | Gives |
| - | - | - |
| Names and setup | `list_ad_targets` | Campaign and ad set names, objectives, goals, placements |
| The account's own ads | `list_ad_examples` | Meta only. Running ads first, then paused ones: names, every primary text, headline and description, CTA, link, Page and Instagram account, format, placement rules, attribution. |
| What performs | `get_ads` | The last 30 days by ad, so the best ads count most |
| Enhancements | `get_ad_publish_settings` | Each enhancement and its default |

`list_ad_examples` only reads. It changes nothing in the ad account. On TikTok and Google
Ads, the agent asks you for two or three of your best ads instead.

## Later runs

| Rule | Detail |
| - | - |
| Read first | The agent calls `get_ad_playbook` before it plans ads, and follows it |
| New things only | It asks only about a new product, offer, landing page or angle |
| Corrections | When you correct the setup, the agent offers to save it. After a yes, it saves only that field. |
| Drift | If the account's own names drift from the playbook, the agent says so once |

A save is a patch. Top-level fields replace the old value. Naming, structure and voice
merge field by field. `null` removes a field.

```json theme={null}
{
  "platform": "meta",
  "account_id": "act_123",
  "playbook": { "voice": { "avoid": ["game-changer"] }, "cta": null }
}
```

## Who can change it

| Who | Can |
| - | - |
| An agent connection at Create paused or Publish live | Read and save it with the tools. `confirmed: true` marks it confirmed. |
| An agent connection at Propose | Read and save it. Its saves stay a draft until a person saves it in Settings. |
| A Read-only connection | Read it. A save is refused with `403`. |
| A workspace owner or admin | Edit or clear it in Settings |
| A member or viewer | Look at it in Settings |

Each save adds 1 to the version and goes in the audit log, from an agent or from
Settings. A save from Settings counts as confirmed.

## Edit it in Settings

Open **Settings → Ad publishing → Ad playbooks**. Each connected ad account has one row.

| Row shows | Meaning |
| - | - |
| **Set up**, with `v1 · confirmed Oct 15 · missing sizes` | A playbook is saved: its version, the date it was confirmed, and the sections still empty |
| **Set up**, with `draft, not confirmed` | An agent saved it, but nobody confirmed it yet. Open it and select **Save** to confirm it. |
| **Not set up** | No playbook yet. The next agent run sets it up. |

<Steps>
  <Step title="Open the row">
    Select the ad account.
  </Step>

  <Step title="Change the fields">
    Put one entry per line. Write each landing page as `Label | https://…`. An empty field removes it.
  </Step>

  <Step title="Select Save">
    The version goes up by 1.
  </Step>
</Steps>

**Clear** removes the playbook after you confirm. The next agent run on the account sets it
up again.

## Verify

1. Ask the agent for a paused ad on an ad account with no playbook.
2. Confirm the agent shows a draft playbook and asks about enhancements.
3. Confirm the draft.
4. Open **Settings → Ad publishing → Ad playbooks**.
5. Confirm the row shows **Set up**, `v1` and today's date.
6. Start a new conversation and ask for another ad.
7. Confirm the agent follows the playbook and doesn't ask the setup questions again.

## Next

* [Create your first agent ad](/agent-ads/get-started): connect an agent and upload a paused ad.
* [How agents publish](/agent-ads/how-publishing-works): what happens after the agent proposes.
* [Agent ad tools](/agent-ads/tools): `get_ad_playbook`, `list_ad_examples` and `save_ad_playbook`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.