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, ocean-cli missions run, or a harness task over the One API (POST /v1/workflows/execute, the Agent Call door POST /v1/execute). 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?, agent?, 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, local) requires a one-task type: harness workflow, run with plungeai_execute_workflow:

name: Claim verification
tasks:
  - type: harness
    agent: one-agent
    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.

Over the One API

A mission is one type: harness task, so REST runs it on the workflows plane. Same ozk_ key (plungeai-api-setup); the YAML above is the program.

Job	REST	MCP	CLI `ocean-cli …`
run inline	`POST /v1/workflows/execute` (`{workflow, input}` or a `text/yaml` body) → `{success, status, workflow_id, final_task_id, request_id, content?}`, answered when the run is done; `POST /v1/workflows/execute-stream` for SSE	`plungeai_run_mission`; `plungeai_execute_workflow`	`missions run GOAL [--sync]`
run a saved one	save with `POST /v1/workflows` (`kind: agent`), then `POST /v1/execute {agent: "<id>", input}` (`<id>@3` pins snapshot 3) or `POST /v1/workflows/{id}/execute {input}`	`plungeai_execute_workflow {workflow_id}`	`workflows run ID`
run a pre-built card	`POST /v1/agents/{id}/execute {prompt, sync?: false}` (the card's id) — the `prompt` is the goal; `sync: false` answers `202` with a pointer	`plungeai_execute_agent`	`agents run ID PROMPT`
poll, resume	`GET /v1/executions/{id}`, `GET …/{id}/output`, `POST …/{id}/continue`, `POST …/{id}/cancel`	`plungeai_get_workflow_status`, `plungeai_get_result`, `plungeai_continue`	`missions status \| poll \| result ID`, `executions continue ID`

What builders get wrong:

The workflow routes have no async flag. POST /v1/workflows/execute holds the connection until the mission ends. For a long one use execute-stream, a pre-built card with sync: false, or fire a saved mission from a schedule (POST /v1/schedules/{id}/run → {run_id, execution_id} at once), then poll GET /v1/executions/{id}.
200 is not "done well". A loop that stops at its turn budget before task_complete answers status: "incomplete" with a partial result; completed is the clean end. A pause reads needs_approval or needs_input on GET /v1/executions/{id} (never an error): answer it with POST …/continue.
A saved mission is linted. kind: agent takes exactly ONE type: harness task; a declared allowed_tools fence must contain task_complete; memory_owner: is refused. A failure is 422 invalid_workflow with errors and nothing is written.
Another account's execution or saved-agent id is a 404 (execution_not_found, agent_not_found), the same as a missing one.

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. The loop runtime is agent: one-agent — name it on every harness task (left out, the task still lands on a legacy id until the switch-over); its default fence is the thin registry-first one, and an explicit allowed_tools always wins over it. 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.

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

Missions — bounded autonomous agent runs (type: harness)

A mission bounds what an agent may do for ONE goal: a standing purpose, a fenced tool set, an iteration cap, optional identity/knowledge injection, and…