Orchestrations

An orchestration is a graph of agents that work together. The CLI treats the orchestration and its member agents as one unit: a single pull recursively fetches the graph plus every member agent, and a single push updates each member before updating the graph itself. A local manifest can also be claimed with orchestration create. See the orchestration manifest reference for every field.

Commands

brainbase orchestration create           # claim the local manifest
brainbase orchestration list             # list orchestrations under a team
brainbase orchestration pull <id>        # fetch the graph + every member agent
brainbase orchestration push             # push each member, then the graph
brainbase orchestration status           # preview what would push / pull

Creating from a manifest

orchestration create claims the brainbase-orchestration.yaml in the current folder. Each members[].slug must have a linked agent checkout at agents/<slug>/; the command resolves those links to cloud agent IDs, validates the graph, creates it under the selected org and team, and stores the orchestration identity in gitignored .brainbase/ state. Use --org <id-or-slug>, --team <id>, and --yes for non-interactive creation.

Updating only the graph

Pass --graph-only to push to update membership, edges, edge settings, and schedule triggers without pushing each member agent's content. Use it when you've only changed the graph and don't want to re-push unchanged members.

brainbase orchestration push --graph-only

Edge settings and schedules

edges:
  - from: planner
    to: worker
    settings:
      max_handoffs: 2

triggers:
  - type: schedule
    node_id: 11111111-1111-4111-8111-111111111111
    is_active: true
    config:
      cron_expression: "0 9 * * *"
    to:
      - agent: planner

Edge settings are free-form and round-trip through create, pull, push, and status drift. Schedule triggers are writable orchestration-level configuration: node_id must be a unique UUID, cron_expression must use standard five-field cron syntax, and every to[].agent must name a member. Omitted is_active defaults to false. Schedule config is normalized to cron_expression plus non-empty configured_props; other runtime-only config keys are not written back. Treat configured_props as integration-specific unless the trigger provider documents a field.

Drift and status

orchestration status compares local and cloud membership; edge description, payload schema, and settings; and schedule node ID, active state, normalized config, and target edges. It also reports member revision drift, missing local member checkouts, and orchestration cloud revision drift even when the modeled graph still matches.

Adding a member agent

add-agent <name> (alias add) creates a new member agent in the orchestration, wires its edges with --from and --to (each repeatable), and pushes the result. Pass --no-push to stage the change locally without pushing.

brainbase orchestration add-agent triage --from intake --to resolver
brainbase orch add researcher --to writer --no-push    # stage without pushing

Scope a listing to a specific org or team with --org <id-or-slug> and --team <id>.