nvoken

https://nvoken.com/docs
Admin
nvoken is a durable agent runtime for product teams that executes recoverable model-and-tool agent...
Tokens:21,446
Snippets:223
Trust Score:3.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install SDKs for other languages

Source: https://nvoken.com/docs/guides/typescript-sdk

Install the same release for Go, Python, Rust, and the CLI.

```bash
go get github.com/deepnoodle-ai/nvoken/sdk/go@v0.32.0
```

```bash
python -m pip install 'nvoken==0.32.0'
```

```bash
cargo add nvoken@0.32.0
```

--------------------------------

### Install and Login to nvoken CLI

Source: https://nvoken.com/docs/guides/authentication

Install the command-line client and initiate the browser-assisted login process.

```bash
go install github.com/deepnoodle-ai/nvoken/cmd/nvoken@v0.32.0
nvoken auth login
```

--------------------------------

### Start stored Agent behavior with client.agent().start()

Source: https://nvoken.com/docs/guides/turns

Starts a stored Agent behavior. `start()` returns after admission, not settlement; store `turn.id` as the recovery handle.

```javascript
const agent = await client.agent("support");
const turn = await agent.start("Summarize this request.", {
  tenant: "acme",
  user: "alice",
  idempotencyKey: "ticket-483:summary-v1",
});
```

--------------------------------

### Install and authenticate nvoken CLI

Source: https://nvoken.com/docs/guides/command-line

Install the released CLI with go install and authenticate using nvoken auth login. Check authentication status with nvoken auth status. For CI, set NVOKEN_BASE_URL and NVOKEN_API_KEY, and add --json when another program consumes output.

```bash
go install github.com/deepnoodle-ai/nvoken/cmd/nvoken@v0.32.0
nvoken auth login
nvoken auth status
```

--------------------------------

### Start a turn and stream updates

Source: https://nvoken.com/docs/guides/typescript-sdk

Start a turn with tenant and user context, then iterate over updates to see status and text snapshots.

```typescript
const turn = await agent.start("Summarize this issue.", {
  tenant: "acme",
  user: "alice",
});
 
for await (const update of turn.updates()) {
  console.log(update.snapshot.status, update.snapshot.text);
}
```

--------------------------------

### Install the nvoken SDK

Source: https://nvoken.com/docs/quickstart

Install the @deepnoodle/nvoken package version 0.32.0 or later using npm.

```bash
npm install @deepnoodle/nvoken@^0.32.0
```

--------------------------------

### Start inline behavior with client.inline().run()

Source: https://nvoken.com/docs/guides/turns

Starts inline behavior with `client.inline()`. Stored and inline sources enter the same execution path; inline is appropriate when the behavior belongs to the call site.

```javascript
const runner = client.inline({
  instructions: "Return a concise sentiment label.",
  model: "anthropic/claude-sonnet-5",
  limits: { maxOutputTokens: 40 },
});
 
const result = await runner.run("The issue is finally fixed.", {
  tenant: "acme",
});
```

--------------------------------

### Stream a Turn with start() and updates()

Source: https://nvoken.com/docs/quickstart

Start a Turn with an idempotency key and stream updates until it ends. The start() method durably accepts work and returns a recoverable handle.

```typescript
const agent = await client.agent("quickstart");
const turn = await agent.start("Write a two-line welcome.", {
  tenant: "quickstart",
  idempotencyKey: "welcome-v1",
});
 
for await (const update of turn.updates()) {
  console.log(update.snapshot.status, update.snapshot.text);
}
```

--------------------------------

### Start a turn and retrieve its result

Source: https://nvoken.com/docs/guides/coming-from-another-agent-api

Use this snippet to start a turn with an idempotency key and then fetch the final result. The `start()` method returns a durable Turn handle, while `result()` waits for the turn's completion. Store the Turn ID and use an idempotency key to recover lost responses without duplicate work.

```javascript
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();
```

--------------------------------

### Create a browser client with createBrowserClient

Source: https://nvoken.com/docs/guides/browser-access

Initializes a browser client using a token-fetching function and starts an Agent Turn with specific conversation constraints. The client token should be refreshed via the backend as it expires within 15 minutes.

