Adding a New Agent

Agents are the backend workers that power Errata's LLM features — prose analysis, librarian chat, fragment refinement, character chat, and more. Each agent has: • A definition (name, input schema, run function) • Context blocks (system prompt + user context assembled from story data) • A model role (determining which LLM provider/model is used) • An instruction key (allowing users to override the system prompt per model) • A block definition (enabling UI-based context customization) Agents are auto-discovered at startup. The only convention required is exporting a register function from src/server/<namespace>/agents.ts.

This guide walks through adding a new agent to Errata. It covers the file structure, registration system, context assembly, streaming, model resolution, UI integration, and testing. The librarian.optimize-character agent (which rewrites character sheets using a creative writing methodology) is used as a running example.

Every agent namespace follows the same pattern: ` src/server/<namespace>/ ├── agents.ts # Registration hub (auto-discovered) ├── blocks.ts # System prompts and context block builders ├── <runner>.ts # Runtime logic (e.g. chat.ts, refine.ts) └── ... # Other files as needed ` For the optimize-character agent, the files are: | File | Purpose | |---|---| | src/server/librarian/agents.ts | Registration (modified — shared with other librarian agents) | | src/server/librarian/blocks.ts | System prompt + block builder + preview context (modified) | | src/server/librarian/optimize-character.ts | Runtime logic (new) | | src/components/agents/AgentContextPanel.tsx | UI ordering (modified) | If you're creating a brand new namespace (not adding to an existing one like librarian), you'd create a new directory under src/server/.

The system prompt is the agent's core instructions. Define it as an exported constant in blocks.ts. `ts // src/server/librarian/blocks.ts export const OPTIMIZE_CHARACTER_SYSTEM_PROMPT = `You are a character optimization agent...