Connect an execution driver

A driver translates a run request into work and returns a HarnessDriverOutput. The runtime supplies controlled model/tool services, session history, state, resource leases, and an abort signal.

Built-in drivers

Factory	Input	Ownership and behavior
`agentDriver(agentOrConfig, { stream? })`	Existing `Agent` or `AgentConfig`	Configuration creates a run-owned Agent; an existing instance is borrowed. `stream` defaults to `false`.
`teamDriver(team)`	Existing `Team`	Borrows the Team. Requires text input; unsupported remote member execution fails explicitly.
`workflowDriver(workflow, { input? })`	Existing `Workflow`	Borrows the Workflow. Input defaults to a JSON object patch over its constructor’s initial state.

All three advertise follow_up, durable: false, policyCoverage: "local", and controlledExecution: true. They propagate run identity, cancellation, run mode, history, and execution services into core.

Agent ownership

Use agentDriver(config) when the definition supplies defaults or limits. The driver applies those settings, resolves paths against projectRoot, disables global registration for its run-owned Agent, and closes it with closeStorage: false. Explicit Agent options override definition defaults; definition limits still cap tool rounds and enabled subagent depth. Use agentDriver(existingAgent) when your application already manages the instance. A borrowed Agent is not reconfigured or closed by the driver. Nonempty definition defaults or limits are rejected for a borrowed Agent because it is already configured. For token-by-token text events, set { stream: true }. Without it, the driver emits text after Agent.run() completes. Large text is split into 8,192-character chunks before event publication. Harness session history is passed explicitly; attaching Agent storage does not make it the harness session store. Choose one lifecycle owner for each resource and see sessions.

Map Workflow input

This integration factory adapts a host-owned workflow without running it:

import type { Workflow } from "@agentium/core";
import { workflowDriver } from "@agentium/harness";

export function questionDriver(workflow: Workflow<{ question: string; answer: string }>) {
  return workflowDriver(workflow, {
    input(value) {
      if (typeof value !== "string") throw new Error("Expected a question string");
      return { question: value };
    },
  });
}

Without input, pass a JSON object string such as '{"question":"What changed?"}'. Arrays, primitives, and non-object input fail. The result’s structured field is the final workflow state and text is its JSON serialization. A failed step yields failed with workflow_step_failed.

Implement a custom driver

Start from the complete local driver example. Give the driver a nonempty id, positive integer version, and accurate capabilities. It must use the supplied services for every model call and tool/effect operation it claims the runtime controls.

Service	Use
`model`, `streamModel`	Controlled task model calls with budgets, policies, middleware, and cancellation.
`dispatch`	Execute a tool call through runtime enforcement.
`dispatchEffect`	Route an application effect through the execution boundary.
`controlModel`	Tool-free policy-model call with an explicitly granted role and shared budgets.
`append`, `recordConversation`	Append canonical messages or record an execution’s conversation.
`runOwned`	Register async work that must settle before run cleanup.
`observeTool`	Record a tool result through the shared observation path.
`takeInput`	Consume queued input for controls handled directly by the driver.
`resource`	Acquire a host-, session-, or run-scoped resource.
`emit`	Publish an allowed payload; started and terminal lifecycle events belong to the runtime.
`putArtifact`, `getArtifact`	Store and retrieve structured-cloneable output scoped to this session.

Read services.history, services.state, services.ctx, services.tools, services.signal, services.executionPolicy, and services.approvalManager as the runtime’s execution context. Append valid message groups; a returned history may extend canonical history but cannot replace its existing prefix. Return at least { text }; omitted status means completed. Optional output fields are structured, status, reason, usage, history, and artifacts. Runtime-accounted usage takes precedence once controlled model calls occurred. Custom driver code is trusted. Calling a provider or service outside the supplied execution services bypasses the harness’s interception. A capability declaration does not sandbox JavaScript. The current runtime rejects durable drivers, interrupt-and-replace, and drivers without mandatory local execution coverage. Verify custom drivers with testDriverContract. See driver signatures and execution-service types.

Build

Agent applications

Harness runtime

Teams and workflows

Data and capabilities

Interfaces and jobs

Voice and telephony

Verify and manage

Connect an execution driver

Built-in drivers

Agent ownership

Map Workflow input

Implement a custom driver

​Built-in drivers

​Agent ownership

​Map Workflow input

​Implement a custom driver

Built-in drivers

Agent ownership

Map Workflow input

Implement a custom driver