Reference

Agent definition

Every field of an agent's YAML file or Markdown file.

For: Plugin authors looking up agent fields.

An agent definition is a YAML file listed under agents: in the manifest, or one Markdown file whose front matter holds the same fields and whose body is the instructions. Like the manifest, it is read strictly. See Agents for a guided tour.

agents/acme-reviewer.yaml
name: acme-reviewer
description: Reviews pull requests.
runtime: pydantic-ai
model:
  primary: anthropic/claude-sonnet-5-5
  fallback: [anthropic/claude-haiku-4-5]
instructions: prompts/acme-reviewer.md
tools: [acme_github.get_pr, acme_github.comment, oz.delegate, web/oz0_web.fetch]  # bare: this plugin's; web's by address
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: [acme-explainer, docs/docs-writer]   # this plugin's agent, and plugin docs's by address
  max_depth: 1
  max_children: 3

Fields

A Markdown agent

An agent can be one Markdown file: YAML front matter holds its fields, and the body after it is its instructions.

triage.md
---
apiVersion: oz0/v1
description: Triage new issues and label them
model:
  use: default
input: text
output: text
tools:
  - github/oz0_github.get_issue
  - github/oz0_github.add_labels
---
You triage new issues. Read the issue, decide whether it is a bug, a question or a request, and label it.
  • The front matter takes the fields below, read strictly as the YAML form's, except instructions: the body is the instructions, so instructions: there is refused. An empty body is an error.
  • name may be left out, and is then the file's name without .md; set, it must be that name.
  • runtime may be left out in both forms, and is then pydantic-ai.
  • apiVersion: oz0/v1 is what tells an Orchestrator Zero agent from a Claude Code subagent, which has the same shape. A file on its own, in a folder without oz0-plugin.yaml, must say it: the folder then loads as a plugin of that one agent (A plugin that is one part). Inside a plugin it may say it, and must say oz0/v1.
  • In a plugin, list the file under agents:, or the folder it is in. A .md file in that folder without front matter, such as a README, is a note and is skipped. A Markdown agent is like any other: lint, inspect, the hub's facts, its card and evals see the same agent. Its prompt is the plugin's own, never untrusted input.

Other plugins' tools and agents

An agent names another plugin's part by its address, <plugin>/<part>, in every field that names one: tools, skills, delegation.allow, delegation.best_of.agents, colleagues.ask, outcome.reviewer, best_of.agents and conversation.continue_from (handoffs stay within the plugin). A bare name means a part of the agent's own plugin. The plugin in an address must be the agent's own or one its manifest lists under uses: (Addresses).

From v1.0 an agent reaches its own plugin's tools and agents and the built-ins oz.*, and another plugin's only when its plugin's uses: lists them and a tenant admin granted that at install. That holds for tools, delegation.allow (the oz.delegate tool offers only granted agents, on Pydantic AI and the OpenAI Agents SDK alike), outcome.reviewer, best_of.agents, colleagues.ask and the agent steps of flows, also when a step's agent is an expression.

A call that was not granted is not made, and the model reads why:

The call to github.merge was not made: it is a function of plugin github, and plugin pr-reviewer was not granted it: from v1.0 a plugin reaches another plugin's tools only when its uses: declares it and a tenant admin granted it.

A question to a colleague of another plugin that was not granted is not asked either, and the model reads why (asker may not ask triage: agent triage is plugin jira's, and plugin pr-reviewer was not granted it). The job checks against its plugin's grant as it is at each such call, not as it was when the job started, so a grant a tenant admin revokes while the job runs bites at its next call.

Each distinct refusal is audited once per job (uses.denied, went_on: true).

A reviewer or a best-of candidate that was not granted fails the job (UsesNotGranted), and so does anything the edge refuses: a child job or a tool call that only a modified node would send.

Built-in tools

ToolStatusDoes
oz.delegateWorks todayHands a task to an allowed agent and waits for its answer
oz.ask_userWorks todayAsks a person a question and waits for the answer (Asking people); oz.ask_human is the same tool under its old name
oz.report_usageAccepted by lint; plannedReports the cost of a service the plugin called itself, so it lands on the job
oz.remainingWorks today, for harness and ACP sessionsReads what the job has left: what its tree spent of its budget, the quota left when it may be shown, and the session's time; read-only, it costs nothing. An agent's own loop sees the same at the end of each model request (What the agent sees)
oz.wait_for_eventWorks today, for Pydantic AI, openai-agents and ACP harness agentsWaits, durably, for an event of an event source, such as CI finishing on a pull request, and reads it as outside text (Waiting for events)
oz.failWorks today, for Pydantic AI, openai-agents, ACP and JSON-lines harness agentsEnds the job as failed with one of the agent's failures: kinds and a message in its own words (kind, message); any other kind ends it as undeclared. Its caller reads the kind, the flags and the message (failure kinds)
oz.quarantineWorks today, for Pydantic AI agentsRuns this agent as a quarantine child that reads what this job should not, with no tool that can send data out, and answers only in a bounded contract (output_schema: booleans, enums, bounded numbers, identifiers; no free text); a fitting answer does not taint this job (Taint and labels). It counts against delegation.max_depth and max_children as a delegation does
oz.skillWorks today, given to an agent that has skills, not listedReads one of the agent's skills, or a file it links to, on the job's home node; another plugin's or an imported one's taints the job
oz.propose_skillWorks today, given by skills.propose, not listedProposes a skill (name, description, body, files) as a changeset of that skill's folder, which a person approves before a draft pull request opens (Skills an agent proposes); one a job; never applied by the agent
oz.read_resultWorks today, given to every agent that lists a plugin function and whose results may be offloaded, not listedReads part of a tool result that was too large to show the model: ref from its stub, and a section (a heading, a top-level key or an item such as [3]), a range of lines (120-180), a query, a view and a budget (large results); only the job tree that produced the result may read it
oz.evidenceWorks today, given to every agent of a plugin that declares reads: [results], not listedReads, read-only, what the jobs of a plugin it was granted came to: findings, failing and kept eval cases, refused approvals with their reasons, error groups, cost per run and scorecards, with plugin, agent, since (at most 90 days), kinds, limit and page_token; answered with the permissions of the person who granted it, and audited as run.evidence_read (Evidence for agents)
oz.find_tools, oz.call_toolWorks today, given by tool_loading: lazy, not listedSearch the functions the agent may call now, and call one by name, as the real function's call (lazy tool loading)
oz.report_outcomeWorks today, for Pydantic AI agentsRecords a downstream result of a finished job of this plugin, such as whether its pull request was merged: job, outcome (success or failure), name and an optional detail; once per name per job, within 14 days of the job's end. A rollout counts the failures per version (Downstream results)
Copyright © 2026