Cortex (Chat)

The customer-facing chat application. Multi-turn conversations, tool-calling, @mentions, sub-agents, content blocks, and admin oversight.

Cortex is the customer-facing chat application. It provides a multi-turn conversational interface backed by an agentic engine — not a raw LLM API, but a tool-calling loop that can search knowledge bases, run workflows, query ontology data, launch automations, call integrations, and delegate to specialist sub-agents, all within a single conversation thread.

Cortex is not an LLM gateway. LLM provider resolution and credential handling happen in the capability runtime hosted by the platform service. Cortex calls agentic for completions and forwards tool results through the governed tool bridge.

What it does

Concern	How Cortex handles it
Conversations	Persists multi-turn conversation history in `@scrydon/db-cortex`. Ordinary Cortex conversations are workspace-scoped and user-owned. A Process Flow action can instead bind one shared resource conversation to everyone currently authorized for that action.
Streaming	Streams LLM responses to the browser over SSE. A snapshot cache lets reconnecting clients replay missed events without restarting the turn.
Tool-calling loop	Runs an iterative tool-call loop (up to 10 iterations per turn). Built-in tools cover KB search, file management, workflows, automations, ontology queries, map/geo layers, integration tools, code execution, and web search.
@mentions	Users can mention workflows, knowledge bases, data sources, or chat tables in their message. The mention resolver injects the resource as structured context before the LLM sees the prompt.
Sub-agents	The `delegate_to_agent` tool routes a sub-task to a named specialist agent and splices its response back into the parent turn as a `subagent_block` content block.
Plan/Todo	The LLM can emit structured `plan_create` / `plan_update_item` / `plan_complete` tool calls that render a live progress indicator in the UI without an extra round-trip.
Content blocks	Responses carry typed blocks (`credential`, `map`, `subagent`, `plan_todo`, `workflow_suggestion`, …) that the UI renders as rich components beyond plain markdown.
Admin oversight	An admin panel exposes conversation logs, extracted topics (via a cron), and retention purge controls.
Consent	A consent gate intercepts new conversations to ensure the user has accepted the active data-handling policy before any data is sent to an LLM provider.
Rate limiting	Per-user, per-workspace rate limits are enforced at the `/api/chat` route level before the turn reaches the LLM.

How a chat turn flows

Browser → POST /api/chat (SSE)
  → auth gate (session + rate limit + consent)
  → context enrichment (@mentions, workspace KB, prior conversation)
  → agentic ScrydonClient.chat.stream(...)
        ↕ tool-calling loop (up to 10 iterations)
           ├── KB search, file tools, ontology query, map layers
           ├── Workflow / automation CRUD (via agentic API)
           ├── Integration tools (via agentic governed tool bridge)
           ├── Code execution
           └── Sub-agent delegation (delegate_to_agent → executor → sub-turn)
  → SSE events flushed to browser in real time
  → conversation + message rows persisted to db-cortex
  → chat message embedded for semantic history search

Cortex does not call LLM providers directly. It calls the agentic service via ScrydonClient; agentic resolves the model, fetches credentials from the capability runtime, and dispatches the completion. This means the LLM provider, fallback policy, and DLP guardrails are all governed by the integration registry — Cortex only needs to supply the messages, tools, and model preference.

Private and shared action conversations

The normal Chat surface and floating Cortex launcher create private, user-owned conversations. The right pane of a Process Flow Wizard is different: it is a Shared action conversation bound to the current action. Everyone who can currently read the process action and satisfies its clearance can see the same ordered history and who asked each question.

Agentic authorizes the action before Cortex opens the thread, sends a message, loads history, applies a refinement, or resolves a source. The shared thread is grounded only in action-shared context: the current action and output, the process instance knowledge base, the latest recording draft when applicable, and the action's configured Company Context briefing. Personal memory, private chat files, and private KB grants are not mixed into it.

While answering, Cortex can also use a small set of governed, read-only tools scoped to the bound action: searching the process instance knowledge base, listing the process flow's steps, and reading another step's current output. Every tool call is re-authorized by Agentic under the conversation's classification ceiling — a step classified above the conversation's ceiling is reported as withheld rather than read — and knowledge found this way is cited with the same source tokens as pre-loaded context. Participants are addressed by their display name, and answers follow the language of the question. Tool use requires the organization's default language model to support function calling.

A normal question does not change the action. On eligible AI outputs, a participant can explicitly choose Apply as refinement on an answer; the platform reauthorizes the action and reruns the canonical refinement path. Relevant decisions and accepted refinements are summarized back into the process instance KB. The raw thread remains in Cortex, and nothing from it is promoted into Company Context.

Source links in the conversation are hydrated and authorized when displayed. If a source was removed or the viewer can no longer access it, Cortex shows it as unavailable rather than exposing a stale link.

Tool domains

Cortex's tool registry is partitioned into named domains. The engine uses workspace capabilities to select which domains are active for a given turn, avoiding unnecessary tool descriptions in the context window.

Domain	Example tools
`knowledge`	`search_kb`, `read_document`, `create_document`
`files`	`upload_file`, `attach_to_kb`, `list_files`
`workflows`	`workflow_list`, `workflow_create`, `workflow_run`, `workflow_suggest`
`automations`	`automation_list`, `automation_create`, `automation_enable`
`tables`	`query_table`, `list_tables`
`ontology`	`ontology_list_types`, `ontology_query`, `query_map`
`integrations`	`integration_tool_search`, `integration_tool_run` (via agentic governed bridge)
`code`	`execute_code`
`utility`	`search_online`, `schedule_task`, `request_oauth_access`

Context injection and @mentions

Before the first LLM call in a turn, Cortex enriches the prompt with:

Workspace context — enabled KB IDs, available workflow and tool capabilities for the workspace environment.
Mention context — any @[Title](type:id) references in the user message are resolved to markdown context blocks (workflow definition, KB excerpt, data source schema, table rows).
Semantic history — the last N turns plus a semantic recall pass over embedded conversation history keep the context window relevant without always including the full transcript.

Admin panel

Cortex ships an admin-only panel at /admin:

Conversations — full conversation log with message detail and DLP-justification viewer.
Topics — conversation topics extracted by a background cron, used for analytics and search.

Where you configure this

Which LLM is used — Settings → Platform → Integrations → [vendor] → Capabilities. Cortex respects the org's default model and any per-block model override.
Which tools are available — determined by the workspace's enabled integrations and the org's capability policy. No Cortex-specific setting.
Data-handling consent — Settings → Platform → Consent policy.
Retention — the purge-retention cron is configurable per deployment via environment variables.

Integrations — governs which tools and models are available in chat.
Architecture → Agentic — the service Cortex calls for LLM completions and tool execution.
Architecture → Knowledge bases — private conversation knowledge, workspace KBs, and read-only Company Context.
Integrations → Capabilities — hosts the capability runtime that resolves LLM providers.
Security → DLP — applied at the agentic/capability layer, not in Cortex itself.
Security → Secrets management — where provider credentials live.

Cortex (Chat)

On this page