Skip to main content
PUT
/
agents
/
{id}
Error
A valid request URL is required to generate request examples
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "tools_config": {},
  "cpus": "1.0",
  "mem_limit": "1g",
  "pids_limit": 200,
  "soul_md": "<string>",
  "rules_md": "<string>",
  "autonomy_level": "act_within_scope",
  "status": "stopped",
  "container_id": "<string>",
  "model_policy_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "models": [
    "<string>"
  ],
  "skills": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "scope": "container_local",
      "tools": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>",
          "description": "<string>",
          "install_method": "builtin"
        }
      ]
    }
  ],
  "container_profile_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "container_profile": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "docker_image": "<string>"
  },
  "error_message": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "created_by": "<string>",
  "principal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "principal_type": "agent"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
string<uuid>
required

Body

application/json
​
name
string
​
description
string
​
tools_config
object
​
cpus
string
​
mem_limit
string
​
pids_limit
integer
​
soul_md
string
​
rules_md
string
​
model_policy_id
string<uuid> | null

Internal-only override. Prefer model_names for user-facing model assignment.

​
model_names
string[]

User-facing model names to assign directly to this agent (one or many).

​
skill_ids
string<uuid>[]

Skill IDs to assign. Empty array to detach all skills (Custom mode). Config is merged from all skills at save time.

​
container_profile_id
string<uuid> | null

Container profile to assign. Omit for no change; explicit null to clear.

​
autonomy_level
enum<string>

Controls agent autonomy. Omit for no change.

Available options:
ask_before_acting,
act_within_scope,
full_autonomy

Response

Agent updated

​
id
string<uuid>
​
agent_id
string

Unique slug identifier (lowercase, alphanumeric, hyphens)

Pattern: ^[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$
​
name
string
​
description
string
​
tools_config
object
​
cpus
string
default:1.0
​
mem_limit
string
default:1g
​
pids_limit
integer
default:200
​
soul_md
string
​
rules_md
string
​
autonomy_level
enum<string>
default:act_within_scope

Controls how much freedom the agent has when executing commands.

Available options:
ask_before_acting,
act_within_scope,
full_autonomy
​
status
enum<string>
Available options:
stopped,
running,
error
​
container_id
string | null
​
model_policy_id
string<uuid> | null

Internal policy reference used by backend model-router plumbing.

​
models
string[]

User-facing model names assigned to this agent.

​
skills
object[]

Skills assigned to this agent.

​
container_profile_id
string<uuid> | null

FK to container_profiles table. Determines Docker image for the agent container.

​
container_profile
object

Resolved container profile object (from LEFT JOIN).

​
error_message
string | null
​
created_at
string<date-time>
​
updated_at
string<date-time>
​
created_by
string
​
principal_id
string<uuid>

Stable principal identifier (equals agent UUID). AI-115 workload principal model.

​
principal_type
enum<string>

Formal principal type. Always 'agent' for workload principals.

Available options:
agent