Actors
Who the agent is talking to — the end user on the other side of a session, keyed by whatever your application already calls them.
Overview
An actor is the identity a turn is attributed to. It carries a name, the persona
instructions composed into that turn's prompt, your own external_id, and an
optional link to the agent that answers for it.
Pass the actor's id as actor_id when you open a session, and every turn in
that session is attributed to that person — which is what makes a transcript
readable later and what lets one agent behave differently per end user without a
second agent.
Cap spend per end user
reads that attribution back as spend per actor.
This module is a verbatim mirror of the runtime: every field, method, status code and error shape is the runtime's own, re-rooted under the project in the path.
See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Actors.
Data Model
Actor
| Field | Type | Description |
|---|---|---|
id | string | Actor ID |
project_id | string | Project ID |
name | string | |
external_id | string, nullable | External identifier (e.g. WhatsApp phone number) |
instructions | string, nullable | Persona-specific instructions composed into the effective system prompt during conversation generation. |
agent_id | string, nullable | Agent this actor is linked to (mutually exclusive with chatId). |
chat_id | string, nullable | Chat this actor is linked to (mutually exclusive with agentId). |
tags | object | 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 iam: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. |
created_at | string (date-time) | |
updated_at | string (date-time) |
name is required on create. external_id is your own key for the person: a
user id, an account number, a phone number.
Key Concepts
Your key, not ours
external_id is yours to choose, and
GET /v1/projects/{project_id}/actors?external_id=…
resolves it back to an actor — so you can hold your own identifier and look the
actor up, rather than storing a second id alongside it.
Creating an actor is idempotent on external_id: a second create with the same
one answers 200 with the existing actor rather than 201 with a new one, as
Cap spend per end user
relies on.
Connect a signed-in person's account to their actor finds or creates the actor of a person your app signed in, then connects their provider account to it.
Linking an actor to an agent
An actor may name the agent_id that answers for it. That is what
POST /v1/projects/{project_id}/conversations/{conversation_id}/generate
leans on for a conversation-level reply, and it is mutually exclusive with
chat_id — one actor answers through one thing.
Filtering the list
GET /v1/projects/{project_id}/actors filters by
external_id, agent_id, chat_id and conversation_id, matches name as a
case-insensitive substring, and paginates with limit/cursor.
Tags
GET / PUT / PATCH …/tags read, replace and merge an actor's tag map — PUT
replaces it wholesale, PATCH merges keys in.
Deleting
DELETE /v1/projects/{project_id}/actors/{actor_id}
removes the actor. It is the erasure path for one end user of one project;
nothing joins two actors that happen to be the same human, so it is a promise
about an identity rather than about a person everywhere.
Examples
Create an actor for one of your users
- CLI
- SDK
- curl
naturali create-actor \
--project-id proj_V1StGXR8Z5jdHi6B \
--name Ana \
--external-id user_42
const { data: actor } = await naturali.actors.createActor({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: { name: 'Ana', external_id: 'user_42' },
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/actors \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "Ana", "external_id": "user_42" }'
Give the actor a persona
- CLI
- SDK
- curl
naturali update-actor \
--project-id proj_V1StGXR8Z5jdHi6B \
--actor-id actor_V1StGXR8Z5jdHi6B \
--instructions 'Speaks Portuguese. Prefers short answers.'
await naturali.actors.updateActor({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
actor_id: 'actor_V1StGXR8Z5jdHi6B',
},
body: { instructions: 'Speaks Portuguese. Prefers short answers.' },
});
curl -X PATCH https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/actors/actor_V1StGXR8Z5jdHi6B \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "instructions": "Speaks Portuguese. Prefers short answers." }'
Resolve your own key back to an actor
- CLI
- SDK
- curl
naturali list-actors \
--project-id proj_V1StGXR8Z5jdHi6B \
--external-id user_42
const { data: actors } = await naturali.actors.listActors({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
query: { external_id: 'user_42' },
});
curl "https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/actors?external_id=user_42" \
-H "Authorization: Bearer $NATURALI_TOKEN"