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.

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 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, 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. 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

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. The workbench 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

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.