```javascript
import { createBrowserClient } from "@deepnoodle/nvoken";
 
const browser = createBrowserClient({
  baseUrl: window.ENV.NVOKEN_BASE_URL,
  clientToken: async () => {
    const response = await fetch("/api/nvoken-token");
    return (await response.json()).token;
  },
});
 
const turn = await browser.start("Help with this order.", {
  conversation: {
    key: "support",
    ownedByUser: "user-481",
    ifActive: "interrupt",
  },
});
 
for await (const update of turn.updates()) {
  render(update.snapshot);
}
```

--------------------------------

### GET /v1/memory-spaces

Source: https://nvoken.com/docs/reference/http-api

List exact scoped namespaces.

```APIDOC
## GET /v1/memory-spaces

### Description
List exact scoped namespaces.

### Method
GET

### Endpoint
/v1/memory-spaces
```

--------------------------------

### Manage agents and turns with nvoken CLI

Source: https://nvoken.com/docs/guides/command-line

Create an agent from a JSON file, look up an agent by name, start a turn with agent, tenant, and user identifiers, and retrieve turn results. Agent creation and publication accept exact JSON files so the CLI never hides behavior fields. Use '-' to read JSON from standard input.

```bash
nvoken agent create --file support-agent.json
nvoken agent lookup support
 
nvoken turn start \
  --agent-id 019b0a12-a5f6-7ed5-b636-76ea74f399ad \
  --tenant acme \
  --user alice \
  --wait \
  "Summarize this request."
 
nvoken turn get 019b0a13-2c74-7a91-8f3d-5b1e0c6d4a28
nvoken turn result 019b0a13-2c74-7a91-8f3d-5b1e0c6d4a28
nvoken turn list --tenant acme --agent-id 019b0a12-a5f6-7ed5-b636-76ea74f399ad
```

--------------------------------

### GET /v1/turns/{turn_id}/traces and GET /v1/traces/{trace_id}

Source: https://nvoken.com/docs/guides/observability

Lists traces for a turn (newest first) and reads a single trace by ID. Traces come from the agent runtime through OpenTelemetry and are diagnostic, best-effort. A summary carries span_count, error_count, duration_ms, and attempt; reading one trace returns a projection of up to 200 spans. Partial traces (is_partial: true) are normal, and attribution is grounded server-side.

```http
GET /v1/turns/{turn_id}/traces
GET /v1/traces/{trace_id}
```

--------------------------------

### GET /v1/memory-spaces/{memory_space_id}

Source: https://nvoken.com/docs/reference/http-api

Read one MemorySpace.

```APIDOC
## GET /v1/memory-spaces/{memory_space_id}

### Description
Read one MemorySpace.

### Method
GET

### Endpoint
/v1/memory-spaces/{memory_space_id}

### Parameters
#### Path Parameters
- **memory_space_id** (string) - Required - The opaque ID of the MemorySpace
```

--------------------------------

### GET /v1/turns/{turn_id}/stream

Source: https://nvoken.com/docs/reference/http-api

Follow one Turn over SSE.

```APIDOC
## GET /v1/turns/{turn_id}/stream

### Description
Follow one Turn over SSE.

### Method
GET

### Endpoint
/v1/turns/{turn_id}/stream

### Parameters
#### Path Parameters
- **turn_id** (string) - Required - The opaque ID of the Turn
```

--------------------------------

### Stream Turn updates via the facade

Source: https://nvoken.com/docs/guides/streaming-and-recovery

Start a Turn and iterate over its updates, rendering each snapshot. Snapshot text is a current projection; treat deltas and previews as replaceable UI state, and rely on the composed result and canonical Conversation messages as authoritative.

```javascript
const turn = await agent.start("Research the options.", { tenant: "acme" });

for await (const update of turn.updates()) {
  render(update.snapshot);
}
```

--------------------------------

### GET /v1/agents/{agent_id}

Source: https://nvoken.com/docs/reference/http-api

Read one Agent.

```APIDOC
## GET /v1/agents/{agent_id}

### Description
Read one Agent.

### Method
GET

### Endpoint
/v1/agents/{agent_id}

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The opaque ID of the Agent
```

--------------------------------

### Inspect conversations and memory spaces

Source: https://nvoken.com/docs/guides/command-line

List conversations for a tenant, retrieve messages and transcript for a conversation, list memory spaces by scope, and get a specific memory space. Use nvoken --help and nvoken <group> --help for the full current command surface.

