Account – Agents (`/account/agents`)

Last updated: 2026-03-23

Route

Path: /account/agents
Parent: README.md
Status: Implemented (v1): global agents table with search, filters, sorting, pagination, inline management actions, and workspace context.

Purpose

Global hub for listing, searching, and managing Live Agents across all workspaces the authenticated user can access.

User roles & permissions

Role	Access
Org Admin	Full view and management across all workspaces
Workspace Admin	View and manage agents for their workspaces
Member	View agents for workspaces they belong to (read-only)

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

Reference: Roles & Permissions Model

Information architecture

/account/agents
├── Merged top section
│   ├── Page header: "Agents"
│   └── Toolbar
├── Agents table
│   ├── Name (+ icon)
│   ├── Workspace
│   ├── Knowledge Base
│   ├── Active
│   ├── Channels (count with hover details)
│   └── Actions: row menu

Layout structure

Merged top section

Title: “Agents”
Count badge is shown beside the title and reflects the total number of agents across all workspaces.
Right side of the toolbar includes the standard primary Add agent CTA, visually matching the workspace Agents tab button.
Toolbar lives directly below the title in the same bordered top section with no internal divider.
Workspace filter: use the shared account workspace-filter combobox with leading workspace icon. Default: “All workspaces”. On Agents this control runs in the same checkbox-based multi-select mode used on the Workspaces page. Empty selection means “All workspaces”; selecting one or more workspaces scopes the table to that subset.
When the workspace filter is active, show a Clear filters action in the toolbar.
Add agent opens the shared agent modal. On this global page, the create form must include an explicit Workspace select above the Knowledge base field. The selected workspace scopes the Knowledge base dropdown. The workspace field is preselected from the current page filter when exactly one workspace is selected; otherwise it falls back to the default workspace.

Agents table

Above the table grid, show a local section header titled “Agents” plus a live count with robot_2 icon and a view_column control button.
The view_column button opens a popover with per-column pill toggles (Switch size="sm"), matching the Workspaces and Knowledge Bases pages. The first column (Name) is always visible and its toggle is disabled.

Columns (in order):

Column	Content	Sortable
Name	Agent name + avatar/icon (fallback: robot icon). The current workspace default agent also shows a dark marker on the icon.	Yes
Workspace	Workspace name	Yes
Knowledge Base	KB name with inline editable selector scoped to the agent workspace	Yes
Active	Switch bound to the agent lifecycle (`active` vs non-active)	No
Channels	Badge showing linked channel count; hover reveals the linked channel-family labels	No
Actions	Row menu with Edit, Set as default (disabled for current default), and Delete (blocked for current default or active agents)	No

Default sort: updatedAt desc.

Notes:

updatedAt desc remains the query-param default, but the Updated column is not currently rendered in the visible table.
The shipped UI supports sorting by Name, Workspace, and Knowledge base.
Status still exists in the underlying agent model, but the current table exposes lifecycle changes through the Active switch instead of a dedicated status column.

Pagination: 20 per page, standard pagination controls.

Row actions

Edit opens the shared agent modal.
Set as default updates workspace.defaultAgentId for that agent’s workspace only. It affects future channel assignments only; existing channels are unchanged.
Delete is disabled for the current default agent (Delete (set another default first)) and for active agents (Delete (deactivate first)).
The row no longer shows a separate “Open workspace” action in the shipped menu.

States

Empty state

No agents exist (new user with default agent in draft):

Icon: robot (outlined)
Heading: “No agents configured yet”
Body: “Add an agent to start handling conversations on Messenger, WhatsApp, Web Chat, or SMS.”
CTA: Add agent

No agents match current filters:

Icon: search_off
Heading: “No agents found”
Body: “Try adjusting your search or filters.”
CTA: “Clear filters”

Loading state

If no local agent data is available yet, show skeleton rows (3–5) while GET /live-agents is in flight.
If local/context agent data is already available, render the table immediately from that data and let the remote list refresh in the background without replacing the table with skeleton rows.
Toolbar is rendered but disabled only during the true empty initial load.

Error state

Icon: error_outline
Heading: “Failed to load agents”
Body: “There was a problem fetching your agents. Please try again.”
CTA: “Retry” (re-triggers the API call)

Data model

Primary source: liveAgent.index (GET /live-agents)

Fields used on this page:

interface AgentListItem {
  id: string;
  name: string;
  status: "draft" | "inactive" | "active";
  workspaceId: string;
  workspaceName: string;       // joined/included by API
  knowledgeBaseId: string;
  knowledgeBaseName: string;   // joined/included by API
  channelIds: string[];
  channelTypes: AgentChannelType[];  // derived from channelIds
  icon: string | null;
  updatedAt: string;
}

Behavior & interactions

On mount, fetch GET /live-agents (no workspace filter — returns all accessible agents).
Apply workspace and status filters client-side if the total result set is ≤ 200 agents; otherwise pass filters as query params.
Search is debounced (300 ms) and applied client-side or via ?search= query param.
Clicking “Open” on a row navigates to /account/workspaces/{workspaceId}?tab=agents.
Clicking a workspace name chip navigates to /account/workspaces/{workspaceId}.
URL state: persist active filters in query params (?status=active&workspaceId=ws-1,ws-2) for shareability and back-navigation.

API dependencies

GET /live-agents — primary list
GET /live-agents?workspaceId={id} — workspace-filtered list (used when workspace filter is applied)

Enterprise constraints

Agents from workspaces the user cannot access must never appear in the list.
The global hub never exposes agent configuration details — it is a navigation surface only.
No cross-workspace mutations are permitted from this page.

Edge cases

Scenario	Behavior
Agent’s KB is deleted	Agent shows status `draft`; KB name shows “Deleted KB” (muted); row action still navigates to workspace
Agent’s workspace is deleted	Agent is excluded from the list (orphaned agents are not surfaced)
User loses access to a workspace mid-session	On next fetch, agents from that workspace disappear; no error shown
All workspaces filtered out	Empty state: “No agents found” with “Clear filters” CTA

Domain refs

Workspace – Agents Tab — Workspace-scoped agent management
Account – Workspaces