Agents

An agent is a single AI worker — one Markdown file whose YAML frontmatter configures it and whose body becomes its system prompt.

What is an agent

An agent is the smallest unit of work in rupu: a narrow, single-purpose AI worker. Each agent lives in one Markdown file. The file has two parts — a block of YAML frontmatter that tells rupu how to run the agent (which provider, which model, which tools, what it is allowed to do), and a Markdown body that is sent verbatim to the model as its system prompt.

Good agents are narrow, explicit, and testable. A well-scoped agent answers six questions clearly: what job it owns, what tools it may use, what sequence it should follow, what counts as done, what it must not do, and what shape the final answer should take. When several specialists, review boundaries, or fix loops are involved, reach for a workflow instead of one giant prompt.

The agent file

An agent is a Markdown file with YAML frontmatter. The frontmatter (between the opening and closing --- lines) tells rupu how to run the agent; everything after the closing --- is the system prompt. rupu parses the frontmatter with strict unknown-field rejection — a misspelled key fails fast rather than being silently ignored. A rupu release older than a field also refuses an agent that sets it, so upgrade remote hosts before adding new keys to agents they run.

Agent files resolve from two locations:

• ~/.rupu/agents/<name>.md — global agents (personal utilities).
• <project>/.rupu/agents/<name>.md — project-local agents (checked into the repo).

Project-local agents shadow global agents by name:. Shadowing is all-or-nothing — rupu does not merge frontmatter or prompts. rupu agent list shows whether each agent comes from project or global scope, and rupu agent validate <name> / --all checks that an agent file parses, names only tools rupu knows and only skills that are installed.

Frontmatter fields

Advanced frontmatter

The fields above cover most agents. The ones below tune reasoning, token limits, findings, failure recovery, skills, messaging and provider-specific behavior. All are optional; leave them out and rupu uses the discovered or configured default.

Provider accounts

provider: names an account, not only a vendor. A bare vendor name (anthropic, openai, …) is its own account; to keep two identities for one vendor, log in to a named account with --kind and point the agent at it, e.g. provider: anthropic-work. auth: (api-key or sso) then picks between that account’s credentials when it holds both. See Providers → Accounts.

Reasoning, context & token limits

Limits come, in order, from the agent's pins, a [[providers.<name>.models]] entry in config.toml, the provider's live model list (cached for 1 hour in ~/.rupu/cache/models/), else unknown. Every run writes a model_limits notice to its transcript saying what it will use and where each value came from. Pin maxTokens / contextWindowTokens only to override what rupu discovers — see Reliability → Model limits discovery.

Coverage & findings

See Coverage and Findings.

Fallbacks

fallbacks: is an ordered list of models to try when the agent’s own model can’t give a usable reply or the provider fails the request (a refusal, repeated truncation, an overloaded provider). Each entry has a model and an optional provider; without one, the entry means the provider the run started on. Unknown keys inside an entry are an error. The list replaces [recovery].fallbacks from config.toml for this agent (it is not merged), and fallbacks: [] means no fallbacks. A cross-provider entry sends the whole conversation to that provider, so list one only when the run's data may go there. See Reliability → Configuring fallbacks.

fallbacks:
  - model: claude-sonnet-5-5        # same provider as the agent
  - provider: openai-codex          # another provider
    model: gpt-5.6-cyber

Skills

skills: and preloadSkills: grant the agent Agent Skills installed under ~/.rupu/skills/ or the project's .rupu/skills/. Installing a skill gives it to no agent: an agent without these keys has no skills, no skill index and no skills.load tool.

skills: [pdf, code-review]     # listed in the prompt; the model loads one when a task matches it
preloadSkills: [house-style]   # its whole body is in the system prompt from the start

A run binds each name once, so granting the same name from both layers (global:x and project:x, or * and project:* over a name in both) is an error. An unknown name, an invalid skill or a malformed entry fails the agent's load with a did-you-mean, and rupu agent validate reports the same.

A granted skill reaches the run as:

• The index. Each skill in skills: is listed under ## Skills in the system prompt, after the agent's body and any ## Run target, with its description. The model calls skills.load with a name to get the skill's instructions, base directory and file list.
• Preloaded bodies. Each skill in preloadSkills: is rendered in full under ## Skill: <name>, ahead of the index, and is not listed in it.
• Its files. read_file, grep, glob and ast_grep may read under a granted skill's directory even outside the workspace; write_file and edit_file may not. A skill's scripts run through bash, under the run's permission mode.

A skill never widens the agent's tools: grant or its permission mode. A child started with dispatch gets its own agent file's skills, never its parent's. A session fixes its agent's skills when it starts (see Sessions → Skills).

Messaging

