AgentHarness

Quick Example

import { react, AgentHarness } from '@noetic/core';

const agent = react({
  model: 'gpt-4o',
  tools: [searchTool, calcTool],
  maxSteps: 10,
});

const harness = new AgentHarness({
  name: 'researcher',
  initialStep: agent,
  params: {},
});

await harness.execute('Find recent AI news');
const response = await harness.getAgentResponse();

The AgentHarness is the execution engine at the heart of Noetic. It creates contexts, manages per-thread sessions with a message queue, dispatches steps, coordinates channels and memory layers, and provides tracing infrastructure.

Calls to execute() enqueue the input on the session identified by options.threadId (a single default thread is used when omitted). Stream accessors are session-scoped — subscribe once and events flow across every turn in that session.

Constructor Options

import { AgentHarness } from '@noetic/core';

const harness = new AgentHarness({
  name: 'my-agent',
  initialStep: myStep,
  params: { model: 'gpt-4o' },
});

execute()

Enqueues input on the session identified by options.threadId (or the default thread). Returns a Promise<void> that resolves once the message is accepted into the queue — not when the model finishes responding. Use the session-scoped accessors to observe the response.

await harness.execute('What is 2+2?');
const response = await harness.getAgentResponse();
console.log(response.text);

// Stream text across all turns in the session
for await (const delta of harness.getTextStream()) {
  process.stdout.write(delta);
}

// With options
await harness.execute('Hello', {
  threadId: 'thread-1',
  resourceId: 'user-1',
});

// Submit a second message while the first turn is still running — it queues
// and runs as a new turn after the current turn completes.
await harness.execute('follow-up', { threadId: 'thread-1' });

Rejects with NoeticConfigError code NO_STEP_CONFIGURED if no initialStep was provided in the constructor.

Session Accessors

Stream accessors are keyed by threadId (via SessionScope), are safe to call before the first execute(), and stay alive across every turn in the session.

Delivery Modes

Each message carries a DeliveryMode. Override per-call via options.deliveryMode, or set defaultDeliveryMode on the harness.

HarnessResponse

interface HarnessResponse {
  readonly items: ReadonlyArray<Item>;
  readonly usage: { inputTokens: number; outputTokens: number; cachedTokens?: number };
  readonly cost?: number;
  readonly text: string;
  readonly lastLayerUsage?: LastLayerUsage;
}

StreamEvent

Events have a source discriminant: 'sdk' for OpenResponses SSE events, 'framework' for Noetic lifecycle events. Framework events use the harness config.name as prefix.

type StreamEvent = SdkStreamEvent | FrameworkStreamEvent;

Framework events emitted during execution:

LLM steps support an emit option to control step/tool framework event emission — set false to suppress or pass a filter function. Turn-level events are emitted by the session runner and are not gated by step.emit.

Stream Idle Timeout

Each provider call is guarded by a watchdog that aborts the round if no SSE event arrives for streamIdleTimeoutMs (default 120000; set 0 to disable). On timeout, {name}:llm_call_stalled is emitted and the surrounding turn fails with turn_aborted { reason: "llm stream idle timeout after <N>ms" }, so upstream providers that quietly drop a connection surface as errors rather than hangs.

run()

Low-level step execution. Use this when you need full control over context creation and step dispatch.

const ctx = harness.createContext({ state: { count: 0 } });
const result = await harness.run(myStep, input, ctx);

createContext Options

Channel Methods

Memory Methods

The agent harness coordinates memory layer lifecycle hooks:

RecallLayerOutput

interface RecallLayerOutput {
  layerId: string;
  items: Item[];
  tokenCount: number;
}

Durability Methods

When the harness is constructed with a checkpointStore (and, typically, a durable subprocess adapter), checkpoint and restore become real crash-recovery hooks. When they are absent every call is a no-op — zero-config harnesses preserve in-memory semantics unchanged.

The subprocess adapter is the companion surface: it persists handle manifests for every long-lived child so a restarted host can call harness.subprocess.listLive() + harness.restore(executionId) per live child to rejoin the execution. Full durable-execution model, storage layout, and IPC protocol live on the Durability page.

Tracing

AgentConfig

AgentConfig defines the configuration for an agent harness. It is generic over TParams, an arbitrary key-value record that steps and tools access via ctx.harness.config.params.

interface AgentConfig<TParams extends Record<string, unknown> = Record<string, unknown>> {
  name: string;
  storage?: StorageAdapter;
  hooks?: AgentHooks;
  params: TParams;
}

AgentHooks

interface AgentHooks {
  beforeStep?: (step: Step, ctx: Context) => Promise<void>;
  afterStep?: (step: Step, result: unknown, ctx: Context) => Promise<void>;
}

const harness = new AgentHarness({
  name: 'researcher',
  initialStep: agent,
  params: { model: 'gpt-4o' },
  hooks: {
    async beforeStep(step, ctx) {
      console.log(`Starting step ${step.id} (depth ${ctx.depth})`);
    },
    async afterStep(step, result, ctx) {
      console.log(`Step ${step.id} used ${ctx.tokens.total} tokens`);
    },
  },
});

Resuming a session from disk

harness.seedSessionHistory(threadId, items) populates a fresh session's accumulated items before the next execute() call. Pair it with append-only persistence (one Item per line in a JSONL file) to make a chat survive subprocess restarts:

import { harness } from './my-harness';
import { readPriorItems } from './my-store';

const threadId = 'task-T-abc123';
harness.seedSessionHistory(threadId, await readPriorItems(threadId));
await harness.execute('continue from here', { threadId });

The Noetic CLI uses this pattern for per-task agent runners — see the "Per-Task IPC for Live Chat" section of specs/08-runtime.md for the end-to-end design.

Subprocess Adapter

The harness always holds a SubprocessAdapter. Every step.run, every spawn, and every harness.detachedSpawn routes through harness.subprocess.spawn(...) — in-process vs out-of-process is a property of the adapter, not the step.

import { AgentHarness, createFileStorage } from '@noetic/core';
import { createLocalSubprocessAdapter } from '@noetic/platform-node';

const subprocess = createLocalSubprocessAdapter({
  storage: createFileStorage({ root: `${process.env.HOME}/.noetic/subprocess` }),
});

const harness = new AgentHarness({
  name: 'durable-agent',
  initialStep: agent,
  params: {},
  subprocess,                                 // real OS subprocess with durable manifests
});

Per-step and per-call overrides let you mix execution backends. A step with subprocess: createInMemorySubprocessAdapter() stays in-process even when the harness default is the local adapter; a detachedSpawn(step, input, ctx, { subprocess: otherAdapter }) overrides both. Resolution order is detachedSpawn-overrides.subprocess ?? step.subprocess ?? harness.subprocess.

Related Pages

• Context & Event Log -- the context object the agent harness creates.
• Channels -- channel send/recv methods on the agent harness.
• Memory -- memory layers managed by the agent harness.
• Observability -- tracing spans created by createSpan.
• Durability -- checkpoint/restore, adapter durability, and the host-restart flow.