Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/coretracker/agentswarm/llms.txt

Use this file to discover all available pages before exploring further.

Postflight checks let you run automated steps — such as a test suite, a linter, or a screenshot comparison — immediately after an agent completes a successful build task and before AgentSwarm creates the final checkpoint. If a postflight step fails and on_failure is set to fail_task, the task is marked as failed and no checkpoint is proposed, keeping your review queue clean. This makes it easy to enforce quality gates without adding manual steps to your workflow.

​
Configuration File

Postflight checks are configured in a YAML file committed directly to the target repository: 
.agentswarm/postflight.yml
AgentSwarm reads this file from the task workspace after the agent finishes. No additional server-side configuration is required — placing the file in the repository is enough to activate it.

​
Full Schema

​
version
integer
required
Must be 1. This is the only supported schema version.
​
enabled
boolean
When false, postflight checks are skipped entirely for this repository even if the file is present. Defaults to true.
​
when
object
Restricts which tasks trigger postflight. When omitted or empty, postflight runs for all build tasks.
​
runner
object
required
Defines the Docker environment in which postflight steps execute.
​
steps
array
required
An ordered list of shell commands to execute inside the runner container. At least one step is required. Each step is an object with a single run key.
​
on_failure
string
What to do when one or more steps exit with a non-zero status.
  • fail_task — marks the task as failed and halts execution. No checkpoint is created. This is the default.
  • ignore — logs the failure but continues and allows the task to proceed to the checkpoint stage.

​
Complete Example

The following example runs Playwright mobile screenshot tests after every successful Codex or Claude build task: 
version: 1
enabled: true

when:
  task_types: ["build"]
  providers: ["codex", "claude"]

runner:
  image: "mcr.microsoft.com/playwright:v1.52.0-jammy"
  timeout_seconds: 1800

steps:
  - run: "npm ci"
  - run: "npx playwright test tests/mobile-screenshots.spec.ts --project=mobile-web --update-snapshots"

on_failure: "fail_task"

​
Runner Image

The runner.image field accepts any Docker image that is accessible on the host running AgentSwarm. The runner container is started with the task workspace mounted, so all files created or modified by the agent are available to your steps. You can use language-specific images, browser testing images, or any custom image that contains the tools your test suite needs.
Use a pinned image tag (e.g. mcr.microsoft.com/playwright:v1.52.0-jammy) rather than latest to ensure consistent postflight behaviour across runs.

​
Failure Modes

fail_task

When any step exits with a non-zero status, the task is marked as failed. No checkpoint is proposed for review. The agent’s changes remain in the workspace but must be re-run or manually inspected. This is the recommended default for enforcing quality gates.

ignore

Step failures are recorded in the task logs but do not affect the task outcome. The task proceeds to the normal checkpoint review flow. Use this when postflight is informational only and failures should not block the workflow.

​
Important Notes

Tabs are not supported in postflight.yml. Use spaces for all indentation. AgentSwarm’s built-in YAML parser will throw an error and skip postflight if it encounters any tab characters. Indentation must also use multiples of 2 spaces.
Only version: 1 is supported. Including any other value for version will cause postflight parsing to fail and the check will be skipped.
Postflight only runs after a successful agent build. It does not run if the agent task itself fails, is cancelled, or is an ask task (unless you explicitly include ask in when.task_types).

Build docs developers (and LLMs) love

Get started for freeTalk to us