Agents
An agent is a YAML file in a plugin, listed under agents: in the manifest (a file, or a folder of them). Each agent runs as AgentWorkflow on the task queue agent.<name>, on the nodes that have the plugin and match its labels.
name: reviewer # unique per tenant; jobs address agents by name
description: Reviews pull requests. # shown to agents that may delegate to this one
runtime: pydantic-ai
model:
primary: anthropic/claude-sonnet-5-5
fallback: [anthropic/claude-haiku-4-5] # tried in order when the primary fails
instructions: prompts/reviewer.md # the system prompt, a path in the plugin
tools: [github.get_pr, github.comment, oz.delegate]
input_schema: schemas/review-input.json # optional JSON Schema for the job's input
output_schema: schemas/review.json # optional JSON Schema for the answer
requires:
labels: {gpu: "true"} # only nodes with these labels run it
limits:
max_steps: 20 # model calls per job (default 50)
max_tokens: 200000 # input plus output tokens per job
timeout: 10m # s, m or h
delegation:
allow: [explainer] # agents oz.delegate may start
max_depth: 1 # how deep a chain of delegations may go
max_children: 3 # delegations per job
Runtime
runtime says how the agent runs:
| Runtime | How it runs | Status |
|---|---|---|
pydantic-ai | A Pydantic AI agent with Temporal durability: the loop is workflow code and every model call is an activity | Works today; the default |
harness:<name> | A whole session of an agent harness, such as harness:claude-agent-sdk, run by a harness plugin, with options under harness:. See Harnesses. | Works today |
openai-agents | The OpenAI Agents SDK | Planned |
Model
Models are named <provider>/<model>: anthropic/claude-sonnet-5-5, openai/<model>. Calls go through the node's local LLM proxy to the edge's gateway, which adds the tenant's key. Nodes never hold provider keys. fallback models are tried in order when the primary fails. See Models and keys.
Tools
tools lists <tool>.<function> names from the tenant's plugins, and built-ins:
| Built-in | What it does |
|---|---|
oz.delegate | Hands a task to an agent in delegation.allow and waits for its answer. See Delegation. |
An agent can call only the tools it lists. Tools run on the job's home node unless their affinity is any.
Contracts
input_schema: a job whose input does not match fails before the agent starts, withInvalidInput. With an input schema, the job's input is JSON.output_schema: the model answers in that structure, and an answer that does not match goes back to it with the reason, at most twice.
Schemas are JSON Schema files in the plugin. See Contracts and limits.
Limits
max_steps, max_tokens and timeout end the job when reached. The platform enforces them; the model cannot ignore them.
Where it runs
requires.labels limits the agent to nodes with those labels. The catalog shows which nodes are ready: orchestrator-zero catalog.
Every field
See the agent definition reference.