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	Public actor ID.
project_id	string	The owning project.
name	string	A human-friendly name. Required on create.
external_id	string, nullable	Your own key for this person — a user id, an account number, a phone number.
instructions	string, nullable	Persona instructions composed into the effective system prompt for this actor's turns.
agent_id	string, nullable	The agent this actor is linked to. Mutually exclusive with chat_id.
chat_id	string, nullable	The chat this actor is linked to. Mutually exclusive with agent_id.
tags	object, nullable	Tag map.
created_at	string (date-time)
updated_at	string (date-time)

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.

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/offset.

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

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

SDK

const { data: actor } = await naturali.actors.createActor({
  path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
  body: { name: 'Ana', external_id: 'user_42' },
});

curl

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

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

SDK

await naturali.actors.updateActor({
  path: {
    project_id: 'proj_V1StGXR8Z5jdHi6B',
    actor_id: 'act_V1StGXR8Z5jdHi6B',
  },
  body: { instructions: 'Speaks Portuguese. Prefers short answers.' },
});

curl

curl -X PATCH https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/actors/act_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

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

SDK

const { data: actors } = await naturali.actors.listActors({
  path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
  query: { external_id: 'user_42' },
});

curl

curl "https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/actors?external_id=user_42" \
  -H "Authorization: Bearer $NATURALI_TOKEN"