Skip to main content

​
Agent networks

An agent network is any mix of agents, plans and tools that call each other:
  • A handoff gives the conversation to another agent, which answers you from then on.
  • A call runs a plan, a tool or a subagent and returns its result to the caller.
  • A step is one call in a plan, made in a fixed order with no model choosing it.
A network can start as one agent and one tool, and grow from there.

​
Agents

An agent is a model with a system prompt and a list of tools it may call. It decides what to call one round at a time, and each round is a model call. It can also call other agents as subagents, or hand the conversation to them. Agents run in graph ask, graph chat and the workbench, and plans call them as steps. See Agents.

​
Plans

A plan is a list of steps that run in order, the same way every time. A step’s input reads the plan’s inputs and earlier steps’ results through templates, such as {{release.tag}}. A plan makes a model call only in a step that asks for one. Plans run with graph plan run, and agents and other plans call them as tools. See Plans.

​
Tools

A tool is anything an agent or a plan step can call: a command wrapped in a tool file, a tool from an MCP server, a tool built into graph, or another plan or agent. See Tools.

​
The catalog

Every tool sits in one catalog, and its name says where it comes from: Saving a plan or an agent adds it to the catalog, so the next thing you build can call it. Two more kinds of names aren’t in the catalog. Plans also use control steps (exit, route, filter, map, reduce, agent and ask), which the plan runs itself. Agents hand off with transfer_to_<name>, which exists only in a conversation.

​
Model roles

Agents, plan steps and tools name a role, such as chat or judge, not a model. [models] in config.toml maps each role to a provider and a model, so moving a job to another model is one line of config. See Models and providers.

​
Threads

graph ask and graph chat save each conversation as a thread, with every message, tool call and handoff. Pass --thread <id> to continue one. See Manage threads.

​
Where files live

  • Config merges both files, and the project file wins where they differ.
  • Agents and plans with the same name in both places: the project one replaces the home one, and either replaces a built-in.
  • Tools need a unique name across both directories.
Threads and other state live in the data directory, ~/.local/share/graph/ by default. Commit ./.graph/ to give your whole team the same network.