```bash
nvoken conversation list --tenant acme
nvoken conversation messages 019b0a13-6e08-7b52-9d41-2af7c9e30b16
nvoken conversation transcript 019b0a13-6e08-7b52-9d41-2af7c9e30b16
 
nvoken memory-space list --tenant acme --scope tenant
nvoken memory-space get 019b0a13-91bd-7c0e-b8a7-43e5d2f10c94
```

--------------------------------

### GET /v1/turns

Source: https://nvoken.com/docs/reference/http-api

List Turns with tenant, actor, behavior, continuity, memory, status, and lineage filters.

```APIDOC
## GET /v1/turns

### Description
List Turns with tenant, actor, behavior, continuity, memory, status, and lineage filters.

### Method
GET

### Endpoint
/v1/turns

### Parameters
#### Query Parameters
- **tenant** - Optional - Filter by tenant
- **actor** - Optional - Filter by actor
- **behavior** - Optional - Filter by behavior
- **continuity** - Optional - Filter by continuity
- **memory** - Optional - Filter by memory
- **status** - Optional - Filter by status
- **lineage** - Optional - Filter by lineage
```

--------------------------------

### GET /v1/agents

Source: https://nvoken.com/docs/reference/http-api

List or resolve Agents in an exact owner namespace.

```APIDOC
## GET /v1/agents

### Description
List or resolve Agents in an exact owner namespace.

### Method
GET

### Endpoint
/v1/agents
```

--------------------------------

### GET /v1/conversations

Source: https://nvoken.com/docs/reference/http-api

List Conversations.

```APIDOC
## GET /v1/conversations

### Description
List Conversations.

### Method
GET

### Endpoint
/v1/conversations
```

--------------------------------

### Add Conversation continuity

Source: https://nvoken.com/docs/quickstart

Create a Conversation with a tenant, key, and owner, then send messages and get responses. The Conversation supplies transcript continuity only; memory is chosen separately with the memory option.

```typescript
const chat = agent.conversation({
  tenant: "quickstart",
  key: "demo-thread",
  owner: "tenant",
});
 
await chat.text("Remember that the release color is indigo.");
console.log(await chat.text("What is the release color?"));
```

--------------------------------

### GET /v1/conversations/{conversation_id}/stream

Source: https://nvoken.com/docs/reference/http-api

Follow current and future Turns over SSE.

```APIDOC
## GET /v1/conversations/{conversation_id}/stream

### Description
Follow current and future Turns over SSE.

### Method
GET

### Endpoint
/v1/conversations/{conversation_id}/stream

### Parameters
#### Path Parameters
- **conversation_id** (string) - Required - The opaque ID of the Conversation
```

--------------------------------

### GET /v1/agents/{agent_id}/revisions/{revision}

Source: https://nvoken.com/docs/reference/http-api

Read one exact revision of an Agent.

```APIDOC
## GET /v1/agents/{agent_id}/revisions/{revision}

### Description
Read one exact revision of an Agent.

### Method
GET

### Endpoint
/v1/agents/{agent_id}/revisions/{revision}

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The opaque ID of the Agent
- **revision** (string) - Required - The revision identifier
```

--------------------------------

### GET /v1/turns/{turn_id}/logs

Source: https://nvoken.com/docs/guides/observability

Retrieves structured lifecycle logs for a turn, correlated to trace_id and span_id. Records include severity, event, component, outcome, and error_class; arbitrary attributes and raw error values are omitted. These are nvoken's logs about running the turn, not your agent's output.

```http
GET /v1/turns/{turn_id}/logs
```

--------------------------------

### Create and run an Agent

Source: https://nvoken.com/docs/quickstart

Create a Client, create an Agent with a key, name, instructions, and model, then run a Turn with tenant and user. Logs the result text and turn ID/status.

```typescript
import { Client } from "@deepnoodle/nvoken";
 
const client = new Client();
const agent = await client.agents.create({
  key: "quickstart",
  name: "Quickstart",
  instructions: "Be concise and helpful.",
  model: "anthropic/claude-sonnet-5",
});
 
const result = await agent.run("Say hello in one short sentence.", {
  tenant: "quickstart",
  user: "developer",
});
 
console.log(result.text);
console.log(result.turn.id, result.status);
```

--------------------------------

