Use cases

The examples live in `packages/sdk/examples/` in the OpenNeox repository. First run npm ci && npm run build:packages at the repository root (see Quickstart), then:

npx tsx packages/sdk/examples/06-mock.ts     # swap in any example file

For the ones that need a key, export one of ANTHROPIC_API_KEY / OPENAI_API_KEY / DEEPSEEK_API_KEY / KIMI_API_KEY first.

Use case 1: Verify the loop offline

Problem: No key yet, or CI must not call a real model, but you need to verify the wiring between the agent and its tools.

Do: 06-mock.ts. mockLlm() replays scripted thinking, tool-call and text events with no network access.

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

const agent = new Agent({
  model: 'mock',
  provider: mockLlm({
    responses: [
      { type: 'tool_call', tool: 'get_weather', input: { city: 'Tokyo' } },
      { type: 'text', content: "It's 22°C in Tokyo." },
    ],
  }),
});

Use it in unit tests to pin model behavior and assert on your tools and post-processing.

Use case 2: Define tools before connecting a model

Problem: Settle Zod schemas, dangerous, readOnly and timeouts first, then hand them to an agent.

Do: 02-tools.ts. It builds and invokes tools directly and needs no key. Rules: Defining tools.

Use case 3: A single-tool agent for business questions

Problem: Attach one read-only lookup (orders, inventory, tickets) and let the model answer from it.

Do: 01-hello.ts (tool() + agent.run()). Mark read-only tools with readOnly: true explicitly so they keep working under permission: 'readonly'.

Use case 4: Stream to a terminal or UI

Problem: Show text and tool-call status as they arrive.

Do: 03-streaming.ts. Consume text_delta / tool_call / done with for await, then await stream.result() for the complete result. For pushing to a browser, see the Cookbook.

Use case 5: Multi-turn sessions across restarts

Problem: Support or coding assistants need context across turns and process restarts.

Do: 04-session.ts. createSession({ checkpointDir }) writes the history to checkpointDir/<sessionId>.json after each turn; after a restart, Session.resume(id, { checkpointDir }) reads it back. The file contains no provider config or API key.

Note: multi-turn context works by folding history into the next prompt, so tokens grow linearly with session length. Trim turns yourself when needed.

Use case 6: Let an agent read and write a directory

Problem: Code cleanup, bulk file edits, running tests.

Do: 07-builtin-tools.ts. builtinTools.fs({ root, allowWrite }) pins every path inside root (symlink escapes included) and is read-only by default; builtinTools.shell({ allowedCommands }) runs only allow-listed commands, without shell interpolation.

Use case 7: One key for several providers

Problem: You don't want separate accounts and keys at DeepSeek, Zhipu, Moonshot and OpenAI.

Do: Use a Neox Platform sk-neox- key with an openai-compatible provider and baseURL https://gateway.neox-dev.com/v1. See Quickstart · Neox Platform.

SDK vs the Neox client

Longer recipes: Cookbook.