Every run with a message space is offered board.claim, board.release, board.post, board.read and msg.send by default. messaging: false turns them off for this agent wherever it runs: as a standalone run, a workflow step, a sub-agent, a session's agent or an agentiflow's lead or unit. The run is still in its space, so the operator and its children reach it, and every child it launches has messaging off too. A file that sets messaging: false and also names a messaging tool in tools: (by name, alias or board.* / msg.*) fails to load. See Messaging.

Anthropic-only fields

Example

---
name: deep-auditor
description: Long-running audit agent with tuned limits, a skill and a fallback chain.
provider: anthropic-work        # a named account
auth: sso
model: claude-sonnet-4-6
tools: [read_file, grep, glob]
permissionMode: readonly
effort: high
maxTokens: 32000
compactAtPercent: 70
concerns:
  - include: secrets-in-source
findingsProfile: summary
skills: [code-review]
messaging: false
fallbacks:
  - model: claude-sonnet-5-5       # same account
  - provider: openai-codex       # another provider
    model: gpt-5.6-cyber
anthropicContextManagement: tool_clearing
---

Audit the repository for hard-coded secrets and record each one you find.

A complete example

This is the code-reviewer agent that ships as a rupu template — a read-only reviewer that can inspect a local file, a diff, or a pull request and return concise findings.

---
name: code-reviewer
description: Read a file, diff, or PR and return concise textual findings.
provider: anthropic
model: claude-sonnet-4-6
tools: [read_file, grep, glob, scm.prs.get, scm.prs.diff]
maxTurns: 12
permissionMode: readonly
---

You are a code reviewer.

If the prompt contains a PR reference, use the SCM tools to inspect the PR metadata and diff.
If the prompt names local files or includes a diff, review that directly.

Focus on:
- correctness bugs
- missing edge-case handling
- unclear or brittle structure
- missing tests where behavior changed

Return either:
- `no issues`
- or a short bulleted list ordered by severity

Do not edit code.

Note the shape: the frontmatter pins a provider and model, declares the smallest useful tool set, and runs readonly so a reviewer can never mutate the thing it is reviewing. The body gives the agent a role, a process, and an explicit output contract.

Tools & permissions

tools: is the agent's tool grant: what its model may call. Each entry is one of:

There are no other wildcards (scm*, coverage_* are errors). Authority is never implied by *. board.directive and board.retract let one agent direct the others, so * leaves them out: an agent gets them only by naming them (or board.*), and an agentiflow lead gets them from its origin grant.

An unknown name is an error. An agent whose tools: names a tool rupu doesn't know fails to load — rupu run, a workflow step and a sub-agent dispatch all refuse it — with a suggestion when a known name is close. rupu agent validate catches it ahead of time.

A tool is offered only where it works. The connector tools (scm.*, issues.*, github.*, gitlab.*) need configured SCM connectors, coverage.* a concerns: block, assets.mark an engagement profile, the board and mailbox tools a message space, goal.* and budget.status an agentiflow lead, and workflows.generate a provider to author with. dispatch and join work in every agent run, and so do the roster tools (agents.list, agents.get, workflows.list, workflows.get, catalog.search). A wildcard silently leaves out a tool the run can't serve; a tool named exactly that the run can't serve is left out too, and the run says so with a tool_unavailable notice in its transcript.

Omitting tools: gives the default grant: the core tools, the launch pair and every connector tool (core.*, dispatch, join, scm.*, issues.*, github.*, gitlab.*). For reusable agents an explicit tools: is better than the default.

Ambient grants. The run's context adds tools the agent didn't list: a concerns: block adds the coverage tools and findings.report; an active engagement profile adds findings.report and assets.mark; a message space adds the default messaging tools; an agentiflow lead's or unit's origin adds its coordination tools. A run granted dispatch (by any route, a legacy name included) also gets join. None of this is hidden: every run's transcript opens with a tool_grant event listing exactly the tools the model was offered and why, and every call is audited (tool_audit).

Tool names

Tools are named namespace.verb (findings.report, coverage.mark); the core fs/shell tools stay unqualified. Earlier names remain accepted forever, in tools: and when a model calls them, as aliases:

Structural search with ast_grep

ast_grep matches code by its syntax tree rather than its text, so a pattern finds every call site or definition however it’s formatted. It runs the ast-grep binary, which must be on PATH as ast-grep (brew install ast-grep or cargo install ast-grep); without it every call returns an “ast-grep not found” error. It is a read tool: readonly mode allows it. It takes a pattern, a lang (required: any language ast-grep supports, e.g. rust, python, typescript, tsx, javascript, go, java, c, cpp) and an optional path inside the workspace.

A pattern is ordinary code in the target language, with metavariables where anything may appear:

The agent sees one path:line:col: match line per hit (1-based, workspace-relative); no matches is empty output, not an error, while a malformed pattern or a bad path surfaces ast-grep's diagnostic as the error. Under a concerns: block, each matched file is recorded in the coverage ledger like a grep hit. Each call also records up to 200 matches as structured data (file, range, matched text and every metavariable's capture), which the control plane uses to show a source slice and a syntax-tree preview per match.

Permission modes

permissionMode is ask, bypass or readonly. Every tool declares one effect, and the mode decides each call from the effect alone — never from the tool's name, so a new tool is gated correctly the day it lands:

• A child never has more than its parent. A child of any kind runs at the more restrictive of the parent's mode and its own permissionMode; a readonly run's children are readonly whatever their frontmatter says, across a process boundary too.
• readonly still records findings. It means “no change to your workspace or the outside world”; rupu's own ledgers are bookkeeping, so a readonly reviewer can report, tag and verify findings.
• ask without an operator (a workflow step, a session turn, a flow, a detached run) cannot prompt, so it allows write/external calls and the transcript says so once with a permission_mode_degraded notice. An interactive rupu run in ask prompts; a non-TTY rupu run in ask is refused at startup, so pass --mode bypass or --mode readonly there.
• “Allow always” (a at the prompt) allows that one tool for the rest of the run, not every tool.

ask is the safest default for agents that edit code. Pass --mode readonly for unattended runs that must not change anything. The CLI --mode flag always overrides the value in the file.

Launching children

An agent can start other runs as tool calls in the middle of its own run, keep working while they run, and fold their results back into its context. This is composition at the agent layer — distinct from a workflow, which composes agents at the step layer. A writer agent can dispatch a reviewer mid-draft, revise against the findings, and carry on, without the workflow author fanning out at the YAML level.

Three tools drive it. The legacy names (dispatch_agent, dispatch_agents_parallel, run_workflow, generate_workflow) are aliases that keep their old behavior and output shapes.

• dispatch — start a child and return at once with {handle, kind, name, run_id, codename}; with wait: true the reply also carries the child's join entry.
• join — collect the results of handles dispatch returned (or every unjoined child when omitted), with a timeout_secs (default 300, at most 3600; 0 just looks) and until: all | any.
• workflows.generate {description} — write a new workflow under the run's generated/ directory, check it, and return {file, name, steps, inputs}. It does not start it: run it with dispatch {kind: "workflow", file}.

join returns one entry per child: handle, kind, name, run_id, codename, status (pending, running, done, failed, abandoned or interrupted) and, once it ended, success, output, error, cause, tokens and duration_ms. While a run has children it has not joined, each turn starts with a status block naming them, so the agent knows what is still out without polling. A workflow child is checked before anything starts: it parses, has no approval gate and no host: / distribute: step, every agent its steps run is one the caller may dispatch, and its inputs resolve.

Rules every kind shares

• Allowlist. The agents and workflows a run may start are its dispatchableAgents / dispatchableWorkflows. Inside an agentiflow the flow's pool applies, intersected with the declared lists when the agent has them. Either way the result is capped by what the parent may launch. Neither declared nor in a flow means none: dispatch is still offered, but a call fails with agent_not_dispatchable / workflow_not_dispatchable.
• Depth. A run you start is depth 0 and each child is one deeper. A run at depth 5 can't start a child (max_dispatch_depth_exceeded).
• Permission ceiling. A child runs at the more restrictive of the parent's mode and its own permissionMode. A sub-agent of an ask parent asks the parent's operator; a process child can't reach that prompt, so under an interactive ask parent it runs readonly, and under an unattended ask parent it runs ask unattended.
• Connector narrowing. A workflow step's actions: narrowing reaches the step's children, and a generated workflow may call a connector tool from an action: step only when the run that generates or starts it is offered that tool itself.
• Concurrency. At most [dispatch].max_concurrent_children (default 8) children of one run run at once; the rest wait as pending.
• Engagement and findings. Children run under the parent's engagement profiles; a child's findings profile comes from its own agent file.
• Usage. A sub-agent's calls are recorded in its parent's usage ledger. A process child keeps its own ledger and copies each call into the root run's ledger as a rollup, which the control plane's usage reports skip, so nothing is counted twice.

---
name: writer
tools: [read_file, edit_file, dispatch]    # join is implied by dispatch
dispatchableAgents: [security-reviewer, perf-reviewer]
dispatchableWorkflows: [release-checks]
---

Draft the change, then dispatch the reviewers on your diff.
Revise against their findings before you finish.

When the parent ends

A run's unjoined children are stopped when the run ends and recorded abandoned, and so is whatever they left below them. A workflow step that pauses, or a rupu run / rupu workflow run stopped by SIGTERM or SIGINT, stops them the same way but records each interrupted; when that run's conversation is continued (rupu workflow resume, rupu run --continue), the continued run takes on every child under the same handles — ended ones as they ended, the rest continued from their own records. Every launch is appended to the parent's children ledger, <RUPU_HOME>/runs/<run id>/children.jsonl, which join, the orphan reaper and the control plane's Children tab read. Each child gets a codename below its parent's (<parent>><role>#n), and a sub-agent can be continued by its sub_… id like any run.