### Create and run agent with tenant context

Source: https://nvoken.com/docs/guides/patterns

Create the agent once and run it for different tenants on separate turns.

```javascript
const support = await client.agent("support");
 
await support.run("Summarize the request.", { tenant: "acme", user: "alice" });
await support.run("Summarize the request.", { tenant: "globex", user: "sam" });
```

--------------------------------

### Create Client with environment variables

Source: https://nvoken.com/docs/guides/typescript-sdk

Create a Client instance that reads NVOKEN_BASE_URL and NVOKEN_API_KEY from the environment, or accepts them explicitly.

```typescript
import { Client } from "@deepnoodle/nvoken";
 
const client = new Client({
  baseUrl: process.env.NVOKEN_BASE_URL,
  apiKey: process.env.NVOKEN_API_KEY,
});
```

--------------------------------

### GET /v1/conversations/{conversation_id}

Source: https://nvoken.com/docs/reference/http-api

Read a Conversation.

```APIDOC
## GET /v1/conversations/{conversation_id}

### Description
Read a Conversation.

### Method
GET

### Endpoint
/v1/conversations/{conversation_id}

### Parameters
#### Path Parameters
- **conversation_id** (string) - Required - The opaque ID of the Conversation
```

--------------------------------

### Create and load Agents

Source: https://nvoken.com/docs/guides/typescript-sdk

Create an agent with a key, name, instructions, and model, then load it by key or by ID. The awaited key lookup fails immediately when the agent is absent or invisible.

```typescript
const agent = await client.agents.create({
  key: "support",
  name: "Support",
  instructions: "Be concise and helpful.",
  model: "anthropic/claude-sonnet-5",
});
 
const sameAgent = await client.agent("support");
const exactAgent = await client.agents.getById(agent.id);
```

--------------------------------

### Bind continuity before running

Source: https://nvoken.com/docs/guides/typescript-sdk

Create a conversation with tenant, key, owner, and memory scope, then send a text request that continues from the previous request.

```typescript
const chat = agent.conversation({
  tenant: "acme",
  key: "ticket-483",
  owner: "tenant",
  memory: { scope: "tenant", namespace: "support" },
});
 
console.log(await chat.text("Continue from the previous request."));
```

--------------------------------

### POST /v1/agents

Source: https://nvoken.com/docs/reference/http-api

Create an Agent and revision 1.

```APIDOC
## POST /v1/agents

### Description
Create an Agent and revision 1.

### Method
POST

### Endpoint
/v1/agents
```

--------------------------------

### GET /v1/turns/{turn_id}

Source: https://nvoken.com/docs/reference/http-api

Read current state of a Turn.

```APIDOC
## GET /v1/turns/{turn_id}

### Description
Read current state of a Turn.

### Method
GET

### Endpoint
/v1/turns/{turn_id}

### Parameters
#### Path Parameters
- **turn_id** (string) - Required - The opaque ID of the Turn
```

--------------------------------

### GET /v1/conversations/{conversation_id}/messages

Source: https://nvoken.com/docs/reference/http-api

Page canonical messages of a Conversation.

```APIDOC
## GET /v1/conversations/{conversation_id}/messages

### Description
Page canonical messages of a Conversation.

### Method
GET

### Endpoint
/v1/conversations/{conversation_id}/messages

### Parameters
#### Path Parameters
- **conversation_id** (string) - Required - The opaque ID of the Conversation
```

--------------------------------

### List and inspect a model

Source: https://nvoken.com/docs/guides/models-and-output

Use the client to list models by provider and retrieve specific model details. The response includes metadata such as input media, controls, and pricing.

```typescript
const catalog = await client.listModels({ provider: "anthropic" });
const model = await client.raw().models.getModel({
  provider: "anthropic",
  modelId: "claude-sonnet-5",
});
 
console.log(catalog.items, model.controls);
```

--------------------------------

### Pass tenant and user context to agent.run

Source: https://nvoken.com/docs/guides/authentication

Use the tenant and user options in the agent.run method to restrict the scope of the machine's actions. This ensures that the request is associated with the specified tenant and user, preventing cross-tenant data access.

```javascript
const agent = await client.agent("support");
const result = await agent.run("Help with this request.", {
  tenant: "acme",
  user: "user-481",
});
```

--------------------------------

