Model

The Model section (an agent’s Configuration group) holds the models the agent runs, one block per task: Conversation (the model that replies, how it reasons, its prompt cache), Embeddings and Audio transcription. On the open-source build each block carries the provider keys its task needs, so a key is typed next to the choice that uses it. Keys stored on the agent that no task uses are listed under Unused keys, where they can be removed.

Managed services. No key is typed here. The section is a table with one row per task the agent calls a provider for (the conversation, the embedder, voice-note transcription, and the voice tasks the agent uses), showing the provider, the model, the provider connection it authenticates with and whether it can run. A row opens the task in a side panel where all of it is chosen and saved together. Connections themselves are listed and added in the agent’s Providers section. There is no Unused keys list: provider keys left in the agent’s secrets after the upgrade to 1.2.0 are removed through the API (see Provider keys left in the secrets).

What the engine injects into each turn, the behaviour overrides and the memory switch are in the Advanced section, the last row of the Behaviour group. This page documents both sections: Behaviour overrides, Turn injection, Memory scope, Attachment storage and the memoryEnabled flag belong to Advanced, the rest to Model.

Per-agent settings vs deployment environment

Everything in these two sections 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:

Two agents in the same engine can run on different providers with different keys. See Environment variables for the deployment side.

A third kind of setting is neither per agent nor in the environment: the installation’s operational limits (rate limits, live-stream caps, agent-to-agent and MCP timeouts, the scheduler’s grace and deadline) are installation policies, edited by a platform admin without a redeploy.

Behaviour overrides

Six values that used to be set once for the whole installation, and are now this agent’s. They are in the Advanced section:

An empty field is not zero. Empty means this agent declares nothing and the default applies - which is why the placeholder shows that default rather than the field being pre-filled with it. Clearing a field hands the value back to the default; typing 0 is a choice (no debounce, no typing delay, no restart) and is kept as one.

The message timings are resolved once per burst, when its first fragment arrives, so a change takes effect from the next conversation rather than halfway through one in flight.

Model

One provider select and one model select - not one dropdown per tier. Providers: openai, anthropic, bedrock, nebius, and with managed services tensorx, scaleway and regolo. The model list is served by the engine and filtered to the chosen provider and, with managed services, to what the agent’s workspace admits. A change of model alone is checked against the provider the agent already runs on, so a model that provider does not serve is refused on save instead of failing at the first message.

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 Model catalog 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 in the Embeddings block, independent of the chat provider. It lists the embedders the server actually serves: openai (text-embedding-3-small) and bedrock (Amazon Titan Text Embeddings v2), and with managed services tensorx and regolo (both Qwen3-Embedding-8B at 1024 dimensions). Anthropic, Nebius and Scaleway have no embedder here, so an agent chatting on one of them still needs an embedder configured - but it does not have to be OpenAI. An embedder name the server does not serve, from an import or a stale row, fails instead of falling back to OpenAI, and an import that names one is refused.

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; with managed services, a Bedrock connection with its region bound to the agent’s embedding role. There is no deployment-wide fallback: a Bedrock embedder with no region is refused, as Bedrock chat is.

Knowledge access level

Beyond the knowledgeEnabled switch, an agent declares how much of its knowledge base tool code may do. The setting is on the Knowledge section, under Tool access: Read only (read), Read and write (write) or Full management (manage). The three are nested, so raising the level adds and never rearranges.

The level governs ctx.knowledge, which is mounted on every tool of the turn - plugin tools included. That is why a new agent starts at read and why the upgrade did not simply grant write to everyone: an agent that already held documents written by its own knowledge tools kept write, because dropping it would break a working agent, and every other agent stayed at read, which is exactly what it was using. manage is never assigned by a migration.

See Add a tool for what tool code can do at each level.

Memory scope

Managed services.

Whether the agent’s long-term memory is one pool shared across its conversations (Shared across conversations, the default) or partitioned so a turn reads only what its own conversation wrote (Isolated per conversation). It changes what later turns can recall, not what is stored, and it is not retroactive. See Memory → Scope.

