Skip to content

People, agents and anyone

Each task says who may claim it with actor:

actor Who may claim it
any (the default) A person or an agent, whoever gets there first
human A person
agent An agent, through the CLI or MCP; a person may take it over
mixed-work.yaml
metadata: { id: mixed-work }
spec:
defaults: { actor: agent }
steps:
- id: gather_logs
instructions: Collect the last hour of error logs.
- id: diagnose
actor: any
instructions: Find the likely cause.
- id: decide_fix
actor: human
instructions: Choose a fix and write it in the summary.

assignee names the person or team a step is for: it puts the step in their inbox and notifications. On its own it’s guidance; anyone actor allows may still claim the step. assignment: strict makes it binding:

assignment: guidance (default) assignment: strict
human or any step Anyone may claim it; it’s in the assignee’s inbox Only the assignees (and the step’s escalation) may claim it; agents can’t
agent step An agent claims it It limits who may take it over
finance-sign-off.yaml
metadata: { id: finance-sign-off }
spec:
steps:
- id: approve_spend
actor: human
assignee: team:finance
assignment: strict
instructions: Confirm the vendor invoice matches the purchase order.

The assignee can also be an expression, such as assignee: "${{ inputs.on_call }}".

The server decides whether a caller is a person or an agent from the kind of credential, never from what the caller says:

Credential Recorded as
A personal access token or a browser session A person
An agent-kind token (runbook token create --agent) An agent, sponsored by the person who made it
An execution pair (runbook run token) An agent, working that one run
An OAuth grant to an MCP client An agent, sponsored by the person who consented
A service token The project’s automation

An agent declares a session, a name and a model when it claims a step, and those go on the record too.

  • on_failure: handoff (often under spec.defaults) hands a failed task to a person instead of failing the run.
  • runbook step request-human lets an agent ask for help with a reason and a question.

Either way the step becomes a person’s, a step.blocked notification goes out, and the run waits for them.

careful-agent.yaml
metadata: { id: careful-agent }
spec:
defaults: { actor: agent, on_failure: handoff }
steps:
- id: rotate_certificate
instructions: Rotate the TLS certificate for api.example.com.

A step left open can remind its people and escalate to others:

nudge.yaml
metadata: { id: nudge }
spec:
defaults:
remind_after: 2h
remind_every: 4h
escalate_after: 1d
escalate_to: [team:eng-leads]
steps:
- id: review
actor: human
assignee: team:oncall

Reminders (step.reminder) go to the step’s people: approvers, the assignee, whoever claimed it; with none, the runbook’s owners. An escalation (step.escalated) goes once to escalate_to, who may then claim the step even under strict assignment.