Skip to main content

Agents

Agents are versioned definitions. Sessions resolve an agent version once and store an immutable snapshot.

Create an agent​

POST /v1/agents

{
  "name": "Repository assistant",
  "model": "claude-model-id",
  "system": "Work carefully and explain changes.",
  "description": "Helps maintain a repository",
  "tools": [],
  "mcp_servers": [],
  "skills": [],
  "metadata": {"team": "platform"}
}

Required fields:

  • name: non-empty string;
  • model: model ID string or an object with a non-empty id.

The object model form also preserves supported effort, speed, and inference_geo values. effort accepts either a level string such as "high" or the tagged object {"type":"high"}; responses use the tagged object form. An explicit non-empty inference_geo is forwarded on every working and outcome grader request. On Agent update, model is whole-object replacement for this field: omitting inference_geo clears a previous pin. Optional collection and metadata fields may be omitted or supplied with their documented array/object shape; explicit null is not a create-time default.

Coordinators declare a roster with the documented multiagent topology:

{
  "type": "coordinator",
  "agents": [
    "agent_latest",
    {"type": "agent", "id": "agent_pinned", "version": 3},
    {"type": "self"}
  ]
}

The roster contains 1–20 distinct Agents. An ID string and an Agent object without version resolve to the latest active Version at write time; an object with version selects that exact Version. self resolves to the coordinator Version being written and may appear at most once. Responses and stored Agent history contain only concrete {"type":"agent","id","version"} references, so later updates to a referenced Agent do not change an existing coordinator. Creating a Session expands those pins into the full immutable definitions returned in session.agent.multiagent.agents; child Threads will execute those Session-owned snapshots rather than re-resolving Agent resources. Archived, missing, duplicate, and nested coordinator references are rejected. If the coordinator pins model.inference_geo, every independently referenced Agent must pin the same value; if the coordinator leaves it unset, every member must also leave it unset. A model change that would violate this invariant must replace or clear the roster in the same Agent update. Ordinary roster entries can execute as persistent child Session Threads with independent context, events, usage, and Workflow state. See the multi-agent guide for an end-to-end example and Session Threads for the public observation API.

The pinned Anthropic Go SDK v1.63.1 also exposes one optional advisor roster entry:

{"type":"advisor","model":"claude-opus-5"}

It must use that exact shape, appears last in stored responses, and has the reserved runtime identity anthropic.advisor. Mango rejects duplicate Advisor entries and ordinary Agents with that name. The Advisor is available only to the primary Agent; it does not appear in list_agents and cannot be targeted by send_to_agent. Mango exposes it to the executor as an ordinary no-argument client tool, runs the configured Advisor model in a separate tool-free request, and returns the review through an ordinary tool result. The harness therefore does not depend on Anthropic's provider-native Advisor beta or an executor/Advisor compatibility matrix. Ordinary child limits such as max_uses and max_tokens do not apply to this roster variant.

Agents written by releases that accepted opaque multiagent objects remain readable without inventing historical version pins. An unresolved legacy topology is read-only: replace or clear multiagent before changing the Agent or creating a new Session.

Custom Skills use the documented tagged reference:

{"type": "custom", "skill_id": "skill_...", "version": "latest"}

version may be omitted or set to latest. Mango validates the Skill and stores the concrete immutable Version in the Agent response and version history. Updating unrelated Agent fields preserves that pin; replacing skills resolves the replacement list again. The latest active Agent Version also holds a relational retention pin, so its Skill archive cannot be deleted until the list is replaced or the Agent is archived. Anthropic-managed references return 422 because Mango does not mirror their archives.

Agents stored before tagged references were enforced may still return a read-only legacy Skill value. The OpenAPI response union marks that compatibility branch explicitly. Mango preserves the value across reads and unrelated Agent updates, but it must be replaced with current custom references before the Agent can start a new Session.

A successful create returns 200 and version 1.

Get and list​

GET /v1/agents/{id}
GET /v1/agents
GET /v1/agents/{id}/versions

GET /v1/agents/{id} returns the latest version. The versions route returns stored versions in ascending version order. It supports the documented limit and opaque page parameters; limit defaults to 20 and has a maximum of 100. Its response contains data and nullable next_page fields.

The Agent list supports the documented created_at[gte], created_at[lte], include_archived, limit, and page parameters. limit defaults to 20 and has a maximum of 100. Results contain only the latest version of each Agent, are ordered newest-first by a stable (created_at, id) key, and use a forward-only opaque next_page cursor.

Update​

POST /v1/agents/{id}

Updates create a new version only when a material field changes:

{
  "version": 1,
  "system": "Use short answers.",
  "metadata": {
    "team": "developer-experience",
    "obsolete_key": null
  }
}

When supplied, version is an optimistic concurrency check. A stale version returns 409.

Field behavior:

  • omitted fields preserve the current value;
  • system and description accept null to clear;
  • tools, mcp_servers, and skills replace the whole list and accept null to clear;
  • multiagent replaces and re-resolves the complete roster, and accepts null to clear;
  • metadata keys patch the map, and a null value removes a key;
  • name, version, and the metadata object itself cannot be null;
  • model may be replaced but cannot be null.

An update with no material change returns the current version.

Archive​

POST /v1/agents/{id}/archive

Archive is idempotent and does not create a new version. An archived agent is read-only and cannot be selected for a new session. Existing sessions keep their stored snapshot.

Response shape​

{
  "id": "agent_...",
  "type": "agent",
  "version": 1,
  "name": "Repository assistant",
  "model": {"id": "claude-model-id"},
  "system": "Work carefully and explain changes.",
  "description": "Helps maintain a repository",
  "tools": [],
  "mcp_servers": [],
  "skills": [],
  "multiagent": null,
  "metadata": {"team": "platform"},
  "created_at": "2026-07-27T00:00:00Z",
  "updated_at": "2026-07-27T00:00:00Z",
  "archived_at": null
}

Custom Skill references are validated and version-pinned. Docker-backed cloud Sessions materialize those pins read-only and expose a private Skill dispatcher that loads the selected SKILL.md into the conversation on demand; this is currently limited to the Docker execution path. Agents with Skills must enable read for referenced files, and may not define a custom tool named Skill. Accepted Agent tool and MCP shapes are validated before a version is stored.