Workspace – Agents Tab

Last updated: 2026-03-19

---

Route

• Path: /account/workspaces/[workspaceId] → Agents tab
• Parent: workspace.md
• Tab ID: agents
• Implementation file: src/app/account/workspaces/[workspaceId]/_components/workspace-agents-tab.tsx

---

Purpose

Workspace-scoped surface for full agent lifecycle management: list, create, edit, activate/deactivate, and delete agents within a single workspace.

---

User roles & permissions

Role	Access
Workspace Admin	Full CRUD + activate/deactivate
Member (with agents.manage)	Create, edit, activate/deactivate
Member (read-only)	View only

Permission gate: agents.view (read), agents.manage (write).

Reference: Roles & Permissions Model

---

Information architecture

Workspace detail page → Agents tab
├── Toolbar
│   ├── Status filter (All / Active / Inactive)
│   └── "Add agent" button
└── Content area
    ├── Summary badges (Total agents, Active agents)
    └── Agents table
        ├── Name
        ├── Knowledge base (inline editable select)
        ├── Active (toggle switch)
        ├── Channels (count badge with hover list)
        └── Actions: Edit (opens modal), Delete (with confirmation)

---

Layout structure

Toolbar

• Status filter: custom Popover-based select (not a native <select>). Options: “All statuses”, “Active”, “Inactive”. Default: “All statuses”. The filter is a button trigger (filter_list icon + label + keyboard_arrow_down icon) that opens a Popover with a listbox. The selected option shows a check icon.
• “Add agent” button (primary CTA, right-aligned): opens the Create Agent modal.

Summary badges (above table)

Two compact Badge (secondary variant, rounded-full) components shown above the agents table:

Stat	Value
Total agents	Count of all agents in this workspace
Active agents	Count of agents with status = "active"

Agents table

Above the table grid, show the summary badges first, then a local section header titled Agents plus a live table-item count and a view_column control button aligned to the right.

• The view_column button opens a popover with per-column toggles, matching the account/workspace table column-visibility pattern.
• The first column (Name) is always visible and its toggle is disabled.

Columns (in order):

Column	Content
Name	Agent name with robot_2 icon. The current default agent also shows the same visual treatment as default KBs: a small dark marker on the icon.
Knowledge base	Inline editable Select dropdown. Changing the KB triggers a Sonner confirm/cancel toast before persisting. Shows a warning icon next to incomplete KBs in the dropdown. If the agent’s KB is not found, shows “KB not found” in destructive color.
Active	Switch toggle. Checked = active, unchecked = inactive. Disabled while a status update is in flight.
Channels	Count badge (HoverCard trigger). Hovering opens a HoverCard listing the channel type names (e.g. “FB Messenger”, “WhatsApp”) for all linked connections. Shows ”—” when no channels are linked.
Actions	Three-dots DropdownMenu (on row hover). Items: Edit (opens edit modal), Set as default (disabled for the current default), Delete (opens delete confirmation; blocked for the current default agent).

Pagination:

• Uses TablePagination below the table.
• Default page size: 25 rows.

Status model: The workspace agents tab uses a two-state model: active / inactive. The draft status exists in the data model but is not surfaced as a distinct badge state in this tab — draft agents are shown as inactive visually. The global /account/agents hub does surface draft as a distinct badge.

Inline KB change flow:

1. User selects a different KB from the inline dropdown.
2. A Sonner toast appears: Assign "{KB name}" to this agent? with Confirm and Cancel actions. The toast persists until the user acts (duration: Infinity).
3. On Confirm: updateAgent is called; on success a “Knowledge base updated.” toast appears; on failure the selection reverts and an error toast appears.
4. On Cancel: the selection reverts immediately.
5. The KB selector is disabled while an update is in flight for that agent.

Activate / Deactivate flow (via toggle switch):

• Activate (inactive → active): calls setAgentStatus(id, "active", kb.status, hasConnected). The context validates prerequisites:
  • KB is incomplete → returns { valid: false, message: "..." } and shows an error toast. Agent stays inactive.
  • No channels linked → returns { valid: false, message: "..." } and shows an error toast. Agent stays inactive.
  • Prerequisites met → agent becomes active; success toast: “Agent activated.”
• Deactivate (active → inactive): calls setAgentStatus(id, "inactive"). No prerequisites check. Success toast: “Agent deactivated.”
• The toggle is disabled while the status update is in flight.

Note: The prerequisite blocking is enforced in the agents context (setAgentStatus), not via a blocking dialog in the UI. The error is surfaced as a Sonner error toast.

Default agent behavior:

1. Every workspace has exactly one defaultAgentId.
2. The auto-provisioned "My Agent" starts as the default.
3. Clicking Set as default updates workspace.defaultAgentId only. It does not reassign any existing channels.
4. New agent-managed channel assignments use the workspace default agent as the preselected choice in the Add Channel wizard when that agent is eligible for the selected channel family.

---

Agent edit modal

The agent edit modal (AgentModal) uses a single General section. It is used for both creating and editing agents.

• Title: “Add agent” (create) or “Edit agent” (edit).
• Footer: “Cancel” (outline) and “Create agent” / “Save changes” (primary). Save is disabled while name is empty or kbId is unset.
• Width: shared dialog scale md (max-w-[480px]).

