Agent API

`Agent`

The single public class, backed by Causal Weave v3.

new Agent(args: AgentArgs)

Constructor

Option	Type	Default
`model`	`Model`	required
`tools`	`Tool[]`	scoped workspace tools
`state`	`AgentState`	empty state
`systemPrompt`	`string`	built-in instruction
`providerSystem`	`string`	built-in action protocol
`maxIterations`	`number`	`30`
`maxNoProgressIterations`	`number`	unset
`maxPromptTokens`	`number`	`64_000` (minimum 256)
`projectionTargetTokens`	`number`	`16_000`, clamped to ceiling (minimum 256)
`enforceCompletionEvidence`	`boolean`	`true`
`nodeTypes`	`SemanticNodeType[]`	memory, preference, wisdom, artifact
`allowDynamicNodeTypes`	`boolean`	`false`
`traceDir`	`string`	no file trace

tools: [] disables tools. Omitting tools creates the default workspace tools.

`run()`

run(input: TaskInput, options?: AgentRunOptions): Promise<AgentRunResult>

TaskInput is a string or { input, objective? }. A stateful agent serializes concurrent calls. Successful runs update its state.

type AgentRunOptions = {
  signal?: AbortSignal;
  state?: AgentState;
  onProgress?: (progress: AgentProgress) => void;
};

Passing options.state runs against that snapshot without mutating the agent-owned session.

`streamEvents()`

streamEvents(input, options?): AsyncIterable<AgentStreamEvent>

Emits metadata first, then model token/metadata events as available, zero or more progress events, and one final. Closing early aborts the run. Errors are thrown by the iterator.

for await (const event of agent.streamEvents("Inspect the workspace")) {
  if (event.type === "model_token") process.stdout.write(event.token);
  if (event.type === "model_metadata") console.log(event.metadata);
  if (event.type === "final") console.log(event.result.finalAnswer);
}

`stream()` and `streamText()`

stream(input, options?): AsyncIterable<string>
streamText(input, options?): AsyncIterable<string>

Both yield the accepted final answer as one string. They do not yield partial protocol text; use streamEvents() for provider token events.

`getState()`

getState(): AgentState | undefined

A structured clone of committed state. undefined before the first success unless initial state was supplied.

`getGraph()`

getGraph(): StateGraph

A visualization view. Not the lossless persistence format.

`reset()`

reset(state?: AgentState): void

No argument clears state. A snapshot validates and replaces it. A generation guard stops an older in-flight run from overwriting a later reset.

Result

type AgentRunResult = {
  finalAnswer: string;
  state: AgentState;
  graph: StateGraph;
  trace: AgentTraceStep[];
  metadata: AgentRunMetadata;
};

Metadata reports run identity, engine, tools, limits, semantic config, timing, step count, and token totals.

`AgentRunError`

class AgentRunError extends Error {
  readonly state: AgentState;
  readonly graph: StateGraph;
  readonly trace: AgentTraceStep[];
  readonly metrics: {
    modelCalls: number;
    toolCalls: number;
    latestContextTokens: number;
    totalInputTokens: number;
    outputTokens: number;
  };
}

These describe the failed run. They do not replace the last successful commit. Invalid configuration and an impossible prompt budget fail before a provider call; a runtime failure after work has started exposes diagnostic state through this error. Next: Types and exports.

Start

Understand

Build

Reference

`Agent`

Constructor

`run()`

`streamEvents()`

`stream()` and `streamText()`

`getState()`

`getGraph()`

`reset()`

Result

`AgentRunError`

​Agent

​Constructor

​run()

​streamEvents()

​stream() and streamText()

​getState()

​getGraph()

​reset()

​Result

​AgentRunError

`Agent`

Constructor

`run()`

`streamEvents()`

`stream()` and `streamText()`

`getState()`

`getGraph()`

`reset()`

Result

`AgentRunError`