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:

{
  "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 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:

{
  "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 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 or Use the API for executable request examples.