Define agents

An Agent is a versioned, reusable configuration for an agent in Orca Agent Engine. It declares the model the agent uses, the system prompt that frames its behavior, the MCP servers it can call, any custom tools it exposes, the skills it can load on demand, and arbitrary metadata for organizing agents across teams. Every change to an agent produces a new version; sessions pin to a version so behavior stays predictable as agents evolve.

Get your registry endpoint

Agent configuration fields

The Agent resource exposes the fields below. Field names use snake_case over the wire; the table shows the JSON form.

The response from any agent endpoint includes server-managed fields: id, type, version, created_at, updated_at, and (for archived agents) archived_at.

You can also override model, system, tools, mcp_servers, and skills for each session without changing the agent.

Choose a harness

The harness is the process that runs the agent loop. Which one an agent uses is fixed at the agent level, through two reserved metadata keys:

claude_agent_sdk runs in separate mode, and claude_code runs in colocated mode. codex_sdk and pi_sdk support both; omitting mode selects separate. For a self-hosted environment, set mode to colocated for either SDK harness. in_sandbox remains a deprecated alias for colocated; use colocated for new agents. Setting mode alone still selects the default claude_agent_sdk harness, so colocated is rejected. Unsupported pairs return 400.

# Default harness - the metadata keys can be omitted entirely
ork agent create --name "support-triage" --model claude-sonnet-4-6

# Run the loop inside the sandbox instead
ork agent create \
  --name "repo-worker" \
  --model claude-sonnet-4-6 \
  --metadata harness=claude_code

The following comparison applies to the two Claude harnesses. Codex SDK and Pi SDK have their own model and capability rules on their Codex SDK and Pi SDK pages.

See the per-harness pages for configuration: Claude Agent SDK, Claude Code, Codex SDK, and Pi SDK.

Create an agent

Create an agent by POSTing a CreateAgentRequest to /v1/agents. The example below registers an agent that uses a system prompt, declares one MCP server, and pins the model speed.

The mcp_toolset entry is not optional here: a declared server that no tool references is rejected with 400. See MCP servers for why the two are checked against each other.

The later examples on this page reuse the new agent's ID and version, so capture them here.

agent=$(ork agent create \
  --name "support-triage" \
  --description "Triages incoming support tickets" \
  --system "You categorize support tickets and route them to the right team." \
  --model-json '{"id":"claude-sonnet-4-6","speed":"standard"}' \
  --mcp-server name=tickets,type=url,url=https://mcp.example.com/tickets \
  --tool-json '{"type":"mcp_toolset","mcp_server_name":"tickets"}' \
  --metadata team=support \
  -o json)

AGENT_ID=$(jq -r '.id' <<< "$agent")
AGENT_VERSION=$(jq -r '.version' <<< "$agent")

A successful create returns 200 OK with the new agent:

{
  "id": "agt_01H8...",
  "type": "agent",
  "name": "support-triage",
  "description": "Triages incoming support tickets",
  "version": 1,
  "model": {
    "id": "claude-sonnet-4-6",
    "speed": "standard",
    "effort": { "type": "high" }
  },
  "system": "You categorize support tickets and route them to the right team.",
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "tickets",
      "default_config": {
        "enabled": true,
        "permission_policy": { "type": "always_allow" }
      },
      "configs": []
    }
  ],
  "mcp_servers": [
    { "name": "tickets", "type": "url", "url": "https://mcp.example.com/tickets" }
  ],
  "skills": [],
  "metadata": { "team": "support" },
  "multiagent": null,
  "archived_at": null,
  "created_at": "2026-05-11T17:24:08Z",
  "updated_at": "2026-05-11T17:24:08Z"
}

$AGENT_ID is what you pass when creating sessions.

Update an agent

Update an existing agent by sending a POST to /v1/agents/{id}. Every update produces a new version of the agent.

Updating takes the current version as well as the ID. Supplying it makes the write a compare-and-swap: if something else changed the agent since you read it, the request returns 409 version mismatch instead of silently overwriting. This is why the create example captured AGENT_VERSION.

updated=$(ork agent update "$AGENT_ID" \
  --version "$AGENT_VERSION" \
  --system "Updated system prompt" \
  -o json)

AGENT_VERSION=$(jq -r '.version' <<< "$updated")

Each of these reassigns AGENT_VERSION from the response, so a second update in the same shell session still compare-and-swaps correctly.

Update semantics

The agents endpoint uses POST with partial-update semantics: fields omitted from the request body are left unchanged on the server. The method is POST rather than PATCH, but the merge behavior on the body is what PATCH would give you.

• Omitted fields are preserved. Sending only system leaves mcp_servers, tools, and skills unchanged.
• Scalar fields are replaced. A new system value overwrites the old one.
• Array fields are replaced as a whole. To add one tool, send the full new tools array.
• Metadata keys are merged. Set a key to null to remove it; omit a key to leave it unchanged.

The response is the new agent version. Existing sessions continue to use the version they pinned at session-creation time.

Agent lifecycle

List versions

Every update increments the version. To inspect prior versions:

curl -fsS "$ORCA_REGISTRY_URL/v1/agents/$AGENT_ID/versions" \
  -H "Authorization: Bearer $ORCA_ACCESS_TOKEN"

The response is a paginated cursor whose data entries are full agent records for each version.

Retrieve a specific version

ork agent get "$AGENT_ID" --version 2 -o json

Omit the version to get the latest.

Archive an agent

Archiving hides an agent from default list results while preserving its history. Sessions started before the archive continue to run.

Archive an agent by sending a POST to /v1/agents/{id}/archive. Nothing is deleted: the agent record stays queryable with include_archived=true and retains its full version history.

ork agent archive "$AGENT_ID"

The response is the agent record with archived_at populated.

Delete an agent

DELETE /v1/agents/{id} is a different operation from archive, and it destroys data. It removes every version row and the agent row in one transaction. The agent is gone: include_archived=true will not bring it back, the version history is not recoverable, and the response carries no agent fields.

Prefer archive. Reach for delete only when the records themselves must not persist.

curl -fsS -X DELETE "$ORCA_REGISTRY_URL/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $ORCA_ACCESS_TOKEN"

{ "id": "agt_01H8...", "type": "agent_deleted" }

Neither ork nor the TypeScript SDK exposes agent deletion, so the registry endpoint is the only route to it.

List agents

ork agent list

Add include_archived=true to surface archived agents. The endpoint reads four other query parameters - limit, page, created_at[gte], and created_at[lte] - and ignores anything else, so filter on metadata labels client-side after listing.

Permissions

Treat every Workspace API key as full access to its Workspace's resources, and separate access with Workspaces. See Control registry access.

What's next