# Agentic flows

Write a step as a goal in plain English. Your coding agent works out the taps the first time, the steps are saved beside the flow, and every later run replays them with no agent and no model.

## A goal instead of steps

```yaml
flow: buy-usdt
steps:
  - runFlow: { file: login.yaml }
  - agent: buy 250 USDT
  - assert: { visible: { text: Bought 250 USDT } }
```

`agent:` says what to achieve. The `assert` after it says how to tell it worked, and only the assert decides whether the step passed. An agent can claim it succeeded; it can’t pass a step.

Step through what happens to this flow over its life:

## Set up your agent

Squiggle never calls a model. Your coding agent does, through Squiggle’s MCP server, with the model and account you already have. `squiggle init` offers to connect the agents it finds (Claude Code, Copilot, Codex and Cursor), and Studio’s Settings has **Connect your agents**; see [Connect your agent](https://squiggle.sh/docs/agents).

Then ask your agent to run the flow, or paste the prompt a run prints for you. Its tools launch the app when they need it, a React web app in Squiggle’s window; see [React web apps](https://squiggle.sh/docs/web).

## Write a good goal and assert

The assert is the contract, so check the outcome. `visible: { text: Bought 250 USDT }` is good: only a finished purchase shows it. `route: token` is weak: the agent could reach that screen without buying anything, the step would pass, and those wrong steps would be saved.

Every `assert` right after an agent step checks it, and all must pass. A step with nothing to check it won’t load. For an agent step at the end of a flow, the flow’s `goal` can check it instead:

```yaml
flow: checkout
goal: { route: order-confirmed }
steps:
  - runFlow: { file: login.yaml }
  - agent: check out the cart with the saved card
```

The long form adds limits and a hint for the agent:

```yaml
- agent:
    goal: set a price alert on SUI at ${PRICE}
    rounds: 3          # answers allowed before the step fails (default 5)
    timeout: 120000    # ms for the whole step (default 180000)
    hints: the alert form is behind the bell on the token screen
- assert: { visible: { testID: alert-saved } }
```

Agent steps can sit inside `runFlow` and `retry`, but not inside `repeat` or `branch`.

## Test data and passwords

Use `${VAR}` in a goal for anything that changes. When the agent types a value that equals one of the flow’s variables, the saved steps keep `${NAME}`, not the value. If it types into a password field and no variable matches, nothing is saved, and the run names the field and asks you to put its value in a variable. Put passwords under `secrets` so they never reach a saved file.

## The saved steps

The steps are saved in `buy-usdt.agent.json`, next to the flow. Commit it: it lets a teammate’s run, or CI, replay the step with no agent. The steps are ordinary flow steps, so a strange path shows up in the pull request like any other change.

- Steps are saved only when the asserts passed.
- A replay that changed nothing leaves the file as it was, so CI never creates a diff.
- The saved steps belong to the goal’s wording. Reword a goal and it needs an agent again.
- To record a step again, run with `--redrive "buy 250 USDT"` (or `--redrive all`), or press **Re-record** on the step in Studio.

## Without an agent

A plain `squiggle flow`, a CI job or Studio’s Replay replays the saved steps. A step with nothing saved, or whose replay no longer reaches its assert, stops the run with **NEEDS AGENT** and exit code 6. Nothing failed, so this isn’t exit 1, unless another step failed.

```shell
squiggle flow price-alert.yaml
```

Output:

```text
agent  NEEDS AGENT  set a price alert on SUI at 3.25
```

| Flag | What it does |
| --- | --- |
| `--print-prompt` | Prints only the prompt to paste into your agent. Studio has the same prompt behind a copy button. |
| `--needs-agent fail` | Exits 1 instead of 6, for a job that should go red. |
| `--redrive <goal\|all>` | Ignores the saved steps, so the step needs an agent again. |

In CI, `squiggle flows --agentic` runs only agentic flows, and `--scripted` only the others. See [Run in CI](https://squiggle.sh/docs/run/ci).

> **In Studio**
>
> The Flows screen shows agentic flows on their own **Agentic** tab. Open an agent step to read its saved steps, copy the prompt for your agent, or press **Re-record**.

## Find what to write next

To see which screens none of your flows reach, and start an agentic flow on one of them, see [Find what to test](https://squiggle.sh/docs/agentic-flows/coverage).
