Tab: Settings
The Settings tab holds the per-agent configuration that is not prompts, tools, skills, or channels: which model answers, how it reasons, what the engine injects into each turn, and the encrypted credentials the agent uses.
Per-agent settings vs deployment environment
Everything on this tab is stored per agent, in the database, and takes effect on the next turn. It is not the same thing as the deployment’s environment variables:
| Configured here (per agent, in the DB) | Configured by the deployment (environment variables) |
|---|---|
| Provider, model, embedder, thinking, temperature | Which providers the engine can reach at all, and the tier→model tables |
The agent’s own API keys, encrypted in instance_secrets | Database URL, encryption key, auth secret, object storage, plugin directories |
| Prompt-cache switch and TTL, datetime injection, state in prompt | Retention default window, throttle limits, default organization |
Feature flags (memoryEnabled, knowledgeEnabled, langsmithEnabled, authEnabled) | Whether enterprise features are enabled for the deployment |
Two agents in the same engine can run on different providers with different keys. See Environment variables for the deployment side.
Model
One provider select and one model select — not one dropdown per tier. Providers: openai, anthropic, bedrock, nebius. The model list is served by the engine and filtered to the chosen provider.
The fast / standard / heavy tier → model mapping is global, defined in the engine’s model catalogue. Picking a model here pins the agent’s user-facing turn; background work (memory extraction, titles, summaries, event matching) stays on the provider’s fast-tier model so a premium pin does not multiply the cost of fire-and-forget work. See AI Gateway for the resolution rules and the tier tables.
A pricing dialog next to the selects lists the catalogued models with their input/output and cache rates, searchable and filterable by provider.
Embedder
A separate select, independent of the chat provider: openai (text-embedding-3-small) or bedrock (Amazon Titan Text Embeddings v2). Anthropic and Nebius have no embedding API, so an agent chatting on Anthropic still needs an embedder configured — but it does not have to be OpenAI.
Changing the embedder permanently deletes data. Vectors live in a provider-specific space and are not converted. Switching the embedder deletes every memory and the entire knowledge base (documents, chunks, and raw content) for that agent, in one transaction, then realigns the vector dimension to the new provider’s default. Conversations themselves are untouched. The panel confirms before saving.
Bedrock embeddings need the AWS provider credentials below, including a region — from the agent’s secret or the engine’s AWS_REGION.
Thinking and reasoning level
Thinking exposes the per-agent thinkingEnabled flag. When on, the engine asks the model for extended reasoning — better quality on hard tasks, at the cost of latency and tokens.
The toggle is gated by the resolved model’s capability, read from the engine’s model catalogue rather than guessed from the model id:
- A model with no reasoning support disables the toggle, and a stale
thinkingEnabled = trueis dropped at resolution time — nothing crashes, the feature is simply off. - A model that always reasons (no off-switch) shows as such: only the effort is tunable.
- When the model exposes reasoning levels, a reasoning level select appears with exactly the levels that model accepts. The sets differ per model, so no request is sent with an effort the provider would reject.
Temperature
Optional per-agent override; left empty, the provider default applies. The field is disabled when the resolved model does not accept a temperature parameter, or when thinking is on for a model that rejects the two together.
Prompt cache
The system prompt is built as a stable prefix (the agent’s prompt sections, the framework tags note, the opt-out hint, and any persisted webhook context) plus a per-turn volatile tail (current datetime, channel identity, conversation summary, conversation state). Only the prefix is worth caching, and that split is why caching pays.
- Cache — on by default. Off skips every cache marker, so the provider never pays a cache write.
- TTL —
5mor1h, default1h.
The trade-off is a real one. A cache write costs more than an uncached read (on Anthropic, roughly 2× at 1h and 1.25× at 5m); a cache read is much cheaper. So 1h fits slow asynchronous channels like WhatsApp and Telegram, where turns arrive minutes apart and a 5-minute prefix would expire between turns and re-pay the write with no read. 5m fits interactive, bursty agents.
Provider behaviour differs, and the panel says which case applies:
- Anthropic and Bedrock need an explicit cache marker — this is where the switch and the TTL act. Bedrock caches at 5 minutes regardless of the TTL chosen.
- OpenAI caches automatically; the switch has no effect.
- Nebius has no cache API and gives no cache discount.
Turn injection
- Conversation state in prompt — off by default. When on, the current conversation state store is rendered read-only into the turn so the model can see the known facts. Off keeps the store purely tool-to-tool. Values are truncated so a large blob cannot blow up the prompt; the store, not the prompt, stays the source of truth.
- Datetime injection — on by default. Injects the current date and time as a
<current_datetime>tag in the volatile tail, outside the cached prefix. Off makes the agent time-agnostic. - Tool results in history — off by default. When on, prior turns’ tool calls and results are reconstructed (truncated) into the cross-turn history, so the model “remembers” what a tool returned. Off keeps the history text-only.
- Debug payload — off by default. When on, the exact LLM request (full system prompt, messages array, tool definitions) is persisted per assistant turn for analysis. It is heavy and it stores personal data at rest — turn it on for an investigation, not permanently.
- Governance history turns — how many recent turns the semantic governance gates receive as context. Default 10.
Feature flags
memoryEnabled— extracts facts from each conversation in the background and writes them to the memory store. Requires a configured embedder (see above). Default: on.knowledgeEnabled— activates the per-agent knowledge base and registers the knowledge tools. Also requires an embedder. Default: off. See Knowledge tab.langsmithEnabled— mirrors every LLM call to LangSmith. Requires the LangSmith API key.authEnabled— requiresAuthorization: Bearer <auth-api-key>on/v1/chat/completions. Off by default; turn it on before exposing the engine to the public internet.
When memory or knowledge is on and the selected embedder has no credentials, the panel warns inline instead of leaving you to find it in the engine logs.
Speech-to-text provider
The sttProvider select picks the backend for inbound voice notes on WhatsApp and Telegram:
openai— Whisper, via the OpenAI key. The default.aws— Amazon Transcribe, via the AWS provider credentials.deepgram— requires the Deepgram key.
API keys (per agent, encrypted)
| Field | Used by |
|---|---|
openai_api_key | OpenAI chat completions; OpenAI embeddings; Whisper STT |
anthropic_api_key | Anthropic chat completions |
nebius_api_key | Nebius chat completions |
bedrock_api_key, aws_provider_access_key_id, aws_provider_secret_access_key, aws_provider_region | Bedrock chat, Bedrock embeddings, Amazon Transcribe |
langsmith_api_key | Tracing, when langsmithEnabled is on |
auth_api_key | The bearer token callers must send to /v1/chat/completions, when authEnabled is on |
deepgram_api_key | Deepgram STT |
tavily_api_key | The webSearch tool |
The AWS provider block appears only when Bedrock chat, the Bedrock embedder, or Amazon Transcribe is selected. It is a dedicated namespace, deliberately distinct from the generic aws_* secrets a tool may declare — so the AI provider and a tool such as file upload can use different AWS accounts.
Beyond these, the tab renders the secrets declared as requiredSecrets by the tools and skills currently enabled on the agent, so the visible list depends on what is enabled.
Every value is encrypted with AES-256-GCM. The panel never shows a stored value back: you can rotate or remove, not view.
See also
- AI Gateway — tiers, provider resolution, capability gates.
- Prompt — what the cached prefix and the volatile tail contain.
- Environment variables — the deployment-level configuration.
- Manage secrets — the API for the same secrets.