Using actions

This guide shows you how to find an action, run it, and read the run it records.

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

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.

Find an action

To list the actions you can run, run:

Terminal

barry 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 filter by name or description, add --query and a word to search for.

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:

Type in Barry

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

Run an action from the terminal

1. To list the runs that have closed, run:

   Terminal

   barry 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.

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

1. To list the action’s recorded runs, newest first, run:

   Terminal

   barry action runs --action actions:list-action-runs

   The filter takes the qualified name. A ✎ marks each run that recorded a deliverable.

2. To print a run’s deliverable, run:

   Terminal

   barry action show <run_id>

   Replace <run_id> with an ID from the list, such as one that starts with arn_.

barry 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.

1. 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.

2. 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.