Skip to content
, ,

Google Antigravity Dynamic Workflows: /run-workflow Guide

12–18 minutes
Smiling silver-haired woman with glasses in a green bomber jacket holding an ANTIGRAVITY card, hook: One command runs many agents

Google added Dynamic Workflows to Antigravity on 13 November 2026. You type /run-workflow, and the agent writes a short Python script that runs many agents for you. It turns long, messy chat sessions into a plan you can read, approve and run again.

This guide covers everything in one place. You will learn who gets it, how to run your first workflow, how JSON Schema results work, and how to save a script for later.

TLDR

  • What it is: /run-workflow makes the agent write a Python orchestration script that runs other agents.
  • Who gets it: Google AI Pro and Google AI Ultra, in the Antigravity app and the Antigravity CLI.
  • Safety: you approve each script before it runs, unless a preset like Turbo allows it.
  • Results: each agent returns data checked against a JSON Schema.
  • Reuse: save the script as a .py file in your project and rerun it any time.

What Dynamic Workflows are

Normally an agent handles a big job turn by turn, inside one chat. That works for small tasks. For “check all 40 files” or “fix each bug, then verify”, the chat gets long and the agent can lose track.

Dynamic Workflows move the plan into code. The agent reads a built-in run-workflow skill, then writes a Python script for your task. The script decides what runs next, starts worker agents, and collects their answers.

  • Predictable control flow: loops and branches live in the script, not in the model’s memory.
  • Structured results: each worker returns data that matches a JSON Schema.
  • Cleaner main chat: worker logs stay in their own conversations, not in yours.
  • Repeatable: a good script can be saved, put in Git and run again.
Quick answer: Dynamic Workflows let Antigravity write and run a Python script that coordinates many agents. You approve the script, the workers do the job in parallel or in order, and you get structured results back.

Who can use it and what you need

Google’s docs say Dynamic Workflows are available on Google AI Pro and Google AI Ultra. They work in both the Antigravity desktop app and the Antigravity CLI. If you are unsure which plan you have, see our Google AI Pro vs Ultra comparison.

You do not need to install Python yourself. Antigravity ships its own Python, which unpacks the first time you run a workflow.

  • Custom Python: set the ANTIGRAVITY_PYTHON environment variable to a name on your PATH or a full path.
  • Version: it must be Python 3.8 or later.
  • Fallback: if the bundled Python can’t start, Antigravity looks for Python 3.8+ on your PATH or common install spots (Homebrew and python.org on macOS, the py launcher on Windows).

Note: On macOS, the app does not see shell environment variables when you open it from the Dock. If ANTIGRAVITY_PYTHON seems ignored, that is the likely reason.

New to the CLI? Our Gemini CLI and Antigravity CLI guide covers setup and limits.

How to run your first workflow

There is no separate switch to turn on. If your plan includes it, the command is ready. Follow these steps for a safe first run.

  1. Open a project. Start the Antigravity app or the CLI inside a Git repository. A repo makes branch workspaces and diffs easy.
  2. Type the command. Enter /run-workflow followed by your task. In the CLI, type /run-work and press Tab to complete it. You can also just say “Run a workflow that…” in plain words.
  3. Start small and read-only. Pick a task that only reads files, such as a review. This keeps your first run low risk.
  4. Read the script. Antigravity shows the generated Python before it runs. Check what each agent will do and which model it uses.
  5. Approve or deny. In the app, choose “Yes, allow this time” for now. In the CLI, choose “Yes, run command”. To change the plan, choose No and tell the agent what to fix.
  6. Watch the run. The workflow shows up as one step, with agent cards you can open. It runs in the background.
  7. Save it if it worked. Ask the agent to save the script as a .py file, for example scripts/review-changes.py.

A good first prompt, taken from Google’s docs:

/run-workflow Find the Python modules in src/bookstore, then review each module in parallel for unhandled exceptions (read files only) and give me a one-line verdict per module.

Tip: Add “read files only” to early prompts. It nudges the agent to write a script that reviews without editing, so you can learn the flow safely.

Example prompts you can copy

Google’s documentation lists several prompt shapes. Each one maps to a common pattern.

Parallel review across files

/run-workflow List the Python files changed since main, then review each file in parallel for unhandled exceptions using the flash model, and log a one-line verdict per file.

Reviewer and fixers loop

/run-workflow Have a persistent Reviewer agent list the bugs in src/billing, fan out one Fixer agent per bug in parallel, and then ask the same Reviewer to confirm that every bug it found is fixed.

Per-package edits in isolated branches

/run-workflow For each package under packages/, start one agent in an isolated branch workspace to replace the deprecated request() helper with fetchJson(), run npm test in that package, and log a diff summary and the test result.

One item at a time

/run-workflow Process BUG-1.md and BUG-2.md one at a time: for each bug, have one agent write a failing pytest test and a second agent fix the code until the new test passes.

Notice the pattern. Each prompt names the items, says parallel or one at a time, and says what each agent should return. The more clearly you say these three things, the better the script.

Inside the script: building blocks

