Skip to the content.

Graph Engine Guide

core/agent-graph is an agent.Engine: an agent as a graph of nodes driven by a frontier. It is a sibling of core/agent, not a layer above it — agent defines what a task and its events are, graph runs nodes whose edges decide where the run goes next, and both produce agent.Event streams, so a deployment exposes either through the same protocol.

The run is a frontier loop, not a wave over a DAG

A graph may loop: a ReAct cycle is model → tools → model. There is therefore no topological order and no cycle rejection. Each step:

  1. invokes the frontier — the nodes reached in the previous step;
  2. applies the step's writes, in declaration order;
  3. evaluates the outgoing edges of every node that ran, to compute the next frontier.

An edge fires when its condition holds (an empty condition always fires), so a node fans out by having several outgoing edges, and branching joins implicitly: a node reached twice in one step runs once. limits.max_steps bounds a loop that never empties the frontier.

No board, and no values on edges

The previous engine kept a board of untyped vars copied per branch and merged with reflection. Three things followed, and this package is built to avoid all three:

A node produces state and nothing else. Values do not travel along edges: in a loop, "the value on this edge" has no answer, so the state is the only carrier that stays well defined.

The document

The graph is its own file; the deployment's engine settings only name it:

# deploy.yaml
agents:
  - name: forge
    engine:
      kind: graph
      settings:
        source: { kind: file, settings: { path: ./graphs/react.yaml } }
    runtime:
      layers:
        - priority: 0
          source: { kind: file, settings: { path: ./runtime.yaml } }
# graphs/react.yaml
version: 1
name: react
entry: model
input: messages

limits:
  max_steps: 24
  max_nodes: 200
  timeout: 5m
  concurrency: 4

checkpoint:
  every: 8 # also write a base every N steps

stream:
  state: false # report each step's writes as a GraphState event

state:
  messages: { type: messages, merge: append, carry: true }
  pending: { type: json }
  answer: { type: text }

nodes:
  - id: model
    kind: model
    config:
      messages: messages
      pending: pending
      usage: usage
      request:
        model: { provider: openai, name: gpt-5 }
        system: "You are a coding agent."
        tools: { names: [read, write, exec] }
  - id: tools
    kind: tool
    config:
      messages: messages
      pending: pending
      parallelism: 4
  - id: done
    kind: condition
    config:
      key: answer

edges:
  - { from: model, to: tools, when: "len(pending) > 0" }
  - { from: model, to: done, when: "len(pending) == 0" }
  - { from: tools, to: model }

output:
  key: answer
Field Rule
version Must be 1.
entry The node the first frontier holds.
input The state key Start seeds with the run's messages. Empty means the graph takes no input, and a caller that supplies some is refused.
limits max_steps, max_nodes (skipped nodes count: a cycle of skipped nodes still spends budget), timeout, concurrency. Zero means no cap — the caller's context is always the outer bound.
checkpoint.every 0 writes a base only when the deltas would be missing; a positive value also writes one every N steps, bounding how long a restart replays.
stream.state Emit a GraphState event per step. Off by default: it costs a JSON projection per step, and a run nobody is watching should not pay for one.
output.key The state key a finished run reports.

YAML is the written form and JSON is accepted; both go through one strict decoding, so an unknown field is an error either way.

Placeholders

Every string value in the document — a node config, the state block, an edge condition — is expanded before the document is decoded, by the same code a runtime layer uses:

Form Resolves through
${NAME} the built-in env scheme (config.SchemeEnv)
${NAME:-fallback} env, with a default when unset
${scheme:arg:arg} a resolver the host registered

A node config may therefore name a value it should not carry:

- id: model
  kind: model
  config:
    messages: messages
    request:
      system: "${secret:agent:prompt}"

Arguments after the scheme are split on : and handed to the resolver untouched; $$ is a literal $. The schemes themselves are the host's: it hands its resolvers to the reader with nodes.WithConfigOptions, and to the engine when the graph is deployed — deploy.md has the two lines. An unregistered scheme is a load error listing what is registered, never a literal handed to a node.

nodes.RequiredPlaceholders reports every reference in a document without resolving it, so a host can print a checklist instead of discovering one missing value per restart. The load itself does this too: a document that cannot be expanded names every reference it makes, because the load fails at the first one and the reader needs the list rather than one value per restart.

The report names an environment variable as itself and a host scheme as scheme:args, and config.Requirement.Missing answers for environment variables only — a scheme reference is the host's own to look up. A resolved value is not part of the deployment's identity either: the fingerprint is the document's bytes as written, so rotating what a reference resolves to does not invalidate the checkpoints taken under it.

State

Field Values
type text, json, messages, bool.
merge single (default: a second write in one step is an error), last (last write wins), append (the writes concatenate).
carry Keep this key across the tasks of one session: a new task seeds it from the previous task's state instead of the declared zero value.

carry is the document's way to say "this is the conversation, not the request". It is meant for bounded state — a game, a form, a plan — which carries in microseconds. A key that grows without bound costs its own size on every turn, because the state is re-read from the store: a 200-message transcript measured 667 µs and 5000 allocations per turn. A long conversation belongs in one task, not in a carried key.

Nodes in one step read the state as it was when the step started. Their writes apply after the step, in declaration order — which is why merge: single turns "two nodes wrote the same key" into an error instead of a coin flip.

