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