plungeai-missions

Run bounded autonomous PlungeAI agent missions (type: harness) — a goal, a tool fence, an iteration cap, and self-checked success criteria, via plungeai_run_mission or a harness workflow task. Use when the steps to reach a goal are not known in advance, when you need one open-ended researcher/verifier/analyst loop instead of a guessed chain of small tasks, or when the user asks for a bounded agent run. For a fixed pipeline of known steps use plungeai-workflows; for cron-scheduled missions use plungeai-scheduling; for a list-to-completion campaign ledger use plungeai-campaigns.

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

A mission gives one agent a goal, a standing purpose, a fenced tool set, an iteration cap, and success criteria it self-checks before finishing — then runs a real ReAct loop (think → tool call → result → …) against it, hard-stopped at every bound. Reach for a mission when the steps to reach the goal are NOT known in advance; use a plain workflow (plungeai-workflows) when they are.

Prerequisites

• A self-service ozk_ API key from Dashboard → One API → Keys (https://dashboard.plungeai.com (opens in a new tab)), or an MCP client already connected to https://mcp.plungeai.com/v1.
• Confirm identity first: plungeai_whoami.

Discovery first

Never guess a skill, expert, persona, plugin, or MCP server id — a wrong id degrades to a silent warning, not a hard failure. Look ids up live: plungeai_list_agents {kind: "skills"|"experts"|"personas"|"connectors", search: "<topic>"} (REST: GET /v1/discovery/search?kind=…&q=…).

Running a mission — the two doors

Quick, from an agent context — plungeai_run_mission accepts a fixed subset of the mission contract:

plungeai_run_mission {goal, mission?, allowed_tools?, max_iterations? (≤50),
                      success_criteria?, persona?, skills?, mode?: "sync"|"async"}

{"user_request": "research the EU AI Act's impact on medical devices",
 "goal": "Produce a sourced brief on how the EU AI Act affects medical-device software vendors",
 "max_iterations": 12,
 "success_criteria": ["cites primary sources", "covers timelines and penalties"]}

Defaults to async: poll plungeai_get_workflow_status, fetch with plungeai_get_result. A paused run (⏸ AWAITING USER APPROVAL / AWAITING USER) is relayed to the user and resumed with plungeai_continue.

Full control, as a workflow task — anything beyond that subset (experts, backgrounds, plugins, mcp, model/provider, effort, max_parallel, permissions, memory_owner, local) requires a one-task type: harness workflow, run with plungeai_execute_workflow:

name: Claim verification
tasks:
  - type: harness
    goal: "Verify the claims in {input} and produce a sourced verdict"
    mission: |
      You are a careful researcher. Verify claims against primary sources.
      Refuse to conclude beyond the evidence.
    skills: [research]
    effort: standard
    allowed_tools: [web_search, web_fetch, task_complete]
    success_criteria:
      - Every verdict cites at least one primary source

Or reuse a pre-built agent card: mission_ref: research-analyst (equivalent shorthand: a single-token mission: research-analyst). Cards are also directly schedulable — see plungeai-scheduling.

The tool fence — the core safety mechanism

allowed_tools is a hard whitelist: an out-of-fence tool call is refused by the runtime, never just discouraged. Always include task_complete. Give the smallest set that can achieve the goal — a verification mission needs web_search, web_fetch, task_complete, not the file tools. Two loop runtimes exist (the full-surface default, and the thin universal-agent registry-first fence, selected with agent:); an explicit allowed_tools always wins over either default. Full catalog and the agent fence / money-class protection: references/missions.md.

Gotchas

• No per-task retry on harness — mission runs are not idempotent; check plungeai_executions before re-firing anything with side effects.
• success_criteria are self-checked by the agent — treat them as guidance-grade, not proof.
• Merge order for cards is last-wins per key (card → workflow root → task), and arrays REPLACE, never union — a task-level skills: [x] replaces the whole card list.
• A run pauses (never dies) on ask_user questions or permissions: ask gates; resume with plungeai_continue, never retry around a pause.
• Memory: the platform recalls the owner's long-term memory as a frozen snapshot at run start and writes back durably mid-run — see plungeai-memory.

Related skills

• plungeai-workflows — plain multi-step CNL pipelines; embed a mission as one task.
• plungeai-scheduling — cron a mission (or a mission_ref card) to run on its own.
• plungeai-memory — the recall/write lifecycle a mission runs against.
• plungeai-skills-plugins — the skills/experts/persona/backgrounds/plugins/mcp capability fields.
• plungeai-results-traces — read a mission run's status, output, and trace.
• plungeai-campaigns — running a list to completion instead of one bounded goal.

Reference

• references/missions.md — full field reference, tool/agent fences, recursion guards, pre-built cards, and the plungeai_run_mission MCP tool contract.

Reference pages