Docs

Per-call Overrides

An agent compiles its model, skills, tools, and system prompt once and caches them. Each stream() or generate() can override settings for that turn — NanoCodana rebuilds only what changed and reuses the rest, so you never construct a second agent just to tweak one knob.

await agent.stream({ messages })                          // uses construction defaults
await agent.stream({ messages, model: openai('gpt-5.1') }) // swap model this turn
await agent.stream({ messages, disableTools: ['Bash'] })  // no shell this turn
await agent.stream({ messages, activeTools: ['Read', 'Grep'] }) // read-only turn

What you can override#

Per call: model, imageModel, toolMiddleware, tools, skills, skillDirs, systemPrompt, compact, needsApproval, activeTools (allow-list), disableTools (deny-list), and stopWhen. Omit a field to reuse the value from construction.

Patterns this unlocks#

A cheap model for summarization turns and a strong one for edits. A read-only “explain this codebase” mode with activeTools: ['Read', 'Grep', 'Glob']. A locked-down turn with approval on everything while a new user builds trust. One agent instance serves all of them.

Pass stable references for unchanged values (don't rebuild the tools record inline on every call) so the compile cache can reuse them rather than rebuild.