GraphBuilder

Defined in: types.ts:301

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:303

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

---

traceContext

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

Defined in: types.ts:306

Trace context for propagating distributed trace information.

spanId

spanId: string

traceId

traceId: string

Methods

addEdge()

addEdge(from, to, type): void

Defined in: types.ts:318

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:360

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

Returns

ExecutionGraph

---

endNode()

endNode(nodeId, status?): void

Defined in: types.ts:312

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:315

Mark a node as failed with an error.

Parameters

Parameter	Type
nodeId	string
error	string | Error

Returns

void

---

getOrganizationalBriefing()

getOrganizationalBriefing(): unknown

Defined in: types.ts:347

Get organizational briefing if available (may return null if briefing hasn't been generated yet).

Returns

unknown

---

getOrganizationalContext()

getOrganizationalContext(): { briefingAvailable: boolean; briefingSummary?: string; insightCount: number; operatorContext?: OperatorContext; teamContext?: string; warningCount: number; }

Defined in: types.ts:350

Get organizational context summary for execution environment.

Returns

{ briefingAvailable: boolean; briefingSummary?: string; insightCount: number; operatorContext?: OperatorContext; teamContext?: string; warningCount: number; }

briefingAvailable

briefingAvailable: boolean

briefingSummary?

optional briefingSummary?: string

insightCount

insightCount: number

operatorContext?

optional operatorContext?: OperatorContext

teamContext?

optional teamContext?: string

warningCount

warningCount: number

---

getSnapshot()

getSnapshot(): ExecutionGraph

Defined in: types.ts:344

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:328

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:309

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:331

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:338

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