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 |
|---|---|---|---|
projectId | string | no | Project ID (optional) |
externalId | string | no | External ID to filter by (e.g. WhatsApp phone number) |
agentId | string | no | Return only actors linked to this agent |
chatId | string | no | Return only actors linked to this chat |
conversationId | 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 |
|---|---|---|---|
projectId | string | no | Project ID. Required for JWT auth; omit when using an project key. |
name | string | yes | — |
externalId | 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 | no | Persona-specific instructions composed into the effective system prompt during conversation generation. |
agentId | string | no | Agent to link this actor to. Mutually exclusive with chat_id. |
chatId | string | no | Chat to link this actor to. Mutually exclusive with agent_id. |
memoryId | string | no | Memory ID to link to this actor. Mutually exclusive with auto_create_memory. |
autoCreateMemory | boolean | no | When true, automatically creates a new memory container for this actor and links it. Ignored if memory_id is set. With external_id (idempotent), memory is only created on first creation. |
get-actor
Get an actor by ID
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
actorId | string | yes | Actor ID |
delete-actor
Delete an actor
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
actorId | string | yes | Actor ID |
update-actor
Update an actor
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
actorId | string | yes | Actor ID |
name | string | no | — |
externalId | string | no | External identifier (e.g. WhatsApp phone number) |
instructions | string | no | Persona-specific instructions |
agentId | string | no | Agent to link this actor to. Mutually exclusive with chat_id. |
chatId | string | no | Chat to link this actor to. Mutually exclusive with agent_id. |
memoryId | string | no | Memory ID to link to this actor. Set to null to unlink. |
tags | object | no | — |
get-actor-tags
Get actor tags
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
actorId | string | yes | Actor ID |
replace-actor-tags
Replace actor tags
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
actorId | string | yes | Actor ID |
merge-actor-tags
Merge actor tags
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
actorId | string | yes | Actor ID |