Legacy launch names

The tools that predate dispatch keep working, in tools: and when a model calls them:

A model only sees dispatch, so a prompt written for an old name arrives as a dispatch call in the old shape. See MCP & tools for the tool surface and Workflows for step-layer composition.

Structured outputs

By default an agent returns free-form text. Two frontmatter fields tighten that when a downstream step or tool needs a predictable shape.

outputFormat: json is a hint — it asks the model to return JSON (describe the shape in the prompt too). On its own it is prompt-driven: nothing structurally guarantees the result parses or matches a particular schema.

outputSchema: goes further. Declare a JSON Schema inline in the frontmatter and, when outputFormat: json is also set, rupu hands it to Anthropic's structured-output mode (output_config.format = {type: "json_schema", schema: ...}), which returns a guaranteed schema-conforming object. Without outputFormat: json the schema has no effect; providers other than Anthropic ignore it.

---
name: security-reviewer
outputFormat: json
outputSchema:
  type: object
  properties:
    findings:
      type: array
      items:
        type: object
        properties:
          severity: { type: string, enum: [low, medium, high, critical] }
          title: { type: string }
          body: { type: string }
        required: [severity, title]
        additionalProperties: false
  required: [findings]
  additionalProperties: false
---

Audit the diff and return your findings.

With a guaranteed shape, downstream workflow steps can rely on those fields in their template expressions instead of defensively parsing free text.

Providers & models

rupu supports four LLM providers, each with two authentication modes (API key or SSO):

An agent picks its provider with provider: and its model with model:. Model ids are provider-specific and are not validated at parse time — an invalid id fails at runtime when the provider is called. When an agent omits model:, rupu uses the provider's default_model from config, else claude-sonnet-4-6; for stable project behavior, set model: per agent. rupu run --model / --provider override the file for one run.

Inspect the models rupu knows with rupu models list and refresh the cached model lists with rupu models refresh. Authenticate a provider before running an agent against it:

# API key (or pipe the secret on stdin)
rupu auth login --provider anthropic --mode api-key --key <secret>

# SSO
rupu auth login --provider anthropic --mode sso

Generate one from a description

Don’t want to hand-write the frontmatter? Describe the agent in plain language and let rupu draft it for you. create scaffolds the .md, with --describe a model drafts the definition, and the file opens in your editor to refine.

# scaffold + AI-draft an agent from a one-line brief
rupu agent create security-reviewer \
  --describe "A read-only reviewer that audits a diff for OWASP Top 10 issues and returns JSON findings"

# or scaffold an empty agent and edit it yourself (omit --describe)
rupu agent create my-agent

The same generate-from-a-description flow is available in the control plane’s authoring UI.

Running an agent

List and inspect the agents rupu can see, validate them, then run one:

# list every resolvable agent (project + global scope)
rupu agent list

# show one agent's resolved frontmatter and prompt
rupu agent show code-reviewer

# check every agent file in both layers (tools:, skills:, syntax)
rupu agent validate --all

# run an agent with a prompt
rupu run code-reviewer --prompt "Review the staged diff for correctness bugs"

Use --mode to override the file's permissionMode at run time — for example --mode bypass or --mode readonly in a non-interactive context. --skill / --preload-skill add skills to one run on top of the agent's own, and --no-messaging / --messaging-tool switch its messaging tools off or narrow them. Every run is recorded as a JSONL transcript you can replay later:

# inspect a recorded run
rupu transcript

Continuing a run

If a run stops before it finishes — a closed terminal, a killed process, a crash — pick it up where it left off instead of starting over. rupu rebuilds the conversation from the run's transcript, drops the turn that was in flight, and tells the agent it was interrupted. The run's command is restored too: its repo target and every flag it was launched with; a flag given on the continue replaces only its own setting. Run it from the same directory as the original run.

# continue an interrupted run
rupu run code-reviewer --continue <agent_run_id>

# continue any ended run with something new to do
rupu run code-reviewer --continue <agent_run_id> "now write the fix"

# a run that failed on a provider-side outcome (a refusal, say) can move to another model
rupu run code-reviewer --continue <agent_run_id> --model <model> [--provider <provider>]

A run that had already finished prints its recorded answer without calling the model; with a prompt it gets a new turn after its answer. A run that failed can't be continued bare — give the continue a prompt, or, when it failed on a provider-side outcome, a --model / --provider. The continued run also takes on the children the interrupted one launched. rupu run pause / rupu run resume act on workflow runs only; a standalone agent run has no pause boundary.