### Accessing Agents by Owner Namespace

Source: https://nvoken.com/docs/concepts/state-ownership

Demonstrates how to reference agents using different owner namespaces. Agent keys are unique only within their specific owner namespace, and the caller must explicitly select the namespace before lookup.

```javascript
await client.agent("support");
await client.agent("support", { ownedBy: { tenant: "acme" } });
await client.agent("support", {
  ownedBy: { tenant: "acme", user: "alice" },
});
```

--------------------------------

### GET /v1/agents/{agent_id}/revisions

Source: https://nvoken.com/docs/reference/http-api

List immutable revisions of an Agent.

```APIDOC
## GET /v1/agents/{agent_id}/revisions

### Description
List immutable revisions of an Agent.

### Method
GET

### Endpoint
/v1/agents/{agent_id}/revisions

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The opaque ID of the Agent
```

--------------------------------

### GET /v1/conversations/{conversation_id}/compactions

Source: https://nvoken.com/docs/reference/http-api

List compaction records for a Conversation.

```APIDOC
## GET /v1/conversations/{conversation_id}/compactions

### Description
List compaction records for a Conversation.

### Method
GET

### Endpoint
/v1/conversations/{conversation_id}/compactions

### Parameters
#### Path Parameters
- **conversation_id** (string) - Required - The opaque ID of the Conversation
```

--------------------------------

### GET /v1/turns/{turn_id}/result

Source: https://nvoken.com/docs/reference/http-api

Read the composed result of a Turn.

```APIDOC
## GET /v1/turns/{turn_id}/result

### Description
Read the composed result of a Turn.

### Method
GET

### Endpoint
/v1/turns/{turn_id}/result

### Parameters
#### Path Parameters
- **turn_id** (string) - Required - The opaque ID of the Turn
```

--------------------------------

### Create a tenant-owned conversation and send turns

Source: https://nvoken.com/docs/concepts/conversations-and-durability

Creates a tenant-owned conversation with a key and sends two text turns to demonstrate ordered transcript continuity. The SDK serializes calls made through one bound Conversation handle.

```javascript
const chat = agent.conversation({
  tenant: "acme",
  key: "ticket-483",
  owner: "tenant",
});
 
await chat.text("Remember the customer asked for a refund.");
await chat.text("Summarize the request so far.");
```

--------------------------------

### GET /v1/conversations/{conversation_id}/transcript

Source: https://nvoken.com/docs/reference/http-api

Drain a fixed-cut transcript of a Conversation.

```APIDOC
## GET /v1/conversations/{conversation_id}/transcript

### Description
Drain a fixed-cut transcript of a Conversation.

### Method
GET

### Endpoint
/v1/conversations/{conversation_id}/transcript

### Parameters
#### Path Parameters
- **conversation_id** (string) - Required - The opaque ID of the Conversation
```

--------------------------------

### Create a tenant or user-owned Agent

Source: https://nvoken.com/docs/guides/agents

Creates Agents scoped to a specific tenant or a specific user within a tenant.

```javascript
const tenantAgent = await client.agents.create({
  key: "support",
  ownedBy: { tenant: "acme" },
  instructions: "Follow Acme's support policy.",
  model: "anthropic/claude-sonnet-5",
});
 
const userAgent = await client.agents.create({
  key: "assistant",
  ownedBy: { tenant: "acme", user: "alice" },
  instructions: "Help Alice organize her work.",
  model: "anthropic/claude-sonnet-5",
});
```

--------------------------------

### Allocate tenant credits via POST /v1/credits/allocations

Source: https://nvoken.com/docs/guides/credits

Use this endpoint to allocate spending capacity to a specific tenant. The request requires a tenant key, amount, and an idempotency key to ensure safe retries.

```http
POST /v1/credits/allocations
```

```json
{
  "tenant_key": "acme",
  "amount": { "amount": "50.000000", "currency": "USD" },
  "reference": "stripe_pi_3Q…",
  "idempotency_key": "topup-2026-08-15-acme-1"
}
```

--------------------------------

### Create an Agent and Run a Standalone Turn

Source: https://nvoken.com/docs/introduction

Creates a versioned Agent with the @deepnoodle/nvoken Client, then runs a standalone Turn with agent.text(). The Turn omits a Conversation but keeps the same durable identity, stream, controls, recovery, and result APIs.

