Agents

An agent is the configuration: the model, the system prompt, the tools and the skills. Create it once and reference it by id from every session.

const agent = await client.beta.agents.create({
  name: "Code Reviewer",
  model: "claude-sonnet-5",
  system: "You review pull requests.",
  tools: [{ type: "agent_toolset_20260401" }],
});

console.log(agent.id, agent.version);

Fields

Field	Type	Notes
name	string	Required.
model	string or object	A model id, or an object with an id and an effort level.
system	string	The system prompt. Null clears it.
description	string	For your own use. The model never reads it.
tools	array	The toolsets the agent may use. Null clears the list.
skills	array	The skills the session mounts. Null clears the list.
metadata	object	String to string. Echoed, never read.

Effort

The model field takes an effort level beside the id. The levels are minimal, low, medium, high, xhigh and max, and the default is low. coreloop adds off, for an agent that must not think at all. coreloop clamps a level the model cannot reach to the highest one it can.

await client.beta.agents.create({
  name: "Planner",
  model: { id: "claude-opus-5", effort: "high" },
  system: "You plan migrations.",
  tools: [{ type: "agent_toolset_20260401" }],
});

An update that repeats the model id and omits the effort keeps the stored level. An update that changes the id resets it.

Versions

Every update mints a version, and the response carries its number. A session resolves the agent at creation and holds a snapshot, so an update never reaches an existing session.

const updated = await client.beta.agents.update(agent.id, {
  system: "You review pull requests and name the risk in each one.",
});

console.log(updated.version); // 2

List the versions with GET /v1/agents/:id/versions. Pin one when you create the session.

await client.beta.sessions.create({
  agent: { type: "agent", id: agent.id, version: 1 },
  environment_id: environment.id,
});

Per-session overrides

A session can replace the system prompt, the model, the tools or the skills of the agent it pins, without minting a version. The override drops the effort level of the model it replaces.

await client.beta.sessions.create({
  agent: {
    type: "agent_with_overrides",
    id: agent.id,
    model: "openrouter/z-ai/glm-5.2",
    system: "You review pull requests in Go.",
  },
  environment_id: environment.id,
});

Tools

agent_toolset_20260401 is the hosted toolset. Its entry says which tools are enabled and their permission policies, described under Tools. An agent with no toolset can only write messages.

mcp_servers declares remote MCP servers by name and URL, up to 20. Each needs one mcp_toolset entry naming it, and each toolset needs its server. The echo fills in every default: a toolset without default_config reads as enabled and always_ask, and each configs entry takes the toolset's default. A URL whose host is localhost or a private IP address is refused; a name is resolved only when a turn connects.

Soon: custom entries. coreloop accepts them. Nothing runs them.

Archiving

POST /v1/agents/:id/archive takes the agent out of the list. It still reads by id. A session that names it gets invalid_request_error.

Endpoints

POST/v1/agents
GET/v1/agents
GET/v1/agents/:id
POST/v1/agents/:id
GET/v1/agents/:id/versions
POST/v1/agents/:id/archive

Quickstart Environments