> ## 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.

# Run your first harness

> Run a complete harness without credentials, then connect an Agent and source context.

This example runs locally without a provider key or external service. It produces a result and a versioned event stream so you can see the runtime contract before adding a model.

## Install

Use Node.js `^22.18.0` or `^24.11.0`. Install the matching core and harness packages and a TypeScript runner:

```bash theme={null}
npm install @agentium/core@4.0.0 @agentium/harness@4.0.0
npm install --save-dev typescript tsx
```

<Note>
  This example targets Agentium 4.0.0. Use matching versions of core and harness; see [local-build installation](/learn/installation#build-a-matching-local-checkout) when developing against SDK source.
</Note>

## Run a local driver

Save this as `hello-harness.ts`:

```typescript hello-harness.ts theme={null}
import { HarnessRuntime, type ExecutionDriver } from "@agentium/harness";

const driver: ExecutionDriver = {
  id: "hello",
  version: 1,
  capabilities: {
    controls: ["follow_up"],
    durable: false,
    policyCoverage: "local",
    controlledExecution: true,
  },
  async start(request, services) {
    const text = `Hello, ${String(request.input)}!`;
    services.append([
      { role: "user", content: request.input },
      { role: "assistant", content: text },
    ]);
    services.emit({ type: "text.delta", text });
    return { text };
  },
};

const runtime = new HarnessRuntime({
  driver,
  grants: { toolIds: [], modelRoles: [] },
  budgets: { maxModelCalls: 0, maxToolCalls: 0 },
});
const identity = { tenantId: "demo", userId: "developer" };
const handle = runtime.start("Agentium", { identity, sessionId: "hello" });

for await (const event of handle.events()) {
  console.log(event.sequence, event.payload.type);
}
const result = await handle.result();
console.log(result.status, result.text);
console.log(await runtime.resources.closeSession(identity, "hello"));
```

```bash theme={null}
npx tsx hello-harness.ts
```

Expected output:

```text theme={null}
1 run.started
2 text.delta
3 run.terminal
completed Hello, Agentium!
[]
```

The runtime acquires the scoped session, calls the driver, commits its history, releases run resources, and emits one terminal event. `result()` returns the same settled result on subsequent calls. The empty array means session-resource cleanup produced no diagnostics.

## Connect an Agent and source context

This complete alternative uses a provider and therefore makes a model call. Install its optional SDK:

```bash theme={null}
npm install openai
export OPENAI_API_KEY="your-key"
```

```typescript research.ts theme={null}
import { openai } from "@agentium/core";
import { agentDriver, HarnessRuntime, research } from "@agentium/harness";

const runtime = new HarnessRuntime({
  definition: research({
    text: {
      id: "project-notes",
      entries: [{ id: "scope", text: "The project studies shipping delays." }],
    },
  }),
  driver: agentDriver({
    name: "research-assistant",
    model: openai(process.env.OPENAI_MODEL ?? "gpt-6.1-sol"),
    instructions: "Answer using the supplied sources. Say when the sources do not answer the question.",
  }),
  grants: { toolIds: [], modelRoles: ["main"] },
  budgets: { maxModelCalls: 4, maxToolCalls: 0, maxTokens: 8000 },
});

const identity = { tenantId: "demo", userId: "developer" };
try {
  const result = await runtime.run("What does this project study?", {
    identity,
    sessionId: "research-1",
  });
  console.log(result.status, result.text);
  if (result.reason) console.log(result.reason.code, result.reason.message);
} finally {
  const diagnostics = await runtime.resources.closeSession(identity, "research-1");
  if (diagnostics.length) console.error(diagnostics);
}
```

```bash theme={null}
npx tsx research.ts
```

Expect a completed answer about shipping delays; model wording varies. `research()` supplies context but does not browse the web or grant tools. Passing configuration to `agentDriver()` creates a run-owned Agent and closes it after the run.

Next, [configure grants and budgets](/harness/runtime), [compose abilities](/harness/definitions), or [consume events in a UI](/harness/events).

For a larger working example, build the [research assistant](/examples/harness-research), [continue a conversation across runs](/examples/harness-sessions), or [review workspace files](/examples/harness-workspace).


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