Actors

MCP tools for the Actors module. See the Actors module docs for permissions and data model.

list-actors

List actors

Arguments

Argument	Type	Required	Description
project_id	string	no	Project ID (optional)
external_id	string	no	External ID to filter by (e.g. WhatsApp phone number)
name	string	no	Case-insensitive substring match on the actor name
agent_id	string	no	Return only actors linked to this agent
chat_id	string	no	Return only actors linked to this chat
conversation_id	string	no	Return only actors that participate in this conversation (derived from the conversation's messages).
tags	array	no	Filter by tag pairs, written key:value (split on the first colon, so a value may contain colons). Repeat the parameter for several pairs; all must be present with exactly that value.
limit	number	no	Results per page. Above the maximum it is clamped, and limit in the response reports the page served; below 1 or not an integer it is 400 VALIDATION_FAILED.
offset	number	no	Results to skip. Negative or not an integer it is 400 VALIDATION_FAILED.

create-actor

Create an actor

Arguments

Argument	Type	Required	Description
project_id	string	no	Project ID. Required for JWT auth; omit when using an project key.
name	string	yes	—
external_id	string	no	Optional external identifier (e.g. WhatsApp phone number). If provided and an actor with this externalId already exists in the project, the existing actor is returned (idempotent — 200 OK).
instructions	string | null	no	Persona-specific instructions composed into the effective system prompt during conversation generation.
agent_id	string	no	Agent to link this actor to. Mutually exclusive with chat_id.
chat_id	string	no	Chat to link this actor to. Mutually exclusive with agent_id.

get-actor

Get an actor by ID

Arguments

Argument	Type	Required	Description
actor_id	string	yes	Actor ID

delete-actor

Delete an actor

Arguments

Argument	Type	Required	Description
actor_id	string	yes	Actor ID

update-actor

Update an actor

Arguments

Argument	Type	Required	Description
actor_id	string	yes	Actor ID
name	string	no	—
external_id	string	no	External identifier (e.g. WhatsApp phone number)
instructions	string	no	Persona-specific instructions
agent_id	string | null	no	Agent to link this actor to. Mutually exclusive with chat_id.
chat_id	string | null	no	Chat to link this actor to. Mutually exclusive with agent_id.
tags	any	no	Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with 400 VALIDATION_FAILED, never coerced. Keys are opaque and stored verbatim, so cost_center and costCenter are two different tags. Matched by JSONB containment wherever tags are read: the ?tags= filter, knowledge search, and the IAM soat:ResourceTag/<key> condition. Keys beginning system. are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with 400 RESERVED_TAG_KEY. They are read and filtered like any other tag. The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is 400 VALIDATION_FAILED with meta.limit naming the bound it crossed. system.* keys are the platform's and do not count against the 50.

get-actor-tags

Get actor tags

Arguments

Argument	Type	Required	Description
actor_id	string	yes	Actor ID

replace-actor-tags

Replace actor tags

Arguments

Argument	Type	Required	Description
actor_id	string	yes	Actor ID

merge-actor-tags

Merge actor tags

Arguments

Argument	Type	Required	Description
actor_id	string	yes	Actor ID