Actors

Humans and AI agents in the workspace.

7 actions. Each is callable by the agent as a tool, over HTTP via /api/invoke, and (usually) from a UI page.

`actors.list`

GET

List all actors (humans + agents) in the workspace.

AI tool: actors_list
API: GET /api/invoke/actors.list

Input

Field	Type	Required	Description
`kind`	"human" \| "agent"	—

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "human",
        "agent"
      ]
    }
  }
}

`actors.get`

GET

Fetch a single actor (human or agent) by id.

AI tool: actors_get
API: GET /api/invoke/actors.get

Input

Field	Type	Required	Description
`id`	string	yes

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "id"
  ]
}

`actors.create`

POST · mutating

Create a new actor — primarily for spinning up AI agents. Defaults kind to "agent". Set autonomy, model, and starting permissions. Humans usually arrive mirrored from the gateway, but a placeholder human can be created too.

AI tool: actors_create
API: POST /api/invoke/actors.create

Input

Field	Type	Required
`name`	string	yes
`kind`	"human" \| "agent"	—
`handle`	union	—
`avatarUrl`	union	—
`autonomyLevel`	union	—
`modelId`	union	—
`permissions`	string[]	—

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "kind": {
      "type": "string",
      "enum": [
        "human",
        "agent"
      ]
    },
    "handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "avatarUrl": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "autonomyLevel": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "supervised",
            "semi-autonomous",
            "fully-autonomous"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "modelId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "permissions": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "name"
  ]
}

`actors.update`

PATCH · mutating

Update an actor's editable config: name, handle, avatar, autonomy band, model, and permission capabilities. Never changes kind.

AI tool: actors_update
API: PATCH /api/invoke/actors.update

Input

Field	Type	Required	Description
`id`	string	yes
`patch`	object	yes

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "patch": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "handle": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "avatarUrl": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "autonomyLevel": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "supervised",
                "semi-autonomous",
                "fully-autonomous"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "modelId": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "permissions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "smsRoutingPreference": {
          "type": "string"
        },
        "bannerSeed": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "bannerTheme": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    }
  },
  "required": [
    "id",
    "patch"
  ]
}

`actors.set_active`

POST · mutating

Activate or deactivate an actor. A deactivated agent stays in the roster (and keeps its history) but is switched off and should not run.

AI tool: actors_set_active
API: POST /api/invoke/actors.set_active

Input

Field	Type	Required	Description
`id`	string	yes
`active`	boolean	yes

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "active": {
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "active"
  ]
}

`actors.delete`

DELETE · mutating

Permanently delete an agent. Refuses if the agent still owns live missions, or if other records (decisions, calls, history) reference it — in those cases deactivate instead to preserve history.

AI tool: actors_delete
API: DELETE /api/invoke/actors.delete

Input

Field	Type	Required	Description
`id`	string	yes

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "id"
  ]
}

`actors.set_phone`

POST · mutating

Set an actor's phone number and SMS routing preference. When mirror-to-platform is set, any SMS to/from this actor surfaces as a message in their platform conversation.

AI tool: actors_set_phone
API: POST /api/invoke/actors.set_phone

Input

Field	Type	Required
`id`	string	yes
`phoneNumber`	union	—
`smsRoutingPreference`	"mirror-to-platform" \| "direct-only" \| "both"	—

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "phoneNumber": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "smsRoutingPreference": {
      "type": "string",
      "enum": [
        "mirror-to-platform",
        "direct-only",
        "both"
      ]
    }
  },
  "required": [
    "id"
  ]
}