```typescript
import { Client } from "@deepnoodle/nvoken";
 
const client = new Client();
const agent = await client.agents.create({
  key: "support",
  name: "Support",
  instructions: "Be concise and helpful.",
  model: "anthropic/claude-sonnet-5",
});
 
console.log(await agent.text("Summarize this request.", {
  tenant: "acme",
  user: "alice",
}));
```

--------------------------------

### Set environment variables for nvoken API

Source: https://nvoken.com/docs/quickstart

Export the nvoken API base URL and App API key as environment variables. Required before using the SDK.

```bash
export NVOKEN_BASE_URL='<your nvoken API base URL>'
export NVOKEN_API_KEY='<your App API key>'
```

--------------------------------

### GET /v1/turns/{turn_id}/timeline

Source: https://nvoken.com/docs/guides/observability

Retrieves the durable execution waterfall for a turn, assembled from one consistent database snapshot. This is the authoritative record and survives Conversation erasure, degrading to a facts-only skeleton. Use it for support and billing questions.

```http
GET /v1/turns/{turn_id}/timeline
```

--------------------------------

### Bind a reusable Conversation workflow

Source: https://nvoken.com/docs/guides/conversations

Initializes a conversation bound to a specific tenant and user, allowing for persistent transcript continuity.

```javascript
const agent = await client.agent("support");
const chat = agent.conversation({
  tenant: "acme",
  user: "alice",
  key: "ticket-483",
  owner: "user",
});
 
await chat.text("Remember that the order number is 1842.");
console.log(await chat.text("What is the order number?"));
```

--------------------------------

### Use inline behavior

Source: https://nvoken.com/docs/guides/typescript-sdk

Create an inline classifier with instructions and model, then run it with a request and tenant context.

```typescript
const classifier = client.inline({
  instructions: "Classify the request.",
  model: "anthropic/claude-sonnet-5",
});
 
const result = await classifier.run("I was charged twice.", {
  tenant: "acme",
});
```

--------------------------------

### POST /v1/memory-spaces

Source: https://nvoken.com/docs/reference/http-api

Resolve an exact scoped namespace.

```APIDOC
## POST /v1/memory-spaces

### Description
Resolve an exact scoped namespace.

### Method
POST

### Endpoint
/v1/memory-spaces
```

--------------------------------

### Send text and image input as an array

Source: https://nvoken.com/docs/guides/models-and-output

Turn input can be an ordered array containing text and image blocks. The image data must be provided as a standard-padded base64 string.

```json
[
  { "type": "text", "text": "Summarize this chart." },
  {
    "type": "image",
    "source": {
      "media_type": "image/png",
      "data": "<standard-padded-base64>"
    }
  }
]
```

--------------------------------

### Run a Conversational Turn with agent.conversation()

Source: https://nvoken.com/docs/introduction

Selects a Conversation explicitly with agent.conversation(), specifying tenant, user, key, owner, and memory. The resulting chat.text() call runs a conversational Turn that includes optional ordered transcript continuity.

```typescript
const chat = agent.conversation({
  tenant: "acme",
  user: "alice",
  key: "ticket-483",
  owner: "user",
  memory: { scope: "user", namespace: "support" },
});
 
console.log(await chat.text("What did we decide last time?"));
```

--------------------------------

### POST /v1/turns/{turn_id}/tool-results

Source: https://nvoken.com/docs/reference/http-api

Submit host-tool results for a Turn.

```APIDOC
## POST /v1/turns/{turn_id}/tool-results

### Description
Submit host-tool results for a Turn.

### Method
POST

### Endpoint
/v1/turns/{turn_id}/tool-results

### Parameters
#### Path Parameters
- **turn_id** (string) - Required - The opaque ID of the Turn
```

--------------------------------

### Bind a host tool locally with defineHostTool

Source: https://nvoken.com/docs/guides/tools

Declares a host tool contract and binds a local handler. The handler returns an idempotency key using the ToolCall ID. The SDK drives bound host tools while the calling process is connected; for remote durability, use callback delivery or submit results via the exact API after a Turn reaches 'waiting'.

