MIT

Overview

Build an agent that is efficient by construction.

@caveman-ai/agent is a TypeScript runtime for tool-using agents. You define the agent, its tools, context, memory, output contract, and evals in one source graph. Every successful run returns a receipt. A run that fails after spending throws with the same partial receipt attached.

It does not need a Caveman account. On a machine with Node and a provider key it calls the provider directly, in observe-only mode: no local transform, and no efficiency claim. When the local Caveman engine is running, eligible calls can run in optimized mode. Local figures stay inferred. Nothing in this package emits verified.

Package: @caveman-ai/agent
Source version: 0.2.0
On npm today: 0.1.0
Runtime: Node.js 22.19 or newer.
Licence: MIT.

The pages that follow document the 0.2 source in JuliusBrussee/agent-sdk. npm still ships 0.1.0, which is an older surface. Use the checkout if you are testing anything described here.

How a run is assembled#

Definition. agent(), tools, context, memory, output, evals. One source graph.

↓

Runtime. Sandbox, budgets, breakers, compaction, receipts. Tools never skip schema, timeout, or abort checks.

↓

observe-only Direct to your provider. Default when the local engine is not running.

optimized Local engine reachable. Eligible transforms and recovery can run. Still inferred.

↓

Receipt. Model calls, tool calls, catalog cost basis, stop reason, compactions, subagents, resume state. claimBasis: "inferred".

A mixed graph that partly bypassed the local runtime reports observe-only. The label under-claims rather than averaging.

auto() picks a configured model. It does not classify tasks or route between models. That is a different product; see Model router.

Smallest agent#

typescript

import { agent, auto, run } from "@caveman-ai/agent";

const support = agent({
  id: "support",
  instructions: "Answer from policy. Never invent policy.",
  model: auto(),
});

const result = await run(support, "Can I get a refund?");
console.log(result.text);
console.log(result.mode);
console.log(result.receipt);

That run works with nothing but Node and a provider credential. result.mode is observe-only there.

Prefer a directory if the agent will grow:

text

support-bot/
├── instructions.md
├── agent.ts
├── skills/
├── tools/
├── subagents/
└── evals/

typescript

import { loadAgentDir, run } from "@caveman-ai/agent";

const support = await loadAgentDir("./support-bot");
const result = await run(support, "Where is order A-123?");

Skill descriptions enter the stable prefix. Skill bodies stay on disk until the model asks for one, so adding a large skill does not enlarge every request.

What lives in this product#

The Agent SDK is one thing you install, with several surfaces behind it.

Install

Source build, doctor, and the npm version gap.

Create an agent

The initializer that writes a typechecking project.

Define an agent

agent(), context, output, filesystem, subagents.

Tools

Effects, result policies, schemas.

Run a turn

run, stream, receipts, budgets, durable resume.

Sandbox

required, fixture, and host.

Memory

Next-turn recall, local only.

Compaction

Recover, summarise, clamp, stop.

Programmatic tools

One caveman_code cell.

Connect

Paginated provider data, fail closed.

Evals and builds

Profile, search, freeze, holdout.

Adapters

Exact-pinned framework lanes.

The TypeScript SDK is a different package. @caveman-ai/sdk talks to a configured Caveman service. @caveman-ai/agent is the agent runtime. Installing one does not start the other.

The Agent SDK repository also ships a frozen wire-contract package used by other Caveman products. It is not this runtime, and this site does not document it.

What it will not do#

It will not mint verified savings. claimBasis is inferred on every public run. USD figures are public-catalog list-price subtotals, never invoices. Token counts are not money.

It will not silently call itself optimized. If any call in the graph went straight to the provider, mode is observe-only.

It will not invent a routing policy from auto(). A pinned string model is a pinned string model.

A lock hash binds reviewed bytes and policy. It is not a signature, a runtime attestation, or proof that those bytes served production traffic.

Claude locked compilation is refused. The public Claude lane stays unlocked.

Do not publish a savings percentage from a local build report.