API reference

This is the full reference for the .nt format. It lists every keyword (block), every field you can set on it, the values each field accepts, and the default when you leave it out.

Field types

input, output, and a tool's input are maps of fields. Each field is either a bare type or an object with more detail.

input:
  clues: string # short form
output:
  age:
    type: number # full form
    description: The best guess.
    required: false # optional; defaults to true

Thinking levels

Several places accept a thinking level. From least to most effort:

config

Project-wide settings. One config block per project.

config.defaults

config
  target: node
  entry: age
  audit: ~/.nt/audit
  show_tool_calls: true
  defaults:
    model: anthropic/claude-sonnet-5
    sandbox: workspace
    thinking: medium
    max_tokens: 8000
  providers:
    anthropic:
      api: anthropic
      api_key: env(ANTHROPIC_API_KEY)

config.audit

This is one scalar setting: use a folder, a disable word, or an enable word.

A leading ~ expands to the home folder; a relative folder resolves against the .nt file that declared it. A map, a list, or an env() reference is an error.

Each line records the time, run id, agent, delegation depth, tool, tool kind, input, success, duration, and output — with credentials redacted. Read them back with nt audit, and see Audit the tool calls for the full field list.

provider

Where the model comes from. Declared on its own or under config.providers.

provider ollama
  api: openai-completions
  base_url: http://localhost:11434/v1
  api_key: env(OLLAMA_API_KEY, ollama)

agent / subagent

The core worker. agent and subagent accept exactly the same fields.

agent age
  description: Guesses a person's age from clues.
  model: anthropic/claude-sonnet-5
  thinking: high
  max_tokens: 8000
  sandbox: workspace
  tools: [current_year, fs_write]
  subagents: [researcher]
  skills: [estimation]
  instructions: |
    Guess the person's most likely age from the clues.
  input:
    clues: string
  output:
    age: number
    reason: string

Built-in tools

You can list these under tools without declaring them:

sandbox

The workspace an agent reads, writes, and runs commands in.

sandbox workspace
  description: In-memory workspace.
  type: virtual
  cwd: /workspace
  env:
    GREETING: hello

tool

A custom power an agent can call. {placeholders} are filled from the tool's input. The built-in tool names (fs_read, fs_write, fs_list, bash) and the delegate_to_ and mcp__ prefixes are reserved and cannot be used as tool names.

tool current_year
  description: Returns the current four-digit year.
  type: shell
  command: date +%Y
  confirm: true

tool lookup
  description: Fetch a record by id.
  type: http
  method: GET
  url: https://api.example.com/records/{id}
  input:
    id: string

A tool with confirm: true never runs unapproved: the CLI stops and asks, the --yes flag pre-approves, and a run with no way to ask (piped output, or an embedder that wired no confirm callback) refuses the call. Recommended for shell tools and http tools that POST.

mcp

Declares a local or remote MCP tool server. Loading and validation remain offline; connecting requires a separately persisted trust fingerprint.

auth.type defaults to none. Bearer auth requires token: env(NAME) without a fallback literal. OAuth accepts scopes: [...] and is completed with nt mcp auth SERVER.

A tools list gives each selected tool the default required approval. Map entries accept approval (required, once, or never), an optional local description, and a per-tool call_timeout_ms. Its effective value is capped at the server timeout. A wildcard "*" may not use never. See the MCP guide for complete security and lifecycle examples.

skill

Reusable instructions loaded into an agent's prompt.

skill estimation
  description: A checklist for guessing an age.
  instructions: |
    1. Turn each clue into a year.
    2. Pick one number.

workflow

A fixed sequence of steps that pass results forward.

Each entry in steps accepts:

workflow estimate_age
  description: Find the year, then guess the age.
  agent: age
  input:
    clues: string
  output:
    estimate: object
  steps:
    - agent: researcher
      prompt: "What year does this point to: {clues}"
      into: year
    - prompt: |
        Guess the age. Clues: {clues}. Year: {year}
      into: estimate

import

Pulls in another file or folder. Put imports at the top of a file.

import ./config.nt
import ./subagents

Defaults & limits

Handy values built into the engine:

TypeScript engine API

Install @age.nt/engine when an application needs to embed NT instead of launching the CLI:

npm install @age.nt/engine

Published packages contain compiled JavaScript and require Node 22.18 or newer. The engine has three exact-pinned runtime dependencies: the official MCP client, Ajv, and Undici. Model-provider requests use the platform fetch.

Load and run

import { Engine } from "@age.nt/engine";

const engine = Engine.load("age.nt", {
  verbose: false,
  onStep: (event) => console.error(event),
  confirm: async (request) => {
    console.error("Approval required", request.tool, request.input);
    return false;
  },
});

try {
  const kind = engine.isRunnable("age");
  const status = engine.bringUp();
  const result = await engine.runAgent("age", { clues: "retired last year" });
  const workflow = await engine.runWorkflow("estimate_age", { clues: "..." });
  const chat = engine.createChat("age");
} finally {
  await engine.close();
}

EngineOptions accepts verbose, onStep, confirm, mcpTrustFile, and mcpCredentialFile. The last two paths let an embedding application isolate MCP persistence. A closed engine rejects new runtime and MCP work; close() is idempotent and should always run in finally.

MCP methods

Trust is never implicit. An embedder should display mcpTrustInfo, review its boundary, and pass the displayed fingerprint to trustMcp before live discovery. OAuth embedders own the loopback or application callback and pass its validated query parameters to authorizeMcp.

Other exports

The package barrel also exports:

• loadProject and discoverNtFiles for offline loading;
• ChatSession for stateful conversations;
• scaffoldProject, DEFAULT_TEMPLATE, SCAFFOLD_ENTRY_FILE, and TEMPLATE_NAMES for starter projects;
• auditFiles and readAuditEntries for bounded audit-log reads;
• NtError and McpError (McpError.code is a stable MCP_* value);
• typed project definitions, statuses, results, callbacks, MCP metadata, diagnostics, and scaffold shapes exported from the package root.

Internal #... modules are not public API. Import consumers only from @age.nt/engine.