Agent · Available now

Stages Agent

Runs one job through phases that each get their own agent, their own instructions, and their own permissions. One focused workflow, with a clear result at the end.

Read docs

How it works

Stages Agent runs a single task through a sequence of phases, and each phase is a completely separate agent with its own configuration. An auditing phase can be read-only, think hard, and be forbidden from touching anything. The implementing phase that follows can be allowed to write, run faster, and carry a different set of standing instructions. The phases no longer share one system prompt, one model, or one sandbox, which is the constraint that makes a single agent bad at multi-phase work. You describe up to 25 stages on the command line, one repeated option per setting, so a whole staged flow is one invocation.

Each stage's agent is discarded the moment its stage ends, and no thread history, tool state, or context crosses a stage boundary. What does cross is the output: in sequential mode a stage's prompt can pull in the previous stage's entire output, and the first stage receives your top-level task instead. You can also run every stage at once, in which case each one sees the top-level task and none of them sees the others. Per stage you choose the model, the reasoning effort, the sandbox, the approval policy, and optional reference material that reaches that stage only.

It does not decide what the phases should be; you do, and the ordering you choose is the part it trusts. A stage can be forced to answer in a fixed JSON shape, so the next stage receives a handoff it can check instead of prose it might misread. When a stage fails, the run either stops with every earlier result intact or records the failure and carries on, and a retry goes to a fresh agent. An offline describe command prints every option a stage accepts, so the whole surface is readable without opening the source.

  • runtime
  • local
  • one-time
  • stages
  • phased-workflow
  • per-stage-config
  • per-stage-sandbox
  • per-stage-model
  • system-prompts
  • audit-then-implement
  • design-doc-flow
  • parallel-reads
  • sequential-handoff
  • structured-handoff
  • output-schemas
  • phase-isolation
  • pipeline

Agent environment

Pricing

$0.01 per run

  • runtime
  • local
  • one-time

Stages Agent runs on your machine through Codex. Each stage gets a separate agent with its own instructions and permissions; stages can run in order or in parallel, and you choose what information passes between them. No stage prompt or intermediate reply is sent to Vidbyte.

Stages Agent is live and ready to use. Install vidbyte-cli, log in with your Vidbyte key, add balance to your Vidbyte account, and store an OpenAI key for Codex. The install prompt below checks those steps for you and then gives you the first command to run your stages. `vidbyte-cli runtime stages describe` works offline, so you can read every stage option before your first run.

Run it from your own agent

Copy prompt

Paste this into the agent you already use and it will ask you what you need, then write the exact Stages Agent invocation for your job.

You are helping me build an invocation for Vidbyte's Stages Agent, which runs one task through up to 25 phases, each a fresh Codex agent with its own system prompt, turn prompt, model, effort, and sandbox. Ask me these one at a time and wai…

Run it from the command line

