Update an Agent

Applies CMA update semantics: omitted top-level fields are preserved, arrays and multiagent are whole-field replacements, metadata merges per key with null deleting one key, and a supplied model is a whole-object replacement with documented defaults. Empty description and system strings clear those fields. Optional version is optimistic concurrency; omission reapplies the patch to the newest head for last-write-wins behavior. A material change atomically creates the next immutable Version, while a no-op returns the current Version.

Checkfu support posture: alpha; hosted. Required evidence journey: agent-definition. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities.

POST /v1/agents/{agent_id}

Update an Agent

cURL

curl --request POST \
  --url https://api.checkfu.com/v1/agents/{agent_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-beta: <checkfu-beta>' \
  --header 'checkfu-version: <checkfu-version>' \
  --data '
{
  "description": "<string>",
  "mcp_servers": [
    {
      "type": "url",
      "name": "<string>",
      "url": "<string>"
    }
  ],
  "metadata": {},
  "model": "<string>",
  "multiagent": {
    "type": "coordinator",
    "agents": [
      "<string>"
    ]
  },
  "name": "<string>",
  "skills": [
    {
      "type": "anthropic",
      "skill_id": "<string>",
      "version": "<string>"
    }
  ],
  "system": "<string>",
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "configs": [
        {
          "name": "bash",
          "type": "bash",
          "enabled": true,
          "permission_policy": {
            "type": "always_allow"
          }
        }
      ],
      "default_config": {
        "enabled": true,
        "permission_policy": {
          "type": "always_allow"
        }
      }
    }
  ],
  "version": 1,
  "workload_trust": {}
}
'

200

{
  "id": "<string>",
  "archived_at": "<string>",
  "created_at": "<string>",
  "model": {
    "id": "<string>",
    "effort": {
      "type": "low"
    },
    "inference_geo": "global",
    "speed": "standard"
  },
  "name": "<string>",
  "description": "<string>",
  "mcp_servers": [
    {
      "type": "url",
      "name": "<string>",
      "url": "<string>"
    }
  ],
  "metadata": {},
  "multiagent": {
    "type": "coordinator",
    "agents": [
      {
        "type": "agent",
        "id": "<string>",
        "version": 1
      }
    ]
  },
  "skills": [
    {
      "type": "anthropic",
      "skill_id": "<string>",
      "version": "<string>"
    }
  ],
  "system": "<string>",
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "configs": [
        {
          "name": "bash",
          "type": "bash",
          "enabled": true,
          "permission_policy": {
            "type": "always_allow"
          }
        }
      ],
      "default_config": {
        "enabled": true,
        "permission_policy": {
          "type": "always_allow"
        }
      }
    }
  ],
  "workload_trust": {
    "declaration": {
      "value": "trusted",
      "recorded_at": "<string>"
    },
    "facts": {
      "authorship": "organization_engineer",
      "source_review": "workspace_controlled",
      "execution_plane": "organization_local",
      "input_exposure": {
        "source_build": "controlled",
        "ingress": "controlled",
        "mounts": "controlled",
        "installations": "controlled",
        "content_capabilities": "controlled"
      }
    },
    "effective": "trusted"
  },
  "type": "agent",
  "updated_at": "<string>",
  "version": 1
}

Authorizations

Authorization · string · header · required

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

Headers

checkfu-version · enum<string> · required

Available options: 2026-08-29

checkfu-beta · string · required

Path Parameters

agent_id · string · required

Pattern: ^agent_[0-9a-f]{32}$

Body

application/json

description · string | null

mcp_servers · object[] | null

Maximum array length: 20

Show child attributes

metadata · object | null

Metadata changes whose string values upsert and null values remove keys.

Show child attributes

model · string object

multiagent · object | null

Show child attributes

name · string

Required string length: 1 - 255

skills · object[] | null

Option 1

Option 2

Show child attributes

system · string | null

tools · object[] | null

Maximum array length: 128

Option 1

Option 2

Option 3

Show child attributes

version · integer

Required range: x > 0

workload_trust · object | null

Show child attributes

Response

200

application/json

BetaManagedAgentsAgent

id · string · required

Pattern: ^agent_[0-9a-f]{32}$

archived_at · string | null · required

created_at · string · required

model · object · required

Show child attributes

name · string · required

Required string length: 1 - 255

description · string | null · required

mcp_servers · object[] · required

Show child attributes

metadata · object · required

at most 16 correlation pairs with keys of 1 to 64 characters

Show child attributes

multiagent · object | null · required

Show child attributes

skills · object[] · required

Option 1

Option 2

Show child attributes

system · string | null · required

tools · object[] · required

Option 1

Option 2

Option 3

Show child attributes

workload_trust · object · required

Show child attributes

type · enum<string> · required

Available options: agent

updated_at · string · required

version · integer · required

Required range: x > 0