Skip to content

Run.terminal

Display data in the terminal while a workflow runs, and ask questions in it.

A screen without answers is a board. It stays on screen until the next board replaces it, and show() returns at once.

def progress(done: int, total: int) -> Screen:
    return Screen(Rows([Row("Fixed", f"{done} of {total}")]))

await run.terminal.show(progress, done=3, total=8)

The terminal calls the function again on every frame, with the same arguments, so a board that reads a list stays current as the list grows.

A screen with answers is a question. show() waits until it is answered in the terminal and returns the answer, which here decides whether to end the run with Stop. The terminal lists the answers by number, and typing one and pressing Enter picks it.

def approve(plan: str) -> Screen[bool]:
    return Screen(Text(plan), [Choice("Go ahead", True), Choice("Stop", False)])

if not await run.terminal.show(approve, plan=plan.text):
    raise Stop("Plan rejected.")

TextInput asks for a line of text instead of a choice, and its function turns the line into the answer. Screens are built from Text, Row and Rows, and a plain string stands for a Text.

def name_it() -> Screen[str]:
    return Screen("Name the release.", [TextInput("Name", str)])

Questions from worktrees working at once take turns, one on screen at a time.

To let an agent ask a question, give its role a tool that shows one.

Reference

agl.sdk.Run.terminal property

The terminal this run shows things on.

Returns:

  • Terminal –

    The Terminal, shared with every child Run.

agl.sdk.Terminal

How a workflow shows screens and asks questions in the terminal.

show(view, /, *, priority=0, **params) abstractmethod async

Shows a Screen in the terminal and returns the answer.

Parameters:

  • view (Callable[..., Screen[T]]) –

    The function returning the Screen. It runs every frame, so keep it short and free of side effects.

  • priority (int, default: 0 ) –

    The place a question takes in the queue. The highest waiting is shown first, and questions at one priority in the order they were asked. If omitted, 0.

  • params (object, default: {} ) –

    The arguments passed to view every frame.

Returns:

  • T –

    The value of the answer given, or None where the screen offered none.

Raises:

pending abstractmethod property

How many screens are waiting at each priority.

Returns:

  • Mapping[int, int] –

    The count of waiting screens at each priority, without the one on screen now.

agl.sdk.Screen dataclass

What the terminal shows, and the answers it takes.

body instance-attribute

What the screen shows. A plain string becomes a Text.

responses instance-attribute

The answers on offer. With none, the screen is a board and nothing waits for an answer.

agl.sdk.Rows dataclass

Several rows shown together, in the order given.

rows instance-attribute

The rows to show, top to bottom.

agl.sdk.Row dataclass

One line of cells on a Screen.

cells instance-attribute

The cells, in the order given. A plain string becomes a Text.

agl.sdk.Text dataclass

Text shown on a Screen.

value instance-attribute

The text to show, as one string.

agl.sdk.Choice dataclass

An answer picked by its number, with the value it returns.

label instance-attribute

The text shown for this answer.

value instance-attribute

What Terminal.show returns when this answer is picked.

agl.sdk.TextInput dataclass

An answer typed as a line, with the function that turns it into a value.

label instance-attribute

The text shown for this answer, and again where its line is typed.

maps class-attribute instance-attribute

Called with the typed line; what it returns is the answer.

agl.sdk.Component = Text | Row | Rows

Anything that can stand as a Screen's body.

agl.sdk.Response = Choice[T] | TextInput[T]

One answer a Screen offers.