The modal does not expose per-channel configuration tabs. Channel-specific settings stay on the connection itself and are managed in the Add Channel wizard or the relevant connection settings dialog.

The Queries tab (described in an earlier spec version) is not implemented in v1.

General section

Field	Type	Validation
Name	Text input	Required; 1–80 chars. Inline error shown after first character if over limit.
Workspace	Not shown in this route	The workspace is implicit from the current page context, so the create/edit modal does not expose a workspace selector in the workspace-scoped Agents tab.
Knowledge base	Select dropdown (KBs in this workspace)	Required. Disabled + inline note “Deactivate the agent before changing its knowledge base.” when agent is active. Shows inline amber warning “This knowledge base is incomplete. Complete it before activating this agent.” when selected KB is incomplete and agent is not active.
Channels	Multi-select via HoverCard + checkbox list	Optional at creation. Lists only Chatti Live connections (facebook-messenger, whatsapp, web-chat, sms) in this workspace. One connection per channel type.
Active	Full-width row at the bottom of the form section. Label left, Switch right. Shown only when editing an existing agent.

Agent icon upload (described in earlier spec) is not implemented in v1.

All form controls and card-like rows inside this modal use the shared dialog control radius rounded-md.

Removed: Channel-specific sections are no longer shown in the agent modal. Web Chat widget settings, Messenger greetings, WhatsApp settings, SMS settings, and widget visibility belong to the connection surface, not the agent. See Account – Channels.

---

Delete agent flow

1. User clicks Delete from the row’s three-dots dropdown menu.
2. If the agent is the workspace default agent, delete is disabled with helper text Delete (set another default first).
3. Otherwise, a Dialog confirmation opens: title “Delete agent”, body “Delete {name}? This cannot be undone.”, footer “Cancel” + “Delete” (destructive).
4. On Delete: deleteAgent(id) is called. On success: “Agent deleted.” toast. On failure: error toast.

Note: Delete is also blocked for active agents. The row dropdown shows a disabled “Delete (deactivate first)” menu item when the agent is active. The agents context also enforces this via AGENT_ACTIVE_DELETE_BLOCKED. To delete an active agent, the user must first deactivate it via the Active toggle. If the agent is both active and default, the user must first choose another default agent, then deactivate, then delete.

---

States

State	Behavior
Loading	Skeleton rows (3) while isLoading is true
Empty (no agents in workspace)	Icon robot_2, heading “No agents yet”, body copy, “Add agent” CTA button
Empty (filters active, no match)	Icon robot_2, heading “No agents found”, body “Try adjusting your filters.”, “Clear filters” button
Normal	Table with summary badges above

---

Data model

The workspace agents tab reads from the useAgents() context via getAgentsForWorkspace(workspaceId). It does not fetch directly from an API — data is managed by the agents context.

AgentsContext — source field

The context exposes a source: AgentsDataSource field that indicates where the current agent data originates:

export type AgentsDataSource = "remote" | "local-fallback" | "local-only";

Value	Meaning
"remote"	Data was successfully fetched from the remote API
"local-fallback"	Remote fetch failed; data is served from local/seed fallback
"local-only"	No remote fetch attempted; data is local/seed only (current MVP state)

This field is available to any consumer of useAgents() and can be used to show data-freshness indicators or debug data origin issues.

interface Agent {
  id: string;
  name: string;
  status: "draft" | "inactive" | "active";
  workspaceId: string;
  knowledgeBaseId: string;
  channelIds: string[];
  integrationConfig: AgentIntegrationConfig;
  updatedAt: string;
}

interface AgentIntegrationConfig {
  webChat?: {
    welcomeMessage?: string;
    primaryColor?: string;
    // autoVisibility and visibilityDelay moved to ChannelConnection
  };
  whatsapp?: {
    welcomeMessage?: string;
  };
  sms?: {
    welcomeMessage?: string;
  };
  // messenger is not yet in v1 — see Tab visibility rules note above
}

interface Workspace {
  id: string;
  defaultKbId?: string;
  defaultAgentId?: string;
}

---

API dependencies (future)

Action	Endpoint
List agents for workspace	GET /live-agents?workspaceId={id}
Create agent	POST /live-agents
Update agent	PUT /live-agents/{liveAgent}
Activate/deactivate	PATCH /live-agents/{liveAgent}/status
Update integration config	PUT /live-agents/{liveAgent}/integration-config
Delete agent	DELETE /live-agents/{liveAgent}

---

Enterprise constraints

• Only channel connections belonging to this workspace may be linked to agents in this workspace.
• Only KBs belonging to this workspace may be assigned to agents in this workspace.
• Agent mutations are audit-logged (actor, action, before/after state, timestamp).

---

Edge cases

Scenario	Behavior
Agent’s KB is deleted externally	KB column shows “KB not found” in destructive color; inline KB select is still available to reassign
Activate with incomplete KB	Error toast from context; agent stays inactive
Activate with no channels linked	Error toast from context; agent stays inactive
KB reassignment blocked (active agent)	KB select is disabled; inline note shown below the field
Concurrent edit (two admins)	Last write wins; no optimistic locking in v1

---

Domain refs

• Agents (Domain)
• Domain: Workspaces
• Domain: Knowledge Bases
• Domain: Channels

Related routes

• Account – Agents (/account/agents) — Global agents hub (/account/agents)
• Account – Open workspace (workspace detail)