Praecise Harness v1.1.0 Get started

Documentation · Running

Running it

sh
praecise dev                 # dashboard, chat, REST, MCP, traces — reloads on save
praecise run support "where is order 4021?"
praecise run handle message="I want a refund"
praecise list
praecise doctor              # everything wrong with this app, in one pass
praecise eval                # run the evals; non-zero if a case misses its bar
praecise capture support     # turn recorded exchanges, or a workflow's runs, into eval cases
praecise search refunds      # look through the app's registries for skills and plugins
praecise add refunds         # add a piece to the app, or a skill or plugin from a registry
praecise acp --agent support # serve an agent over stdio, for an editor
praecise ingest ./docs --store catalogue

doctor is the first thing to run when something is not working. It reports what will stop the app, then what merely degrades it, then what is only worth knowing, and exits non-zero only on the first kind — so CI can gate on it.

run also reads stdin, and takes --json.

The rest of the commands, and the options that are not tied to one section of this page:

sh
praecise init my-app --template support  # start from a template; --template alone lists them
praecise memory support      # what an agent carries, and what is proposed (see below)
praecise mcp                 # serve the app on stdin and stdout, for an MCP client
praecise package ./dist      # write a package someone else can run
praecise dev --port 4000     # the port, when it is not the config's or 3000
praecise eval --bail         # stop at the first case that misses its bar
--dir <path> the project directory, for every command; the default is the working directory
--force with init, add and capture: overwrite files that already exist
--template <name> with init: assistant, support, research or plan
--provider <name> with dev, run and eval: put one endpoint from models first, whatever the order they are declared in
--json with run, list, eval and the Praecise Cloud commands: output a program can read
--hosted with package: package for a server others reach, where a caller is not trusted because a person launched it and anything gated stays hidden until the caller proves itself
--agent <name> with acp, the agent to serve; with ingest --fields, the agent that does the extracting
--scope <name> with ingest: the scope the rows are written under

praecise check is doctor and praecise ls is list. praecise help prints the usage. Colour is left out when output is not a terminal or NO_COLOR is set. Each command reads .env from the project directory before loading the app.

praecise --version prints the version from 0.6.1; in 0.6.0 and earlier, use praecise -v.

While dev is up:

GET / dashboard
GET /<agent> chat UI
GET /w/<workflow> run form and history
POST /api/agents/<name> { input, thread?, attachments? }
POST /api/workflows/<name> the workflow's inputs
POST /api/functions/<name> a function's inputs; answered as { result }, through the guard
GET /api/runs the runs the app has kept
GET /api/runs/<id>/events one run, followed as a stream of its events
GET /api/threads, GET /api/threads/<id>, DELETE /api/threads/<id> conversations: listed (?agent= narrows), read, and forgotten
GET /api/resources/<name> what a resource reads, in its own media type
GET /api/traces, DELETE /api/traces the spans behind /traces as JSON, and clearing them
POST /api/events/<workflow> a CloudEvent; continues the run waiting for it, or starts one, once
POST /api/events a CloudEvent, published to every workflow that declared its type
POST /api/runs/<id> { approved, approver?, signature?, note? }
POST /api/runs/<id>/cancel stop a run; it is recorded as cancelled
POST /api/ui/<service> what an MCP App's view asks of the service that brought it
POST /v1/responses an agent through the Responses API; model is the agent's name
POST /mcp every agent and workflow, as MCP tools
POST /a2a the same app as an agent a peer delegates to (A2A 1.0, and 0.3 for a caller that speaks it)
POST /a2a/message:send, POST /a2a/message:stream the same over A2A's HTTP+JSON binding
GET /a2a/tasks, GET /a2a/tasks/<id> a peer's tasks, and one of them
POST /a2a/tasks/<id>:cancel, POST /a2a/tasks/<id>:subscribe stop a task, or follow it as a stream
/a2a/tasks/<id>/pushNotificationConfigs where a peer is told what a task does
GET /asyncapi.json the events this app receives and sends, as AsyncAPI
GET /.well-known/agent-card.json what a peer needs to know first
GET /ask, POST /ask a natural-language question, answered from this app's own store
GET /llms.txt a map of this app, for a model that arrived knowing nothing
GET /ai.json, GET /.well-known/ai-plugin.json the same, as JSON-LD
GET /robots.txt allows the front page, llms.txt and the server card, and disallows the routes that cost a model call
GET /traces what the last few requests actually did
GET /mcp/server-card what an MCP client needs before it connects
GET /.well-known/ai-catalog.json everything this origin offers, from one address
GET /.well-known/http-message-signatures-directory the public half of the key outbound requests are signed with; served only when botAuth is set
GET /health the app's name, what it contains by name, and its problems

A function that declares http: "POST /webhook" is also served at that method and path, with the same token and origin checks as /api: the body (or the query, for a GET) is its input and what it returns is the response.

