# Actors

> MCP tools for the Actors module. See the [Actors module docs](/docs/modules/actors) for permissions and data model.

# Actors

MCP tools for the Actors module. See the [Actors module docs](/docs/modules/actors) 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 |