# Saved agents

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

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.

_Figure: save once run many, on the page at /docs/concepts/saved-agents._
## Save one

[`POST /o/{org}/agents`](/docs/api/create-saved-agent):

```json
{"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`](/docs/api/get-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:

```bash
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](/docs/concepts/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}`](/docs/api/update-saved-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}`](/docs/api/delete-saved-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`](/docs/api/list-saved-agents) lists yours as `{"agents": [...]}`.