You rarely write the script yourself. Still, knowing the parts helps you review it before you approve. These are the building blocks Google documents.

Building block What it does
phase(name) Groups the steps that follow under a title.
log(*args) Prints a message to the workflow output.
agent(prompt, schema, role, type_name, workspace, model) Starts one agent and returns its validated result.
parallel(items, fn) Runs one task per item at the same time. If one fails, the others are canceled.
pipeline(items, fn) Runs items one at a time, in order.
await trajectory(...) Reads earlier steps of the conversation.
args A dictionary of optional arguments.
CONVERSATION_ID, STEP_INDEX, WORKSPACES Context values the script can read.

Options for each agent

  • model: inherit (default), flash_lite, flash or pro.
  • type_name: self (default), the built-in research agent, or a custom subagent.
  • workspace: inherit (default), branch (an isolated Git worktree) or share (a new working copy that shares repository storage).
  • role: a title shown on the agent’s card.

Here is the example script from Google’s docs. It finds changed files, then reviews each one in parallel with the flash model.

phase("Discover")
files = await agent(
    "List the Python files changed since main. Paths only.",
    schema={"type": "array", "items": {"type": "string"}},
)

phase("Review")
# parallel() runs one agent per file at the same time.
# role titles each agent's card.
reviews = await parallel(
    files,
    lambda f: agent(
        f"Review {f} for unhandled exceptions. Reply with a one-line verdict.",
        schema={"type": "string"},
        role=f"Review {f}",
        model="flash",
    ),
)
for r in reviews:
    log(r)

JSON Schema results explained

Every worker agent returns its answer through a finish tool. That tool checks the answer against the JSON Schema the script gave it. The script then receives the parsed value, not loose prose.

This is what makes branching reliable. If a schema says “array of strings”, the next phase can loop over it safely.

  • Free text: {"type": "string"} gives a free-form answer.
  • A list: {"type": "array", "items": {"type": "string"}} gives a list of strings, such as file paths.

For richer results, you can ask for an object schema in your prompt. Here is an illustrative schema (our own example, not from Google’s docs) for a bug review:

{
  "type": "object",
  "required": ["file", "severity", "summary"],
  "properties": {
    "file": {"type": "string"},
    "severity": {"type": "string", "enum": ["low", "medium", "high"]},
    "summary": {"type": "string"}
  }
}

A prompt like “return file, severity (low, medium or high) and a one-line summary for each finding” usually leads the agent to write a schema of this shape. If you want to learn more about schemas in general, see our structured outputs guide.

Approvals and permission presets

Antigravity shows the script and asks before it runs, unless your permission preset already allows it. Google names Turbo as a preset that lets workflow scripts run without asking.

Approval options

Surface Choices
App Yes, allow this time; Yes, and always allow in this conversation; Yes, and always allow; No
CLI “Run this command?” with Yes, run command; No, cancel

Two rules matter here. An approval covers that exact script. A command prefix rule can’t cover a Python script, so allow-listing “python” will not skip the prompt.

Agents started by a workflow also ask for approval in their own conversations. They wait until you answer, so a run can pause if you walk away.

The four app presets

Antigravity’s permissions page lists four presets in the app:

  • Request Review: sandbox off, terminal commands always ask, workspace-only file access.
  • Default: sandbox on, sandboxed commands run without asking, others ask.
  • Auto: sandbox on, commands outside the sandbox are checked automatically, so safe ones run and risky ones ask.
  • Turbo: sandbox off, unrestricted commands, full filesystem access, MCP and web allowed.

Change the preset in Settings > General > Global Permissions > Permission Preset, or per project under Settings > Projects. The CLI does not use preset names. It uses modes (default, accept-edits, auto) and a toolPermission setting instead.

Warning: Turbo removes the sandbox and gives agents full filesystem access. Combined with auto-run scripts, one bad prompt can edit many files at once. Keep Turbo for throwaway clones or well-tested saved scripts.

Saving and rerunning workflows

Once a script does what you want, keep it. Ask the agent to save it as a .py file in your workspace. Google does not name a default folder, so pick one, such as scripts/.

  1. Ask to save. Say “Save this workflow script as scripts/review-changes.py”.
  2. Commit it. Add the file to Git so teammates can read and reuse it.
  3. Rerun it. Type /run-workflow Run scripts/review-changes.py.
  4. Approve again. You are asked each time, unless you chose “Yes, and always allow”.

Because the file is plain Python, you can also edit it by hand. Change a model from pro to flash to cut cost, or change which folder it scans.

Watching a workflow run

In the app

  • One step: the workflow shows as a single step, with a title like “workflow · Review · 3/4 agents”.
  • Background Tasks: it is listed under Background Tasks in the side panel’s Overview.
  • Agent cards: click a card to open that agent’s conversation.

In the CLI

  • Ctrl+O: expands the phase tree.
  • /tasks or Ctrl+T: opens Task Details.
  • Alt+J: jumps to an agent waiting for approval.
  • Ctrl+K: approves that agent’s pending request.

Limits and what Google has not said

