Run jobs

A job is one run of an agent. Start it with run, which waits for the answer:

orchestrator-zero run reviewer "Review PR 42 in acme/api"         # text input
orchestrator-zero run reviewer '{"repo": "acme/api", "pr": 42}'   # JSON, for agents with an input schema
echo "Review PR 42" | orchestrator-zero run reviewer -            # input from stdin

The answer goes to stdout. Everything else goes to stderr, so you can pipe the answer on: while the job runs, what its agents write and the tools they call, child jobs on other nodes included, and at the end what the job cost, one row per job in its tree.

lead → oz.delegate {"agent":"helper","task":"Please greet Ada"}
lead ⇢ helper (job job-1746aef4-.../helper-8c872bc6)
helper → team.hello {"name":"Ada"}
helper ← team.hello Hello, Ada!
helper: Done: Hello, Ada!
lead ← oz.delegate Done: Hello, Ada!
lead: Done. Ada has been greeted.

→ is a tool call, ← its result, ⇢ a child job and name: what an agent writes. --quiet turns the live output off.

run also runs flows, by name: their tool steps, agent steps and approvals show up the same way.

Don't wait

orchestrator-zero run reviewer --detach "Review PR 42 in acme/api"   # prints the job ID and returns
orchestrator-zero job watch <job-id>                                 # follow it live until it ends
orchestrator-zero job get <job-id>                                   # status, answer and cost per branch

Jobs are durable. If you stop waiting, with Ctrl+C or --wait 30s, the job keeps running; follow it again with job watch, or check it with job get.

Choose the ID

orchestrator-zero run reviewer --id pr-42-review "Review PR 42 in acme/api"

Starting a job with the ID of one that is still running follows that job instead of starting a second one, which makes retries from scripts and apps safe. IDs may not contain /, which separates a job from its children.

Limit it

orchestrator-zero run reviewer --timeout 15m "..."
orchestrator-zero run reviewer --budget 0.50 "..."

--timeout limits the whole job on top of the agent's own limits. --budget caps what the job and the jobs it delegates to may spend on model calls, in US dollars; see budgets.

List and cancel

orchestrator-zero job list                  # recent top-level jobs, newest first
orchestrator-zero job list --limit 50 --tenant acme
orchestrator-zero job cancel <job-id> --reason "wrong PR"

Cancelling a job cancels the jobs it delegated to as well. The reason goes into the job's history.

A job's states

From apps

Apps start and follow jobs through the runtime API on the edge, the same API the CLI uses.