Agent Config

The agent section configures the LLM model, system prompt, tools, and behavior.

Basic Configuration

Configuration Options

Models

Specify models in provider/model-id format. Any model supported by the provider's SDK will work.

Supported Providers

Examples

Dynamic Model Selection

The model field can also reference an input variable, allowing consumers to choose the model when creating a session:

When creating a session, pass the model:

This enables:

• Multi-provider support — Same agent works with different providers
• A/B testing — Test different models without protocol changes
• User preferences — Let users choose their preferred model

The model value is validated at runtime to ensure it's in the correct provider/model-id format.

Backup Model

Configure a fallback model that activates automatically when the primary model encounters a transient provider error (rate limits, outages, timeouts):

When a provider error occurs, the system retries once with the backup model. If the backup also fails, the original error is returned.

Key behaviors:

• Only transient provider errors trigger fallback — authentication and validation errors are not retried
• Provider-specific options (like anthropic:) are only forwarded to the backup model if it uses the same provider
• For streaming responses, fallback only occurs if no content has been sent to the client yet

Like model, backupModel supports variable references:

System Prompt

The system prompt sets the agent's persona and instructions. The input field controls which variables are available to the prompt — only variables listed in input are interpolated.

Variables in input can come from protocol.input, protocol.resources, or protocol.variables.

Input Mapping Formats

The left side (label) is what the prompt sees. The right side (source) is where the value comes from.

Example

prompts/system.md:

Agentic Mode

Enable multi-step tool calling:

How it works:

1. LLM receives user message
2. LLM decides to call a tool
3. Tool executes, result returned to LLM
4. LLM decides if more tools needed
5. Repeat until LLM responds or maxSteps reached

Extended Thinking

Enable extended reasoning for complex tasks:

Thinking content streams to the UI and can be displayed to users.

Skills

Enable Octavus skills for code execution and file generation:

Skills provide provider-agnostic code execution in isolated sandboxes. When enabled, the LLM can execute Python/Bash code, run skill scripts, and generate files.

See Skills for full documentation.

References

Enable on-demand context loading via reference documents:

References are markdown files stored in the agent's references/ directory. When enabled, the LLM can list available references and read their content using octavus_reference_list and octavus_reference_read tools.

See References for full documentation.

Image Generation

Enable the LLM to generate images autonomously:

When imageModel is configured, the octavus_generate_image tool becomes available. The LLM can decide when to generate images based on user requests. The tool supports both text-to-image generation and image editing/transformation using reference images.

Supported Image Providers

Image Sizes

The tool supports three image sizes:

• 1024x1024 (default) — Square
• 1792x1024 — Landscape (16:9)
• 1024x1792 — Portrait (9:16)

Image Editing with Reference Images

Both the agentic tool and the generate-image block support reference images for editing and transformation. When reference images are provided, the prompt describes how to modify or use those images.

Agentic vs Deterministic

Use imageModel in agent config when:

• The LLM should decide when to generate or edit images
• Users ask for images in natural language

Use generate-image block (see Handlers) when:

• You want explicit control over image generation or editing
• Building prompt engineering pipelines
• Images are generated at specific handler steps

Web Search

Enable the LLM to search the web for current information:

When webSearch is enabled, the octavus_web_search tool becomes available. The LLM can decide when to search the web based on the conversation. Search results include source URLs that are emitted as citations in the UI.

This is a provider-agnostic built-in tool — it works with any LLM provider (Anthropic, Google, OpenAI, etc.). For Anthropic's own web search implementation, see Provider Options.

Use cases:

• Current events and real-time data
• Fact verification and documentation lookups
• Any information that may have changed since the model's training

Temperature

Control response randomness:

Guidelines:

• 0 - 0.3: Factual, consistent responses
• 0.4 - 0.7: Balanced (good default)
• 0.8 - 1.2: Creative, varied responses
• > 1.2: Very creative (may be inconsistent)

Provider Options

Enable provider-specific features like Anthropic's built-in tools and skills:

Provider options are validated against the model—using anthropic: with a non-Anthropic model will fail validation.

See Provider Options for full documentation.

Thread-Specific Config

Override config for named threads:

Each thread can have its own model, backup model, MCP servers, skills, references, image model, and web search setting. Skills must be defined in the protocol's skills: section. References must exist in the agent's references/ directory. Workers use this same pattern since they don't have a global agent: section.

Full Example