0. Build from source

The npm package is not published yet. The SDK lives in the OpenNeox repository and depends on the kernel package in the same repo, so install and build from the repository root:

git clone https://github.com/neoxlabs/OpenNeox
cd OpenNeox
npm ci && npm run build:packages
npx tsx packages/sdk/examples/06-mock.ts    # runs offline, no API key

All examples are in packages/sdk/examples/. See Use cases for a walkthrough by scenario.

1. Add it to your project

Pack a tarball from the SDK folder (the kernel is inlined into the package) and install it in your project as a local file:

cd packages/sdk && npm pack                 # writes neoxlabs-sdk-2.7.0.tgz
cd /path/to/your-app
npm install /path/to/neoxlabs-sdk-2.7.0.tgz zod
export ANTHROPIC_API_KEY=sk-...             # or OPENAI_API_KEY / DEEPSEEK_API_KEY / KIMI_API_KEY

Without an explicit provider, the SDK resolves one from the environment in this order: ANTHROPIC_API_KEY → OPENAI_API_KEY → DEEPSEEK_API_KEY → KIMI_API_KEY. If none is set, run() throws and says a provider is missing.

2. Three lines

import { Agent } from '@neoxlabs/sdk';

const agent = new Agent({ model: 'claude-sonnet-4-6' });
console.log((await agent.run('Explain the CAP theorem in one sentence')).text);

run() resolves to { text, usage, steps, messages, stopReason }.

3. Add a tool

Tools declare their input with Zod; the handler type is inferred:

import { Agent, tool } from '@neoxlabs/sdk';
import { z } from 'zod';

const getOrder = tool({
  name: 'get_order',
  description: 'Look up an order status and amount by id. Read-only.',
  schema: z.object({ orderId: z.string() }),
  readOnly: true,
  handler: async ({ orderId }) => db.orders.get(orderId),
});

const agent = new Agent({
  model: 'claude-sonnet-4-6',
  tools: [getOrder],
});

const res = await agent.run('What is the status of order A-1024?');
console.log(res.text, res.usage);

Tools run by default (permission: 'auto'). Tools marked dangerous: true are denied — wire an approval handler to let them through:

new Agent({
  model: 'claude-sonnet-4-6',
  tools: [refundOrder],
  permission: async ({ tool, input, dangerous }) => ({
    approved: !dangerous || (await confirmWithUser(tool, input)),
  }),
});

4. Streaming

stream() is an async iterable of AgentEvent:

for await (const ev of agent.stream('Cluster these log lines by root cause')) {
  if (ev.type === 'text_delta') process.stdout.write(ev.delta);
  if (ev.type === 'tool_call') console.log('\n→', ev.tool, ev.input);
  if (ev.type === 'done') console.log('\n', ev.stopReason, ev.usage);
}

The stream also carries the finished result:

const stream = agent.stream('...');
for await (const ev of stream) render(ev);
const { text, usage, messages, stopReason } = await stream.result();

5. Abort

const agent = new Agent({ model: 'claude-sonnet-4-6' });
setTimeout(() => agent.abort(), 5_000);
const res = await agent.run('...');   // stopReason: 'aborted'

An external signal works too: new Agent({ model, signal: controller.signal }).

6. Neox Platform

Instead of opening a key with every provider, you can use Neox Platform: one sk-neox- key for DeepSeek, GLM, Kimi, Qwen, GPT and more, charged per token from a prepaid balance. It is an OpenAI-compatible endpoint, so the SDK connects with openai-compatible:

import { Agent, provider } from '@neoxlabs/sdk';

const agent = new Agent({
  model: 'deepseek-v4-flash',
  provider: provider({
    type: 'openai-compatible',
    baseURL: 'https://gateway.neox-dev.com/v1',
    apiKey: process.env.NEOX_API_KEY!,     // create one in Console → API keys
  }),
});

console.log((await agent.run('Explain the CAP theorem in one sentence')).text);

Models and prices: the Platform page or GET https://gateway.neox-dev.com/v1/models
With an empty balance requests return 402 and the run will not end with end_turn; top up in the console to continue
Each key can carry its own spend cap and be revoked on its own

Use cases: run the bundled examples by scenario
Core concepts: events, stop reasons, step caps, thinking
Defining tools: schemas, errors, timeouts, danger flags

Quickstart