> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an execution driver

> Connect Agents, Teams, Workflows, or custom execution loops to HarnessRuntime.

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](/harness/sessions).

## Map Workflow input

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

```typescript theme={null}
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](/harness/quickstart). 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`](/harness/testing). See [driver signatures](/harness/api/drivers) and [execution-service types](/harness/api/runtime#harnessexecutionservices).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.