That MCP line means anything that speaks it — a chat app, an IDE, another agent — can use this app without knowing it is one. The rest is the same idea for the other kinds of caller: a peer agent (A2A), a person's front end (AG-UI, below), a client written against the Responses API, an editor (the Agent Client Protocol), and a machine that arrived at the URL knowing nothing (llms.txt).

A peer agent

Beside JSON-RPC at /a2a, the same methods are served in A2A's HTTP+JSON binding under the same address, as the routes above; there are no tenant-prefixed paths. gRPC is not offered and is not listed on the card.

Push notifications. A peer speaking 1.0 may register a webhook for a task (CreateTaskPushNotificationConfig, and Get, List and Delete beside it, or taskPushNotificationConfig on the message that starts the task). Each change is posted to it as application/a2a+json. The address must be https and not a private or loopback one unless its host is allowed:

ts
await serve({ root, a2a: { push: { allowHosts: ["hooks.internal.example"] } } });

A peer speaking 0.3 is refused push, and registrations are not kept across a restart.

Signed cards. With botAuth set, the agent card is signed (JWS over the card's canonical JSON form). Before believing a peer's card:

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

const { card } = await fetchAgentCard("https://peer.example", { keys, unsigned: "refuse" });

keys is a key set already held for that agent, and trust names origins whose key sets are believed; the card's own origin is always among them. A card that is unsigned or cannot be verified is returned marked unverified, or refused with unsigned: "refuse". verifyAgentCard checks a card already in hand.

An interface the agent describes

When a request says which A2UI catalogs its renderer can draw (a2uiRendererCapabilities), the agent gets a show_surface tool. What it sends is checked as an A2UI 1.0 envelope and returned beside the answer: over A2A as a data part of type application/a2ui+json, over AG-UI as an ACTIVITY_SNAPSHOT, and over HTTP as a2ui on the response. What the person does on the surface comes back as a2ui input on the next request. Component contents are not checked against a catalog, and there is no renderer here: that is the front end's.

In an editor

sh
praecise acp --agent support

serves one agent over stdin and stdout in the Agent Client Protocol, for an editor that launches it. A prompt streams the agent's words and tool calls; a call the authority wants a person for is put to the editor as a permission request; and where the editor offers to read files or run a terminal, those are lent to the agent as tools for that session. The editor is given five minutes to answer a request (AcpOptions.requestTimeoutMs). Sessions can be created, loaded and cancelled. MCP servers an editor names when it creates a session are not connected, and plans, modes, listing sessions, authentication and audio are not offered.

As a Responses endpoint

POST /v1/responses answers in the shape of the Responses API, so a client written against that API can call an agent by putting its name in model:

sh
curl "$URL/v1/responses" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"support","input":"where is order 4021?"}'

input is a string or a list of items, stream: true streams the events, and previous_response_id continues the conversation. A client's own function tools are offered to the agent: a call comes back as a function_call item and the client answers with function_call_output, within two minutes unless serve({ responses: { toolWaitMs } }) says otherwise. Errors use the API's envelope. Refused by name, not ignored: background, a structured text.format, tool_choice other than auto or none, item references, file inputs, image URLs, the WebSocket transport and /compact.

Streaming

Any agent endpoint streams when you ask for text/event-stream. praecise's own event shape is the default; ?protocol=ag-ui switches to AG-UI, which anything built to render agents already understands, and ?stream= narrows what you get:

sh
curl -N -H "Accept: text/event-stream" \
  "$URL/api/agents/support?protocol=ag-ui&stream=messages,tools" \
  -d '{"input":"where is order 4021?"}'

messages is the agent's words, tools what it reached for, updates how the answer was routed, custom your own notes, values lifecycle only. They combine.

A workflow streams too: POST /api/workflows/<name>?protocol=ag-ui with Accept: text/event-stream. A run that stops at an approval gate ends its stream with RUN_FINISHED carrying an interrupt, and is continued by a request whose resume answers it, under the same rules as POST /api/runs/<id>.

Seeing what happened

praecise dev collects OpenTelemetry GenAI spans in memory and renders them at /traces — a timeline per request, with how long each call took, tokens in and out, which model, and which failed. In production you pass your own tracer and the spans go to whatever you already run; praecise adds no OpenTelemetry dependency, because the convention is in the data and the transport is yours.

Every /api/* route, /mcp, /a2a, /v1/responses, /traces and a function's own http route needs the bearer token the server prints on startup. Pass it as Authorization: Bearer <token>. The discovery documents (llms.txt, ai.json, the agent card, asyncapi.json) and /ask answer without it and show a caller who has not presented it only what is open; the server card, the AI catalog, robots.txt and /health are the same for everyone.

Edit this page on GitHub · Read it as Markdown

    Type to search. Arrow keys move, Enter opens.