```typescript
import { defineHostTool, defineJsonSchema } from "@deepnoodle/nvoken";
 
const lookupOrder = defineHostTool({
  mode: "host",
  name: "lookup_order",
  description: "Look up one order by ID.",
  inputSchema: defineJsonSchema({
    type: "object",
    properties: { orderId: { type: "string" } },
    required: ["orderId"],
    additionalProperties: false,
  }),
});
 
const runner = client.inline({
  instructions: "Call lookup_order before answering order questions.",
  model: "anthropic/claude-sonnet-5",
  tools: [lookupOrder],
}).bindTools({
  lookup_order: async ({ orderId }, context) => ({
    orderId,
    state: "ready",
    idempotencyKey: context.toolCallId,
  }),
});
 
console.log(await runner.text("Where is order-42?", { tenant: "acme" }));
```

--------------------------------

### Create an App-owned Agent

Source: https://nvoken.com/docs/guides/agents

Creates an Agent owned by the App, which is the default namespace and visible to all tenants.

```javascript
const support = await client.agents.create({
  key: "support",
  name: "Support",
  instructions: "Be concise and helpful.",
  model: "anthropic/claude-sonnet-5",
  limits: { maxOutputTokens: 800, maxIterations: 8 },
});
```

--------------------------------

### Select continuity and memory independently with agent.run()

Source: https://nvoken.com/docs/guides/turns

Selects continuity and memory independently. Omit `conversation` for standalone execution; use `memory: { scope: "none" }` to disable an Agent's default memory policy for one Turn.

```javascript
const result = await agent.run("Continue the investigation.", {
  tenant: "acme",
  user: "alice",
  conversation: {
    key: "ticket-483",
    owner: "tenant",
  },
  memory: {
    scope: "user",
    namespace: "support",
  },
});
```

--------------------------------

### Shared tenant memory

Source: https://nvoken.com/docs/guides/patterns

Let multiple users or agents intentionally select the same tenant MemorySpace.

```javascript
await support.text("Remember the escalation policy.", {
  tenant: "acme",
  user: "alice",
  memory: { scope: "tenant", namespace: "support-team" },
});
```

--------------------------------

### POST /v1/agents/{agent_id}/restore

Source: https://nvoken.com/docs/reference/http-api

Restore an Agent.

```APIDOC
## POST /v1/agents/{agent_id}/restore

### Description
Restore an Agent.

### Method
POST

### Endpoint
/v1/agents/{agent_id}/restore

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The opaque ID of the Agent
```

--------------------------------

### Send image input via HTTPS URL

Source: https://nvoken.com/docs/guides/models-and-output

Images can be provided via a public HTTPS URL. The URL must be at most 2,048 characters and nvoken will download the bytes once when the turn is created.

```json
{
  "type": "image",
  "source": { "url": "https://cdn.example.com/chart.png" }
}
```

--------------------------------

### POST /v1/turns/{turn_id}/resume

Source: https://nvoken.com/docs/reference/http-api

Raise eligible held limits for a Turn.

```APIDOC
## POST /v1/turns/{turn_id}/resume

### Description
Raise eligible held limits for a Turn.

### Method
POST

### Endpoint
/v1/turns/{turn_id}/resume

### Parameters
#### Path Parameters
- **turn_id** (string) - Required - The opaque ID of the Turn
```

--------------------------------

### Lookup Agents by namespace or ID

Source: https://nvoken.com/docs/guides/agents

Retrieves Agents using specific namespace lookups or a unique identifier.

```javascript
await client.agent("support");
await client.agent("support", { ownedBy: { tenant: "acme" } });
await client.agents.getById("019b0a12-a5f6-7ed5-b636-76ea74f399ad");
```

--------------------------------

### POST /v1/conversations

Source: https://nvoken.com/docs/reference/http-api

Create a Conversation.

```APIDOC
## POST /v1/conversations

### Description
Create a Conversation.

### Method
POST

### Endpoint
/v1/conversations
```

--------------------------------

### POST /v1/conversations/{conversation_id}/fork

Source: https://nvoken.com/docs/reference/http-api

Fork an inclusive transcript prefix.

```APIDOC
## POST /v1/conversations/{conversation_id}/fork

### Description
Fork an inclusive transcript prefix.

### Method
POST

### Endpoint
/v1/conversations/{conversation_id}/fork

### Parameters
#### Path Parameters
- **conversation_id** (string) - Required - The opaque ID of the Conversation
```
Tokens:
Raw