AI Assistant - Chat & Streaming

The AI Assistant is the in-app conversational interface. Open it with Cmd+K (or Ctrl+K) and switch to the AI tab, or use the dedicated chat panel. It streams responses token by token, calls tools to fetch and modify Opbox data, and refreshes the host page's UI live when it makes a write.

What It Can Do

• Real-time streaming - responses render token by token via SSE.
• ~427 tools - search, knowledge retrieval, matter / table / form operations, dashboards, files, integrations.
• Multiple providers - Anthropic Claude or OpenAI GPT, resolved via BYOK Credentials.
• Page context - the AI knows which page you're viewing and can preload relevant data automatically.
• @-mention references - type @ to attach matters, forms, tables, documents, workflows, or submissions as explicit context (max 10 references).
• Plan Mode - read-only mode for "explore before changing." See Security & Limits.
• Saved Prompts (Skills) - reusable per-user prompt library. See Saved Prompts.
• Live UI refresh - when the AI completes a write, the host page reloads its data automatically.
• Chat history - threads persist server-side per user.

Endpoint

POST /api/ai/chat
Content-Type: application/json

{
  "messages": [
    { "role": "user", "content": "Summarise this matter and suggest next steps" }
  ],
  "provider": "anthropic",
  "pageContext": "/matters/cm1abc...",
  "planMode": false,
  "scopeToPage": true,
  "references": [
    { "id": "cm1abc...", "type": "matters", "title": "ACME Ltd Incorporation" }
  ]
}

Response is text/event-stream.

SSE Event Types

Example Stream

data: {"type":"text_delta","content":"Here"}
data: {"type":"text_delta","content":" are"}
data: {"type":"tool_start","toolName":"list_matters","toolId":"toolu_01...","input":{"status":"OPEN"}}
data: {"type":"tool_result","toolName":"list_matters","toolId":"toolu_01...","result":{...},"isError":false}
data: {"type":"text_delta","content":"You have 5 open matters..."}
data: {"type":"done"}

Page Context Preloading

When you send your first message from a matter or document page, the resource is preloaded into context - no need for the AI to call get_matter or get_document first.

Matter pages preload:

• Title, status, priority, assignee, due date, labels.
• Board name + board properties (with current values).
• Step pipeline with stepId for each step (so subsequent tools can use the IDs directly).
• FORM step titles (e.g. "KYC Questionnaire") for both pending and completed steps.
• APPROVAL step -> reviewed FORM linkage (e.g. "reviews: Collect KYC - form: KYC Questionnaire").

Document pages preload:

• Title, content (first 3000 chars), and custom metadata properties.

The result: from a matter page, the AI can call add_subtask, complete_step, assign_step directly on the right stepId without first calling get_matter. Saves a round-trip per request.

@-Mention References

Type @ in the chat input to open the entity picker. Filter by name, pick the entity, repeat. Up to 10 references can be attached to a single message.

When the request fires:

1. The server fetches each referenced entity's content (matter steps, form fields, document content, workflow definition, etc.).
2. The content is added to the system prompt as explicit context, separately from pageContext.
3. The AI sees the references and treats them as direct user-attached attachments.

References are useful when the AI needs to reason across multiple resources without you having to paste them or navigate.

Tool Result Entity Cards

When the AI calls read-only tools that return structured entity data, the chat UI renders the results as clickable inline cards below the tool indicator. Each card shows the entity icon, title, and metadata chips.

Cards are clickable - clicking navigates to the entity detail page and closes the Spotlight dialog. List results show a maximum of 5 cards with a "Show N more" toggle.

Write/action tools display only the tool badge - cards are read-only by design.

Chat Thread Management

Conversations persist server-side per user.

Threads are auto-created on first message. Compaction sends only the last 25 messages per request - the full thread is preserved on disk.

Custom System Prompt

Admins can configure a custom system prompt at Settings > AI (the Workspace or Organisation tier). The prompt is prepended to the assistant's built-in instructions. Maximum 8000 characters server-side, 2000 in the UI.

Useful for: domain priming ("you are a corporate-services AI for ADGM company formation..."), tone enforcement ("always respond in formal English"), or rules of engagement ("never modify a matter without explicit confirmation").

The custom prompt applies to the Spotlight AI chat. Automation AI steps use their own per-step prompt configured in the workflow builder.

Live UI Refresh

When the AI performs writes via the sidebar chat, the host page automatically refreshes without a manual reload. Examples:

• Adding a subtask -> the matter pipeline rerenders with the new subtask.
• Completing a step -> the step transitions, the next step activates.
• Updating board properties -> the property panel reflects the new values immediately.

Implementation: tool results carry an affects hint; the chat UI dispatches a custom DOM event the host page listens for.

Parallel Tool Execution

The AI can call multiple tools per turn. Independent calls execute concurrently. The chat UI groups them visually:

• Single tool call - shown inline with status indicator and label (expand for input/result).
• Multiple tool calls - collapsed into "N tool calls"; click to expand.
• During streaming - auto-expanded to show progress; auto-collapses when all complete successfully.
• On error - failed count shown in the collapsed summary; group stays expanded if anything errored.

See Also

• Tools & Actions - the full tool surface, confirm-then-act, page-context.
• Saved Prompts - reusable per-user prompt library.
• Voice Transcripts - upload audio, transcribe to KB.
• Security & Limits - rate limits, plan mode, injection scanning.