AI Ads Agent

September 8, 2026 · View on GitHub

An AI agent for paid media — ad intelligence, creative testing, and ROAS optimization across PPC, paid social, and programmatic — backed by real ad-platform APIs.

Part of Agency Agents OS, an open ecosystem of specialized AI agents for real business work.

Agency Agents OS — the central catalog this repo is part of.
ai-marketing-agent — organic counterpart to this repo's paid-media sub-agents.
ai-competitor-intelligence-agent — shares this repo's ad-library-mining capability for cross-cutting audits.
ai-video-agent — its ad-creative-remake sub-agent regenerates the creative this repo flags as underperforming.
ai-image-agent — generates static ad creative variants.
MuAPI MCP docs — connect this repo's SKILL.md files via MCP.
MuAPI access keys — create the API key this agent needs.

What this covers

This repo is the umbrella for anything an agency or in-house team would call "the AI ads agent": watching what competitors are running, structuring and reading creative A/B tests, and turning spend/return data into a budget reallocation recommendation.

Paid media is deliberately its own umbrella here, separate from organic content at ai-marketing-agent. At a real agency, paid media is run as its own service line — different stakeholders, different cadence, different budget accountability — so it gets its own agent rather than being folded into content/social work.

Sub-agents

Agent	Does	Status
Ad Intelligence	Mines public ad-library-style data to see what competitors are running, in what formats, and for how long	Blueprint
Creative Testing	Structures and analyzes A/B creative tests across ad variants	Coming Soon
ROAS Optimization	Analyzes spend/return data across campaigns and recommends budget reallocation	Coming Soon

Required Muapi APIs

ads.campaign_performance — spend, return, and efficiency metrics across campaigns.
ads.ad_library_search — public ad-library-style search for competitor creative and run duration.
ads.creative_metrics — per-variant creative performance for A/B testing.

See each sub-agent's SKILL.md for the specific capabilities it uses.

Setup

Create a Muapi account and API key at muapi.ai.
Review the Muapi API quickstart and OpenAPI schema for the ads endpoints.
Load the SKILL.md for the sub-agent you need into your agent runtime (hosted agent, MCP client, or custom LLM app), or follow it manually.

Using with an AI agent

Every sub-agent's SKILL.md is model- and runtime-agnostic — it's plain Markdown, so it works with any LLM agent, not just Claude. Two integration paths:

As an MCP connection (the agent gets live Muapi tools):

Muapi runs an MCP server at https://api.muapi.ai/mcp that any MCP-compatible client can connect to — Cursor, Windsurf, Claude, or your own custom agent.

Cursor / Windsurf / other clients with a header field: connect to https://api.muapi.ai/mcp with an Authorization: Bearer YOUR_MUAPI_KEY header.
claude.ai / Claude Cowork / other connector UIs with no header field: use the URL-embedded key form instead, https://api.muapi.ai/mcp/YOUR_MUAPI_KEY, via Settings → Connectors → Add custom connector.
Claude Code / Claude Desktop: claude mcp add muapi -e MUAPI_API_KEY=YOUR_MUAPI_KEY -- muapi mcp serve (uses the muapi CLI's stdio transport — Claude Code's HTTP MCP client doesn't reliably inject tools).

Full setup details for every client: muapi.ai/docs/mcp.

As agent instructions (any LLM follows the workflow directly):

Drop a sub-agent's SKILL.md into a Claude Code project's .claude/skills/ directory, paste it into a custom-GPT/Project's system instructions, hand it to an autonomous agent framework as a tool spec, or attach it directly in a chat conversation — then ask the agent to follow it.

Read-only vs. write actions

Every action in this repo is read-only or draft-only — analysis, reports, and recommended budget splits, not live changes. Changing live campaign budgets, pausing ads, or pushing spend changes to an ad platform is explicitly out of scope for this repo; a human operator applies any recommendation through the ad platform's own console.

Status and limitations

Ad Intelligence is Blueprint: its workflow and decision rules are fully built against ads.ad_library_search (public ad-transparency search across Meta, Google, TikTok, and LinkedIn), but that capability is coded and not yet live on Muapi's production API — see its own SKILL.md for the exact scope (currently-visible listings only, no date-range filtering, no spend/impression data). Creative Testing and ROAS Optimization remain Coming Soon: they depend on ads.creative_metrics/ads.campaign_performance, which require the official Google Ads/Meta Ads APIs OAuth'd per advertiser's own ad account — a different, larger integration than public ad-library search, and not yet started.

Contributing

See Agency Agents OS CONTRIBUTING.md.

License

MIT