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). |
limit | number | no | Maximum number of results to return |
offset | number | no | Number of results to skip |
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 | object | no | — |
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 |