Skip to content

YAML Flows

The run_flow tool allows the AI agent to execute a pre-defined sequence of interactions against a terminal.

This is highly effective for integration testing or for avoiding back-and-forth roundtrips between the agent and the server for predictable interactions.

Flow Schema

A flow is a YAML file (or inline YAML string) that defines a sequence of steps. Each step must define an action and its corresponding parameters.

Here are all the supported actions according to the schema:

  1. spawn: Starts the command.

  2. cmd: The command to execute (string).

  3. wait_for: Waits for a regular expression pattern to appear on the screen.

  4. pattern: The regex string to wait for.

  5. timeoutMs (optional): Milliseconds to wait before throwing an error. Defaults to 10000.

  6. type: Types out text.

  7. text: The string to type.

  8. submit (optional): Whether to press Enter after typing. Defaults to true.

  9. send_key: Sends a specific key combination (e.g., Escape, C-c).

  10. key: The key to send.

  11. sleep: Pauses execution for a specific duration.

  12. ms: Milliseconds to wait.

  13. snapshot: Captures the state of the terminal.

  14. format (optional): "png" or "txt". Defaults to "txt".
  15. outputPath: The file path to save the snapshot.
  16. intent (optional): Hint for the LLM regarding what to verify in this snapshot. Defaults to empty string.

Example

version: "1.0"
description: "Neovim Boot Test"
steps:
  - action: "spawn"
    cmd: "nvim"

  - action: "wait_for"
    pattern: "lazy.nvim"
    timeoutMs: 10000

  - action: "snapshot"
    format: "png"
    outputPath: "nvim-boot.png"
    intent: "Neovim loaded successfully"

  - action: "type"
    text: ":qa!"
    submit: true

When an agent invokes run_flow({ yaml_path: 'example-flow.yaml' }), the Flow Engine will run through the sequence, spawn the session, wait for the expected text, take the snapshot, type the exit command, and return the snapshot paths back to the agent.