Reference
Agent definition
Every field of an agent's YAML file.
An agent definition is a YAML file listed under agents: in the manifest. Like the manifest, it is read strictly. See Agents for a guided tour.
agents/reviewer.yaml
name: reviewer
description: Reviews pull requests.
runtime: pydantic-ai
model:
primary: anthropic/claude-sonnet-5-5
fallback: [anthropic/claude-haiku-4-5]
instructions: prompts/reviewer.md
tools: [github.get_pr, github.comment, oz.delegate]
input_schema: schemas/review-input.json
output_schema: schemas/review.json
requires:
labels: {gpu: "true"}
limits:
max_steps: 20
max_tokens: 200000
timeout: 10m
max_cost_usd: 2.0
delegation:
allow: [explainer]
max_depth: 1
max_children: 3
Fields
name
string required
Lowercase letters, digits and dashes. Unique per tenant; jobs address the agent by it, on the task queue
agent.<name>.description
string
What the agent does. Agents that may delegate to this one see it.
runtime
string required
pydantic-ai (works today), harness:<name> (works today, with a harness plugin) or openai-agents (planned).model.primary
string
The model, as
<provider>/<model>, for example anthropic/claude-sonnet-5-5. Required unless the runtime is a harness.model.fallback
string[]
Models tried in order when the primary fails.
instructions
string
The system prompt: a path to a file in the plugin.
tools
string[]
<tool>.<function> names from the tenant's plugins, and built-ins. A tool from another plugin is a warning, since that plugin must be installed too.input_schema
string
A path to a JSON Schema file. A job whose input does not match fails with
InvalidInput before the agent starts.output_schema
string
A path to a JSON Schema file. The model answers in that structure; a non-matching answer goes back to it, at most twice.
requires.labels
map
Labels a node must have to run the agent.
limits.max_steps
integer
Model calls per job. Default 50.
limits.max_tokens
integer
Input plus output tokens per job.
limits.timeout
duration
How long a job may run, such as
90s, 10m or 1h30m.limits.max_cost_usd
number
The default budget of the agent's jobs, in US dollars, for a job and every job it delegates to.
run --budget overrides it for one job. Unset means no budget.delegation.allow
string[]
Agents
oz.delegate may start.delegation.max_depth
integer
How deep a chain of delegations may go. Unset means 1.
delegation.max_children
integer
Delegations per job. Unset means no limit.
harness
map
Options for the harness, passed on as they are, for agents with
runtime: harness:<name>. See Harnesses for the Claude Agent SDK's. requires_approval lists the harness's tools whose calls each wait for a person's approval, for a harness that asks before each call.Built-in tools
| Tool | Status | Does |
|---|---|---|
oz.delegate | Works today | Hands a task to an allowed agent and waits for its answer |
oz.ask_human | Accepted by lint; planned | Asks a person and waits for the answer |
oz.report_usage | Accepted by lint; planned | Reports the cost of a service the plugin called itself, so it lands on the job |