Docs
Configuration
The full option surface, shared by NodeAgent, BrowserAgent, and the core NanoCodana constructor — platform-specific options are marked.
Common options#
| Option | Description |
|---|---|
| model | Required. Any AI SDK LanguageModel. |
| imageModel | Optional AI SDK ImageModel. When set, exposes a GenerateImage tool that writes generated images to the filesystem. |
| imageOutputDir | Where images a multimodal model emits directly (not via the tool) are auto-saved. Default generated. |
| systemPrompt | Override the generated prompt. |
| tools | Extra tools (a record, or (ctx) => record). Merged with the built-ins. |
| toolMiddleware | 'auto' | 'hermes' | 'morphXml' or any AI SDK middleware. Parses tool calls the model emits as plain text, so models without native tool calling can still drive the agent. |
| promptCaching | Default true. Automatic Anthropic prompt caching: marks the system prompt, tools, and conversation tail as cacheable — up to ~90% cheaper input on long sessions. See Prompt Caching. |
| initialFiles | Seed the agent's filesystem with { path, content } entries. content may be a function (sync or async) to hydrate lazily on first read. Not on NodeAgent, which works against a real directory. |
| onFilesChange | Callback fired with every file the agent creates, edits, or deletes — the hook for mirroring the agent's work into your own UI or store. |
| mcpServers | MCP servers to connect; their tools are merged in. |
| needsApproval | Names (or a predicate) of tools that require approval. |
| skills / skillDirs | Explicit skills / dirs to scan (default .agents/skills, .claude/skills). |
| compact | Compact tool descriptions + prompt to save tokens. |
| stopWhen | When the tool loop should stop. |
| virtualBash | Include the in-memory Bash tool (default true). false drops it; an object configures the shell, e.g. { env, maxCommandCount }. |
Platform-specific#
| Option | Description |
|---|---|
| workingDirectory | (Node) Root for the file tools. |
| persist / persistKey | (Browser) IndexedDB (default) vs in-memory only, and which store to use. |
| fs / sandbox | (Core) Your own filesystem or sandbox backend. |
Nearly all of these can also be changed for a single turn — see Per-call Overrides for the exact list and the caching rules.