Step Breyta (`:breyta`)

Quick Answer

Use :breyta to give an agent a narrow, allowlisted tool for reading and, when explicitly enabled, mutating Breyta workspace control-plane resources such as flows, runs, docs, and resources.

{:type :agent
 :objective "Inspect the latest failed run and summarize the likely fix."
 :tools {:mode :execute
         :breyta {:allow [:flows/list :runs/show :resources/read]
                  :mutations :none}}}

The runtime owns workspace identity, actor identity, auth, and API routing. The model can only choose an allowed operation and operation-specific arguments.

Canonical Agent Tool Config

Field	Type	Required	Notes
`:allow`	vector	Yes	Default-deny operation allowlist.
`:mutations`	keyword	No	One of `:none`, `:draft-only`, `:run-only`, `:write`. Defaults to `:none`.
`:require-approval`	vector	No	Operations that trigger an agent approval request before execution.

Operations

Read operations:

:flows/list
:flows/show
:flows/pull
:runs/list
:runs/show
:resources/list
:resources/read
:docs/find
:docs/show

Mutation operations:

:flows/push-draft requires :mutations :draft-only or :write
:flows/run requires :mutations :run-only or :write
:feedback/send requires :mutations :draft-only or :write

Operation Arguments

Tool calls use this shape:

{:op :runs/show
 :args {:workflow-id "workflow-id-from-runs-list"}}

The :args map is specific to :op.

Use kebab-case keys in flow definitions.
JSON callers use the full operation string, for example "flows/list" or
"runs/show"; do not shorten it to "list" or "show".
Runtime-owned fields such as :workspace-id, :actor, :auth, :token, :api-url, :allow, and :mutations are stripped.
Published agent tool schemas expose operation-specific :args variants.

Operation	Required Args	Optional Args
`:flows/list`	None	`:archived` boolean, `:include-archived` boolean, `:limit` integer up to 100, `:cursor` string
`:flows/show`	`:flow-slug` string/keyword	`:source` `:active`/`:draft`/`:latest`, `:version` integer, `:include-flow-literal` boolean, `:include-templates` boolean, `:include-functions` boolean
`:flows/pull`	`:flow-slug` string/keyword	Same optional args as `:flows/show`; intended for reading source/export details
`:flows/push-draft`	`:flow-literal` string containing a complete flow definition	`:deploy-key` string
`:flows/run`	`:flow-slug` string/keyword	`:input` map, `:installation-id` string, `:target` `:draft`/`:live`, `:source` `:active`/`:draft`/`:latest`, `:version` integer
`:runs/list`	None	`:flow-slug` string/keyword, `:installation-id` string, `:version` integer, `:status` string/keyword, `:limit` integer up to 100, `:cursor` string
`:runs/show`	`:workflow-id` string	`:include-steps` boolean, `:include-result` boolean
`:resources/list`	None	`:type` string, `:prefix` string, `:tags` vector of strings, `:query` string, `:limit` integer, `:cursor` string, `:storage-backend` string, `:storage-root` string, `:path-prefix` string
`:resources/read`	`:uri` string	`:format` `:json`/`:text`/`:raw`
`:docs/find`	None	`:query` string, `:limit` integer, `:source` `:all`/`:public`/`:cli`, `:with-snippets` boolean
`:docs/show`	`:slug` string	`:format` `:json`/`:markdown`
`:feedback/send`	`:title` string, `:description` string	`:type` `:issue`/`:feature_request`/`:general`, `:source` `:agent`/`:human`/`:system`, `:tags` vector of strings, `:metadata` map, `:context` map, `:command` string, `:flow-slug` string/keyword, `:workflow-id` string, `:run-id` string

For :flows/run, use :target :draft to test an unreleased draft. Use :target :live or :installation-id when running a released/public installation target.

Examples:

{:op :flows/list
 :args {:limit 20}}

{:op :flows/show
 :args {:flow-slug :lead-research
        :source :draft
        :include-flow-literal true}}

{:op :flows/run
 :args {:flow-slug :lead-research
        :target :draft
        :input {:company "Breyta"}}}

{:op :resources/read
 :args {:uri "res://v1/ws/ws-acme/result/table/tbl_leads"
        :format :json}}

CLI JSON probe:

breyta steps run --flow my-flow --source draft --type breyta \
  --params '{"op":"flows/list","allow":["flows/list"],"args":{"limit":5}}'

Runtime Behavior

The workspace is always the current workflow runtime workspace.
Auth tokens, API base URLs, actor ids, and workspace ids are not accepted from tool-call arguments.
Tool-call arguments named like workspace-id, auth, token, api-url, allow, mutations, or require-approval are stripped before step execution.
Calls run through an activity-backed worker executor and reuse existing Breyta command, docs, and resource handlers.
Every successful or failed call can emit a redacted audit event when the runtime provides :breyta-control-plane-audit-fn.
Mutation activities use the single-attempt execution profile; expose mutations only with explicit idempotency in the called operation arguments.

Direct Step Shape

The direct step shape is available for non-agent orchestration, but most uses should expose it through :agent tools.

(flow/step :breyta :show-run
  {:op :runs/show
   :allow [:runs/show]
   :args {:workflow-id (:workflow-id (flow/input))}})

Example With Approval

{:type :agent
 :objective "Inspect the draft and run it only after approval."
 :approval {:mode :all-mutations}
 :tools {:mode :execute
         :breyta {:allow [:flows/show :flows/run]
                  :mutations :run-only
                  :require-approval [:flows/run]}}}

Step Breyta (:breyta)