Skip to content
Learn Agent Substrate

Create actor

CreateActor is intentionally minimal: it produces a new Actor record with STATUS_SUSPENDED and no assigned worker. The first real work happens later, on the first ResumeActor call.

Sequence

CreateActorRequest carries an Actor body. Identity comes from actor.metadata.{atespace, name} - there is no bare actor_id field anymore. The referenced ActorTemplate and the target atespace must both already exist.

sequenceDiagram
  autonumber
  participant C as Client<br/>(kubectl-ate, etc.)
  participant A as ateapi
  participant R as Redis

  participant K as K8s API
  C->>A: CreateActor(Actor{ metadata{atespace,name},<br/>actor_template_namespace, actor_template_name })
  A->>K: Lister: ActorTemplate exists?
  K-->>A: ok
  A->>R: AtespaceExists(atespace)?
  R-->>A: yes
  A->>R: Conditional write to actor:{atespace}:{name}<br/>{ status: SUSPENDED }
  R-->>A: ok
  A-->>C: Actor{ metadata{atespace,name,...}, status=SUSPENDED }

What’s actually written

A new actor record in Redis at key actor:<atespace>:<name> containing:

FieldValue at create time
metadata.atespace / metadata.namecaller-supplied in CreateActorRequest.actor.metadata (identity)
actor_template_namespace / actor_template_namefrom the request’s Actor body
statusSTATUS_SUSPENDED
worker_selectorcopied from the request if set (per-actor placement)
ateom_pod_*empty
latest_snapshot_infounset

The server assigns the rest of ResourceMetadata (uid, version, timestamps) on write. There is no last_snapshot string field - snapshot state now lives in latest_snapshot_info (a SnapshotInfo).

No call to atelet or atecontroller. One K8s lister hit (to verify the referenced ActorTemplate exists - fails with a precondition error if not), one Redis atespace-exists check (fails with a precondition error if the atespace does not exist), and one conditional Redis write.

Why this is so simple

Actor creation is cheap and lazy. The expensive work - pulling images, allocating a worker, restoring memory - only happens when something actually needs the actor to be running. That’s the resume flow.

What if an actor with that name already exists?

CreateActor uses a conditional write - a duplicate create for the same (atespace, name) returns AlreadyExists and does not overwrite the record.