Praecise Harness v1.1.0 Get started

Documentation · Building

Agents

ts
import { agent } from "@praecise/harness";

export default agent({
  role: "Customer support for Acme. Warm, brief, never guesses.",
  knows: ["memory/policies.md"],
  tools: ["refund"],
  rules: ["Never promise a refund date.", "Escalate anything about a chargeback."],
  greeting: "Hi — what can I help with?",
});

Every field but role is optional. memory/** is already included for every agent, so knows is for narrowing, or for pulling in something from elsewhere.

When the documents do not fit in the agent's instructions, none of them are dropped. The instructions carry an outline of every document — its name, its size and its headings — along with the documents that still fit whole, and the agent gets one read_knowledge tool to read a document, or a single section of it by heading. The tool offers only the names that exist, and an unknown name or heading is answered with the ones that do. A folder that fits is composed as it always was and gets no tool. If the outline itself cannot fit, the documents it leaves out are named in the app's problems.

Ask for structured data instead of prose:

ts
export default agent({
  role: "Sort an incoming support message.",
  quality: "fast",
  memory: false,
  returns: {
    category: "one of: refund, shipping, account, other",
    urgency: "low, normal, or high",
    summary: "one sentence",
  },
});

returns takes three forms. Fields and hints, as above, constrain the structure and leave each value as text. A JSON Schema object asks for typed data. A Standard Schema validator, which is what most validation libraries hand over, also types answer.data:

ts
const triage = agent({
  role: "Sort an incoming support message.",
  returns: Ticket, // any Standard Schema validator
  read: (ticket) => (ticket.urgency === "high" && !ticket.summary ? "A high-urgency ticket needs a summary." : undefined),
});

const answer = await app.ask(triage, "My order never arrived.");
answer.data.category; // typed by the schema

A JSON Schema or a Standard Schema is sent to the endpoint for constrained decoding where it has that, and the answer is checked against it either way. read is a check of your own on the result: say nothing to accept it, or a sentence to refuse it. An answer that fails either is asked for again with more depth, then from a stronger model, and after the strongest the request ends in a ShapeError carrying issues and the text that failed. The JSON Schema keywords that are checked are listed in CHECKED_KEYWORDS; a schema that uses one that is not (UNCHECKED_KEYWORDS: $ref, allOf, pattern, format and others) is reported in the app's problems.

quality is "fast" | "balanced" | "best" and is the only dial. It is not a model name — it says how much room there is to work in, not which model answers.

Which model answers

That is decided per request, before anything is spent, from the size of the request and what has to be read to answer it. An easy question goes to the cheap model and costs one call. A large one goes straight to a stronger model, because starting cheap and climbing would mean paying twice and making the second model read everything again from cold.

When a request lands near the edge of what a model handles, that model is asked the same question more than once, at the same time, and the answers are compared against each other. A model that knows the answer gives it twice; a model that is guessing does not guess the same way twice. Only then does the agent climb.

Nothing asks a model how sure it is. A model asked that will say it is sure, and an answer wrapped in a report on itself is worse than the answer.

The framework keeps a record of what it chose and what came of it, under .praecise/routing/. The fact worth having is the one it would otherwise never learn: whether a stronger model, once asked, said anything different. An agent whose climbs keep landing on the same answer stops climbing so readily.

None of that is configuration. It is what quality means.

Bounding one request

A caller can narrow the ladder for a single request, never widen it:

ts
// economise: this request may not reach the strongest rung
await app.ask("support", question, { ceiling: "balanced" });

// the cheap answer was rejected: re-ask without starting on that model again
await app.ask("support", question, { floor: "balanced" });

ceiling is the most expensive rung the request may reach. It trims the agent's declared ladder rather than picking one rung, so the router still escalates below it. floor is the cheapest rung it may start on. Lifting a ceiling does not move a request up, because the router still enters cheapest-first; a floor is how a caller that already rejected the cheap model's answer says not to ask it again.

Both can only remove rungs the agent declared, never add one, so neither can reach a model its author did not put on that agent. With both set the floor is clamped to the ceiling: a floor above the ceiling gets the ceiling, never an empty ladder.

A caller can narrow what the agent may use the same way:

ts
await app.ask("desk", question, {
  allow: { tools: ["lookup"], knows: ["pricing"] },
  maxCalls: 12,
});

allow.tools lists what the agent may still call and allow.knows what stays in its instructions. Both only take away. Anything else the agent was given is not offered and is refused if it is called anyway, through tool search, through code mode, or by an agent this one asks, which is held to the same lists. A name the agent does not have is an error. A live session is not narrowed.

maxCalls is the most model calls the request may make, counting tool turns, samples, climbs, summaries and the calls of any agent asked on the way. Reaching it ends the request with CallLimitReached. limits.calls in the config is the default for requests that do not say.

Who a request is for

ts
await app.ask("support", question, {
  caller: { person: "u_1", plan: "pro" },
  context: { tenant },
});

caller is who the request is for, as the app vouches for them, and context is anything else the app wants to travel with it. Both reach the guard and the authority on every tool call (attempt.caller, attempt.context), the second argument of every function called, the meter, and any agent this one asks, in the background or not. Neither is sent to a model, a trace or a recording. startWorkflow, resumeWorkflow and callTool take the same two.

Sending more than text

A question can carry anything that has a media type: a picture, a recording, a film, a PDF, a sensor log, a robot's joint state, a table, a scene.

ts
await app.ask("support", "What does this invoice say is due?", {
  attachments: [{ mime: "application/pdf", url: "https://files.example.com/invoice.pdf" }],
});

An attachment is a media type and either the bytes (data, base64) or a url the endpoint can fetch. Over HTTP it is attachments on the request body, up to ten, and a url must be https: or data:. An attachment belongs to the request it came with: a named conversation keeps what was said, not what was shown.

What the model is shown follows one rule, the same on every wire:

  1. The endpoint reads it. Images and PDFs on messages and responses; images on chat; images, audio, video and PDFs on contents and interactions. A chat server that takes audio or video says so with takes: ["image", "audio", "video"] on the endpoint. These are sent as they are, in the shape the wire has for them.

  2. A reader renders it. Data no model reads is shown as a faithful rendering, placed after the question:

    Media type What the model is shown
    application/senml+json (RFC 8428 sensor measurements) each channel as a series: count, span, min, max, mean, deviation, and 24 evenly spaced values
    JSON tensors in the Open Inference Protocol form ({ name, shape, datatype, data }): robot state, action chunks, latents each tensor's name, shape, type, range and first values
    text/csv, text/tab-separated-values columns with their statistics, and the first and last rows; a short table whole
    model/gltf+json what the scene contains, counted and named
    text/*, JSON, XML, YAML the text, cut to fit
  3. Neither. It is left out, and answer.notes says which attachment and why.

The data is never rewritten: a tool or a store handed the same attachment gets every sample. Teach the framework another kind of data with a reader:

ts
import { registerReader } from "@praecise/harness";

registerReader("a robot log", "application/vnd.mcap", (attachment) => summarise(attachment));

A function returns something other than text with attach, and an MCP tool that returns an image, audio or a file has it handed to the model the same way rather than spelled out as base64:

ts
import { attach, fn } from "@praecise/harness";

export default fn({
  description: "Take a picture with the front camera.",
  effect: "read",
  run: async () => attach("Frame 12.", { mime: "image/jpeg", data: await frame() }),
});

What a model makes that is not text (an image from contents or interactions, speech from chat) comes back on answer.attachments. Asking an endpoint for it is the endpoint's own field, set through body in models.

A film an endpoint cannot watch is taken apart by a decoder the app registers. One ships, over an ffmpeg binary the app points to:

ts
import { ffmpegDecoder, registerDecoder } from "@praecise/harness";

registerDecoder("ffmpeg", "video/", ffmpegDecoder({ bin: "/usr/bin/ffmpeg", every: 2, frames: 16 }));

The stills are sent as images. The sound is sent as audio where the endpoint takes it, transcribed by the cheapest rung that does where it does not, and otherwise left out with a note.

A large attachment is uploaded once. Past a size, an attachment is sent through the endpoint's files API and named from then on instead of being sent inside every request: past 5 MB on messages, 20 MB on responses, contents and interactions, and not at all on chat unless the endpoint says uploads: true. uploads: { over, keep } sets the size in bytes and how long the endpoint is asked to hold the file; uploads: false turns it off. What was uploaded is remembered for the life of the process. An upload that fails is sent inside the request, with a note.

Large media can be kept by address. app.blobs holds bytes under the SHA-256 of what they are, on disk under .praecise/blobs unless the app brings a store:

ts
import { detach, sweepBlobs } from "@praecise/harness";

const light = await detach(app.blobs, attachment); // { mime, blob: "sha256:…" }
await sweepBlobs(app.blobs, live);                  // remove what `live` does not name

An attachment carried as blob costs its address wherever it is written down, and its bytes are put back before a model or a reader is shown it. Bytes are hashed again when read. Nothing is removed until sweepBlobs is run, and a sweep leaves anything kept within the last day (olderThan, in milliseconds), because a blob is written before the row that names it; dryRun: true reports what would go without removing it. An HTTP caller cannot send a blob.

More formats, as a plugin. @praecise/harness/formats adds readers for robotics, scene and array data:

ts
import { defineConfig } from "@praecise/harness";
import { formats } from "@praecise/harness/formats";

export default defineConfig({ plugins: [formats()] });

It reads MCAP, ROS 1 bags, LeRobot dataset metadata, Parquet footers, Arrow IPC schemas, PCD and PLY point clouds, Gaussian splats (PLY and .splat), USD (.usda in full; .usdc and .usdz described) and .npy/.npz arrays, and identifies a ROS 2 .db3 bag. Each rendering ends by saying what was not read. formats({ only }) and formats({ except }) choose among them, and registerFormats() registers them without a plugin. MCAP chunks compressed with zstd need Node 22.15 or newer.

Work that takes a while

An agent may go to its tools sixteen times in one request before it has to answer; turns on the agent changes that. What keeps long work inside the endpoint's context is not the count:

  • A tool result too long to hand over is kept whole for the length of the request. The agent sees the start and the end of it and a name, and reads the rest with read_result, by line or by search.
  • When the record of the work passes half the endpoint's room, older tool results are replaced by a line saying they were cleared and can be asked for again. The calls themselves stay.
  • If that is not enough, the model is asked once for notes on the earlier work, and those notes replace it. The question itself is never rewritten.

Each of these is reported in answer.notes. Calls in one turn that only read (effect: "read") run together; anything else runs in the order the model asked.

Many questions at once

askMany hands many questions for one agent to the endpoint's batch API:

ts
const results = await app.askMany("triage", messages);

for (const { answer, error } of results) {
  // one entry per question, in the order asked
}

Each entry is an answer or the error that question ended in. An agent's tools run between batches. Batching ships for the messages, responses, chat and contents shapes; on interactions, or on an endpoint that says batch: false, the requests are sent one at a time. poll, within, linger, signal and onBatch are the options, and registerBatch teaches the framework the batch API of a shape of your own.

A live session

A conversation over one connection, for voice and anything else that is not a request and a reply. The endpoint says where sessions run:

ts
house: { url: "https://models.example", credential: "HOUSE_KEY", speaks: "responses", realtime: { model: "…" } },
ts
const session = await app.open("desk", { output: "audio" });

session.send({ text: "Where is order 4021?" });

for await (const event of session) {
  if (event.kind === "audio") play(event.data);
  if (event.kind === "turn" && event.state === "ended") break;
}

await session.close();

send takes text, audio or attachments; interrupt() stops the agent speaking. Events are text, audio, transcript, speech, turn, tool, tool result, refused, usage, note, error and closed. The agent's tools are called through the same guard and authority as in a request.

Sessions run over WebSocket. Protocols ship for the responses, chat, contents and interactions shapes, not for messages; registerSession adds one. A session has no failover: a connection that drops is closed, not reopened on another endpoint. A named conversation's history, recall and selves are not carried into a session, and images are the only media that can be sent beside audio and text.

One agent asking another

Name an agent in another agent's tools and it becomes a tool:

ts
// agents/lead.ts
export default agent({
  role: "Answer questions about an account.",
  tools: ["researcher", "refund"],
});

The agent asked starts from its own role and tools and sees nothing of the conversation that led to it, so the task it is given has to stand on its own. Only its answer comes back; the results it read along the way never enter the asking agent's context. Its tokens are counted in the asking request's usage, the call goes through guard.ts like any other, and what it read marks the answer tainted the same way. A request may go three agents deep (limits.depth); past that the model is told why not.

A name in tools is a function if functions/ has it, a service if tools/ has it, and an agent otherwise.

With background: true the asking agent may start another agent and carry on:

ts
export default agent({
  role: "Answer questions about an account.",
  tools: ["researcher"],
  background: true,
});

Calling researcher with background: true returns a handle at once. The agent then has check_agent, steer_agent, cancel_agent and collect_agent to see how the other is getting on, tell it something more, stop it, and take its answer. Four may be working at once in one request, and any still working when the request answers are stopped.

Advice from a stronger model

ts
export default agent({
  role: "Triage incoming tickets.",
  quality: "best",
  tools: ["lookup"],
  advisor: true,
});

With advisor: true the agent gets a consult tool. Calling it sends the agent's instructions and the work so far to the strongest model on its ladder, which says what it would do next in at most about two thousand tokens and does none of the work. The cheaper model carries on. It is not offered while the strongest model is itself answering.

An agent that remembers who it is

An agent starts every request from its role, its rules and its tools. A self is what persists around it: an identity, what it has learned, what it has been reading, and what came of its earlier work. An agent declares the self it is, and the harness does the rest on every request, however the agent is reached:

ts
export default agent({
  role: "Find the pieces in the catalogue that carry an idea.",
  tools: ["search-products"],
  self: "design",
});

Before the request, the self's context is read and placed after everything stable in the system prompt, as the self's own notes. After it, what was asked and answered is recorded against a ticket, so that what comes of the answer later reaches exactly what the self drew on.

Where selves live is the app's choice, in praecise.config.ts:

ts
export default defineConfig({
  selves: { url: "https://selves.example.com", credential: "SELVES_KEY" },
});

url may also come from SELVES_URL. The provider speaks a small protocol:

POST {url}/selves/{handle}/context {surface, task, interactive} → {preamble, ticket, lessons}
POST {url}/tickets/{ticket}/work {brief}
POST {url}/tickets/{ticket}/outcome {signal: -1..1, label, detail?, by?}
PUT {url}/selves/{handle} create a self from the agent's template, with adminCredential (default SELVES_ADMIN_KEY)

Or bring your own provider in code: App.load({ selves: myProvider }) with anything that implements SelfProvider.

A self per person. A handle with {person} is a self for each person the app serves, created from a template the first time they ask:

ts
self: {
  handle: "coach-{person}",
  template: { name: "Coach", charter: { purpose: "Remember what works for this person." } },
},

The person is the one the caller names (caller.person in ask, person on the HTTP body, _meta["com.praecise/person"] on an MCP tools/call), vouched for by whoever holds the app's token. A caller can name where it is asking in the same way (surface, or _meta["com.praecise/surface"]), which picks the self's persona for that surface. It is reduced to a digest before it becomes part of a handle.

Rating an answer. Every answer from a self carries answer.self: the handle, what it drew on, and a ticket. Set SELVES_TICKET_SECRET (or ticketCredential) and the ticket is bound to the person it was issued to, which makes it safe to send to their browser. A rating comes back through app.rate(ticket, verdict, person) or POST /api/selves/outcome, optionally with a check: something the app measured about what came of the answer ({ name, passed, failures }). A rating is credit; a failed check is what a self learns from; a ticket issued to somebody else reads exactly like one that has expired. The ticket also arrives early, as a self progress event, and in _meta["com.praecise/self"] on an MCP result.

One memory. A self already remembers, so an agent that is a self cannot also declare memory: two records of the same life would disagree.

What a self is sent. After an answer, the provider is sent what was asked, what was answered and which tools were used. An agent and an app each have a say over that:

ts
self: {
  handle: "coach-{person}",
  record: (work) => ({ ...work, answer: redact(work.answer) }),
},

record returns what is sent instead; returning nothing sends nothing. The app's beforeRecord hook in hooks.ts is asked after it, with what it left, and answers the same way. One that throws sends nothing.

Memory, not a dependency. If the provider cannot be reached, the agent answers as it would have without its self and says so in a note. selves: { required: true } makes that an error instead.

Edit this page on GitHub · Read it as Markdown

    Type to search. Arrow keys move, Enter opens.