Every agent starts with the same two setup commands: install vidbyte-cli, then log in with your Vidbyte key. Stages Agent also needs an OpenAI key stored for Codex, and then it is a run command whose repeated options describe each stage, plus a free describe command. Only the run command charges; describe never contacts Vidbyte.

  1. bash
    pipx install vidbyte-cli

    Installs vidbyte-cli from PyPI, the command line every Vidbyte agent is started and tracked from. pipx gives it its own environment and puts the `vidbyte-cli` command on your PATH; without pipx, run `python -m pip install vidbyte-cli` inside an activated virtual environment instead, and read the CLI repository README for the full installation notes. Run `vidbyte-cli --version` afterwards, and if it prints a version number the install worked.

    View subcommands
    --python
    Picks the Python interpreter pipx builds the CLI's environment with, such as `--python python3.12`. vidbyte-cli needs Python 3.11 or newer, so set it when your default Python is older and the install refuses to resolve.
  2. bash
    vidbyte-cli login

    Stores your Vidbyte API key, which is what identifies you and what every agent's charge is billed against. It reads the key at a hidden prompt, checks it against Vidbyte before saving anything, and then keeps it in your operating system's keyring. Run `vidbyte-cli whoami` afterwards to confirm which account the stored key belongs to.

    View subcommands
    --with-token
    Reads the key from standard input instead of a hidden prompt, which is how you log in from a script or a CI job. Pipe it in from your secret store rather than typing it into the command. There is deliberately no --api-key flag, because anything in the command line leaks into process listings, shell history, and CI logs.
    --allow-file-fallback
    Approves storing the key in a permission-restricted file when the machine has no operating-system keyring, such as a bare Linux server. Without it, login asks before falling back, or refuses when there is no terminal to ask on. Anything running as your user can read that file, so use it only where a keyring genuinely is not available.
  3. bash
    vidbyte-cli provider login openai

    Stores the OpenAI key that every stage's agent will run against, separately from your Vidbyte key. Every stage's model calls are billed to that account. The CLI resolves the key from OPENAI_API_KEY first, then from this stored profile.

    View subcommands
    --with-token
    Reads the OpenAI key from standard input instead of a hidden prompt. Use it in scripts and CI, piping the key from your secret store. The key never has to appear in the command line or your shell history.
    --allow-file-fallback
    Approves storing the key in a permission-restricted file when no operating-system keyring is available. Without it, the command asks first or refuses when it cannot ask. Anything running as your user can read that file.
  4. bash
    vidbyte-cli runtime stages describe

    Prints every option a stage accepts, what one occurrence of it configures, and the exact words each closed value set takes. It touches no network, buys no admission, starts no agent, and costs nothing. Read it first if you are building a staged invocation programmatically.

  5. bash
    vidbyte-cli runtime stages run "<the whole job>" --stage-prompt "..." --stage-system-prompt "..."

    Runs every stage of one task, one fresh agent per stage, in the current working directory. The task argument is the top-level statement of what the run is for, and it is what the first stage sees. Every stage option is given once per stage, in stage order, so the first occurrence configures stage one, the second configures stage two, and so on.

    View subcommands
    --stage-prompt
    The turn prompt for one stage, and the option that decides how many stages run: give it three times and three stages run. The token {{previous}} is replaced with the previous stage's output, or with the task for the first stage and in parallel mode. A run accepts between 1 and 25 prompts.
    --stage-system-prompt
    The standing instructions for one stage, given exactly as many times as --stage-prompt. This is where a stage's role lives: what it is for, what it must not do, and what shape its output should take. It is discarded with the stage's agent, so it never leaks into another stage.
    --stage-name
    A short label for one stage, used as the agent's name and in progress lines. Leave it out entirely and stages are named stage-1, stage-2, and so on. Give one per stage or none at all, because a partial list is rejected.
    --stage-model
    The model one stage runs on; leave the option out and every stage uses the model Codex is already configured with. Pass an empty value to keep a single stage on that default while pinning the others. An unrecognized model is not caught until Codex runs it.
    --stage-effort
    How much reasoning one stage spends, accepting none, minimal, low, medium, high, or xhigh, defaulting to medium. Analysis and review stages usually justify high, while mechanical stages rarely do. A misspelled value is rejected before anything runs.
    --stage-sandbox
    How far one stage may reach into the filesystem: read-only, workspace-write, or full-access, defaulting to workspace-write. Codex enforces it, so it is a real boundary rather than a hint. Give read-only to stages that only inspect, audit, or plan.
    --stage-approval
    What one stage does when an action needs approval: auto_review lets Codex review and proceed, and deny_all refuses outright. A staged run never stops to prompt you either way. Pair deny_all with a read-only sandbox for a stage that must not act at all.
    --stage-context
    Turn-scoped reference material for one stage, such as a file excerpt, a schema, or a prior decision. It reaches that stage only and never carries forward. Leave it out and every stage runs with none.
    --stage-output-schema
    A JSON object schema that forces one stage to answer in a fixed shape. Use it when the next consumer is another stage, so the handoff can be checked mechanically. Leave a stage's value empty to let it answer in prose.
    --stage-summary
    How much of its own reasoning one stage reports back: none, auto, concise, or detailed, defaulting to auto. It changes what you read, not what the agent does. Choose detailed when a stage exists to show its reasoning to the next one.
    --stage-personality
    The tone one stage writes in: none, friendly, or pragmatic, defaulting to none. It changes framing only, never capability, sandboxing, or cost. Set it on stages whose output a person will read.
    --stage-image
    One image input for one stage, given as a web URL, a data URL, or a local file path. It travels with that stage's turn only. Use it for a screenshot a review stage must look at.
    --stage-skill
    One Codex skill for one stage, written as NAME=PATH pointing at the skill's directory. The skill is loaded by that stage's agent only. Two stages that need the same skill each need their own occurrence.
    --stage-mention
    One named resource for one stage to read, written as NAME=PATH. It reaches that stage's agent only. Leave it out when the prompt already names everything the stage needs.
    --parallel / --sequential
    Chooses whether every stage runs at once or one after another, defaulting to sequential. Sequential passes each finished output into the next stage's {{previous}}, while parallel gives every stage the task and no sight of the others. Stages that build on each other must run sequentially.
    --stop-on-error / --no-stop-on-error
    Decides what happens the first time a stage runs out of attempts. The default stops the run and keeps every result completed before the failure. The no- form records the failure and starts the next stage anyway.
    --max-retries-per-stage
    Sets how many extra attempts a failed stage gets, from 0 to 3, defaulting to 1. Each retry sends the same prompt to a brand-new agent, which recovers from crashes and timeouts. Every attempt is model usage on your own account.
    --idempotency-key
    Recovers an admission whose response you never saw, so the balance is not charged twice for the same run. Leave it out and a fresh key is generated for every run. Reusing a key does not resume the stages; they run again from the first.
  6. bash
    vidbyte-cli runtime list

    Lists the runtimes Vidbyte will admit, with the charge for each read from Vidbyte's catalog rather than hard-coded. Stages Agent appears there as runtime.stages, next to its current charge. Run it before scripting a batch of staged runs, so the price you budget is the price your balance is charged.

