Agentic flows

For AI agents: this page is Markdown at https://squiggle.sh/docs/agentic-flows.md. Every docs page is listed at https://squiggle.sh/llms.txt, and all of them are one file at https://squiggle.sh/llms-full.txt.

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

buy-usdt.yaml
flow: buy-usdtsteps:  - 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:

buy-usdt.yaml
flow: buy-usdtsteps:  - runFlow: { file: login.yaml }  - agent: buy 250 USDT  - assert: { visible: { text: Bought 250 USDT } }
buy-usdt.agent.json (not yet)
{  "steps": {    "0:3f4403e82834eac6": {      "goal": "buy 250 USDT",      "recordedBy": { "surface": "mcp", "agent": "claude-code" },      "from": { "route": "home" },      "modelTurns": 1,      "steps": [        { "type": { "into": { "testID": "token-search" }, "value": "usd" } },        { "tap": { "testID": "search-result-USDT" } },        { "tap": { "testID": "buy-button" } },        { "type": { "into": { "testID": "amount-input" }, "value": "250" } },        { "tap": { "testID": "buy-confirm" } }      ]    }  }}

You

Terminal
squiggle flow buy-usdt.yamlagent  NEEDS AGENT  buy 250 USDT

exit 6

No recording yet, so the run stops and prints the prompt to give your agent. Exit 6: nothing failed.

Loading the live Studio…
An agentic flow and its recorded steps. Live, in your browser.Open in Studio

Agentic flowsStudio tour · 9 steps

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.

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.

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: checkoutgoal: { 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.

Terminal
squiggle flow price-alert.yamlagent  NEEDS AGENT  set a price alert on SUI at 3.25
FlagWhat it does
--print-promptPrints only the prompt to paste into your agent. Studio has the same prompt behind a copy button.
--needs-agent failExits 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.

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.