Meta Ads Agent

Status

• Document status: public portfolio README
• Project documentation: project-docs/README.md
• Active implementation stage: STAGE_09_CONTEXT_AND_AGENT_MEMORY.md

A portfolio snapshot of a bounded Meta Ads copilot built around the official Meta Ads MCP, project-level Skills, DeepSeek/OpenAI-compatible model providers, durable context, and approval-aware Draft workflows.

This is a curated public release snapshot. Internal development history, operational logs, credentials, and customer account identifiers are intentionally excluded. It represents the final engineered state rather than the private iteration log.

What It Demonstrates

• A bounded ReAct loop with explicit step, time, token, and tool budgets.
• Progressive disclosure: a short Skill catalog is visible first; only active Skill tools are exposed.
• 12 project Skills covering account briefs, diagnosis, audits, creative, optimization, planning, tracking, audience, catalog, competitive research, experiments, and policy review.
• Official Meta Ads MCP discovery with provider-neutral tool execution.
• DeepSeek deepseek-flash with high reasoning as the default provider; OpenAI Responses remains optional.
• Five recent conversation rounds plus structured summary compaction.
• Long-term user/account Memory and resumable task state.
• Account directory, account context, and MCP read-result caches with TTL and stale fallback.
• Idempotent turns, per-session leases, optimistic state versions, and conflict responses.
• Direct Meta Draft Mode creation for campaign, ad set, ad, and creative objects.
• Activation, updates, deletes, and publication are code-blocked.
• Execution logs for direct Draft creation.

Architecture

Next.js workbench
  -> POST /api/agent/turn (JSON or SSE)
  -> turn lease + idempotency + version checks
  -> context assembler
       - five recent rounds
       - rolling summary
       - active Skills
       - task progress
       - long-term Memory
       - selected-account cache
  -> bounded ReAct loop
       - DeepSeek Chat Completions or OpenAI Responses
       - Skill-scoped Meta MCP tools
       - structured observations
  -> final answer / local action record / non-live Meta Draft

Core implementation:

• backend/agent/runtime.py: ReAct loop and provider-neutral tool handling
• backend/agent/deepseek.py: DeepSeek Chat Completions adapter
• backend/agent/tools.py: MCP discovery, budgets, Draft routing, activation blocking
• backend/agent/context.py: five-round window, summary contract, token estimates
• backend/services/turn_control.py: turn leases, idempotency, replay
• backend/services/long_term_memory.py: typed Memory
• backend/services/task_state.py: task progress and tool ledger
• backend/services/account_cache.py: account and MCP result caches
• backend/skills/: 12 project Skills with contracts and on-demand references
• frontend/: single-page account, chat, context, trace, and action workspace

Safety Boundary

• All Meta credentials stay in environment variables and never enter prompts, Memory, caches, traces, or source.
• Only four create tools may reach MCP: ads_create_campaign, ads_create_ad_set, ads_create_ad, ads_create_creative.
• Official Draft Mode returns non-live Draft objects.
• ads_activate_entity, update, delete, and publish paths are unavailable to the model.
• Draft approval is not execution.
• Live execution returns 410 execution_disabled_in_demo.

Run Locally

python -m venv .venv
.venv\Scripts\pip.exe install -r requirements.txt
docker compose up -d postgres
.venv\Scripts\python.exe -m alembic upgrade head
.venv\Scripts\python.exe -m uvicorn backend.main:app --host 127.0.0.1 --port 8010
npm.cmd install --prefix frontend
npm.cmd run dev --prefix frontend

Open http://127.0.0.1:3000/app.

Copy .env.example to .env and provide your own credentials. Never commit .env.

Verification

$env:OPENAI_API_KEY=""
.venv\Scripts\python.exe -m pytest tests -q
npm.cmd run lint --prefix frontend
npm.cmd run build --prefix frontend
npm.cmd run test:smoke --prefix frontend

The local verification suite covers the ReAct loop, 12 Skill contracts, progressive tool exposure, context compaction, Memory/task state, account caches, turn leasing/idempotency, SSE, Draft safety, and frontend flows.

Known Constraints

• Meta Graph API and the official Meta Ads MCP require outbound HTTPS access to Meta; some networks require a VPN or proxy.
• Meta account data can be empty or historical. The agent must surface missing and stale data instead of inventing current facts.
• Token estimates are conservative and may require calibration against provider usage.
• Multi-Skill tool schemas can still raise actual provider input beyond the configured estimate; hard budget enforcement remains an area for further calibration.

Development Journey

See DEVELOPMENT_JOURNEY.md for the five-stage engineering journey. The public snapshot intentionally omits exact development dates and private iteration history.

Documentation

• project-docs/01-product/: product scope and functional behavior
• project-docs/02-architecture/: runtime, MCP, data, and workflow design
• project-docs/03-stages/STAGE_09_CONTEXT_AND_AGENT_MEMORY.md: active implementation contract
• project-docs/05-quality/: verification and quality evidence