Attachment storage

The Store attachments card in the Advanced section decides whether the files users send (photos, documents, voice notes) are kept in this agent’s S3 bucket, so they can be reopened from the conversation. It is off by default, and the model sees the file either way. Once it is on, the card asks for the bucket, its region and an access key that may write, read and delete under attachments/, stored as the agent’s s3_bucket_name, aws_region, aws_access_key_id and aws_secret_access_key secrets. These are separate from the AI provider’s AWS credentials. With managed services the bucket and region can come from the organization’s shared credentials; the card shows a value inherited that way.

The bucket is reached only with these static keys, never with the deployment’s own AWS identity. See Attachment storage for the IAM permissions and what happens to stored files when a conversation or the agent is deleted.

Thinking and reasoning level

Extended 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.

When off, the engine says so to the model on the models that reason by default: OpenAI gpt-6-sol and gpt-6-luna receive reasoning_effort: "none", and Claude Opus 5 and Sonnet 5 receive thinking disabled, on the Claude API and on Bedrock alike. Leaving the parameter out would let them keep reasoning, and billing for it. Claude Sonnet 5.5 refuses the usual off-switch, so off sends its lowest setting (thinking only between tool calls).

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 = true is dropped at resolution time - nothing crashes, the feature is simply off.
• A model that always reasons (no off-switch) shows the toggle locked on: only the effort is tunable. Claude Fable 5 and Fable 5.1, Claude Opus 5.5 and gpt-6-astra are among them.
• 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 - 5m or 1h, default 1h.

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 for a new agent: off. The switch is in the Advanced section.
• 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 - requires Authorization: Bearer <auth-api-key> on /v1/chat/completions. On by default for a new agent since 1.2.0; turn it off only for an agent meant to be public.

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.

With managed services the warning comes from the engine’s own resolution of the agent’s embedding role, the same one the embedder runs: no connection bound, a connection not lent to the workspace, a private connection in a managed-only organization, or one for another provider. See Provider connections and roles.

Speech-to-text provider

The Transcription Provider select (sttProvider), in the Audio transcription block, picks the backend for inbound voice notes on WhatsApp and Telegram. A new agent starts at Disabled.

• openai - Whisper, via the OpenAI key.
• aws - Amazon Transcribe, via the AWS provider credentials.
• deepgram - requires the Deepgram key.
• disabled - no transcription at all. An explicit choice rather than an absent key, so “we do not transcribe voice” and “someone forgot the key” stop looking the same. The agent’s Status section reports the second and not the first.

With managed services, transcription authenticates with the connection bound to the agent’s stt role, which must be for the provider this select names: an OpenAI connection, a Bedrock connection holding an access-key pair and a region (Amazon Transcribe never signs with the deployment’s own AWS identity), or a Deepgram connection. A provider the workspace does not admit is refused; Deepgram is outside the provider catalogue, so no admission applies to it. See Provider connections and roles.

API keys (per agent, encrypted)

A key is typed beside what uses it. On the open-source build a provider key goes in this section, in the block of the task that reads it (Conversation, Embeddings, Audio transcription). A tool’s keys are typed in that tool’s panel on Tools, a hook’s on Hooks, a channel’s credentials on Channels. There is no separate Credentials section. The table below is the reference for what each provider-side key is used by.

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.

The secrets a tool declares as requiredSecrets are not listed here: they are typed in that tool’s panel, and a tool whose required secret is missing is not served to the model.

Every value is encrypted with AES-256-GCM. The panel never shows a stored value back: you can rotate or remove, not view.

With managed services the provider keys in this table are not agent secrets. Each task authenticates with the provider connection bound to its role in the agent’s Providers section: one the organization lends to the agent’s workspace, or one private to the agent where the organization allows it. The key bytes never reach the panel, and the secret routes refuse to store a provider key. langsmith_api_key, auth_api_key and tavily_api_key stay agent secrets. See Provider connections and roles.

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.