Matches the actual exports of @neoxlabs/sdk 2.7.0.

Exports

import {
  Agent, tool, provider, providerFromEnv, createSession, Session, VERSION,
} from '@neoxlabs/sdk';
import { builtinTools } from '@neoxlabs/sdk/tools';

Types: AgentConfig AgentResult AgentStream AnyNeoxSdkTool PermissionHandler PermissionDecision PermissionRequest ToolConfig ToolContext NeoxSdkTool ProviderConfig ProviderType CreateSessionOptions AgentEvent AgentEventHandler TokenUsage Step Message Tool ThinkingMode PermissionMode StopReason

new Agent(config)

Field	Type	Default	Notes
`model`	`string`	—	required, e.g. `claude-sonnet-4-6`
`systemPrompt`	`string \	(() => string \	Promise<string>)`	—	may be generated asynchronously
`tools`	`NeoxSdkTool[]`	`[]`	tool list
`provider`	`ProviderConfig`	from env	LLM provider
`thinking`	`'auto' \	'high' \	'off'`	—	extended thinking
`maxSteps`	`number`	`50`	per-run step cap
`permission`	`'auto' \	'readonly' \	'ask' \	PermissionHandler`	`'auto'`	`'ask'` requires a handler or it throws
`onEvent`	`(e: AgentEvent) => void`	—	callback alternative to `stream()`
`signal`	`AbortSignal`	—	external abort

Methods

Method	Returns
`agent.run(prompt)`	`Promise<AgentResult>`
`agent.stream(prompt)`	`AgentStream` (iterable + `.result()` + `.abort()`)
`agent.abort()`	`void`
`agent.config`	readonly `AgentConfig`

AgentResult

{ text: string; usage: TokenUsage; steps: Step[]; messages: Message[]; stopReason: StopReason }

tool(config)

Field	Type	Default
`name`	`string`	—
`description`	`string`	—
`schema`	`z.ZodType<Input>`	—
`handler`	`(input, ctx: ToolContext) => Output \	Promise<Output>`	—
`timeout`	`number`	`60000`
`cacheable`	`boolean`	`false`
`dangerous`	`boolean`	`false`
`readOnly`	`boolean`	`!dangerous`
`readOnly`	`boolean`	`!dangerous`

ToolContext: { signal: AbortSignal; logger: { debug, info, warn, error }; emit?: (event) => void }

provider(config) / providerFromEnv()

ProviderType: anthropic · openai · openai-responses · openai-compatible · deepseek · gemini · kimi · glm · doubao

ProviderConfig: { type, apiKey, baseURL?, defaultHeaders?, proxy?, timeout? }

providerFromEnv() resolves in the order ANTHROPIC_API_KEY → OPENAI_API_KEY → DEEPSEEK_API_KEY → KIMI_API_KEY/MOONSHOT_API_KEY, returning null when none is set.

AgentEvent

| { type: 'text_delta'; delta: string }
| { type: 'thinking'; delta: string }
| { type: 'step_start' | 'step_end'; step: number }
| { type: 'tool_call'; tool: string; input: unknown; id: string }
| { type: 'tool_result'; tool: string; output: unknown; id: string }
| { type: 'tool_error'; tool: string; error: string; id: string }
| { type: 'permission_request'; tool: string; input: unknown; id: string }
| { type: 'done'; usage: TokenUsage; stopReason: StopReason }
| { type: 'error'; error: Error }

TokenUsage: { inputTokens, outputTokens, cacheReadTokens?, cacheWriteTokens? }

Step: { index, toolCalls, textDelta?, thinkingDelta?, durationMs }

PermissionHandler

type PermissionHandler = (req: {
  tool: string;
  input: unknown;
  dangerous: boolean;
  risk?: 'low' | 'medium' | 'high' | 'critical';
}) => PermissionDecision | Promise<PermissionDecision>;

interface PermissionDecision {
  approved: boolean;
  remember?: boolean;   // stop asking for this tool within the run
  reason?: string;      // denial reason, fed back to the model
}

Session

Member	Notes
`createSession(options)`	`AgentConfig` plus `checkpointDir?` `sessionId?`
`session.send(prompt)`	one turn, returns `AgentResult`
`session.stream(prompt)`	one streaming turn, returns `AgentStream`
`session.history()`	`Message[]` snapshot
`session.fork()`	branch with the history carried over
`session.close()`	persist and release
`Session.resume(id, { checkpointDir, model? })`	read history back; throws when missing

Snapshots live at checkpointDir/<sessionId>.json and exclude the provider and API keys.

builtinTools (subpath `@neoxlabs/sdk/tools`)

Factory	Options
`fs`	`root` `allowWrite` `exclude` `maxBytes`
`shell`	`allowedCommands` `cwd` `env` `timeout` `maxOutputChars`
`agent`	`name` `description` `model` `systemPrompt` `tools`
`web` / `mcp`	not implemented; throws

API reference