MCintelligentplus DocsChat Agents
Thinking controls, org-defined agents, prompt guard, approvals, and subagents in chat
Chat Agents
Chat is the primary surface of MCintelligentplus: a multi-agent assistant that searches your knowledge base, calls live connector tools, and produces deliverables — with per-user permissions and human-in-the-loop approvals. This page covers the agent-side features that shipped after the fork.
What you get
- Thinking mode + reasoning effort — a composer control with Thinking
(
auto/on/off) and, for reasoning-capable models, reasoning effort (auto/low/medium/high). Effort is inert while Thinking is off (per ADR-0024), and a turn that ran with thinking off renders no reasoning disclosure. - Agent approval modes — the composer's approval switcher decides which
tool calls ask for confirmation: Ask for approval (
manual), Auto approve (smart), and Full access (off). Under issue #956 the default is locked to off (FORCE_APPROVAL_MODE_OFF, defaultTRUE); set it toFALSEto restore user-configurable modes. - Human-in-the-loop (HITL) interrupts — approval cards render, resume, and reload on the parent side of a paused turn, reject emits a ToolMessage and the turn refuses new input while paused, and paused activity rows continue across a resume.
- Subagents — the main agent delegates to built-in specialists (knowledge
base, google search, web crawler, deliverables, external tools, and
code_executionwhen sandboxed code execution is on) and reports back inline, with bounded waits, cancel, and traces.code_executionruns Python over your attached files in an isolated sandbox and returns pptx, xlsx, docx, html, md, and csv files as artifact cards (see Code Execution). - Org-defined agents — organisations author agent definitions with
capability packs,
replacesrules, and roster control; workspaces pin them (see Org-defined agents). - Prompt-injection guard — screens chat input and agent-authored content in
three states:
off,audit,enforce. - Chat UX refresh (S18-01) — sub-agent lanes, trace detail, turn status labels, clarify mode, and plan mode.
Org-defined agents
An organisation can author its own specialist agents and hand them to chosen
workspaces. To the main assistant they look like any other specialist: it
decides when to delegate from the agent's description and the workspace the turn
runs in. Definitions live in the org portal at /org/<slug>/agents and are
gated by SURFSENSE_ORG_AGENTS_ENABLED (default false) — while the flag is
off the editor pages 404 and the chat path never reads definitions, so authoring
ahead configures something inert rather than something broken.
What a definition contains
| Field | What it is |
|---|---|
| Name / slug | Display name and URL-safe identifier. The runtime subagent name is org_agent_<slug> |
| Description | Routing text the main agent uses to decide when to delegate |
| System prompt | The agent's instructions (up to 50 000 characters), screened by the prompt-injection guard at save time |
| Capability packs | The tool selection unit: deliverables (or its least-privilege slices documents, media, office, data, comms), web_search, web_crawl, knowledge_base, external_tools, memory. Selecting a pack binds its tools plus any middleware they need |
| Tool policy | Per-tool Allow / Ask / Deny rows that refine a pack without hand-picking individual tools (one row per tool name) |
| Replaces | Built-in specialists this agent takes over: deliverables, knowledge_base, google_search, web_crawler, external_tools, google_drive, dropbox, onedrive. Each replaced built-in is suppressed in the agent's workspaces, and its routing description merges into this agent's. main, memory, and mcp cannot be replaced |
| Skills | Baseline org/global skill slugs the agent loads |
| Models | Chat and image model from the global model catalogue (a workspace-scoped model could be valid in one workspace and broken in the next). Empty inherits the workspace's model. An ordered fallback chain of up to 2 chat models is supported |
| Enabled | Off makes the definition inert. An organization may keep at most 20 enabled definitions |
Every edit snapshots the previous configuration into an agent version, and the editor lists that history newest-first so you can see what changed.
Roster control
The Built-in specialists card on the Agents page controls which built-ins exist for the organisation. Turning one off removes it from every workspace of the organisation, for every member — workspaces cannot turn it back on. Use it when an org agent replaces the built-in, or when the capability is not wanted at all.
Assigning agents to workspaces
An org owner assigns a definition to one or more of the org's workspaces from the editor's workspace checklist. Only enabled, assigned definitions are live in a workspace, and routing stays scoped: an agent assigned to workspace A is never consulted in workspace B.
The workspace side lives at Workspace Settings → Org Agents
(/dashboard/<workspace_id>/workspace-settings/org-agents). Tools, instructions,
and models are read-only there — they belong to the org owner. What the
workspace decides is which of its own skills each assigned agent loads: a
workspace skill loads by default, and this page is where one is turned off.
Personal skills never reach an org agent at all.
How to enable
Flags live in the backend environment (surfsense_backend/.env for local dev,
docker/.env for Docker). New-chat flags are resolved at agent build time, so
an env change needs a process restart; most default ON so upgrades work
without new variables.
| Env var | Default | What it does |
|---|---|---|
SURFSENSE_DISABLE_NEW_AGENT_STACK | false | Master kill switch — forces every flag below OFF |
SURFSENSE_ENABLE_SKILLS | true | Skills feature (see Skills) |
SURFSENSE_ORG_AGENTS_ENABLED | false | Org agents consulted by the chat path (the org editor routes work either way, but definitions are inert while off) |
SURFSENSE_PROMPT_GUARD | audit | Guard mode: off, audit, or enforce |
FORCE_APPROVAL_MODE_OFF | TRUE | Locks the approval-mode selector to Off |
THINKING_RULES_V2 | FALSE | Complexity-aware Auto thinking effort + sub-agent effort cap |
THINKING_V2_SUBAGENT_EFFORT_CAP | low | Ceiling for built-in sub-agents under the v2 rules |
SURFSENSE_SUBAGENT_INVOKE_TIMEOUT_SECONDS | 300 | Wall-clock budget per task(...) call; 0 disables |
SURFSENSE_TASK_BATCH_CONCURRENCY / SURFSENSE_TASK_BATCH_MAX_SIZE | 3 / 8 | Batch-mode subagent fan-out caps |
SURFSENSE_SUBAGENT_BILLABLE_THRESHOLD | 15 | Soft per-turn warning threshold for subagent calls |
SURFSENSE_SUBAGENT_LANES | false | Live parallel sub-agent lanes (S18-01) |
SURFSENSE_TRACE_DETAIL | false | Trace drawer |
SURFSENSE_TURN_STATUS_LABEL | false | Persist new_chat_messages.turn_outcome |
SURFSENSE_CLARIFY_TOOL | false | Clarify mode |
SURFSENSE_PLAN_MODE | false | Plan mode |
OUTPUT_GUARD_ENABLED | FALSE | Redact server internals from tool results and streamed text |
For the thinking-rule thresholds (THINKING_V2_*) and the prompt-guard admin
switch, see the annotated surfsense_backend/.env.example.
Where in the UI
- Chat composer (
/dashboard/<workspace_id>/new-chat) — thinking control, reasoning effort, approval-mode switcher, model selector. - Chat thread — approval (HITL) cards, subagent status, trace drawer, reasoning disclosure, deliverables.
- Org portal → Agents (
/org/<slug>/agents) — org agent definitions, version history, roster control, and workspace assignment. - Workspace Settings → Org Agents
(
/dashboard/<workspace_id>/workspace-settings/org-agents) — which workspace skills each assigned org agent loads. - Admin → System → Security — the prompt-injection guard selector (DB-first: the portal value wins over the env var).
- Admin → Audit Logs — filter
action=prompt_guard.flaggedto review audit-mode findings.
Related PRs
- #967 / #972 — thinking mode + reasoning effort, compact thinking control
- #968 / #969 — approval-mode quick switcher, Qoder-style option naming
- #956 / #957 — default approval mode Off and lock the selector
- #975 — org-defined agents with capability packs (INT-017/S16-01)
- #1105 / #1110 / #1111 / #1112 — parent-side HITL routing, cards, reject, resume
- #1113 / #1053 / #1024 — prompt guard enforcement, SQLite survival, pre-check
- #1074 / #1088 — subagent dispatch fixes that hardened subagent reports
- #1143 — S18-01 chat UX refresh (lanes, trace, metrics, plan mode)
- #1172 — agent quality review: thinking rules v2, output guard, turn budget