Concepts

Saved agents

Save a harness with its model, effort, instructions, skills and connections once, then start every run of it with one agent_id.

View .md

When you run the same kind of work again and again, the request should not repeat the setup each time. A saved agent keeps it: a harness with its model, effort, standing instructions, skills and connections. A run names it with agent_id and sends only the task.

Saved agents live at /o/{org}/agents. They belong to the person who saved them, not to the org. An API key reaches its creator's saved agents.

04Every run starts from the same setup

Scene. A saved agent fixes the harness, model, effort, instructions, skills and connections; each run names it with agent_id and adds its own input.

Save one

POST /o/{org}/agents:

{"name": "Plugin reviewer", "harness": "claude", "model": "claude-opus-5-5", "effort": "high",
 "instructions": "Review each plugin.json and report every problem with its file and a fix.",
 "skills": [{"url": "https://github.com/anthropics/skills/tree/main/skills/frontend-design"}],
 "connections": ["deepwiki"]}

Field	What it fixes
`name`, `description`	How it is listed.
`harness`	`claude`, `codex` or `opencode`. It cannot change after saving.
`model`, `effort`	A model and effort level `/agents/available` lists for the harness. Without `model`, the harness's first model.
`instructions`	Standing instructions every run receives, up to 16 KiB.
`skills`	Up to 10 skills by URL, as on a run.
`connections`	Ids or names of your own connections, as on a run. They read back as `[{"id", "name"}]`.
`capabilities`	`browser` and `computer`, when the agent should use them.

A model or effort the catalog does not list is 422 UNSUPPORTED_PROFILE, with per-field codes such as UNKNOWN_MODEL and INVALID_EFFORT. A field the route does not take is 400 UNKNOWN_FIELD.

Skills are pinned

Skills are fetched and pinned when you save: a GitHub source to the commit its branch or tag points at, any other source to its content. Every run of the agent loads exactly that pin. If a pinned file changes upstream, runs are refused with 422 SKILL_INVALID until you save the agent again, which pins the new content.

Run one

Send the agent's id instead of a harness:

curl -X POST https://api.prix.dev/o/$ORG/sessions \
  -H "Authorization: Bearer $RUSH_API_KEY" -H "Content-Type: application/json" \
  -d '{"agent_id": "'$AGENT_ID'", "input": "Review the plugins changed in PR 412."}'

The agent fixes the harness, model, effort, instructions, skills and connections. A run can add skills, connections and resources of its own on top. The session names its agent_id.

A run of a saved agent gets exactly the connections the agent names, plus any the run names in connections, and none of your others. See Connections.

The model is checked every time

The agent's model is checked against the catalog when you save it and again at every run. If the catalog has changed since you saved, the run is refused with 409 CATALOG_REFRESH_REQUIRED instead of running a different model. Edit the agent to pick a listed one.

Edit, revisions and delete

PATCH /o/{org}/agents/{agent} changes only the fields you send, and the result is checked against today's catalog. Each edit makes a new revision. Sessions already started keep the revision they started with; new sessions use the latest.

Every read returns an ETag for the revision you read. Send it as If-Match on a PATCH or DELETE to make sure nobody changed the agent since; a stale one is 412 STALE_ETAG. It is optional.

DELETE /o/{org}/agents/{agent} answers {"id": "…", "deleted": true}. The agent starts no new session and is no longer listed or readable. Runs already started from it run to the end.

GET /o/{org}/agents lists yours as {"agents": [...]}.