---
title: "Agent definition"
description: "Every field of an agent's YAML file or Markdown file."
canonical_url: "https://docs.oz0.ai/reference/agent-definition"
---
# 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](#a-markdown-agent)
whose front matter holds the same fields and whose body is the instructions. Like the manifest, it is read strictly.
See [Agents](https://docs.oz0.ai/build/parts/agents) for a guided tour.

```yaml [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

- [Identity, instructions and tools](https://docs.oz0.ai/reference/agent-definition/identity)
- [Models and placement](https://docs.oz0.ai/reference/agent-definition/models)
- [Limits and spend](https://docs.oz0.ai/reference/agent-definition/limits)
- [Judges and candidate selection](https://docs.oz0.ai/reference/agent-definition/quality)
- [Delegation and human decisions](https://docs.oz0.ai/reference/agent-definition/coordination)
- [History and recovery](https://docs.oz0.ai/reference/agent-definition/history)
- [Sandbox, data and retention](https://docs.oz0.ai/reference/agent-definition/security)

## A Markdown agent

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

```markdown [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](https://docs.oz0.ai/reference/plugin-manifest#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](https://docs.oz0.ai/reference/plugin-manifest/dependencies#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:`](https://docs.oz0.ai/reference/plugin-manifest/dependencies#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:

```text
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

<table>
<thead>
  <tr>
    <th>
      Tool
    </th>
    
    <th>
      Status
    </th>
    
    <th>
      Does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        oz.delegate
      </code>
    </td>
    
    <td>
      Works today
    </td>
    
    <td>
      Hands a task to an allowed agent and waits for its answer
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        oz.ask_user
      </code>
    </td>
    
    <td>
      Works today
    </td>
    
    <td>
      Asks a person a question and waits for the answer (<a href="https://docs.oz0.ai/agents/asking-people">
        Asking people
      </a>
      
      ); <code>
        oz.ask_human
      </code>
      
       is the same tool under its old name
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        oz.report_usage
      </code>
    </td>
    
    <td>
      Accepted by lint; planned
    </td>
    
    <td>
      Reports the cost of a service the plugin called itself, so it lands on the job
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        oz.remaining
      </code>
    </td>
    
    <td>
      Works today, for harness and ACP sessions
    </td>
    
    <td>
      Reads 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 (<a href="https://docs.oz0.ai/build/parts/contracts-and-limits/budgets#what-the-agent-sees-of-its-spend">
        What the agent sees
      </a>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        oz.wait_for_event
      </code>
    </td>
    
    <td>
      Works today, for Pydantic AI, <code>
        openai-agents
      </code>
      
       and ACP harness agents
    </td>
    
    <td>
      Waits, durably, for an event of an <a href="https://docs.oz0.ai/build/parts/event-sources">
        event source
      </a>
      
      , such as CI finishing on a pull request, and reads it as outside text (<a href="https://docs.oz0.ai/agents/waiting-for-events">
        Waiting for events
      </a>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        oz.fail
      </code>
    </td>
    
    <td>
      Works today, for Pydantic AI, <code>
        openai-agents
      </code>
      
      , ACP and JSON-lines harness agents
    </td>
    
    <td>
      Ends the job as failed with one of the agent's <code>
        failures:
      </code>
      
       kinds and a message in its own words (<code>
        kind
      </code>
      
      , <code>
        message
      </code>
      
      ); any other kind ends it as <code>
        undeclared
      </code>
      
      . Its caller reads the kind, the flags and the message (<a href="https://docs.oz0.ai/build/parts/contracts-and-limits/failures#failure-kinds">
        failure kinds
      </a>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        oz.quarantine
      </code>
    </td>
    
    <td>
      Works today, for Pydantic AI agents
    </td>
    
    <td>
      Runs 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 (<code>
        output_schema
      </code>
      
      : booleans, enums, bounded numbers, identifiers; no free text); a fitting answer does not taint this job (<a href="https://docs.oz0.ai/govern/taint-and-labels/quarantine#the-quarantine-child">
        Taint and labels
      </a>
      
      ). It counts against <code>
        delegation.max_depth
      </code>
      
       and <code>
        max_children
      </code>
      
       as a delegation does
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        oz.skill
      </code>
    </td>
    
    <td>
      Works today, given to an agent that has <a href="https://docs.oz0.ai/build/parts/skills">
        skills
      </a>
      
      , not listed
    </td>
    
    <td>
      Reads 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
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        oz.propose_skill
      </code>
    </td>
    
    <td>
      Works today, given by <code>
        skills.propose
      </code>
      
      , not listed
    </td>
    
    <td>
      Proposes a skill (name, description, body, files) as a changeset of that skill's folder, which a person approves before a draft pull request opens (<a href="https://docs.oz0.ai/build/parts/skills/usage-and-proposals#skills-an-agent-proposes">
        Skills an agent proposes
      </a>
      
      ); one a job; never applied by the agent
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        oz.read_result
      </code>
    </td>
    
    <td>
      Works today, given to every agent that lists a plugin function and whose results may be offloaded, not listed
    </td>
    
    <td>
      Reads part of a tool result that was too large to show the model: <code>
        ref
      </code>
      
       from its stub, and a <code>
        section
      </code>
      
       (a heading, a top-level key or an item such as <code>
        [3]
      </code>
      
      ), a <code>
        range
      </code>
      
       of lines (<code>
        120-180
      </code>
      
      ), a <code>
        query
      </code>
      
      , a <code>
        view
      </code>
      
       and a <code>
        budget
      </code>
      
       (<a href="https://docs.oz0.ai/build/parts/tools/results-and-files#large-results">
        large results
      </a>
      
      ); only the job tree that produced the result may read it
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        oz.evidence
      </code>
    </td>
    
    <td>
      Works today, given to every agent of a plugin that declares <a href="https://docs.oz0.ai/reference/plugin-manifest/data#reads">
        <code>
          reads: [results]
        </code>
      </a>
      
      , not listed
    </td>
    
    <td>
      Reads, 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 <code>
        plugin
      </code>
      
      , <code>
        agent
      </code>
      
      , <code>
        since
      </code>
      
       (at most 90 days), <code>
        kinds
      </code>
      
      , <code>
        limit
      </code>
      
       and <code>
        page_token
      </code>
      
      ; answered with the permissions of the person who granted it, and audited as <code>
        run.evidence_read
      </code>
      
       (<a href="https://docs.oz0.ai/improve/evidence-for-agents">
        Evidence for agents
      </a>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        oz.find_tools
      </code>
      
      , <code>
        oz.call_tool
      </code>
    </td>
    
    <td>
      Works today, given by <code>
        tool_loading: lazy
      </code>
      
      , not listed
    </td>
    
    <td>
      Search the functions the agent may call now, and call one by name, as the real function's call (<a href="https://docs.oz0.ai/build/parts/agents#lazy-tool-loading">
        lazy tool loading
      </a>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        oz.report_outcome
      </code>
    </td>
    
    <td>
      Works today, for Pydantic AI agents
    </td>
    
    <td>
      Records a downstream result of a finished job of this plugin, such as whether its pull request was merged: <code>
        job
      </code>
      
      , <code>
        outcome
      </code>
      
       (<code>
        success
      </code>
      
       or <code>
        failure
      </code>
      
      ), <code>
        name
      </code>
      
       and an optional <code>
        detail
      </code>
      
      ; once per name per job, within 14 days of the job's end. A rollout counts the failures per version (<a href="https://docs.oz0.ai/improve/outcome-checks/rollouts#downstream-results">
        Downstream results
      </a>
      
      )
    </td>
  </tr>
</tbody>
</table>


## Sitemap

See the full [sitemap](https://docs.oz0.ai/sitemap.md) for all pages.
