GraphBuilder

Defined in: types.ts:232

Mutable graph builder returned by createGraphBuilder.

Example

const builder = createGraphBuilder({ agentId: 'main' });
const rootId = builder.startNode({ type: 'agent', name: 'main' });
const toolId = builder.startNode({ type: 'tool', name: 'search', parentId: rootId });
builder.endNode(toolId);
builder.endNode(rootId);
const graph = builder.build();

Properties

graphId

readonly graphId: string

Defined in: types.ts:234

The graph's ID, available before build().

---

traceContext

readonly traceContext: { spanId: string; traceId: string; }

Defined in: types.ts:237

Trace context for propagating distributed trace information.

spanId

spanId: string

traceId

traceId: string

Methods

addEdge()

addEdge(from, to, type): void

Defined in: types.ts:249

Add an explicit edge between two nodes.

Parameters

Parameter	Type
from	string
to	string
type	EdgeType

Returns

void

---

build()

build(): ExecutionGraph

Defined in: types.ts:278

Freeze and return the completed execution graph. Throws if no root node exists.

Returns

ExecutionGraph

---

endNode()

endNode(nodeId, status?): void

Defined in: types.ts:243

End a node. Status defaults to 'completed'.

Parameters

Parameter	Type
nodeId	string
status?	NodeStatus

Returns

void

---

failNode()

failNode(nodeId, error): void

Defined in: types.ts:246

Mark a node as failed with an error.

Parameters

Parameter	Type
nodeId	string
error	string | Error

Returns

void

---

getSnapshot()

getSnapshot(): ExecutionGraph

Defined in: types.ts:275

Return a frozen snapshot of the current graph state without finalising. The builder remains usable after calling this.

Returns

ExecutionGraph

---

pushEvent()

pushEvent(event): void

Defined in: types.ts:259

Record a trace event. Timestamp is added automatically.

Parameters

Parameter	Type
event	Omit<TraceEvent, "timestamp">

Returns

void

Example

builder.pushEvent({ eventType: 'custom', nodeId: rootId, data: { key: 'value' } });

---

startNode()

startNode(opts): string

Defined in: types.ts:240

Start a new execution node. Returns the generated node ID.

Parameters

Parameter	Type
opts	StartNodeOptions

Returns

string

---

updateState()

updateState(nodeId, state): void

Defined in: types.ts:262

Shallow-merge state into a node's state object.

Parameters

Parameter	Type
nodeId	string
state	Record<string, unknown>

Returns

void

---

withParent()

withParent<T>(parentId, fn): T

Defined in: types.ts:269

Execute fn with an implicit parent context. Any startNode calls inside fn that omit parentId will automatically use parentId as their parent.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
parentId	string
fn	() => T

Returns

T