Stateful automations

Most automation tools run if X, then Y: a trigger and an action, with nothing in between and nothing after. That works when the answer is always the same. It fails on the questions that need judgement, because “ROAS fell from 4.2 to 3.1” could mean a product went out of stock, a price rose, a promo ended, spend shifted, a competitor cut prices, conversion fell on one product, or you are intentionally buying growth. Same number, seven different right actions.

A stateful automation represents the whole responsibility, every time it runs: observe, detect, establish the state, investigate, decide, explain, get approval, act, verify, and watch what happens. It knows where it is in that loop, what it has already asked and been told, and what it predicted last time. This page explains how that works in Meerkats, from a rule you type in plain words to the record it leaves.

Anatomy of a rule#

You create an automation on the New automation page (Automation Agents › + New Agent) by describing it in plain words: “Pause any Flipkart campaign whose ROAS drops under 0.4”. Meerkats turns that into a rule with these fields and shows them back to you before saving.

Over the API, the same rule is a JSON object:

{
  "name": "Pause low-ROAS search campaigns",
  "platform": "google",
  "target_campaign": null,
  "metric": "real_roas",
  "comparator": "lt",
  "threshold": 2.0,
  "window_days": 4,
  "action": "pause_campaign",
  "mode": "suggest",
  "schedule_cron": "*/30 * * * *",
  "cooldown_hours": 24
}

The window is the first piece of state: a rule fires when the condition has held for the whole window, not on one bad hour. The cooldown is the second: once fired, the rule waits before it can fire again on the same target, so one dip doesn’t produce five proposals.

Cadence and what it implies#

The cadence you choose sets how much the automation is expected to do on its own. The app groups rules by it in Agents run history.

A paused rule keeps its history but doesn’t run. You can also run any rule once, on demand, or test it against a recent example without writing anything.

What a proposal contains#

When a rule matches, the automation doesn’t fire an action. It stages a plan: one coherent set of changes with one goal, for example a fix set, a reallocation, or a new campaign tree. Each line in the plan is a registered action, and each line carries:

• Risk class: none, low, medium or high. The class sets the friction, never the predicted return.
• Predicted impact: the metric it expects to move, by how much, over what window, with the prior the forecast came from.
• Before state: the target’s actual current values, fetched in this run, not from cache.
• Reversible: whether it can be undone, and the rollback that does it.
• Provenance: where every number in the line came from.
• Origin: what triggered it: the rule, an investigation finding, or a request.
• Expiry: after which the approval is void and the plan must be re-validated.

Plans land in your Inbox under Agent runs — need approval, with the evidence attached: the metric, the window, what changed, the why-chain through the relationship graph, and the forecast.

Risk classes and limits#

Caps apply whatever the mode: budget cuts up to 20% per change, increases up to 50% per week per campaign, bid changes up to 15%, and a bidding-strategy change waits 14 days after the last one. Anything Meerkats creates is born paused; switching it on is its own high-risk action. Price and stock changes on a store or marketplace are never made by an ad rule; they are staged as tasks for the person who owns the listing.

Approval#

• One approval per plan. Approving a plan approves its lines; you aren’t asked line by line.
• High risk asks twice. Activating a created campaign, for example, has its own confirmation after the read-back verification and a preview.
• Edit in place. Change a number in the plan and Meerkats re-resolves everything downstream, restates the diff, and re-offers it.
• Reject with a reason. One optional question. The reason goes into the workspace’s known failure modes, so the same proposal doesn’t return.
• Approvals expire. A lapsed approval is re-validated against live state and re-staged. It is never executed as-is.
• Chains approve per step. When an investigation hands off to an action, each step gets its own approval, and the handoff shows what it will feed the next step.
• Approve all low-risk in the Inbox approves every low-risk line at once.

If no goal frame exists when a plan reaches approval, that is the moment Meerkats asks for it: once, saved as the standing frame.

Autonomy#

Every workspace starts with every action type in ask every time. There are three modes.

Execution#

An approved plan runs under a fixed contract, the same for every platform.

1. Registered actions only. A plan with an unknown action or an unresolved target is refused at staging, never at run time.
2. Re-read live. Immediately before applying, Meerkats reads the target’s current state from the platform. Any drift from the before state aborts the run and re-stages.
3. Create paused. New campaigns, ad sets and ads are created paused. Activation is a separate high-risk action.
4. Read back and verify. After every write, the object is read back and compared with the approved plan. A non-empty difference stops the plan and is reported verbatim.
5. All or nothing. A multi-object plan is a transaction. If one step fails, everything the plan created or changed is rolled back, and the exact step and the platform’s error are reported, along with the account’s state now.
6. No write path yet? Where a platform has no write access, the plan becomes a guided checklist: exact changes with before and after values, which you tick off, and the watch attaches the same way.

After success, four things happen at once: the action log gets the full provenance chain; the account knowledge is updated so it never lags its own actions; a watch is attached with the plan’s forecast as the yardstick; and any sibling lines not yet executed stay visible in a carry-forward register, so nothing is silently dropped between sessions.

Watch#

Every executed action gets a watch. The forecast in the plan is the yardstick, so predicted-versus-actual is computed, not judged. Default windows are a first read at three days and a verdict at fourteen; platforms with slower attribution push the first read later, and no verdict is given on an unripe window.

During a platform’s learning phase, edits are frozen and the freeze is shown with its end date. A watch that completes writes back: predicted-versus-actual to the ledger that governs autonomy, the outcome to the account’s priors, a logged gap when a forecast misses by more than 40%, and effectiveness stats to the rule that fired.

The trace#

Open any run in Automation Agents › Agents run history and you see the whole loop:

• What triggered it, and when.
• What it read, with the sync time of each source.
• The state it established and the path it investigated.
• The plan: each line, its risk, forecast, before state and provenance.
• Who approved, edited or rejected it, and when.
• The change made, the read-back verification, and the value it replaced.
• The watch: predicted versus actual, and the verdict.

The workspace Activity log records the same actions at the account level: sharing, access changes, data changes and automation, with the person or app that did each.

A worked example#

The rule: “Tell me when ROAS is below 4 for three days and work out why.” Illustrative numbers.

1. Detect. Day three closes with corrected ROAS at 3.1 against the frame’s target of 4.0. The window is met; the cooldown is clear.
2. Establish state. Two campaigns account for the drop, both Google Search, both since Tuesday. The goal frame says the account is in efficiency mode; no entity is protected.
3. Investigate. Spend flat, CPC up 8%, CTR flat, conversion rate down 24% on search terms containing the hero product. Shopify shows the hero SKU in stock. Competitor tracking shows a rival cut its price on the matched listing by 12% on Tuesday. Measurement checks pass.
4. Decide and explain. Cause: price-sensitive search demand moving to the rival. Proposal: hold bids on the price-sensitive terms and lead with the bundle, rather than cut budget. Forecast: conversion rate recovers to within 10% of baseline in 7 days, from the account’s prior on the last bundle push.
5. Approve. The plan is medium risk, one approval. You approve at 09:40.
6. Act. Meerkats re-reads both campaigns (unchanged), applies the bid holds, reads them back (match), logs the change with the previous bids.
7. Watch. Day three read: conversion rate up 14%. Day fourteen verdict: on track. Written to the ledger; the bundle-lead prior gets stronger.

See also autonomy level, approval and trace in the glossary.