# Agents and runs

Save an agent once, then run it with different inputs. AgentRun keeps the revision used by each run, so changing today's instructions does not rewrite yesterday's history.

## Define the agent

In the console, choose **Agents → New agent**. Set its instructions, choose an available harness and model, and grant only the tools it needs.

The equivalent API request is `POST /v2/agents`:

```json
{
  "definition": {
    "id": "release-notes",
    "name": "Release notes",
    "instructions": "Write release notes from the changes provided. Do not invent changes.",
    "harness": "pi",
    "tools": [],
    "learning": true
  }
}
```

`harness` selects the adapter: `pi`, `claude-agent`, `codex`, or `opencode`. Availability depends on the server's installed dependencies and credentials. Omitting `model` uses its default model. `learning: true` opts this agent into learning between runs.

Use [compute settings](/docs/durability-and-compute) on the definition when it needs a box. Do not put compute settings on the run request.

## Start and inspect a run

Send `POST /v2/agents/release-notes/runs`:

```json
{
  "input": {
    "content": "Write release notes: added CSV export; fixed the date filter."
  },
  "max_cost_usd": 1
}
```

The response identifies the new run. Read `GET /v2/runs/{run_id}` for its status, result, error, pending question, and cost. Read `GET /v2/runs/{run_id}/timeline` for its activity and `GET /v2/runs/{run_id}/files` for its output files.

| State | What to do |
| --- | --- |
| Queued or working | Follow the timeline while the agent runs. |
| Input required | Inspect `pending`: it may need an answer, a budget decision, or a follow-up after stopping. |
| Completed | Read the result. An agentic run can accept a follow-up with its existing conversation. |
| Failed or cancelled | Inspect the error or cancellation, correct the cause, and start a new run. |

## Answer, stop, or cancel

`POST /v2/runs/{id}/messages` with `{"content":"..."}` answers a question, steers an active agent, or follows up on a completed or stopped agentic run.

**Stop** ends the current turn and leaves the conversation available for a new turn. **Cancel** ends the run; a cancelled run cannot continue. These are different from crash recovery, which resumes interrupted execution from saved state.

Workflow runs have their own pause/resume behavior and do not accept agentic chat messages. See the [server API reference](/docs/server-reference#what-it-serves) for those routes.

## Revise without losing history

Edit the agent in the console to create a revision. With the API, send the new definition wrapped as `{definition}` to `PUT /v2/agents/{id}/definition`. Use the `ETag` returned by `GET /v2/agents/{id}` in `If-Match` to detect concurrent edits. Inspect revisions at `GET /v2/agents/{id}/revisions`, and choose the current revision with `POST /v2/agents/{id}/current` and `{"revision":"REVISION_ID"}`.

A run pins the revision it starts with. Archive an agent or run to hide it from default lists while retaining its history.

Continue with [Models and API keys](/docs/model-keys) or [Use the API](/docs/platform-api) for executable request examples.