Concepts

Coming from another agent API

Map nvoken's concepts onto OpenAI, Claude, Mistral, and Cursor, and learn the three places where a familiar word means something different here.

If you have built on another agent API, most of nvoken will feel familiar. This page exists for the parts that will not: three places where a word you already know means something different here, and one table so you can stop guessing at the vocabulary.

The concept map

nvoken	OpenAI	Claude	Mistral	Cursor
Invocation	Response	A turn within a Session	Conversation turn	Run
Session	Conversation	Session	Conversation	Agent conversation
Host tool	Function	Custom tool	Function	—
`waiting`	`requires_action`	`requires_action`	—	—
Inline definition, recorded per turn	Request body fields	Agent version	Agent version	Agent config

The last row is the one that changes how you structure your code. There is no version to publish, no agent to update, and no registry to migrate. Every turn carries what it needs and nvoken keeps a record of what it ran with.

Trap 1: our Agent stores nothing

agent_key creates an Agent, and an Agent has an ID and a creation time. That is all it has. No prompt, no model, no tool policy, no version history.

It is an identity anchor for grouping and filtering — the thing that lets you ask "show me every turn the support agent ran". It is not a configuration object, and pointing two Invocations at the same Agent does not make them behave alike.

If you are coming from Claude's or Mistral's agent versions, this is the biggest structural difference. Your agent's definition lives in your code and travels with each call:

const agent = client.agent({
  agentKey: "support",
  instructions: "Be concise and helpful.",
});

Nothing is registered by that line. instructions are sent with each call; nvoken stores only the key.

Trap 2: interrupt keeps the work, cancel throws it away

Both stop a running turn. They are not variants of one operation.

	`interrupt`	`cancel`
Terminal status	`completed`	`cancelled`
`stop_reason`	`interrupted`	null
The work it produced	Stays in the Session, and in later turns' context	Excluded from later model context

If you are coming from an API whose cancel only discards, interrupt is the one you want for a chat "stop" button: the user gets to keep the half-written answer and ask a follow-up about it.

The same pair exists at admission time. if_active: "interrupt" is "stop and redo"; if_active: "supersede" is "discard and redo".

How turns end covers why an interrupted turn is completed rather than something more alarming.

Trap 3: provider keys are not a credential vault

Claude's vaults hold the credentials an agent's tools need to reach other services. nvoken's provider keys answer a narrower question: whose model account pays for this turn.

They are Anthropic, OpenAI, Google, and xAI API keys, scoped to your App or to one of your customers, and every Invocation records which one paid. Credentials for your agent's own tools stay with those tools, in your application, because that is where the tools run.

Other differences worth knowing up front

Admission is idempotent, and the key is required. idempotency_key is not optional. Send the same request twice and you get the same turn back with deduplicated: true. A changed replay returns idempotency_conflict rather than quietly running something else.
Admit, then read or stream. POST /v1/invocations returns 202 with the Invocation, not the answer. Read /result or open the stream. This is what makes a turn survive a closed tab.
A Session runs one turn at a time. A second concurrent turn is rejected with session_invocation_active unless you name an if_active policy. Two answers never interleave by accident.
tenant_key is a real boundary. Sessions and Invocations belong to one of your customers, and the database enforces it. user_key sits alongside as per-turn attribution, not access control.
Thinking is live-only. It streams while the turn runs and is never stored.
Media is base64. URLs and provider file IDs are not accepted as input sources today.

Where to go next

How nvoken works is the resource model in one page. How turns end is the short page that stops the most common integration bug. Patterns covers memory, scheduling, and multi-agent work — the three things you may be used to finding as platform features.