Meta Ads Agent

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

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

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

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

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.

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

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

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

• 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