Agents

version: 1
name: release_notes
description: Writes release notes from the changes since the latest release.
model: chat
tools:
- plan__unreleased_changes
subagents:
- reviewer
system_prompt: |
  You write release notes for this repository. Before you write them, ask
  reviewer whether any change since the release is risky to ship.

version: 2
identifier: unreleased_changes
name: Unreleased changes
description: The commits since the latest release, each with a one-line release note.
steps:
- id: release
  tool_name: github__tool__gh_release
  input: {}
- id: commits
  tool_name: github__tool__git_log
  input:
    base: '{{release.tag}}'
    head: HEAD
- id: notes
  tool_name: map
  input:
    over: '{{commits.commits}}'
    concurrency: 4
    do:
    - id: files
      tool_name: github__tool__git_changed_files
      input:
        base: '{{item.sha}}~1'
        head: '{{item.sha}}'
        prefix: ''
    - id: note
      tool_name: builtin__infer
      input:
        instruction: |-
          Write one release-note line for this commit.
          Subject: {{item.subject}}
          Files changed: {{files.files}}
finish:
  output:
    since: '{{release.tag}}'
    notes: '{{notes.results}}'

version: 1
name: release_notes
description: Writes release notes from the changes since the latest release.
model: chat
tools:
- plan__unreleased_changes
subagents:
- reviewer
system_prompt: |
  You write release notes for this repository. Before you write them, ask
  reviewer whether any change since the release is risky to ship.

version: 2
identifier: unreleased_changes
name: Unreleased changes
description: The commits since the latest release, each with a one-line release note.
steps:
- id: release
  tool_name: github__tool__gh_release
  input: {}
- id: commits
  tool_name: github__tool__git_log
  input:
    base: '{{release.tag}}'
    head: HEAD
- id: notes
  tool_name: map
  input:
    over: '{{commits.commits}}'
    concurrency: 4
    do:
    - id: files
      tool_name: github__tool__git_changed_files
      input:
        base: '{{item.sha}}~1'
        head: '{{item.sha}}'
        prefix: ''
    - id: note
      tool_name: builtin__infer
      input:
        instruction: |-
          Write one release-note line for this commit.
          Subject: {{item.subject}}
          Files changed: {{files.files}}
finish:
  output:
    since: '{{release.tag}}'
    notes: '{{notes.results}}'

An agent is a model with instructions and a list of tools it may call. It decides what to call at run time, one round at a time, until it can answer.

version: 1
name: release_notes
description: Writes release notes from the changes since the latest release.
model: chat
tools:
- plan__unreleased_changes
subagents:
- reviewer
system_prompt: |
  You write release notes for this repository. Before you write them, ask
  reviewer whether any change since the release is risky to ship.

version: 2
identifier: unreleased_changes
name: Unreleased changes
description: The commits since the latest release, each with a one-line release note.
steps:
- id: release
  tool_name: github__tool__gh_release
  input: {}
- id: commits
  tool_name: github__tool__git_log
  input:
    base: '{{release.tag}}'
    head: HEAD
- id: notes
  tool_name: map
  input:
    over: '{{commits.commits}}'
    concurrency: 4
    do:
    - id: files
      tool_name: github__tool__git_changed_files
      input:
        base: '{{item.sha}}~1'
        head: '{{item.sha}}'
        prefix: ''
    - id: note
      tool_name: builtin__infer
      input:
        instruction: |-
          Write one release-note line for this commit.
          Subject: {{item.subject}}
          Files changed: {{files.files}}
finish:
  output:
    since: '{{release.tag}}'
    notes: '{{notes.results}}'

Agent files

An agent is a YAML file in ./.graph/agents/ or ~/.config/graph/agents/. It names a model role, the tools it may call, and its system prompt. It can also list other agents to call as subagents or hand the conversation to. See Agent file for every field.

Agent networks

An agent network is any mix of agents, plans and tools. One agent calling one plan and one subagent is already a network: Agent Plan Tool An agent chooses its next call each round, and each round is a model call. A plan fixes its steps ahead of time, makes no model call between them, and can run a step over many items at once. Move work an agent repeats into a plan it calls, and keep the agent for the decisions.

Delegation

An agent can pass work to other agents in two ways. See Build a multi-agent network for both.

Subagents

An agent lists the agents it can call under subagents, and calls each one as agent__<name> with a prompt. The subagent works in a fresh context and returns its result to the caller, which keeps the conversation. reviewer is a subagent of release_notes.

Handoffs

An agent lists the agents it can hand the conversation to under handoffs, and hands off with transfer_to_<name>. The new agent takes over the conversation and answers the user from then on.

Where agents run

Where	How
Your terminal	`graph ask` for one turn, `graph chat` for a conversation
The workbench	Built-in agents draft and edit plans, tools and agents with you
A plan step	A step calls a named agent as `agent__<name>`

A plan can also run an inline agent step, with its own prompt and tools, for one task that doesn’t need its own file.

Built-in agents

graph ships chat, the default for graph ask and graph chat, plus the drafters and workbench agents listed in Built-in agents. An agent file with the same name replaces a built-in. A project file replaces one in your home directory, so committing ./.graph/agents/ gives your whole team the same agents.

Guides

Create an agent in the workbench

Draft an agent with tools and save it.

Talk to an agent

Ask one question or hold a conversation from the terminal.

Optimize an agent with plans

Move repeated tool calls into a plan to make fewer model calls.

Build a multi-agent network

Connect agents with handoffs and subagents.

Customize a built-in agent

Give the chat agent a researcher subagent.

Steer tool choice

Get an agent to call the right plan.

Manage threads

Find, read, continue and delete conversations.

Getting started

Plans

Tools

Packs

Integrating

Reference

Agents

Agent files

Agent networks

Delegation

Subagents

Handoffs

Where agents run

Built-in agents

Guides

Create an agent in the workbench

Talk to an agent

Optimize an agent with plans

Build a multi-agent network

Customize a built-in agent

Steer tool choice

Manage threads

​Agent files

​Agent networks

​Delegation

​Subagents

​Handoffs

​Where agents run

​Built-in agents

​Guides

Create an agent in the workbench

Talk to an agent

Optimize an agent with plans

Build a multi-agent network

Customize a built-in agent

Steer tool choice

Manage threads

Agent files

Agent networks

Delegation

Subagents

Handoffs

Where agents run

Built-in agents

Guides