Use cases

Each example names the problem, the setup, the command to run, and the result you should expect.

Why use this agent

Real work has phases that want different things from an agent. Auditing wants patience, breadth, and no ability to change anything. Implementing wants decisiveness and write access, and verifying wants suspicion. A general agent gives you exactly one configuration for all of them, so every phase runs under settings that are a compromise, and the compromise is worst for whichever phase is least like the others. This agent makes each phase a separate agent with its own complete configuration, so nothing has to be watered down.

The second thing it gives you is enforced phase boundaries. In a single session, do not edit anything until you have finished reviewing is a request, and it is the kind of request an agent breaks when it notices an easy fix. Here the review stage's sandbox is read-only, so the instruction is not needed and cannot be ignored. The same applies to context: each stage's agent is discarded when its stage ends, so no thread history or tool state leaks forward. The only thing that crosses a boundary is the output you chose to pass on.

The third is that the whole flow is one invocation you can save, script, and rerun. Multi-phase work done by hand is a sequence of prompts you retype slightly differently every time, which makes it unrepeatable and makes comparing two runs meaningless. A staged run is fully described by its options, so the same flow behaves the same way tomorrow. A change to one phase is a change to one option rather than a rewrite of a conversation. The number of phases is decided by the work, not by how much retyping you can stand.

  • One configuration for everything

    Each stage carries its own system prompt, model, effort, and sandbox. An auditing phase and an implementing phase stop sharing settings that suit neither. Every phase runs the way it should.

  • Prompts serving opposite purposes

    A prompt that makes an agent a good reviewer makes it a timid implementer. Per-stage system prompts remove the need to average the two. Each prompt is written for one job.

  • Phase boundaries by request

    A read-only stage physically cannot write. The boundary is enforced by the sandbox rather than by the agent's cooperation. It holds even when the agent spots an easy fix.

  • Context leaking between phases

    Each stage's agent is discarded when the stage ends. No thread history or tool state crosses a boundary. The only thing that does is the output you explicitly pass on.

  • Reference material everywhere

    Stage context reaches the one stage that needs the spec or the excerpt. It does not survive into the next stage. Supporting material for one phase never becomes noise in another.

  • Effort spent in wrong places

    Reasoning effort is set per stage. You buy deep thinking for the phase that needs it and speed for the phases that do not. On a long flow, that is most of the difference.

  • Unrepeatable multi-phase work

    The whole flow is described by its options rather than by a conversation you had. The same run behaves the same way tomorrow. That is what makes two runs comparable.

  • Handoffs lost in prose

    A stage can be forced to answer in a fixed JSON shape. The next stage receives a handoff it can check mechanically. Findings stop getting lost between phases.

  • Analyses contaminating each other

    Parallel mode gives every stage the top-level task and no sight of the others. Independent reads therefore stay independent. That is the only way a comparison between them means anything.

  • Permissions shared across phases

    Sandbox and approval policy are set per stage. One run can hold a phase that reads everything and a phase that changes almost nothing. Neither has to compromise for the other.

  • Guessing what options accept

    An offline describe command prints every stage option and its exact accepted values. It touches no network and costs nothing. A caller building an invocation never has to read the source.

When to use it

  • When the work has phases that want genuinely different things from an agent.

  • When a review phase must not be able to edit anything.

  • When one phase needs deep reasoning and the next needs speed.

  • When you have been trying to write one system prompt that serves two opposite jobs.

  • When context from an earlier phase would mislead a later one.

  • When a phase needs reference material that should not follow it forward.

  • When you want the same multi-phase flow to be repeatable rather than retyped.

  • When two runs of the same flow have to be comparable.

  • When you want several independent reads of one task and no cross-talk.

  • When permissions should differ between the beginning and the end of a run.

  • When you are assembling the invocation programmatically and need a stable option surface.

  • When one phase has to hand the next a result it can check rather than interpret.

  • When the phases are known in advance and the ordering is the part you trust.

  • When you want an audit trail that shows which phase produced which output.

  • When a design-doc flow has audit, design, implement, and verify steps that each need their own agent.

  • When a single long session keeps blurring phases that should have been separate.

  • When a failed phase should stop the run with every earlier phase's result intact.

Similar agents

More in agent workflows

  • Task Board

    Pick this one instead when you have a flat list of comparable tasks rather than phases that need different configurations.

    Open agent page →

  • Ensemble Agent

    Pick this one instead when the phases you would define are all "propose an approach" and what you actually want is a slate to choose from.

    Open agent page →

  • Persistent Agent

    Pick this one instead when the work is a single phase that simply needs to be carried all the way to done.

    Open agent page →
Browse all agents →