Praecise Harness v1.1.0 Get started

Documentation · Getting started

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:

ts
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 readdir and dynamic import of 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:

ts
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:

ts
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 order

Each 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.

Edit this page on GitHub · Read it as Markdown

    Type to search. Arrow keys move, Enter opens.