> ## 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 file

> One named agent, in `./.graph/agents/` or `~/.config/graph/agents/`. A file with a built-in agent's name replaces that agent everywhere it runs.

| File type | Location |
| - | - |
| YAML | `./.graph/agents/<name>.yaml` (project) `~/.config/graph/agents/<name>.yaml` (global) |

Unknown keys are a load error. For completion in your editor, start the file with `# yaml-language-server: $schema=https://raw.githubusercontent.com/tylerdavis/graph/main/docs/schemas/agent.schema.json`.

## Fields

**version** `integer`

The file version the document is written in. Omitted means 1; files graph writes always carry it.

**name** `string` *required*

Starts with a lowercase letter; lowercase letters, digits and `_` only. Other agents and plan steps call it as `agent__<name>`.

**description** `string` *required*

What the agent is for, written for the people and agents choosing it.

**model** `string` *required*

The model role the agent runs on, standard (`chat`) or custom.

**tools** `string[]` *required*

Catalog tools the agent may call, as exact names or `*` globs such as `linear__*`. `[]` means none and `["*"]` means the whole catalog. Control step names and generated `agent__` and `transfer_to_` names aren't allowed.

**subagents** `string[]`

Agents this one can run as a subagent, each in a fresh context, called as `agent__<name>`. Listing the agent's own name lets it run a fresh copy of itself. Nesting is capped at 3.

**handoffs** `string[]`

Agents this one can hand the conversation to, called as `transfer_to_<name>`. An agent can't hand off to itself, and an agent handed the conversation gets `transfer_back` without listing it.

**input\_schema** `object`

Typed input when the agent runs as a subagent or plan step. An object schema with a `description` on every property. Without it, a call takes `{prompt}`.

**output\_schema** `object`

Typed output when the agent runs as a subagent or plan step. An object schema. Without it, a call returns the final reply as `{result}`.

**max\_iterations** `integer`

A cap on model rounds. Omitted means no cap as a subagent; in a conversation, `[settings].max_agent_iterations` applies.

**system\_prompt** `string` *required*

The agent's instructions, rendered with the template language. It can reference `{{session.date}}`, `{{session.user}}` and the `{{rules.*}}` blocks (`control_steps`, `templating`, `tool_format`, `agent_format`), and nothing else.

```yaml Example theme={null}
version: 1
name: release_notes
description: Answers questions about what shipped, from the repo's commit history.
model: chat
tools:
- plan__weekly_changes
- github__tool__git_log
subagents:
- chat
system_prompt: |
  You answer questions about what shipped in this repository.
  Current date and time: {{session.date}}
```


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