Skip to main content

AI Assistant

The AI Assistant lets users chat with the organization's Agent workflows from any organization screen. It is available as a docked panel and as a full-screen conversation view.

Availability​

The header button and docked panel appear when both conditions are met:

  • the white label enables features.enableChat;
  • GET /api/organizations/{organizationId}/ai/models returns at least one agent.

The full-screen route is /[lang]/org/[orgId]/assistant[/sessionId]. It remains reachable without configured agents and displays an empty state in that case.

On wide screens (at least 1100px), the 420px panel docks beside the page content. On narrower screens it overlays the page. Both horizontal and vertical application layouts support it.

Conversations​

The client sends turns to POST /api/organizations/{organizationId}/ai/responses and renders the streamed response. Users can:

  • select among the organization's Agent workflows;
  • start a new conversation or resume a recent session;
  • choose Ask or Auto approval mode per conversation;
  • approve or decline tool calls that require confirmation;
  • open the current conversation in the full-screen view.

The current application URL is sent as conversation context only for recognized organization routes. Conversation state is isolated by agent and is cleared when the user logs out or changes organization.

Files in chat​

Users attach files with the paperclip in the composer, or by dropping them onto the panel or the full view — up to 5 per message, 25 MB each: PDF, PNG, JPG, TXT, CSV, JSON and MD. Each file uploads as soon as it is picked and shows as a chip with its progress. A chip shows why a file can't be sent: an unsupported type, over 25 MB, over 5 files, or a PDF or image for an agent whose model can't read them (supports_files from GET .../ai/models). Send is disabled while an upload runs or a chip shows an error. A message may be files only; it is then sent as "See the attached file(s)."

The client uploads through the presigned uploadUrl flow and sends the files as input_file / input_image parts; the backend turns them into session attachments — the client never calls createAttachment. Sent messages show their files as image thumbnails or document cards (type, size, download); a reopened chat rebuilds them from the transcript's attachment blocks. Download becomes available once the chat is reopened.

Library​

The books button in the chat header opens the Library, with a badge counting the current conversation's files. It lists This Thread and All Threads (every conversation the user may see), filtered by All, Images or Documents. Images show as a thumbnail grid and documents as a list with type, size, agent and time. Every file links back to its conversation ("Uploaded to …"), opens a preview (the image, or a PDF's first page) and can be downloaded. In the panel, the Library replaces the chat area with a back button; in the full view it opens as a 360px column. It refreshes after every turn.

Data comes from the agentSessionAttachments query; previews and downloads use presigned URLs from the attachment query.

Agent display metadata​

Configure an Agent workflow's agent.ui object to control its presentation:

FieldPurpose
nameDisplay name in the agent menu and chat header.
shortDescriptionSupporting text in the selector and empty state.
iconTabler icon name without the prefix; defaults to robot.
colorTheme color; defaults to primary.
promptsUp to five suggested opening prompts.

For the workflow contract, see Agent workflows. For session loading and transcripts, see Agent Sessions GraphQL API.