Preference Reference

Behavior is shaped through a flat set of settings addressed by dotted paths, grouped into four namespaces: inference, capability, source, and trait. Four layers contribute values on these paths. The project and each agent contribute through prefers, and they also restrict what the layers above them may contribute through constrains and pins. A user and an individual request contribute preferences only. This page is the complete catalog of preference paths, with the type, allowed values, and default for each.

With the one exception noted below, every path listed here is a preference: a value that a user or a request can contribute, subject to the constraints and pins set by the project and the selected agent. Behavior that a request must never influence is policy, not a preference, and lives on a resource body instead. For those fields, such as the project context budget, see the Resource Reference page. For how a value is resolved across the request, user, agent, and project layers, see the Overview page. For the authoring primitives and the decision rule between prefers, constrains, and pins, see the Authoring Agents page.

Tri-State Toggles

The capability and source switches accept three values rather than a plain boolean:

• true

  The capability is on. The value is taken as written and never re-derived, so turning on a capability backed by a resource kind you have not published gives the agent the capability with nothing to reach.

• false

  The capability is off. Again the value is taken as written, so a capability set to false stays off even when the resources that would back it are present. This is the difference from auto: only auto is derived.

• auto

  The default. The platform derives the effective value. For a switch backed by a resource kind, such as capability.mcp.enabled or source.knowledge_graph.enabled, auto turns the capability on when your configuration publishes at least one resource of that kind, and off otherwise. A per-graph switch, source.knowledge_graph.graphs.<id>.enabled, is backed by the one graph it names, so auto keeps every graph you publish in scope. For a switch that is not backed by a resource, auto turns the capability on.

No other value is accepted. A deploy that sets a switch to anything else, 0 and 1 included, is rejected. A value of the wrong type from a user or a request, such as the string "false" or the number 1, is recorded as invalid, and resolution moves on to the next source.

A switch resolves separately for each agent. A switch that a request turns off stays off for every agent that turn delegates to, unless that agent pins it on, whereas a value set on an agent governs that agent alone. A restriction that must hold for every agent therefore belongs on the Project resource.

Inference Settings

Path	Type	Default	Description
inference.model	Model id	none	The model used to generate responses. The value is the metadata.id of a Model resource. It has no built-in default, so every project must set it in prefers or pins. A project that does not fails both genai lint and the deploy.
inference.reasoning_effort	disabled / low / medium / high	unset	How much reasoning depth to trade for latency. When unset, the provider default applies. disabled suppresses reasoning on a reasoning-capable model, and low, medium, and high step the effort up. Effort applies only to a model whose catalog entry sets enable_reasoning: true.

Capability Settings

Path	Type	Default	Description
capability.code_interpreter.enabled	true / false / auto	auto	Allow the agent to run code in a sandbox. Backed by the CodeInterpreter resource.
capability.mcp.enabled	true / false / auto	auto	Allow the agent to use tools from external MCP servers. Backed by the MCP resource.
capability.subagents.enabled	true / false / auto	auto	Allow the agent to delegate to other agents.
capability.filesystem.enabled	true / false / auto	auto	Allow the agent to read from the sandbox filesystem.
capability.tasks.enabled	true / false / auto	true	Allow the agent to create and manage scheduled tasks on behalf of the user. The platform controls this path, so writing it in prefers or pins fails the deploy. See the note below.
capability.studio_mcp.enabled	true / false / auto	auto	Allow the agent to use tools exposed by Squirro Studio plugins. Unlike the MCP switch, this reaches a cluster-internal channel rather than a resource you publish, which is why auto is on. Setting false withdraws every Studio plugin tool at once, so it is an operator-level switch rather than a way to pick among servers. To choose which Studio plugin tools each agent sees, see the Studio Plugin Tools section.

Note

capability.tasks.enabled is the one path in this table you cannot author. It is on for every project, and it is listed here because it governs whether users can create scheduled tasks by asking an agent. Every other path in the table is set through prefers, constrains, or pins in the usual way.

Source Settings

Path	Type	Default	Description
source.documents.enabled	true / false / auto	auto	Use document retrieval for the conversation.
source.documents.limit	integer, 1 to 200	20	Maximum number of documents to retrieve.
source.documents.filter	string	""	Search filter expression applied to retrieval.
source.knowledge_graph.enabled	true / false / auto	auto	Use knowledge graph retrieval for the conversation. Backed by the KnowledgeGraph resource. While it is off, every knowledge graph query is refused.
source.knowledge_graph.graphs.<id>.enabled	true / false / auto	auto	Keep the KnowledgeGraph whose metadata.id is <id> in scope. There is one path per graph you publish. A graph out of scope cannot be queried, even by a call that names it.
source.knowledge_graph.default	KnowledgeGraph id	unset	The knowledge graph the agent queries when a call does not name one. It must name a published graph. When it names one that is out of scope and is not pinned, the next source in the resolution order that names a graph in scope supplies the default instead. A pinned default that names an out-of-scope graph leaves no default. An explicit null means no default, even with one graph in scope. Failing that, a single graph in scope becomes the default if the restrictions on this path admit it, and otherwise the agent names a graph on each call.

Trait Settings

The trait namespace is parametric: it has one path per TraitDimension your configuration declares.

Path	Type	Default	Description
trait.<dimension>	trait id	unset	The active trait for the dimension named <dimension>, whose value is the id of one trait within that dimension. When unset, the dimension contributes no prompt fragment.

For example, a TraitDimension with metadata.id: style is addressed as trait.style, and setting trait.style: concise activates the concise trait. For the authoring workflow, see the Authoring Agents page.