Chapter 01

Getting started

Start here if you need the product mental model, the expected repository shape, and the first end-to-end path from install to a governed runtime request.

Three-minute mental model

agent-harness is not a new agent framework. It is the runtime product layer around existing execution frameworks. Those backends continue to own agent execution semantics. The harness owns application runtime concerns: persisted records, approvals, recovery, operator visibility, queueing, inspection, and stable lifecycle APIs.

Shortest definition

You bring the workspace, agents, tools, prompts, and product behavior. The harness makes that workspace operable as a product runtime.

When this product is a fit

Use it when your team already has agent behavior but the missing layer is runtime control.

Good fit

Approvals, restart recovery, queueing, inspection, or persisted runtime records are product features.

Bad fit

You only need one short-lived call with no persistence, no approvals, and no operator surface.

Repository and workspace shape

The repository contract matters because the product is workspace-shaped. This repo also enforces a clear source and test split: implementation in src/, verification in test/.

your-workspace/
  config/
    agent-context.md
    runtime/
      workspace.yaml
      runtime-memory.yaml
    catalogs/
      models.yaml
      embedding-models.yaml
      vector-stores.yaml
      stores.yaml
      backends.yaml
      tools.yaml
      mcp.yaml
    agents/
      direct.yaml
      orchestra.yaml
  resources/
    package.json
    tools/
    skills/

Contributing to the open-source package

The layout above is for an application workspace. If you work on the agent-harness package itself, keep implementation in src/ and tests in test/ at the repository root.

From install to first governed run

Install the package and create the standard workspace folders.
Define named models, stores, tools, and MCP servers in YAML catalogs.
Define at least one host agent with kind: Agent.
Point the runtime at the workspace root with createAgentHarness(...).
Use request(...) to start work, subscribe(...) to observe it, and inspection APIs to read the persisted result.

import { createAgentHarness, request, listSessions, stop } from "@botbotgo/agent-harness";

const runtime = await createAgentHarness(process.cwd());
const result = await request(runtime, {
  agentId: "orchestra",
  input: "Review this repository and propose the next runtime improvement.",
});

console.log(result.output);
console.log(await listSessions(runtime));
await stop(runtime);

First decisions a new team should make

Pick a backend that matches your workload

Prefer backend: deepagent when you want a higher-level orchestration shape with minimal application wiring. Keep backend: langchain-v1 for lighter direct-response flows or when your workspace explicitly wants the lighter backend shape.

Decide what stays runtime-owned

Approvals, recovery, inspection, queueing, and operator behavior should remain runtime concerns. Do not move them into prompt conventions or app-private glue unless the product boundary explicitly requires it.

Use published docs as the behavior contract

README, the developer docs, and RELEASE_NOTES.md describe what ships in each release. When you integrate or upgrade, treat them as the source of truth for stable runtime behavior.

What to read next

Once the first run path is clear, the next step is understanding the runtime contract itself: which concepts stay stable across backends, and which concepts remain upstream implementation details.