Actana Assistant

Actana Assistant is the conversational surface in your workspace. You type, the assistant runs against your real workspace — workflows, tables, files, knowledge — and streams the result back. Each turn provisions a fresh Sandbox and disposes of it when the turn ends.

The Assistant is not a chatbot wrapper around an LLM. It runs an agent loop with skills attached: by default actana_workflow_editor, actana_tables, and actana_files. The agent loop can call back into the workspace API as the current user — creating workflows, querying tables, reading and writing files.

When to use the Assistant

The Assistant is the right surface when:

• You're describing what you want in natural language and don't know which blocks to drag.
• You're operating on the workspace itself — "add an Inference node here", "show me rows where X", "summarize this PDF I just uploaded".
• You want to iterate on a workflow conversationally before committing to a structure.

For deterministic, scheduled, or production-shape work, build a Workflow instead. For reusable agent definitions that can run from a workflow or be called from outside, define a Crew Agent and run it via the Agents block.

How a turn flows

user types
  │
  ▼
POST /api/assistant/chat/stream
  │  ├─ persists user message to copilotChats (type: 'assistant_sandbox')
  │  ├─ mints OTPs (setup, run, optional upload)
  │  ├─ resolves any attached chat-bag files
  │  └─ provisions a sandbox via lib/assistant-sandbox/sandbox-client
  │
  │  NDJSON stream (log | step | result | error)
  ▼
stream-processor → SSE → browser
  │
  ▼
final assistant message persisted onto the conversation

A few facts pulled straight from the route handler:

• The Next.js route timeout is 8 hours (maxDuration = 28860s) plus a 60s grace, matching the sandbox runtime cap.
• Each turn replays the most recent 20 turns to the sandbox (REPLAY_TURN_LIMIT).
• The first message creates a copilotChats row with type: 'assistant_sandbox' and locks the conversationId to the user message id (appendUserMessage).
• File attachments on the request are resolved against assistantChatBagFiles and persisted onto the user message so a history reload renders the chip rail without an extra round-trip.

See assistant/conversations for persistence + replay details.

What the agent can do per turn

Inside the sandbox, the assistant runs with three skills mounted unconditionally:

• actana_workflow_editor — owns the cold-start recipe (new-workflow.sh) plus node-edit recipes. Without this skill mounted on cold prompts, the agent has no way to drive workflow construction.
• actana_tables — read + write the workspace's Tables.
• actana_files — read + write the workspace's Files.

Tool calls land in the stream as step lines so users see what the agent is doing in real time.

File attachments

Drag a file into the composer, or paste one. The upload service stores it in the chat file bag (assistantChatBagFiles) scoped to the current conversation. The next turn dispatches with attachmentIds, and the sandbox config endpoint projects the bag into the run as a signed zip — see Sandbox › Assets.

Why the table is named copilotChats

Historical naming. The conversational surface was originally branded "Copilot"; the table name predates the rename. The schema still uses copilotChats but the rows for the Assistant carry type: 'assistant_sandbox', distinguishing them from any legacy data. Old /copilot URLs 301-redirect to /assistant.

Source

• apps/actana/app/workspace/[workspaceId]/assistant/ — UI
• apps/actana/app/workspace/[workspaceId]/home/hooks/use-assistant-chat-stream.ts — client streaming hook
• apps/actana/app/api/assistant/chat/stream/route.ts — server entrypoint
• apps/actana/lib/assistant-sandbox/ — runtime + persistence