Agents

Tools and presets

Understand the action surface a model sees, and narrow it when a workflow should not reach every operation.

A preset is the tool surface a model sees: the tool definitions, the system prompt describing them, and the dispatcher that runs them. The SDK ships core, full, and legacy.

The core preset

preset: 'core' advertises two tools:

ToolPurpose
superdoc_inspectRead-only snapshots of current document state
superdoc_perform_actionOne named, statically validated edit verb from the action registry

Every edit runs through the second tool with an action argument naming what to do. The actions are grouped by what they touch: text and structure, lists and numbering, comments, tracked-change review, formatting, tables, and history. The action reference lists each one with its arguments.

Two tools instead of one per action keeps the advertised surface small while the action enum stays explicit. The model picks a verb by name rather than assembling an operation, and an unknown verb is rejected before anything touches the document.

Narrow the surface

Pass excludeActions when a workflow should not reach part of the surface:

import { createAgentToolkit } from '@superdoc/sdk';

const { tools, systemPrompt, dispatch } = await createAgentToolkit({
  provider: 'anthropic',
  preset: 'core',
  excludeActions: ['accept_tracked_changes', 'reject_tracked_changes'],
});

An agent that proposes edits but never resolves them is a common shape: it can suggest, and a person still decides.

Exclusions apply to all three pieces at once. The action leaves the tool enum, its documentation leaves the system prompt, and dispatch refuses it even if the model guesses the name. An unknown action name throws immediately rather than silently doing nothing, so a typo in an exclusion list surfaces at startup instead of in production.

enforceChangeMode: 'tracked' narrows the surface by policy instead of by name: every action that cannot record a tracked change is excluded the same way, every other action is forced to run tracked, and allowDirectActions reopens the direct-only actions a workflow still needs. Build an agent covers it in full.

Prompt caching

Tool definitions and system prompts are stable across requests, so they cache well:

import { createAgentToolkit } from '@superdoc/sdk';

const { tools, meta } = await createAgentToolkit({
  provider: 'anthropic',
  preset: 'core',
  cache: true,
});

meta.cacheStrategy reports what actually happened. Anthropic marks the tool block explicitly and reports explicit. OpenAI caches long prompts on its own and reports automatic. Vercel and generic providers pass through and report unsupported, because caching depends on the model underneath.

The legacy preset

preset: 'legacy' is the older surface: ten grouped intent tools, each taking an action argument, generated from the Document API contract.

It remains the default when preset is omitted, so code written before presets existed keeps working. One consequence is worth knowing:

  • A createAgentToolkit() call with no preset gets legacy, not core.

Build new integrations on core. Use legacy when you already have one running on it, and see Legacy tools for what it advertises and how to move.

The full preset

preset: 'full' keeps the two core tools and adds two, so the model can reach the whole Document API:

ToolPurpose
superdoc_api_searchSearch the Document API and read an operation's parameters
superdoc_api_callRun one Document API operation, or several in order as one batch

To switch an existing toolkit, change preset: 'core' to preset: 'full'. Use the returned tools, systemPrompt, and dispatch together; the toolkit updates all three. If you configure them separately, select full for each.

import { createAgentToolkit } from '@superdoc/sdk';

const { tools, systemPrompt, dispatch } = await createAgentToolkit({ provider: 'openai', preset: 'full' });

Use it when a workflow needs operations the core actions do not cover, such as Word table styles, page setup, or headers and footers. Pin the SDK version because its tools and prompt can change between releases. The Node.js and Python SDKs offer it. The MCP server does not.

Custom loops must accept superdoc_api_search and superdoc_api_call and handle their results. The Build an agent example includes core-specific tool checks that need adapting.

Replay a call without the model

Any tool call the model makes is an ordinary SDK operation underneath. When output looks wrong, run the same operation directly:

const receipt = await dispatch(doc, 'superdoc_perform_action', {
  action: 'replace_text',
  find: 'termination',
  replaceWith: 'cancellation',
  changeMode: 'tracked',
});

If the direct call produces the right result, the operation is fine and the model chose or parameterized it badly. If it reproduces the problem, the operation is where to look. Separating those two cases first is the fastest way to stop debugging the wrong layer.

Next

Custom actions adds a verb of your own to this surface. Safety covers the operational boundary around an agent. Receipts and errors explains the result contract a dispatched action returns. Reads and validation failures do not follow it: superdoc_inspect returns a snapshot with no status, and an invalid argument throws before any receipt exists.

On this page