Using actions

Use this when you want to find an action, run it, and read the run it records, or add an action of your own.

An action is a validated procedure with declared inputs and requirements, optional checks, and a recorded run. For the full definition, see actions.

Before you begin

Build a Barry. These commands act as the bonanza identity from that guide; use your own identity’s command in its place.
The example is list-action-runs, which lists recorded action runs, the ones still open by default. The actions bag ships with Barry and provides it.
To run an action that declares a prompt:, have Barry’s services running.

Find an action

To list the actions you can run, run:

bonanza tool actions find-actions

Each result gives the action’s name, its bag, its qualified name in the form bag:name, a description, and its inputs. To search by name or description, add a word after the command.

In a session, ask for the task instead. The agent searches with the find_actions tool, starts the action with begin_action, and closes the run with complete_action, or with cancel_action if it stops early:

Find the action that lists action runs, and show me the ones that have closed.

Run an action from the terminal

To list the runs that have closed, run:
Terminal
```
bonanza action run list-action-runs --input active=false
```
Barry prints the run’s status and ID, followed by the deliverable if the run recorded one. The command exits non-zero unless the run completes.

Pass --input once per input. Barry reads each value as JSON when it parses, and as a string otherwise. To pass every input as one object, use --inputs-json instead.

Where the action runs depends on its kind. Barry runs an action that declares a run: command itself, in the same process. An action that declares a prompt: goes to Barry’s API, which gives it to an agent, so the API must be running. list-action-runs declares run:, so it works with the API down.

Read recorded runs

To list the action’s recorded runs, newest first, run:
Terminal
```
bonanza action runs --action actions:list-action-runs
```
--action filters by the action’s qualified name, in the form bag:name. Other filters narrow the list too: --status, --trigger, --session, and --limit.
To print a run’s deliverable, run:
Terminal
```
bonanza action show <run_id>
```
Replace <run_id> with an ID from the list, such as one that starts with arn_.

bonanza action show prints the deliverable alone on standard output and the run’s status and summary on standard error, so you can redirect the deliverable to a file.

Add an action of your own

Actions come from bags: each directory under a bag’s actions/ holds one action.yaml.

In your bag’s directory, create an action:
Terminal
```
barry new action triage-report
```
Barry writes actions/triage-report/action.yaml with a placeholder prompt. From another directory, add --bag and the bag’s name.
Edit action.yaml. Replace the placeholder prompt with the steps an agent follows, or replace prompt: with a run: command for Barry to execute.

The actions bag documents every action.yaml field.

Verify

bonanza action run prints the run’s status and ID on standard error, and the status reads complete when the run succeeds. The command exits zero only then, so a script can check it:

bonanza action run list-action-runs --input active=false && echo complete

In bonanza action runs, a run with a recorded deliverable carries a ✎ marker; print it with bonanza action show.

If it fails

No action named …. Barry found no action by that name. Search with bonanza tool actions find-actions and use the name it lists.
Could not reach the API to run an agent action. A prompt: action needs Barry’s API. Start the services with barry up, and see See what is running.
--input expects key=value. Write each input as name=value, or pass them all with --inputs-json.
This run never completed. bonanza action show found no deliverable because the run stopped early. Check its status in bonanza action runs.

What’s next

Automate a recurring task to turn a prompt into an action and schedule it.
Schedule and distribute work to fire an action on a trigger.
Action fields for the full action.yaml schema.