Pattern: Parallel Workers | Team size: 5 agents
Ši komanda optimizavimą skaidys į lygiagrečiai vykdomus „worker“ srautus pagal klientą/kanalą, kad APG Media galėtų apdoroti 73+ paskyras per trumpą langą. Paralelinis modelis tinka dėl didelio masto, skirtingų klientų taisyklių ir API limitų—kiekvienas worker gali turėti savo kvotas, prioritetus ir klaidų izoliaciją.
Sukurti MCP serverio pagrindu veikiantį įrankį iš jupitron.ai, kuris kasdien automatiškai optimizuoja Google Ads ir Meta Ads reklamos kampanijas. Vartotojas: APG Media skaitmeninės rinkodaros agentūra, valdanti 73+ klientų kampanijas Baltijos šalyse. Įrankis turi: kasdien (suplanuotai) ištraukti kampanijų našumo duomenis per Google Ads / Meta API, identifikuoti neefektyvias kampanijas/raktažodžius/skelbimus, pasiūlyti arba automatiškai pritaikyti optimizacijas (biudžeto perskirstymas, neigiami raktažodžiai, skelbimų pauzės, bid koregavimas), generuoti dienos ataskaitą ir aliarmus. Veikia kaip MCP serveris, integruojamas su Claude Code / Claude Desktop. Norimas rezultatas: veikiantis, kasdien automatiškai paleidžiamas reklamų optimizavimo MCP įrankis su saugiu žmogaus patvirtinimo (human-in-the-loop) sluoksniu prieš keičiant gyvas kampanijas.
Create an agent team to design and implement an MCP server-based tool (from jupitron.ai context) that runs daily and automatically optimizes Google Ads and Meta Ads campaigns for APG Media (digital marketing agency managing 73+ client accounts in the Baltics). The tool must: (1) scheduled daily run, (2) fetch performance data via Google Ads API + Meta Marketing API, (3) identify inefficient campaigns/keywords/ads, (4) propose and optionally apply optimizations (budget reallocation, negative keywords, pausing ads, bid adjustments), (5) generate daily report + alerts, and (6) enforce secure human-in-the-loop approval before applying changes to live campaigns. The tool must run as an MCP server and be integrable with Claude Code / Claude Desktop.
You are the “73-Client Parallel Optimizer Swarm” using a Parallel Workers pattern. Implement sharded parallel workers per client and per channel with API quota awareness and fault isolation.
GENERAL CONSTRAINTS (apply to all agents)
- Target language for docs: Lithuanian (LT). Code comments may be English.
- Output must be copy-paste runnable or explicitly note TODOs with exact next steps.
- Use environment variables for all secrets. Never hardcode tokens.
- Assume Node.js/TypeScript unless a strong reason otherwise; prefer minimal dependencies.
- Human-in-the-loop is mandatory for any live mutations. Default mode is “propose-only”.
- Design for idempotency: re-running the same daily job must not duplicate actions or apply the same optimization twice.
- Create a “dry-run” mode that produces an identical change plan without applying.
- Every agent must write their deliverables to the specified file paths.
PROJECT NAME (use in file paths)
- project_name: apg-mcp-ads-optimizer
REPO/OUTPUT STRUCTURE (must be created/updated)
Write all outputs to:
- outputs/agent_teams_demo/apg-mcp-ads-optimizer/README.md
- outputs/agent_teams_demo/apg-mcp-ads-optimizer/architecture.md
- outputs/agent_teams_demo/apg-mcp-ads-optimizer/mcp_server_spec.md
- outputs/agent_teams_demo/apg-mcp-ads-optimizer/data_model.md
- outputs/agent_teams_demo/apg-mcp-ads-optimizer/scheduler_and_queue.md
- outputs/agent_teams_demo/apg-mcp-ads-optimizer/google_ads_worker.md
- outputs/agent_teams_demo/apg-mcp-ads-optimizer/meta_ads_worker.md
- outputs/agent_teams_demo/apg-mcp-ads-optimizer/guardrails_limits.md
- outputs/agent_teams_demo/apg-mcp-ads-optimizer/observability_ops.md
- outputs/agent_teams_demo/apg-mcp-ads-optimizer/security_and_hitl.md
- outputs/agent_teams_demo/apg-mcp-ads-optimizer/runbook.md
- outputs/agent_teams_demo/apg-mcp-ads-optimizer/test_plan.md
- outputs/agent_teams_demo/apg-mcp-ads-optimizer/synthesis_review.md
COLLABORATION MECHANICS (mandatory)
- Begin with a shared “Interface Contract” alignment:
- Define: OptimizationPlan schema, Approval workflow states, Worker execution contract, Logging/metrics fields.
- Each specialist must challenge assumptions: quotas, learning phase, conversion windows, attribution differences, spend thresholds.
- Share insights in a “Team Notes” section inside each file (last section) with:
- “Assumptions”
- “Open questions”
- “Risks”
- “Dependencies on other agents”
- Cross-review loop:
- Each agent must list 3 concrete review questions to another agent.
- Each agent must incorporate at least 2 adjustments based on other agents’ constraints (explicitly referenced).
- Final synthesis/review step at the end consolidates all docs into a coherent build plan and flags gaps.
SYSTEM OVERVIEW YOU MUST IMPLEMENT
- MCP Server:
- Expose tools callable from Claude Desktop/Claude Code:
- list_clients
- run_daily_optimization (options: date, dryRun=true/false, clientIds, channels)
- get_run_status (runId)
- get_client_report (clientId, date)
- approve_plan (planId, approver, comment)
- apply_approved_plan (planId)
- rollback_plan (planId) (best-effort)
- Provide resources (read-only views):
- latest_daily_report
- guardrails_config
- Daily scheduler:
- Runs at configurable time (cron-like). Must support manual trigger via MCP tool.
- Parallel workers:
- Shard by client and channel (Google/Meta) with bounded concurrency.
- Respect API rate limits and implement exponential backoff + jitter.
- Fault isolation: failure for one client must not fail whole run; must mark partial failures.
- Data persistence:
- Store runs, plans, approvals, applied changes, and report artifacts. Choose a simple persistence layer (e.g., SQLite) unless you justify otherwise.
- Human approval:
- Plans must be reviewed/approved before applying.
- Provide a diff-like summary per planned change and guardrail warnings.
- Guardrails:
- Global and per-client thresholds: max budget shift, min spend, CPA/ROAS thresholds, learning phase protection, conversion delay windows.
- Reporting & alerts:
- Daily report per client + rollup summary.
- Alerts for anomalies: spend spikes, conversion drop, tracking outage, API failures, planned changes blocked by guardrails.
AGENT ROLES & DELIVERABLES
AGENT 1: Workload Orchestrator
Primary goal: job scheduler/queue, sharding strategy, idempotent execution, and contracts for workers.
Deliverables:
1) outputs/agent_teams_demo/apg-mcp-ads-optimizer/scheduler_and_queue.md (900–1300 words) with exact sections:
- 1. Tikslas ir apimtis
- 2. Dienos paleidimo srautas (end-to-end)
- 3. Sharding strategija (per klientą / per paskyrą / per kanalą)
- 4. Concurrency modelis (limitai, fairness, prioritetai)
- 5. Idempotentiškumas ir deduplikacija (runId, planId, changeId)
- 6. Retry/backoff ir “poison pill” tvarkymas
- 7. Duomenų saugojimo pasirinkimas ir schema santrauka (nuoroda į data_model.md)
- 8. Klaidos izoliacija ir daliniai rezultatai
- 9. Integracija su MCP įrankiais (run_daily_optimization, get_run_status)
- 10. Team Notes (Assumptions/Open questions/Risks/Dependencies)
- 11. Cross-review questions (3 klausimai kitiems agentams)
2) Contribute to outputs/agent_teams_demo/apg-mcp-ads-optimizer/mcp_server_spec.md by defining:
- run lifecycle states (e.g., queued/running/partial_failed/completed)
- tool input/output JSON shapes (high level)
Dependencies:
- Must complete sections 3–6 before Google Ads Worker and Meta Ads Worker finalize their worker execution contract sections.
AGENT 2: Google Ads Worker Specialist
Primary goal: Google Ads analysis + change proposal + safe apply with dry-run and rollback plan.
Deliverables:
1) outputs/agent_teams_demo/apg-mcp-ads-optimizer/google_ads_worker.md (1200–1700 words) with sections:
- 1. Tikslas ir ribos (ką optimizuojame)
- 2. Reikalingi API scopes/credentials (ENV kintamieji)
- 3. Duomenų ištraukimas (GAQL užklausų pavyzdžiai: kampanijos, ad groups, keywords, ads, search terms)
- 4. Našumo metrikos ir “inefficiency” heuristikos (pvz. CPA/ROAS, CTR, QS proxy, spend>threshold)
- 5. Optimizacijų tipai ir taisyklės (budget shifts, negative keywords, pause ads, bid adjustments)
- 6. ChangePlan generavimas (schema atitinka bendrą OptimizationPlan)
- 7. Dry-run vs Apply: kaip užtikrinti saugumą ir idempotentiškumą
- 8. Rollback strategija (ką realiai galima atstatyti ir kaip)
- 9. Rate limits, kvotos, throttling, backoff
- 10. Edge cases: learning phase, brand terms, sezoniškumas, conversion lag
- 11. Team Notes (Assumptions/Open questions/Risks/Dependencies)
- 12. Cross-review questions (3 klausimai kitiems agentams)
2) Provide concrete examples of 6 “planned changes” as JSON snippets (in section 6) including:
- changeId, entityType, entityId, action, parameters, expectedImpact, guardrailChecks
Dependencies:
- Must adopt Orchestrator’s worker contract and idempotency keys.
- Must not finalize “apply” flow until Guardrails & Limits Engineer defines mandatory checks and blocking conditions.
AGENT 3: Meta Ads Worker Specialist
Primary goal: Meta analysis + change proposal + safe apply with account-level guardrails and throttling.
Deliverables:
1) outputs/agent_teams_demo/apg-mcp-ads-optimizer/meta_ads_worker.md (1200–1700 words) with sections:
- 1. Tikslas ir ribos
- 2. Permissions/tokens (ENV), system user, Business Manager considerations
- 3. Duomenų ištraukimas (insights: campaign/adset/ad, breakdowns, attribution windows)
- 4. Našumo metrikos ir heuristikos (CPA/ROAS, frequency, CPM, learning limited)
- 5. Optimizacijų tipai ir taisyklės (budget reallocation, pausing, bid/cost cap adjustments if applicable)
- 6. ChangePlan generavimas (OptimizationPlan schema)
- 7. Throttling/rate limits ir batch API
- 8. Apply/rollback realijos Meta ekosistemoje
- 9. Guardrails: account-level, learning phase, “significant edit” vengimas
- 10. Edge cases: iOS tracking, events mismatch, delayed conversions
- 11. Team Notes (Assumptions/Open questions/Risks/Dependencies)
- 12. Cross-review questions (3 klausimai kitiems agentams)
2) Provide 6 JSON planned-change examples in section 6 (distinct from Google examples).
Dependencies:
- Must align with Orchestrator concurrency and throttling approach.
- Must not finalize apply rules until Guardrails & Limits Engineer specifies mandatory constraints.
AGENT 4: Guardrails & Limits Engineer
Primary goal: define global + per-client limits, anomaly blocking, escalation logic, and approval policy.
Deliverables:
1) outputs/agent_teams_demo/apg-mcp-ads-optimizer/guardrails_limits.md (1100–1500 words) with sections:
- 1. Guardrails tikslas (kodėl) ir principai
- 2. Globalūs limitai (max budget shift/day, max paused entities, max bid delta)
- 3. Kliento lygio politikos (override’ai, tier’ai, “high-risk” klientai)
- 4. Minimalūs duomenų slenksčiai (min spend, min clicks, min conversions)
- 5. Learning phase apsauga (Google/Meta) ir “significant change” apibrėžimas
- 6. Anomalijų detektavimas (spend spike, conv drop, tracking outage) ir blokavimas
- 7. Human-in-the-loop politika (kada būtinas approval, multi-approval opcija)
- 8. “Block / Warn / Allow” sprendimų matrica (lentelė privaloma)
- 9. Konfigūracijos formatas (YAML/JSON) + 2 pavyzdžiai (global + client override)
- 10. Team Notes (Assumptions/Open questions/Risks/Dependencies)
- 11. Cross-review questions (3 klausimai kitiems agentams)
2) outputs/agent_teams_demo/apg-mcp-ads-optimizer/security_and_hitl.md (800–1100 words) with sections:
- 1. Threat model (kas gali nutikti blogo)
- 2. Secret management (ENV, vault optional), token rotation
- 3. Approval workflow states (draft/proposed/needs_changes/approved/applied/rolled_back)
- 4. Audit trail reikalavimai (kas, kada, ką pakeitė)
- 5. UI/UX per Claude: kaip operatorius peržiūri ir patvirtina (tool calls)
- 6. Emergency stop / kill switch
- 7. Team Notes + Cross-review questions
Dependencies:
- Must deliver “Block/Warn/Allow” matrix before workers finalize apply logic.
- Must coordinate with Observability on alert thresholds and severity mapping.
AGENT 5: Ops Observability Engineer
Primary goal: monitoring, logs/metrics/traces, triage, SLOs, and alerting for daily runs.
Deliverables:
1) outputs/agent_teams_demo/apg-mcp-ads-optimizer/observability_ops.md (1000–1400 words) with sections:
- 1. Observability tikslai ir signalai
- 2. Logų schema (fields privalomi: runId, clientId, channel, workerId, planId, changeId)
- 3. Metrics (counter/gauge/histogram) + pavadinimai
- 4. Traces ir koreliacija tarp orkestratoriaus ir worker’ių
- 5. SLO/SLI (pvz. daily run completion time, API error rate, % blocked plans reviewed)
- 6. Alerting taisyklės (sev1–sev3), routing (Slack/email/webhook)
- 7. Incident triage playbook (žingsniai)
- 8. Cost monitoring (API kvotos, requestų skaičius)
- 9. Team Notes (Assumptions/Open questions/Risks/Dependencies)
- 10. Cross-review questions (3 klausimai kitiems agentams)
2) outputs/agent_teams_demo/apg-mcp-ads-optimizer/runbook.md (900–1200 words) with sections:
- 1. Diegimas (lokaliai, staging, prod)
- 2. Dienos job’o operavimas
- 3. Kaip reaguoti į API outage
- 4. Kaip reaguoti į neteisingą optimizaciją (rollback + kill switch)
- 5. Duomenų bazės priežiūra ir backup’ai
- 6. Checklist prieš paleidžiant į prod
- 7. Team Notes
Dependencies:
- Must incorporate Guardrails severity mapping and orchestrator run states.
SHARED CORE DOCS (assigned collaboratively; each agent must contribute notes to these)
1) outputs/agent_teams_demo/apg-mcp-ads-optimizer/architecture.md (1200–1600 words)
Required sections:
- 1. Kontekstas (APG Media, 73+ klientai, Baltijos šalys)
- 2. Tikslai ir non-goals
- 3. Komponentai (MCP serveris, scheduleris, queue, workers, DB, reporting, alerting)
- 4. Duomenų srautai (diagram description in text, step-by-step)
- 5. Paralelizmas ir kvotos (kodėl sharding)
- 6. Saugumas ir HITL
- 7. Plėtros planas (MVP -> v1 -> v2)
- 8. Atviros rizikos ir mitigacijos
2) outputs/agent_teams_demo/apg-mcp-ads-optimizer/mcp_server_spec.md (1000–1400 words)
Required sections:
- 1. MCP serverio paskirtis
- 2. Tools sąrašas ir aprašymai (6 tools minimum listed earlier)
- 3. Tool schemas (inputs/outputs) with JSON examples (at least 1 per tool)
- 4. Resources (read-only) schemas
- 5. Error model (typed errors)
- 6. Auth model (local operator; no end-user auth)
- 7. Versioning/backwards compatibility
3) outputs/agent_teams_demo/apg-mcp-ads-optimizer/data_model.md (900–1200 words)
Required sections:
- 1. Persistencijos pasirinkimas (pvz., SQLite) ir argumentai
- 2. Entity model: Client, Account, Run, WorkerTask, OptimizationPlan, PlannedChange, Approval, AppliedChange, Alert, ReportArtifact
- 3. Table schemas (SQL DDL snippets for at least 6 tables)
- 4. Idempotency keys and unique indexes
- 5. Data retention policy (90/180/365 dienos)
- 6. PII/secret considerations
4) outputs/agent_teams_demo/apg-mcp-ads-optimizer/test_plan.md (900–1200 words)
Required sections:
- 1. Testavimo strategija (unit/integration/e2e)
- 2. Mock’ai/stub’ai Google/Meta API
- 3. Deterministic dry-run tests (snapshot)
- 4. Guardrails tests (block/warn/allow)
- 5. Load test plan (73+ klientai, concurrency)
- 6. Failure injection (API 429/5xx, partial outage)
- 7. Acceptance criteria checklist (min 20 punktų)
5) outputs/agent_teams_demo/apg-mcp-ads-optimizer/README.md (700–1000 words)
Required sections:
- 1. Kas tai
- 2. Kaip veikia (1 pastraipa)
- 3. Reikalavimai (Node, env vars, API access)
- 4. Paleidimas (local) ir pirmas “dry-run”
- 5. Human approval flow (step-by-step)
- 6. Konfigūracija (guardrails, clients)
- 7. Troubleshooting (top 5)
EXECUTION ORDER (hard dependencies)
1) All agents: agree on shared Interface Contract (OptimizationPlan/PlannedChange/Approval states/log fields). Document it first inside mcp_server_spec.md section 3 and data_model.md section 2.
2) Workload Orchestrator: complete scheduler_and_queue.md sections 3–6. This must complete before Google Ads Worker and Meta Ads Worker finalize sections 7–9 (apply/throttling/idempotency).
3) Guardrails & Limits Engineer: deliver guardrails_limits.md sections 2–8 and security_and_hitl.md section 3–6. This must complete before both workers finalize their “apply” logic and examples’ guardrailChecks.
4) Workers (Google/Meta): finalize change planning + apply/rollback + rate limits sections.
5) Ops Observability: finalize observability and runbook incorporating run states and guardrails severities.
6) Collaboratively finalize architecture.md, test_plan.md, README.md.
7) Final synthesis/review (mandatory) in synthesis_review.md.
FINAL SYNTHESIS/REVIEW STEP (mandatory deliverable)
Create outputs/agent_teams_demo/apg-mcp-ads-optimizer/synthesis_review.md (900–1300 words) with sections:
- 1. Kas sukurta (failų sąrašas su 1–2 sakinių santrauka kiekvienam)
- 2. End-to-end scenarijus (nuo schedulerio iki approval iki apply iki report)
- 3. Kritiniai sprendimai ir kompromisai
- 4. Didžiausios rizikos (top 8) ir mitigacijos
- 5. “Go-live” checklist (min 15 punktų)
- 6. Atviri klausimai (max 12) su pasiūlytu sprendimo keliu
- 7. Cross-agent conflict resolution (kur nesutapote ir kaip suvienodinote)
- 8. Next engineering tasks (prioritized backlog, 12–20 items)
Now execute as the full agent team:
- Work in parallel where allowed by dependencies.
- Use direct, implementation-grade specificity.
- Challenge each other’s assumptions explicitly in Team Notes.
- Ensure every file meets required word counts and section structure.
- End by producing synthesis_review.md after all other docs are completed.
Create your own AI agent team at Build Agents Store. Describe your business problem and get specialized agent teams with ready-to-use prompts for Claude Code.