> ## Documentation Index
> Fetch the complete documentation index at: https://graph.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent files

> The field reference for agent YAML files, where they live, and how built-ins are overridden

An agent file defines one named agent: what it's for, which model it runs on, which tools it may call, which other agents it can use, and its system prompt. graph ships built-in agents, and a file with the same name replaces a built-in everywhere it's used.

```yaml theme={null}
version: 1
name: search_bot
description: Answers questions about the team's work by searching Linear and the repo.
model: chat
tools: ["linear__*", user__repo_grep]
subagents: [chat]
handoffs: [chat]
system_prompt: |
  You answer questions about what the team is working on.
  Current date and time: {{session.date}}
  {{session.user}}
```

## Fields

| Field | Required | Type | Notes |
| - | - | - | - |
| `version` | no | integer | the [file version](/reference/file-versions) the document is written in; omitted means `1`. Files graph writes always carry it |
| `name` | yes | string | starts with a lowercase letter; lowercase letters, digits, and `_` only |
| `description` | yes | string | what the agent is for, written for the agents and people choosing it |
| `model` | yes | string | a [model role](/models/models-and-providers#roles), standard or custom |
| `tools` | yes | list of patterns | catalog tools the agent may call, as exact names or `*` globs (`linear__*`). `[]` means none and `["*"]` means the whole catalog. Plan step names (`map`, `exit`, …) and the generated `agent__` and `transfer_to_` names aren't allowed here |
| `subagents` | no | list of agent names | agents this one can run as a subagent (`agent__<name>`), each in its own fresh context. Listing the agent's own name lets it run a fresh copy of itself |
| `handoffs` | no | list of agent names | agents this one can hand the conversation to (`transfer_to_<name>`), in [`chat` and `ask`](/using/chat-and-ask#agents). An agent can't hand off to itself. Handing back needs no entry: an agent that was handed the conversation gets `transfer_back` |
| `input_schema` | no | JSON Schema | typed input when the agent runs as a subagent. Without it, a subagent call takes `{prompt}`. Must be an object schema with a `description` on every property |
| `output_schema` | no | JSON Schema | typed output when the agent runs as a subagent. Without it, the call returns the agent's final reply as `{result}`. Must be an object schema |
| `max_iterations` | no | integer ≥ 1 | a cap on model rounds. Omitted means no cap when the agent runs as a subagent; in a conversation, `[settings].max_agent_iterations` applies |
| `system_prompt` | yes | template | the agent's instructions, rendered with the [template language](/reference/plans/template-language) |

Unknown keys are a load error that names the key. The two schemas are independent: an agent may declare either, both, or neither.

## Prompt templates

`system_prompt` can reference two roots, and nothing else:

| Root | Values |
| - | - |
| `rules.*` | shared prompt sections graph maintains: `rules.control_steps` (how to use plan control steps), `rules.templating` (the plan template language), `rules.tool_format` (the user tool file format) and `rules.agent_format` (this file format) |
| `session.*` | `session.date` (the current date and time) and `session.user` (the `[user]` name and context from config) |

Inserted text is never parsed again, so a section that contains template syntax arrives intact. The template language has no escape for literal braces, so a prompt can't contain an example like `{{E0.values}}` directly. Reference `{{rules.templating}}` instead, which carries the template rules with their examples.

## Where agents come from

graph loads agents in layers. A later layer replaces an earlier agent with the same name, as a whole file — fields aren't merged.

1. **Built-in** agents, compiled into the binary.
2. **Global** agents in `~/.config/graph/agents/*.yaml`.
3. **Project** agents in `./.graph/agents/*.yaml`.

Two files with the same name in one directory are a load error. The built-in `chat` agent is graph's default general assistant. It can call any catalog tool and run copies of itself as subagents. The built-in `tool_drafter` and `agent_drafter` agents [write user tools and agents with you](/using/chat-and-ask#drafting-tools-and-agents). The [workbench](/workbench/plan-workbench#the-workbench-agents) adds four more built-ins (`front_desk`, `plan_drafter`, `plan_loader`, `plan_editor`) and its own versions of `tool_drafter` and `agent_drafter` that work in the drafting pane, which `graph agents` lists and shows like any other.

## Checks

`graph agents validate` checks every agent, or one file against the others:

* every name under `subagents` and `handoffs` is a defined agent;
* subagents don't form a cycle, except an agent listing itself;
* `tools` patterns, the schemas, and the prompt template are well formed, and the prompt references only `rules.*` and `session.*`.

## Commands

```text theme={null}
graph agents list [--json]
graph agents show <name> [--json]
graph agents validate [<path>] [--json]
graph agents migrate <path> [--json]
```

`show` prints an agent's effective file with its current `version`, the starting point for customizing a built-in: copy it to `./.graph/agents/<name>.yaml` and edit. `list` also shows the workbench's own agents (`front_desk`, `plan_drafter`, `plan_loader`, `plan_editor`), marked workbench only: they run in `graph wb`, not in `graph chat`, `graph ask --agent` or a plan step. See the [CLI reference](/reference/cli#graph-agents).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.