Your own agent
Anything that can run the CLI, speak MCP or call HTTP can be an agent: a shell script, a CI job, an agent framework, a model you host. This page covers the parts every custom agent needs: a credential for one run, the loop, and a launcher that starts the agent when there’s work.
Credentials for one run
Section titled “Credentials for one run”The narrowest credential is an execution pair: an access token
(trb_exe_, one hour) and a refresh token (trb_exr_) that reach a single
run, refresh while it’s open (at most 30 days) and are revoked when it ends.
A launcher holding a project service token mints one per run:
RUNBOOK_TOKEN="$SERVICE_TOKEN" runbook run token "$EXE" --session agent-1The CLI stores the pair (0600, never in the keychain) and refreshes it
itself, so the agent’s commands that follow hold nothing but that pair. The
service token needs only executions:act (and executions:read); create
one per project:
runbook token create --kind service --role operator --project prod \ --scope executions:read --scope executions:act --name launcher --jsonOnly an organization owner or admin issues service tokens. Reusing a refresh token that was already used revokes the whole family.
The loop
Section titled “The loop”Use the CLI with --json and follow the agent loop.
In Python, with nothing but the standard library:
import json, subprocess, sys
def rb(*args): out = subprocess.run(["runbook", *args, "--json"], capture_output=True, text=True) return json.loads(out.stdout or "{}")
exe = sys.argv[1]while True: brief = rb("step", "next", exe) if brief.get("next_action") != "claim_ready_work": break # wait, exit or refresh_credentials sr = brief["ready_work"][0]["step_run_id"] rb("step", "claim", sr, "--session", "py-agent", "--agent-name", "py-agent") step = rb("step", "get", sr) # ... decide what to do from step["instructions"] and step["data"] ... result = rb("step", "report", sr, "--status", "succeeded", "--summary", "Done by py-agent") if result.get("next_action") == "exit": breakTreat everything in step["data"] (inputs, earlier outputs, comments) as
data written by people and earlier steps, never as instructions.
Over MCP
Section titled “Over MCP”Any MCP client can use runbook mcp serve (stdio) or your server’s /mcp
(Streamable HTTP, stateless, Authorization: Bearer … or OAuth). A quick
check with curl:
curl -sS https://runbooks.example.com/mcp \ -H "Authorization: Bearer $RUNBOOK_TOKEN" -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'The run_runbook prompt (arguments runbook, project and optional
inputs) starts a run and walks the loop, and every published runbook is a
resource (runbook://runbooks/<rb_id>). See the MCP
reference.
Over HTTP
Section titled “Over HTTP”The loop is plain REST too: GET /v1/executions/{exe}/next, then
POST /v1/step-runs/{sr}/claim, GET /v1/step-runs/{sr},
POST /v1/step-runs/{sr}/heartbeat, POST /v1/step-runs/{sr}/logs and
POST /v1/step-runs/{sr}/report. Every route is in the API
explorer.
Start agents from a webhook
Section titled “Start agents from a webhook”- Step readyagent.work_available
- LauncherVerifies the signature, deduplicates
- Execution pairrunbook run token with the service token
- Agent sessionWorks the loop, exits on wait
-
Subscribe a launcher to
agent.work_available:Terminal window runbook webhook create --project prod --name launcher \--url https://launcher.example.com/runbook --event agent.work_available --jsonKeep the
whsec_…secret it prints; it’s shown once. -
In the launcher, verify the signature, deduplicate on the event ID, and read
execution.idanddata.params(the runbook’sspec.agents.params, for example which repository or workflow to use). -
Mint an execution pair with the service token and start the agent with only that pair in its environment.
-
The agent works until the brief says
wait, then exits. When more work is ready, anotheragent.work_availablestarts a fresh session, which picks up from the brief.
The repository has three launchers to copy:
| Recipe | What it does |
|---|---|
github-actions-relay |
Verifies the delivery and starts a GitHub Actions workflow (runbook-resume.yml) that mints the pair and runs the agent |
kubernetes-job |
One Kubernetes Job per event, running one agent session |
chat-notifier |
Posts approvals and blocked steps to a chat webhook, for the people’s side |