Some behaviour is documented. Some is not, so plan around it.

  • Stopping: stopping the parent conversation stops all running workflow agents.
  • Hidden agents: workflow agents don’t appear in your main conversation list.
  • Fail-fast parallel: in parallel(), if one item fails, the others are canceled.
  • No published caps: Google gives no number for max agents or max runtime per workflow.
  • No API: Google has not announced standalone API access outside Antigravity.
  • Usage: many agents means more model usage, which counts against your plan’s limits.

Tip: Test a new workflow on one folder first. Use flash or flash_lite for simple checks and keep pro for the hard step.

Antigravity vs Claude Code vs Codex

Antigravity is not alone here. Claude Code has its own dynamic workflows, and Codex has subagents. Here is how they compare, based on each vendor’s docs.

Feature Antigravity Claude Code Codex
Trigger /run-workflow or plain words “use a workflow”, the ultracode keyword, or /effort ultracode Ask for subagents directly, or via AGENTS.md or skills
Script language Python JavaScript No script; Codex orchestrates
Structured output JSON Schema via finish Optional JSON schema per agent Results merged into one reply
Saving Save as .py in your project .claude/workflows/ or ~/.claude/workflows/, runs as /name Custom agents as TOML in .codex/agents/
Published limits None stated 16 concurrent by default, 1,000 agents per run Concurrency setting, default chosen by Codex
Plans Google AI Pro and Ultra All paid plans and API (Pro turns it on in /config) ChatGPT plans with Codex

The big difference is language and saving. Antigravity uses Python files you manage yourself. Claude Code saves workflows as slash commands and documents hard caps. See our Codex vs Claude Code comparison for the wider picture.

When to use workflows vs /swarm and others

Antigravity now has several multi-agent tools. Google’s docs describe each one like this:

  • Dynamic Workflows: scripted control flow for the same check across many items, staged steps, or review-and-fix loops.
  • /swarm: peer agents coordinate on a shared message board and address each other with @name. See our Antigravity swarm guide.
  • Subagents: hand off one task, like research or a build, while you keep working.
  • /boost: deep reasoning on hard bugs, race conditions or algorithms, with independent checking.
  • /teamwork: a team for large, multi-milestone projects that starts with a scoping interview.
  • Orchestrator: one conversation where a planner model plans and reviews while a faster model runs routine tool calls.

Pick a workflow when you can describe the steps in advance. Pick /swarm when agents need to talk to each other freely.

Troubleshooting

/run-workflow is not recognised

Check that you are signed in with a Google AI Pro or Ultra account. Update the app or CLI to the latest version, since the feature arrived on 13 November 2026.

Python fails to start

The bundled Python unpacks on first use, so give it a moment. If it still fails, install Python 3.8 or later and set ANTIGRAVITY_PYTHON to its path.

ANTIGRAVITY_PYTHON is ignored on macOS

Apps opened from the Dock don’t see shell variables. Launch Antigravity from a terminal, or rely on the bundled Python instead.

The workflow seems stuck

A worker agent is probably waiting for approval in its own conversation. In the CLI, press Alt+J to jump to it and Ctrl+K to approve. In the app, open Background Tasks and check each agent card.

The whole parallel step stopped

In parallel(), one failed item cancels the rest. Open the failed agent card, fix the cause, then rerun. For fragile jobs, ask for pipeline() so items run one by one.

I get asked to approve every time

That is expected. An approval covers one exact script, and prefix rules can’t cover Python. Choose “Yes, and always allow” for trusted saved scripts.

Results are not in the shape I need

Spell out the fields in your prompt, such as “return file, severity and summary”. The agent then writes a matching schema, and finish enforces it.

Frequently Asked Questions

What is Antigravity Dynamic Workflows?

It is a feature launched on 13 November 2026 that makes the Antigravity agent write a Python script to coordinate many agents. You start it with /run-workflow and approve the script before it runs.

Is Dynamic Workflows free?

No. Google’s docs list it for Google AI Pro and Google AI Ultra plans. Workflow agents also use model capacity from your plan.

Does it work in the Antigravity CLI?

Yes. It works in both the app and the CLI. In the CLI, type /run-work and press Tab to complete the command.

Do I have to approve every script?

Yes, unless your permission preset allows scripts, such as Turbo, or you chose “Yes, and always allow”. Each approval covers that exact script.

How do I save and rerun a workflow?

Ask the agent to save the script as a .py file in your project. Later, type /run-workflow Run scripts/your-file.py to run it again.

Which models can workflow agents use?

Each agent() call can use inherit, flash_lite, flash or pro. The default is inherit, which uses the conversation’s model.

Can I call Dynamic Workflows from an API?

Not at launch. Google has not announced standalone API access outside the Antigravity app and CLI.

Sources

Free weekly email

Get new AI guides every week

One short weekly email with our newest local AI, ComfyUI and AI tool guides. No spam, no pop-ups, just the good stuff.

Free. Unsubscribe anytime in one click. We only use your email to send this newsletter. See our privacy policy.

Smiling silver-haired woman with glasses in a green bomber jacket holding an ANTIGRAVITY card, hook: One command runs many agents