Nodes

- id: model # unique within the document
  kind: model # a registered kind; unknown is a load error
  config: { ... } # the kind decodes this strictly
  skip: "step > 10" # a condition: when it holds, the node is not invoked
  timeout: 90s # one invocation
  retries: 2 # retryable failures

A skipped node is not invoked, but its outgoing edges still fire: it routes without running. That is what makes skip useful for a terminating branch.

model

One model call per invocation.

Config Meaning
messages State key carrying the conversation (a messages value).
pending State key the call's tool calls are written to.
usage State key the token usage is appended to.
output State key the response text is written to.
request.stream Nil streams (incremental events, what a reader watches); false returns one finished response for a call whose answer is data.
request.model provider, name, profile — resolved against the runtime's routing table.
request.system The system framing for this call.
request.tools enabled, names (restrict the offer), require (force visible in a dynamic catalog), choice.
request.extensions Provider extensions, decoded by the registered ExtensionDecoders.

tool

Executes the pending tool calls.

Config Meaning
messages, pending As above: read the conversation, drain the pending calls.
effects after (default) records a finished call; before writes the started record before the tool runs, so a crash leaves an outcome to reconcile instead of a silent duplicate.
parallelism Caps how many calls of one batch run at once; 0 leaves the batch unbounded.

condition

Evaluates an expression and writes the branch it took.

- id: done
  kind: condition
  config: { key: answer, when: "answer != nil", then: yes, else: no }

script

Not built in: a host registers it, because a script engine is a dependency choice. See script.md.

Conditions

Conditions are expr expressions over the state as it was when the step started, plus step:

skip: "step > 10"
when: "pending != nil and len(pending) > 0"

They are compiled once at build, so a typo is a load error rather than a run-time surprise, and a step evaluates its skip conditions and its edges against one snapshot. Values keep their shape in the environment: text is a string, a number or object is decoded JSON, a message list is the slice (so len(messages) works), media is its descriptor. A condition that returns a non-bool is a run error naming the node.

Extending it with a node kind

type NodeKind interface {
    Name() string
    Invoke(ctx context.Context, in Invoke) (NodeStream, error)
}

// Optional: parse the config once, at Build.
type ConfigDecoder interface {
    DecodeConfig(raw json.RawMessage) (any, error)
}

Invoke carries everything a node needs and nothing it could misuse:

Field Use
Node, Config, Decoded The instance id, its raw settings, and the value Build decoded.
State(key), Snapshot() Read a declared key, or the whole step. The snapshot is read-only: it is shared by every node of the step.
Step The loop counter, so a node can decide to stop.
Answer The reply to a question this node asked by suspending.
Lookup, Replay A recorded model call by request hash, and whether the run must answer from records (a miss is an error, not a silent live call).
Records(kind), Checkpoint Durable facts earlier steps recorded, and an immediate write for a side effect that must be recorded before it runs.
Trace, Bodies How much is traced, and whether response bytes are kept.

A node returns a NodeStream rather than calling back into the engine — the engine pulls, so backpressure and cancellation are the contract rather than a convention, and a kind can be tested by feeding it inputs and reading the stream. Most kinds compute and return Static(result); only one that reports progress (a streaming model call, a long tool run) needs its own stream.

Result has three fields: State (the writes), Records (durable facts), Suspend (a question). A node that suspends loses its writes — it is re-entered from the start on resume and produces them again, so committing them now would apply them twice.

Register kinds where the graph is opened:

built, err := nodes.Open(ctx, rt, "graphs/react.yaml", config.File("graphs/react.yaml"),
    nodes.WithKinds(myKind()),                  // static kinds
    nodes.WithRuntimeKinds(func(rt nodes.Runtime) ([]graph.NodeKind, error) {
        kind, err := script.New(script.WithRuntime(rt))
        if err != nil {
            return nil, err
        }
        return []graph.NodeKind{kind}, nil
    }),
    nodes.WithModelDecoders(decoders),          // request.extensions
    nodes.WithBlobStore(store),                 // media out of the state
)

The registry's shape matches the engine tables in core/deploy: a kind is a name resolved at build time, so an unknown kind is a document error listing the known names.

Suspension

Asking is a primitive, not a node kind: any node may ask — a tool node relaying an ask_user tool, a custom node collecting a missing parameter. One node may suspend per step, and the step finishes first, so a suspension cannot tear a concurrent step apart. On resume the node is re-entered from the start with Invoke.Answer set; anything it did before suspending is its own idempotency problem, which is why a node with a side effect should record it with Checkpoint before suspending.

Checkpoints and replay

graph.NewRunner takes a RunnerConfig with the store, the run's identity and the session/task ids. The graph itself is compiled once per deployment and shared by every session; the runner owns one run.

Events

Besides the events every run emits (text, reasoning, tool calls, usage), the graph adds NodeEvent and — when stream.state is on — GraphState, which reports each step's writes. Both are agent.EventExtension payloads, so a protocol forwards them without knowing the graph exists.

What replaced what

Gone Now
core/graph, a board of untyped vars core/agent-graph, declared state keys with merge rules
Message channels copied per branch Persistent message sequences, shared on append
reflect.DeepEqual + MergeFunc merge: single / last / append, declared per key
Edges as bare connections Edges carrying a compiled condition
A fixed node set A registry of kind names, extended by the host