Agents
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:
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:
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 schemaA 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:
// 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:
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
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.
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:
-
The endpoint reads it. Images and PDFs on
messagesandresponses; images onchat; images, audio, video and PDFs oncontentsandinteractions. Achatserver that takes audio or video says so withtakes: ["image", "audio", "video"]on the endpoint. These are sent as they are, in the shape the wire has for them. -
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, latentseach tensor's name, shape, type, range and first values text/csv,text/tab-separated-valuescolumns with their statistics, and the first and last rows; a short table whole model/gltf+jsonwhat the scene contains, counted and named text/*, JSON, XML, YAMLthe text, cut to fit -
Neither. It is left out, and
answer.notessays 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:
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:
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:
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:
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 nameAn 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:
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:
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:
house: { url: "https://models.example", credential: "HOUSE_KEY", speaks: "responses", realtime: { model: "…" } },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:
// 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:
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
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:
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:
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:
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:
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.