Class AgentGraph<TState>

Fluent builder for agent execution graphs.

Each mutating method returns this to support method chaining. All state is held in private Maps/arrays; nothing is compiled or validated until .compile() is called.

Type Parameters

  • TState extends GraphState = GraphState

    Narrows the GraphState type used in conditional-edge callbacks. Defaults to the base GraphState when not specified.

Constructors

constructor

Methods

addNode addEdge addConditionalEdge addDiscoveryEdge addPersonalityEdge compile

Constructors

constructor

  • new AgentGraph<TState>(stateSchema, config?): AgentGraph<TState>

  • Type Parameters

    Parameters

    • stateSchema: {
          input: any;
          scratch: any;
          artifacts: any;
      }

      Zod schemas for the three GraphState generic partitions.

      • input — shape of the frozen user-provided input passed to invoke().
      • scratch — shape of the mutable node-to-node communication bag.
      • artifacts — shape of the accumulated external outputs returned by invoke().
      • input: any

        Zod schema for GraphState.input.

      • scratch: any

        Zod schema for GraphState.scratch.

      • artifacts: any

        Zod schema for GraphState.artifacts.

    • Optional config: {
          reducers?: StateReducers;
          memoryConsistency?: MemoryConsistencyMode;
          checkpointPolicy?: "none" | "every_node" | "explicit";
      }

      Optional graph-wide configuration overrides.

      • Optional reducers?: StateReducers

        Field-level merge strategies for scratch and artifacts fields.

      • Optional memoryConsistency?: MemoryConsistencyMode

        Graph-wide memory consistency mode (default: 'snapshot').

      • Optional checkpointPolicy?: "none" | "every_node" | "explicit"

        Graph-wide checkpoint persistence strategy (default: 'none').

    Returns AgentGraph<TState>

Methods

addNode

  • addNode(id, node): this

  • Add a node to the graph.

    The node's id field is overridden with the supplied id argument so the user-declared identifier is always canonical.

    Parameters

    • id: string

      Unique node identifier within this graph. Must not equal START or END.

    • node: GraphNode

      A GraphNode produced by one of the factory helpers in builders/nodes.ts.

    Returns this

    this for chaining.

    Throws

    When id has already been registered.

addEdge

  • addEdge(source, target): this

  • Add an unconditional (static) edge that is always followed at runtime.

    Either source or target (or both) may be the START / END sentinels.

    Parameters

    • source: string

      Source node id (or START).

    • target: string

      Target node id (or END).

    Returns this

    this for chaining.

addConditionalEdge

  • addConditionalEdge(source, condition): this

  • Add a conditional edge whose target is determined at runtime by a callback.

    The condition function receives the current GraphState and returns the id of the next node to activate. The returned id is resolved against the edge list at runtime; no compile-time validation of the returned id is performed.

    Because conditional edges encode the target resolution in a closure, the target field stored in the IR is set to the placeholder '__CONDITIONAL__'.

    Parameters

    • source: string

      Source node id (or START).

    • condition: ((state) => string)

      Pure function (state: TState) => string returning the next node id.

        • (state): string

        • Parameters

          Returns string

    Returns this

    this for chaining.

addDiscoveryEdge

  • addDiscoveryEdge(source, config): this

  • Add a discovery edge whose target is resolved at runtime via the capability discovery engine.

    When discovery returns no result, execution falls back to config.fallbackTarget (if provided) or the placeholder '__DISCOVERY__'.

    Parameters

    • source: string

      Source node id.

    • config: {
          query: string;
          kind?: "tool" | "skill" | "extension" | "any";
          fallbackTarget?: string;
      }

      Discovery configuration. config.query is forwarded to the CapabilityDiscoveryEngine. config.kind optionally restricts discovery to a specific capability kind. config.fallbackTarget is used when discovery resolves no target.

      • query: string

        Semantic query forwarded to the capability discovery engine.

      • Optional kind?: "tool" | "skill" | "extension" | "any"

        Optional capability kind filter ('tool', 'skill', 'extension', or 'any').

      • Optional fallbackTarget?: string

        Fallback node id used when discovery resolves no target.

    Returns this

    this for chaining.

addPersonalityEdge

  • addPersonalityEdge(source, config): this

  • Add a personality edge whose target is chosen based on the agent's current trait value.

    At runtime the engine reads config.trait from the agent's HEXACO/PAD state and routes to config.above when the value is ≥ config.threshold, or config.below otherwise.

    Parameters

    • source: string

      Source node id.

    • config: {
          trait: string;
          threshold: number;
          above: string;
          below: string;
      }

      Personality routing configuration. config.trait identifies the HEXACO/PAD value to inspect. config.threshold is the decision boundary in the 0–1 range. config.above is used when the trait value is greater than or equal to the threshold. config.below is used when the trait value is below the threshold.

      • trait: string

        HEXACO/PAD trait name, e.g. 'conscientiousness' or 'openness'.

      • threshold: number

        Decision threshold in range 0–1.

      • above: string

        Target node id when the trait value is at or above the threshold.

      • below: string

        Target node id when the trait value is below the threshold.

    Returns this

    this for chaining.

compile

  • compile(options?): CompiledAgentGraph<TState>

  • Compile the builder state into a CompiledAgentGraph ready for execution.

    Compilation steps:

    1. Call GraphCompiler.compile() to produce the raw CompiledExecutionGraph IR.
    2. (Optional, default: enabled) Call GraphValidator.validate() to assert structural correctness — any validation error or warning causes an exception.
    3. Wrap the IR and a checkpoint store in a CompiledAgentGraph instance.

    Pass { validate: false } to skip validation (e.g. for cyclic graphs under construction).

    Parameters

    • Optional options: {
          checkpointStore?: ICheckpointStore;
          validate?: boolean;
      }

      Optional compilation flags. options.checkpointStore overrides the default InMemoryCheckpointStore. options.validate can be set to false to skip structural validation.

      • Optional checkpointStore?: ICheckpointStore

        Custom checkpoint persistence backend. Defaults to an in-memory store.

      • Optional validate?: boolean

        Whether to run GraphValidator.validate() before returning. Defaults to true. Set to false for cyclic or incomplete graphs under construction.

    Returns CompiledAgentGraph<TState>

    A CompiledAgentGraph instance ready for invoke() / stream() / resume().

    Throws

    When validation is enabled and the graph contains structural errors or warnings.

Settings

Member Visibility

Theme

On This Page

constructoraddNodeaddEdgeaddConditionalEdgeaddDiscoveryEdgeaddPersonalityEdgecompile