Learn

Run a saved agent from code

Save a harness with its model, instructions, skills and connections once, then start each run with its id and a task.

When every run of a job uses the same model, the same instructions and the same tools, repeating them in each request is how they drift apart. A saved agent holds those choices in one place. In this lesson you save one, start a run from it with two fields, change it, and see what the model check refuses.

Save the agent

1. Pick a model it can run

A saved agent's model and effort must be ones the harness lists. getAgentsAvailable returns each harness with its models:

curl https://api.prix.dev/o/$ORG/agents/available \
  -H "Authorization: Bearer $RUSH_API_KEY"

Each model has a name, the value model takes, and the effort levels it accepts. A model with no effort list takes none.

2. Create it

createSavedAgent takes the harness and the choices every run of it uses:

curl -X POST https://api.prix.dev/o/$ORG/agents \
  -H "Authorization: Bearer $RUSH_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "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"]
  }'

The answer is 201 with the agent and its id. Skills are fetched and pinned when you save: a GitHub source to its commit, any other to its content. connections take ids or names, as on a run, and read back as [{"id": "...", "name": "deepwiki"}].

3. List what you have

curl https://api.prix.dev/o/$ORG/agents -H "Authorization: Bearer $RUSH_API_KEY"

listSavedAgents answers {"agents": [...]}, 50 a page. A key sees the saved agents of the admin who created it.

Run it

4. Start a session with agent_id

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 added this week.",
       "resources": [{"url": "https://github.com/acme/plugins"}]}'

The agent fixes the harness, model, effort, instructions, skills and connections, so the request names none of them. You can still add skills, connections and resources: the run gets exactly the connections the agent names plus the ones the run names. The session it returns carries agent_id, and so does every later read of it.

Change it

5. Edit only what changes

updateSavedAgent changes only the fields you send and keeps the rest:

curl -X PATCH https://api.prix.dev/o/$ORG/agents/$AGENT_ID \
  -H "Authorization: Bearer $RUSH_API_KEY" -H "Content-Type: application/json" \
  -d '{"effort": "max"}'

harness is fixed once saved. Each save is a new version of the agent: runs started after it use the new choices, and sessions already started keep what they started with. Send If-Match with the ETag you read to refuse an edit made on top of someone else's; a stale one is 412 STALE_ETAG.

6. Remove it

DELETE /o/{org}/agents/{id} answers {"id": "...", "deleted": true}. The agent starts no new run and is no longer listed or readable; runs already started from it finish.

What the model check refuses

The model and effort are checked against today's list each time you save, and again when a run of the agent starts:

Request	Answer
A `model` the harness does not list	`422 UNSUPPORTED_PROFILE`, with `UNKNOWN_MODEL` on the field
An `effort` the model does not take	`422 UNSUPPORTED_PROFILE`, with `INVALID_EFFORT` on the field
A field the route does not take	`400 UNKNOWN_FIELD`
A pinned skill file that has since changed	`422 SKILL_INVALID` until you save the agent again

A refused save names the field in fields, so you can show the exact problem to whoever configured the agent.

Saved agents covers saved agents in the console and the CLI, and Models explains how the model list is kept current.