Agent builder guide

Building teams of controlled agent workers is the product's core differentiator. On the CLI and MCP path you do the technical setup directly: you author the agent's contract and submit it as structured data, and the server validates and persists it — it does not re-synthesize it from free text. Read the exact contract of any command first with command.describe (rost command schema agent.create_custom), which returns the JSON Schema and a validated worked example.

The full setup sequence

1. Seat — the agent occupies a seat in the Responsibility Graph (a function, not a person). Create or pick the seat first. 2. Steward — every agent needs a human steward chain (invariant: no orphan agents). Set steward_seat_id so the chain resolves to a human; without it the occupancy is blocked. 3. Job — what the seat owns. On agent.create_custom this is the operational answers (what it owns, what success looks like, what it must never do alone); for a strong contract, submit the full Charter directly via charter.update_draft (see the charter-authoring deep-dive). 4. Boundaries — the Charter's decision_authority (can-do / must-ask / never / escalate), escalation_rules, and budget. Conservative by default: send/spend/irreversible actions are approval-gated or escalated. 5. Tools — pick from the discoverable catalog (rost tools list); each tool has a default scope tier and access policy. Connect or decline via agent.configure_tools. The catalog is configuration the builder reads — the tools do not execute yet (real tool execution is a separate, deferred capability). 6. Credentials — a tool that needs access declares a credential-ingress request (provider, scope, secret name). The secret itself flows through the vault-backed ingress command as a vault ref — never paste a secret into a builder command. 7. Operating instructions — the runtime composes the agent's context from its Charter; you do not write a system prompt. 8. Model — select the structured model config (see below). 9. Heartbeat — set the schedule (schedule_cron) for a recurring agent; a live scheduled agent must keep a steward chain. 10. Dry-run — agent.run_dry_run rehearses in sandbox after the manifest is signed; it is ungated by human approval but requires a signed manifest. 11. Go-live — agent.go_live is human_required. Prepare everything and surface the go-live to a human; never go live on a human's behalf.

Choosing the model (structured config)

The agent's model is a structured object, not a bare string:

{ "provider": "anthropic", "model": "claude-sonnet-4-6", "effort": "medium" }

• provider is "anthropic" (Claude-only for now; the field exists so other providers can be added later).
• model is a model id. Pick by the work the seat does — a triage tier for cheap, high-volume classification; a balanced tier for most seats; a complex tier for judgment-heavy reasoning; the hardest tier for long-horizon agentic work. The builder offers tier shortcuts (triage, balanced, complex, hardest) that map to a current Claude id, so you never hardcode a stale one.
• effort (low → max) trades thoroughness for cost/latency. Low for triage; high or xhigh for the hardest agentic seats.

On the CLI, rost agent create --custom --seat-id <id> --model balanced --effort medium …, or set it later with rost agent setup answer --seat-id <id> --model complex. The model cannot change after the agent is live.

Access tiers

When you connect a tool, you grant a scoped permission in the Charter's manifest. The tiers, from least to most authority:

• read-only — the agent reads source data; it never writes, sends, or commits.
• draft-only — the agent produces drafts a human reviews; it never sends or commits.
• send-with-approval — the agent can write/send/commit, but every such action is approval-gated (the always_ask policy — ROST's escalation gate).
• full — unrestricted within the tool's domain. Rare and deliberate; reserve it for low-risk internal tools.
• custom — a scope you state explicitly in the manifest entry when none of the tiers fit.

Conservative by default: anything beyond read/draft defaults to always_ask. Loosening a tool to always_allow is a deliberate human act, not a default.

What good looks like per seat archetype

• Finance clerk (AP/AR). Tight read + draft scopes (ap.invoices.read, accounting.bills.draft_update); posting and payment escalate; measurables track drafted-on-time and discrepancies caught. Balanced model.
• Inbox / scheduling assistant. gmail.read + draft + calendar.propose_hold; sends and confirmed meetings are approval-gated; sensitive messages escalate. Triage or balanced model.
• Research / SDR. web.research + crm.contacts.draft_update (draft only); outreach and paid data escalate. Balanced model.
• Reviewer / QA. Read release artifacts + draft issues; release approval and production changes escalate. Complex model for judgment.

The full JSON shape

The Charter you submit for an agent seat is the full Charter document (see the charter-authoring deep-dive for every field). This is the document charter.update_draft validates:

{
  "payload_version": 1,
  "purpose": "AP intake clerk: draft accounts-payable invoice entries from inbound vendor emails for human review.",
  "accountabilities": [
    { "title": "Draft every inbound invoice", "description": "Convert each inbound vendor invoice into a draft AP entry with correct vendor, amount, and GL coding within one business day." }
  ],
  "decision_authority": {
    "autonomous": [
      { "action": "Draft AP entries and propose GL coding", "condition": "Allowed when the vendor is known and the amount is within the standard range.", "rationale": "Drafting is reversible and human-reviewed.", "unanswered_boundary": false }
    ],
    "approval": [
      { "action": "Post an invoice or send a vendor message", "condition": "Require human approval before posting or sending.", "rationale": "Posting and sending are durable, money-moving actions.", "unanswered_boundary": false }
    ],
    "escalate": [
      { "action": "Unknown vendor, payment over the threshold, or suspected duplicate", "condition": "Always escalate to the Steward before acting.", "rationale": "Conservative default for ambiguous or financial exposure.", "unanswered_boundary": true }
    ]
  },
  "escalation_rules": [
    "Escalate any invoice over $5,000 or from a vendor not already in the ledger."
  ],
  "measurables": [
    { "name": "Invoices drafted within one business day", "target": "100%", "cadence": "weekly", "source": "agent" }
  ],
  "permission_manifest": [
    { "tool": "ap.invoices.read", "scope": "Read inbound invoices and the vendor ledger.", "granted": true, "rationale": "Needed to draft entries from source invoices." }
  ],
  "budget": { "monthly_usd": null, "approval_required_over_usd": 0, "notes": "No autonomous spend; any spend requires Steward approval until a budget is set." },
  "unanswered_boundaries": ["Approval threshold for auto-posting"],
  "seat_type_recommendation": { "recommendation": "agent", "rationale": "High-volume, rule-bound, fully reviewable work suits a draft-and-confirm agent under a human Steward.", "confidence": 0.8 }
}

The model config shape

{ "provider": "anthropic", "model": "claude-sonnet-4-6", "effort": "medium" }

Show your human a review

When you have built the setup, render a clean markdown card for your human before go-live: rost agent show --seat-id <id> --markdown (or rost charter show --seat-id <id> --markdown / rost compass show --markdown). The card composes the setup, model, steward, tools, and Charter into one skimmable readout. Then surface the go-live for a human to approve — go-live is human-gated and a seat token never goes live on its own setup.