plungeai-campaign-agent

Design and emit ONE PlungeAI (Ocean Studio) campaign agent — a long-running, list-driven, resumable agent that works an owned ledger of items in short scheduled runs until the current cycle is exhausted — as CNL YAML (a claim task plus a type: batch with ledger: campaign) and a campaign-config block (list source, cycle, schedule, max_attempts, then, deliver). Use when the Studio Think composer has "Campaign agent" selected, or when a user asks for an agent that works through a list, a backlog, a catalog, "N things to check", "run until the list is done", "start again every week", or "then move to the next list". NOT for single scheduled reports (plungeai-bot-agent), interactive agents (plungeai-agentic-agent) or multi-step pipelines (plungeai-workflows).

Download zip (opens in a new tab) · View raw SKILL.md (opens in a new tab)

A campaign is a task list with an owner. Each run claims a slice of the not-yet-done items, works them at bounded concurrency, and records every outcome before it ends; the scheduler re-fires runs until the cycle is exhausted. Runs are short by law — the platform cannot hold one invocation past ~10 minutes — so never design a run that "keeps going". Repetition is the schedule's job, resumption is the ledger's job.

The conversation (before any YAML)

1. Unit. What is one item? A product, a lead, a URL, a document. Name the key that identifies it.
2. List source. Exactly one: a Task-app table + filter (point-and-pick; never raw SQL), an agent op that returns a JSON array (discover the id with registry_search, never from memory), a CSV the user will upload in the Task app after save, or an inline list for a handful of items.
3. Per-item job. A plain agent op when the item is "call one agent, store one row" (cheapest). A harness mission only when the item genuinely needs a tool loop; then the same rules as a bot: no ask_user, no platform_action, effort: quick unless argued, mission ends with the task_complete sentence. The job MUST upsert by {item.key} + {item.cycle} — say so in the mission or pass both to the op.
4. Cycle. once (a backlog), hourly | daily | weekly | monthly (a recurring pass), continuous (restart as soon as exhausted). cycle_start: reset reuses the same keys; refill re-queries the source.
5. Schedule. When runs may happen — a 5-field cron. Propose a window that finishes the list with margin: batch_size × seconds per item ÷ concurrency ≤ 600 s, then enough ticks to cover the list.
6. Deliver. Where the cycle summary and alerts go: inapp, email or slack (see deliver below).

Confirm, then emit BOTH blocks.

Output contract — two fenced blocks, in this order

workflow:
  name: "<short campaign name>"
  description: "<one line: what one item is and how often the list is worked>"
  tasks:
    - type: task
      id: claim
      agent: data-table-agent
      operation: campaignClaim
      campaign_id: "<written by Step-2 at save>"
      batch_size: 40
    - type: batch
      id: work
      items_from: claim
      concurrency: 5
      ledger: campaign
      tasks:
        - type: task            # or type: harness + agent: one-agent when a tool loop is needed
          id: one
          agent: <agent id>
          operation: <op>
          key: "{item.key}"
          cycle: "{item.cycle}"

list:
  table: { project: <project>, table: <table>, filter: { <column>: <value> }, key: <column> }
cycle: weekly
cycle_start: refill
schedule: "*/5 9 * * 1"
max_attempts: 2
then: ""
deliver:
  - channel: inapp
local: false

Rules the lint enforces — violating them makes the save fail:

• Exactly one top-level claim task (agent: data-table-agent, operation: campaignClaim) and exactly one type: batch with items_from: claim, ledger: campaign, and concurrency ≤ 5.
• Inner tasks are unattended: no ask_user, no platform_action; a harness inner task MUST include task_complete in allowed_tools and end its mission with the task_complete sentence.
• The per-item task must reference {item.key} (warning if it looks insert-only — the ledger is at-least-once).
• An inner task that can reach data-table-agent (e.g. allowed_agents: [data-table-agent]) needs max_items: a max_items: <n> line in the YAML (on the claim and batch tasks) and the same cap in campaign-config.
• max_attempts is required. No memory_owner. No emails or ids in the YAML — recipients belong in deliver.
• local: true only with a harness inner task on agent: one-agent, and in BOTH blocks.

campaign-config fields

• list — one of table {project, table, filter, key}, agent {id, operation}, csv: true, inline: [...].
• cycle — once | hourly | daily | weekly | monthly | continuous. Calendar cycles never restart inside their bucket.
• cycle_start — reset | refill. Default refill for table/agent sources, reset for csv/inline.
• schedule — 5-field cron; each tick is one run (an empty claim returns in about a second). Optional: left out, no cron job is made and the ledger schedules its own next run.
• max_attempts — dead-letter threshold on explicit failures; required.
• then — optional campaign id to start when a cycle completes. Never chain a dependent report onto a collection campaign; keep reports time-triggered.
• deliver — {channel, to?} items (default inapp). Only inapp, email (to = address; bare = the owner) and slack (bare = DM the owner, or to) deliver from a campaign today: the block carries no chat_id or phone_number_id, which telegram, discord, whatsapp and teams need (accepted, then skipped at delivery).
• batch_size (positive integer, the per-run claim slice, default 40), max_items (positive integer, rows per cycle), pace (seconds ≥ 0) — optional.
• local — run-on-my-computer, as for bots.

Worked examples for all four use cases plus the full field reference: references/campaign-config.md.

Outside Studio, one call saves the campaign and sets up its ledger and schedule: MCP (https://mcp.plungeai.com/v1) plungeai_workflow {action: "create", kind: "campaign", yaml, campaign_config: {…}}, or REST POST https://api.plungeai.com/v1/workflows with kind: campaign and campaign_config (the block's fields as an object; list, cycle and max_attempts required, 422 invalid_params otherwise); ocean-cli campaigns setup <workflow_id> --config @file arms an existing one (Studio session). Discover the agent ids you name in the per-item task live — plungeai_list_agents from a client, or registry_search inside the loop — never from memory.

Reference pages