Ad playbooks

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.
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.

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.

The agent drafts the playbook

It drafts every section from what it read, not from guesses.

You correct it

The agent shows the draft in one message. It asks one short question for each thing it isn’t sure of.

You pick the enhancements

The agent asks which AI enhancements to keep on, and saves them in the ad publishing settings.

The agent saves it

It calls save_ad_playbook with confirmed: true.

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.

{
  "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.

Open the row

Select the ad account.

Change the fields

Put one entry per line. Write each landing page as Label | https://…. An empty field removes it.

Select Save

The version goes up by 1.

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

Verify

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

Create your first agent ad: connect an agent and upload a paused ad.
How agents publish: what happens after the agent proposes.
Agent ad tools: get_ad_playbook, list_ad_examples and save_ad_playbook.

Agents and MCP

Agent ads

API Reference

Analytics

Events and users

Attribution and revenue

Cohorts and funnels

Metrics

Query

Workspace

Keys and approvals

Conversion rules

Trackable links

Saved reports

Dashboards, analyses and share links

Session replay

Exports

What a playbook holds

The first run

Later runs

Who can change it

Edit it in Settings

Verify

Next

​What a playbook holds

​The first run

​Later runs

​Who can change it

​Edit it in Settings

​Verify

​Next

What a playbook holds

The first run

Later runs

Who can change it

Edit it in Settings

Verify

Next