Concepts

Coming from another agent API

Map common response-style APIs onto nvoken's explicit Agent, Turn, Conversation, and MemorySpace resources.

The shortest useful mapping is:

Common concept	nvoken
Assistant or reusable prompt	Agent with immutable revisions
Response or run	durable Turn
Thread	optional Conversation
Long-term memory	independently selected MemorySpace
Background job ID	Turn ID

Three differences matter in application design.

Behavior is versioned before execution

An Agent is reusable behavior, not a customer instance. It may be owned by the App, one tenant, or one tenant/user pair. Publishing creates a new immutable revision. Every Turn records the exact revision it resolved.

Continuity and memory are optional and separate

A Conversation keeps an ordered transcript but does not bind an Agent. A MemorySpace keeps durable memory but does not follow automatically from the actor or Conversation. Select each only when the workflow needs it.

Admission and waiting are distinct

start() returns a durable Turn handle. run() waits for its result. text() waits and requires text. Store the Turn ID and use an idempotency key so a lost response can be recovered without creating duplicate work.

const agent = await client.agent("support");
const turn = await agent.start("Help with this request.", {
  tenant: "acme",
  idempotencyKey: "request-1842",
});
 
const final = await client.turn(turn.id, { tenant: "acme" }).result();