Skip to content

Run.step()

Run an agent role on an instance of Run.

Run a builder agent and wait for it to finish.

await run.step(builder)

Agent roles can declare the parameters their agents need to receive. Run.step() passes these parameters from the call site to the role. It accepts any number of them, and checks at runtime that they match what the role declares. Here request, spec and review are parameters the builder role asks for. Each one is written into the agent's prompt as JSON, where the prompt names it.

await run.step(builder, request, spec, review)

After an agent finishes, the changes it made can be committed on its branch or cleared. Use the commit parameter to commit its work. This is the only way to keep an agent's work. Without commit, every change made during the step is wiped, and its branch goes back to what it was when Run.step() was called. Changes committed by earlier steps stay untouched.

await run.step(builder, request, spec, review, commit="Implement what the run was asked for")

A commit that isn't a str, or is empty or only spaces, tabs and line breaks, is refused with InputError before the agent starts. A step that raises an exception commits nothing, even with commit.

Leaving commit out is useful for agents that don't build but investigate and report. If a role has a reporting_tool(), Run.step() returns that tool's payload. This runs the reviewer agent with design_spec written into its prompt as JSON, collects the payload from its reporting_tool(), and wipes every change it made on its branch, including commits it made on its own.

findings = await run.step(reviewer, design_spec)

Steps on one Run take turns. To run agents at the same time, give each one its own worktree.

Recorded steps

Every Run.step() is recorded. When a run crashes or is stopped, agl resume runs the workflow again, and each step that finished returns its recorded result without running its agent. A step runs again when its role, its parameters or the work before it changed.

A step that returns its recorded result also keeps its commit on the branch.

Reference

agl.sdk.Run.step(role, *inputs, commit=None) async

Runs a Role in the worktree this Run owns.

Parameters:

  • role (Role[R]) –

    The role to run, built by a @role function.

  • inputs (object, default: () ) –

    The values the role accepts, at most one per type it declares.

  • commit (str | None, default: None ) –

    The message to commit the agent's work under. If omitted, AGL throws the work away: it reverts tracked edits, deletes untracked files and drops the agent's own commits.

Returns:

  • R –

    The payload the role's reporting tool was called with, or None where the role declares no reporting tool.

Raises:

  • InputError –

    A role no @role function built, an input the role doesn't accept, two inputs of one type, one that can't be written down as JSON, or a commit that isn't a string or is empty or only spaces, tabs and line breaks.

  • NotFoundError –

    The ref this worktree was cut from names nothing.

  • ConflictError –

    Another line of work is holding this worktree's place.

  • DeniedError –

    The backend behind the role's model doesn't offer something the role requires.

  • RoleIncompleteError –

    The agent never called the role's reporting tool, or hit a limit in a role that has none.

  • UpstreamUnavailable –

    AGL couldn't start the agent's backend, or the backend stopped without answering.

  • UpstreamUnexpected –

    The agent's backend answered in a way AGL can't read.