Agents
Create agents in plain words or from GitHub, manage them, ask them questions, and decide how much they do alone.
An agent is an AI worker that reads your business context and does a job: answers a question, monitors a metric, investigates a drop, audits an account, or proposes a change. Every agent in Meerkats runs on the same context layer and the same metric definitions, so two agents never disagree about what ROAS is.
Agents live under Automation Agents in the sidebar. The page is titled Agents and has three tabs: Agents (the list), Agents run history (every run), and Inbox Activity (what each agent sent to your Inbox).
Two kinds of agent#
- Built-in agents come with every workspace. They cover the checks most businesses want: spend and ROAS monitors, a daily triage, a weekly optimisation pass, a monthly review. They start disabled; turn on the ones you want.
- Your agents are the ones you create. Describe the job in plain words on the New automation page, or import a skill from a GitHub repository.
Both kinds show in the same list with the same controls.
What an agent can do#
| Job | What it does | Say this |
|---|---|---|
| Monitor | Watches a metric on a cadence and fires when a condition holds | "Alert me on Slack when total ad spend goes over $500 in a day" |
| Report | Sends a summary on a schedule, whether or not anything happened | "Every Monday, send a report of the top 10 campaigns by spend" |
| Investigate | Works out why a number moved, walking the relationship graph | "Why did corrected ROAS on Meta fall this week?" |
| Audit | Checks an account against platform best practice and your conventions | "Audit the Google Ads account for wasted spend and structure problems" |
| Act | Proposes a change in a connected tool when a condition holds | "Pause any Flipkart campaign whose ROAS drops under 0.4" |
One agent can do several of these: a monitor that, when it fires, investigates the cause and then proposes a change. A rule is the simplest form of agent: one metric, one condition, one action.
Create an agent#
- Open New automation
Select Automation Agents, then + New Agent.
- Describe the job
Say what to watch or do, on which platform, how often, and what should happen. Mention the output: email, Slack, or a change. Meerkats supports scheduled reports, alerts by email or Slack, conditional alerts, and conditional campaign changes.
- Create it
Select Create automation (⌘/Ctrl + Enter). Meerkats shows the agent it built: the trigger or schedule, the steps, the output, and the mode. Edit anything, then save.
- Test it
Run it once as a test. A test run reads real data but sends nothing and stages nothing; it shows what the agent would have done. Test runs are labelled Test in run history.
- Turn it on
Enable the agent. It runs on its schedule from the next slot.
Import a skill#
A skill is an agent definition kept in a Git repository: the job, the steps, the checks, in plain text. Select Import from GitHub on the Agents page, paste the repository URL, and pick the skill. Imported skills behave like agents you created; updates to the repository can be pulled in from the agent’s page.
Manage agents#
The Agents tab lists every agent with its platform, cadence, plan and status. Filter by:
- Platform: Meta, Google, Blinkit & Zepto, Flipkart, Amazon, or Demo. A platform shows not connected until you connect it.
- Cadence: event-based, every 5 minutes, hourly (all day, working hours, or 8am to 11pm), daily, weekdays, weekly, monthly, or once.
- Plan: which plan the agent needs.
On each agent:
| Control | What it does |
|---|---|
| Enable / Disable | Turns the schedule on or off. A disabled agent keeps its history and settings. |
| Run now | Runs immediately, outside the schedule. Uses credits like any run. |
| Test | Runs against recent data without sending or staging anything. |
| Edit | Change the description, schedule, output or mode. Takes effect from the next run. |
| Pause | Keeps the agent and its history but it doesn't run. Paused rows are counted at the top of run history. |
| Delete | Removes the agent. Its past runs stay in Agents run history. |
Cadence and autonomy#
The cadence you give an agent sets the expectation for how much it does on its own.
| Cadence | Job | Autonomy |
|---|---|---|
| Daily | Triage and protect: fast signals, mostly reversible | Can be allowed to act alone within caps once it has a record |
| Weekly | Optimise: enough data for significance | Recommends; a person approves |
| Monthly | Strategise: structural, slow-signal | The agent frames the options; a person decides |
An agent that changes something starts in suggest mode: its proposals wait in your Inbox. Switching to auto is per agent and per action type, for low-risk actions only, and Meerkats recommends it only once the agent’s predicted-versus-actual record clears an accuracy bar. See Autonomy.
Ask an agent#
The chat box on Cockpit (Ask anything about your store…) is an agent too, without a schedule. Ask it anything the data can answer: “Which campaigns spent the most last week and what was their ROAS?”, “Why did orders drop on Tuesday?”, “Which products with ad spend are under 7 days of cover?” Answers cite their sources; ask “how is that defined?” and it quotes the metric definition.
The model picker next to the box shows which model answers. The default is gemini-3.1-flash-lite; you can switch to another Gemini model or to Claude Sonnet 4.5. Whichever you pick, the numbers come from the same queries, so only the writing changes. Chats are saved under Recent chats; select + to start a new one. An answer can become an agent: ask “check this every morning” and Meerkats drafts the automation.
What agents never do
Agents never do arithmetic on your numbers; they request metrics and render the result. They never present stale data as current. They never guess an ambiguous object; they ask once, with a recommended default. And they never change a connected tool without a proposal, unless you allowed that specific agent and action type to run alone.Credits#
Each agent run uses one credit. Each call an agent makes to your business context uses one credit; a typical question is about three. An approved action uses one credit. Syncing, storing history and reviewing proposals are free. The Free plan includes 500 credits a month. See Credits and billing.
Agents over the API#
GET /agents
→ the workspace's agents, built-in and yoursRun, enable and disable need a key with write scope. See the API overview.
Troubleshooting#
No agents match these filters
A new workspace shows the built-in agents only after a platform is connected. Connect one on Integrations, or clear the platform filter.
An agent shows needs review
Its last run hit something it couldn't resolve: stale data, an ambiguous target, or a failed check. Open the run in Agents run history; it says what it needs.
An agent shows critical
Its runs are failing, usually because a connection lost access. Check Integrations for a card that says needs attention.
The agent ran but I got nothing
Monitors only send when the condition holds. Check the run: it shows the values it saw and whether the condition was met. For Slack, make sure Meerkats is in the channel.
I want it to stop for a while
Pause it. It keeps its settings and history and resumes when you un-pause.