As an SDK, without a folder
The folder is the default and not the only way in. The same app can be a value you import:
import { createApp, agent, fn, guard } from "@praecise/harness";
const app = await createApp({
name: "acme",
config: { models: { /* ... */ } },
agents: {
support: agent({ role: "Help.", description: "Answers questions.", tools: ["lookup"] }),
},
functions: {
lookup: fn({
description: "Look up an order.",
input: { id: "the order id" },
effect: "read",
run: ({ id }) => ({ id, status: "delivered" }),
}),
},
guard: guard((attempt) => (attempt.effect === "write" ? "read-only today" : undefined)),
});
await app.ask("support", "where is order 12?");The record key is the name, which is the rule the folder already uses:
agents/support.ts and { agents: { support } } are the same agent by the same name.
Reach for this when the folder cannot be one:
- You are shipping agents in a package. A library cannot ship a folder — it can ship one to copy, which stops receiving fixes the moment it is copied. It can export an app, or a piece of one.
- There is no filesystem to scan. An edge worker, a bundled binary, a browser. The
loader needs
readdirand dynamicimportof arbitrary paths; a bundler needs to see imports statically. Those requirements are opposed, and this side satisfies the second. - The app is assembled, not written. Generated from a spec, composed per tenant, built from parts.
Both doors produce the same project and run the same checks. An agent with no role, memory pointing at a store that does not exist, a workflow with a cycle — each is refused the same way in the same words, because two front doors with two standards is a framework where a bug report cannot be reproduced.
defineApp returns the project without starting it, so you can inspect warnings and
faults first. createApp refuses to start a faulted app rather than serving one that is
missing the agent the next request names.
Changing agents while the app runs
A running app can take a new agent, a new version of one, or lose one:
await app.add(agent({ name: "billing", role: "Answer billing questions." }));
await app.replace(agent({ name: "support", role: "Customer support for Acme.", tools: ["lookup"] }));
await app.remove("billing");The agent is checked and planned as it would be at load. Requests already under way finish on the plan they started with; the next request for that name gets the new one. MCP clients are not sent a list-changed notification.
Testing without a model
@praecise/harness/testing is a model that says what a test tells it to:
import { createApp } from "@praecise/harness";
import { scriptedModel } from "@praecise/harness/testing";
const model = scriptedModel([
{ tool: { name: "lookup", args: { order: "9" } } },
"It shipped.",
]);
const app = await createApp({ config: { models: model.models }, agents, functions });
const answer = await app.ask("support", "where is order 9?");
model.requests; // every request the app made, in orderEach entry is one reply: text, a tool call, or a function of the request.
scriptedEndpoint does the same one level down, as a fetch that answers with
the bodies it is given, and systemText reads the instructions out of a request.