Skip to main content
A mission groups related tasks into an orchestrated workflow. Missions handle dependency resolution, quality gates, checkpoints, and scheduling so you can express multi-step agent work as a single declarative object.

​
Mission fields

FieldTypeDescription
idstringAuto-generated unique identifier
namestringHuman-readable mission name
dataobjectArbitrary JSON payload available to all tasks
promptstringHigh-level instruction for the mission
statusMissionStatusCurrent lifecycle state
deadlinestringISO 8601 timestamp — hard deadline for the entire mission
schedulestringCron expression or ISO timestamp (see Scheduling)
endDatestringISO 8601 timestamp — stop recurring missions after this date
qualityThresholdnumberMinimum score (1-5) for tasks to pass assessment
executionCountnumberNumber of times this mission has run

​
Lifecycle

Missions follow a strict status state machine: 
draft → scheduled    → active → completed
     → recurring     → active → paused → active
                              → completed
                              → failed
                              → cancelled
StatusMeaning
draftCreated but not yet started
scheduledWill fire once at a specific time
recurringWill fire on every cron tick
activeCurrently executing tasks
pausedHalted at a checkpoint or manually
completedAll tasks finished successfully
failedOne or more tasks failed after retries
cancelledManually cancelled

​
Example mission

{
  "name": "weekly-report",
  "prompt": "Generate the weekly engineering report",
  "data": { "team": "backend", "week": 12 },
  "schedule": "0 9 * * 1",
  "endDate": "2026-12-31T00:00:00Z",
  "qualityThreshold": 3.5,
  "tasks": [
    {
      "title": "Gather PR data",
      "assignTo": "data-collector",
      "dependsOn": []
    },
    {
      "title": "Write summary",
      "assignTo": "writer",
      "dependsOn": ["Gather PR data"]
    },
    {
      "title": "Review and publish",
      "assignTo": "reviewer",
      "dependsOn": ["Write summary"]
    }
  ],
  "team": {
    "name": "report-crew",
    "volatile": true,
    "agents": [
      { "name": "data-collector", "role": "Fetch metrics from GitHub" },
      { "name": "writer", "role": "Draft the report" },
      { "name": "reviewer", "role": "Review for accuracy" }
    ]
  },
  "qualityGates": [
    {
      "afterTasks": ["Write summary"],
      "blocksTasks": ["Review and publish"],
      "minScore": 4.0,
      "requireAllPassed": true,
      "notifyChannels": ["slack:eng-reports"]
    }
  ],
  "checkpoints": [
    {
      "afterTasks": ["Review and publish"],
      "blocksTasks": [],
      "message": "Approve the final report before distribution"
    }
  ]
}

​
Volatile teams

Missions can define their own short-lived team of agents. Set volatile: true on the team definition and the agents are created when the mission starts and automatically cleaned up when it completes. This is useful for one-off or recurring workflows that need purpose-built agents without polluting your project’s permanent agent roster.
Volatile agents inherit the project’s LLM configuration (gateway or provider keys) and sandbox configuration. They do not persist memory between mission runs.

​
Quality gates

A quality gate blocks downstream tasks until upstream tasks meet a minimum assessment score.
FieldTypeDescription
afterTasksstring[]Tasks that must be assessed before the gate
blocksTasksstring[]Tasks held until the gate passes
minScorenumberMinimum average score (1-5) required
requireAllPassedbooleanIf true, every task in afterTasks must individually pass
notifyChannelsstring[]Channels to notify on gate failure
If a quality gate fails, blocked tasks will not execute. The mission will pause until the upstream tasks are fixed and reassessed, or the mission is cancelled.

​
Checkpoints

A checkpoint pauses the mission for human review.
FieldTypeDescription
afterTasksstring[]Tasks that trigger the checkpoint
blocksTasksstring[]Tasks held until a human approves
messagestringMessage shown to the reviewer
The mission moves to paused status. Execution resumes when a human approves the checkpoint via the dashboard or API.

​
Delays

A delay inserts a timed wait between tasks. Durations use ISO 8601 format.
FieldTypeDescription
afterTasksstring[]Tasks that trigger the delay
blocksTasksstring[]Tasks held until the delay elapses
durationstringISO 8601 duration (PT2H, PT30M, P1D)
DurationMeaning
PT30M30 minutes
PT2H2 hours
P1D1 day
PT1H30M1 hour 30 minutes
P7D7 days

​
Mission report

When a mission completes, a MissionReport is generated: 
{
  "allPassed": true,
  "totalDuration": 14230,
  "avgScore": 4.2,
  "results": [
    {
      "task": "Gather PR data",
      "status": "done",
      "score": 4.5,
      "duration": 3200
    },
    {
      "task": "Write summary",
      "status": "done",
      "score": 3.8,
      "duration": 7800
    },
    {
      "task": "Review and publish",
      "status": "done",
      "score": 4.3,
      "duration": 3230
    }
  ]
}

​
Managing missions

Missions are defined in .polpo/ files and synced to the cloud via polpo deploy. You can also manage missions via the REST API or the dashboard.