Skip to main content

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​

FieldTypeDescription
idstringActor ID
project_idstringProject ID
namestring
external_idstring, nullableExternal identifier (e.g. WhatsApp phone number)
instructionsstring, nullablePersona-specific instructions composed into the effective system prompt during conversation generation.
agent_idstring, nullableAgent this actor is linked to (mutually exclusive with chatId).
chat_idstring, nullableChat this actor is linked to (mutually exclusive with agentId).
tagsobjectKey-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_atstring (date-time)
updated_atstring (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​

naturali create-actor \
--project-id proj_V1StGXR8Z5jdHi6B \
--name Ana \
--external-id user_42

Give the actor a persona​

naturali update-actor \
--project-id proj_V1StGXR8Z5jdHi6B \
--actor-id actor_V1StGXR8Z5jdHi6B \
--instructions 'Speaks Portuguese. Prefers short answers.'

Resolve your own key back to an actor​

naturali list-actors \
--project-id proj_V1StGXR8Z5jdHi6B \
--external-id user_42