Agents (Domain)

Last updated: 2026-03-15

Definition

A Live Agent (referred to as “Agent” in the UI) is a workspace-scoped, AI-powered runtime entity that handles inbound conversations on Chatti Live channels (Facebook Messenger, WhatsApp, Web Chat, SMS). Each agent is bound to exactly one Knowledge Base and can be linked to up to four channel connections simultaneously.

Agents are not Comment Responder entities. Comment Responder (social-comments, review-platforms) operates independently and does not use the Live Agent system.

Scope model: workspace-first with global hub

Agents are workspace-scoped objects. Every agent belongs to exactly one workspace (via its KB → workspace chain). The global /account/agents page is an aggregated read-only hub that lists agents across all workspaces the authenticated user can access. All create/edit/delete actions are performed within workspace context.

Surface	Purpose	Scope
`/account/agents`	Global hub: list, search, filter, navigate to agent	Cross-workspace (read + navigate)
`/account/workspaces/[id]` → Agents tab	Workspace-scoped list + full CRUD	Single workspace
Agent edit modal/drawer	Full agent configuration	Single agent within workspace

Rationale: Enterprise operators need a cross-workspace view to audit agent status at a glance. But all mutations are workspace-scoped to preserve isolation invariants. The global hub never exposes agents from workspaces the user cannot access.

Agent lifecycle states

draft → inactive → active
                ↓
           deprecated (soft-delete; v2)

State	API value	Meaning
`draft`	`"draft"`	Agent created but KB is incomplete (KB status = `incomplete`). Cannot be activated.
`inactive`	`"inactive"`	Agent is configured and KB is complete, but not currently listening on any channel.
`active`	`"active"`	Agent is listening on ≥ 1 channel connection. Conversations are routed to this agent.

Activation prerequisites (hard rules)

An agent cannot transition to active unless ALL of the following are true:

knowledgeBaseId is set and the referenced KB has status = "complete".
At least one channel connection is linked (channelIds.length >= 1).
All linked channel connections have status = "connected" (healthy).
Agent name is non-empty.

If any prerequisite is unmet, the API must reject the status update with 422 Unprocessable Entity and a structured error body (see Error Contract).

State transitions

From	To	Trigger	Allowed
`draft`	`inactive`	KB becomes complete	Automatic (system)
`inactive`	`active`	User activates	Manual (user)
`active`	`inactive`	User deactivates	Manual (user)
`active`	`draft`	KB reverts to incomplete	Automatic (system)
any	deleted	User destroys	Manual (user); requires `inactive` or `draft` state

Deleting an active agent is blocked. The user must deactivate first.

Semantic definitions

Capability enabled

The agent entity exists and its KB is complete. The agent is capable of handling conversations but may not yet be listening. Maps to state inactive or active.

Channel connected

A channel connection (ChannelConnection) with status = "connected" exists and is linked to this agent via channelIds. The connection credential is valid and the platform integration is healthy.

Channel active/listening

The agent is in active state AND the specific channel connection is in channelIds AND that connection has status = "connected". Only in this state does the agent actually receive and respond to inbound messages on that channel.

Per-agent channel limits

Constraint	Rule
Total channel links per agent	Maximum 4 (`channelIds.length <= 4`)
Per channel type	No per-type cap in v1
Minimum to activate	1

Rationale: The total cap of 4 ensures reasonable scope per agent. No per-type uniqueness is enforced in v1; an operator may link multiple connections of the same channel type if needed.

KB assignment rules

Rule	Detail
Cardinality	Each agent is assigned to exactly one KB (`knowledgeBaseId` is required and non-nullable).
KB must be workspace-scoped	The assigned KB must belong to the same workspace as the agent. Cross-workspace KB assignment is forbidden.
Reassignment	Allowed at any time when agent is `inactive` or `draft`. Reassigning an `active` agent is blocked — deactivate first.
KB deletion	Cannot delete a KB that has ≥ 1 agent assigned (any state). The user must reassign or delete all agents first.
Multi-KB per agent	Not supported in v1. One agent = one KB.
Multiple agents per KB	Allowed. Multiple agents can reference the same KB (e.g., one agent per channel type, all sharing one KB).

Auto-created on new user registration

Entity	ID convention	Name	Status
Workspace	`ws-1` (or server-generated)	“My Workspace”	active
Knowledge Base	`kb-default-1` (or server-generated)	“My Knowledge Base”	`incomplete`
Agent	`agent-default-1` (or server-generated)	“My Agent”	`draft`

The default agent is linked to the default KB. No channels are linked at creation. The agent remains in draft state until the KB is completed and at least one channel is connected.

Workspace: active, no channels connected
KB: incomplete (no brand personality fields filled)
Agent: draft (KB incomplete, no channels)

Idempotent backfill rule for existing users

On backfill for existing users:

Ensure each workspace knowledge base has at least one agent.
For each KB, assign existing Agent-managed channels (facebook-messenger, web-chat, whatsapp, sms) linked to that KB into KB-scoped agents.
Respect max 4 channel links per agent by creating additional KB-scoped agents as needed.
Keep the process idempotent: reruns do not duplicate already-covered assignments.

Data contract

Canonical Agent entity

Field	Type	Required	Notes
`id`	`string`	Yes	Server-generated UUID
`name`	`string`	Yes	Display name; 1–80 chars
`workspaceId`	`string`	Yes	Parent workspace; immutable after creation
`knowledgeBaseId`	`string`	Yes	Must belong to same workspace
`status`	`"draft" \| "inactive" \| "active"`	Yes	Lifecycle state
`channelIds`	`string[]`	Yes	Array of ChannelConnection IDs; max 4 total; no per-type cap in v1
`icon`	`string \| null`	No	URL to uploaded agent icon image
`integrationConfig`	`AgentIntegrationConfig \| null`	No	Per-channel integration settings (see below)
`createdAt`	`string` (ISO 8601)	Yes	Server-set
`updatedAt`	`string` (ISO 8601)	Yes	Server-set

AgentIntegrationConfig (per-channel settings)

interface AgentIntegrationConfig {
  webChat?: {
    primaryColor?: string;       // hex color
    welcomeMessage?: string;     // max 500 chars
    autoVisibility?: boolean;    // show widget automatically
    visibilityDelay?: number;    // seconds before auto-show
  };
  messenger?: {
    welcomeMessage?: string;
    iceBreakers?: string[];      // max 5 items
  };
  whatsapp?: {
    welcomeMessage?: string;
  };
  sms?: {
    welcomeMessage?: string;
  };
}

Relationship constraints

Relationship	Constraint
Agent → Workspace	N:1; workspace is immutable after creation
Agent → KB	N:1; KB must be in same workspace; one KB per agent
Agent → ChannelConnection	1:N (max 4 total); each connection must be in same workspace and can belong to only one agent
KB → Agent	1:N; KB can have multiple agents
Workspace → Agent	1:N; no hard cap per workspace in v1

Validation rules

Field	Rule	Error code
`name`	Required, 1–80 chars, non-empty after trim	`AGENT_NAME_REQUIRED`, `AGENT_NAME_TOO_LONG`
`knowledgeBaseId`	Must reference existing KB in same workspace	`KB_NOT_FOUND`, `KB_WORKSPACE_MISMATCH`
`channelIds`	Max 4 items total; each must be valid ChannelConnection ID in same workspace; no per-type cap in v1; a connection ID cannot be assigned to multiple agents	`CHANNEL_LIMIT_EXCEEDED`, `CHANNEL_NOT_FOUND`, `CHANNEL_WORKSPACE_MISMATCH`, `CHANNEL_ALREADY_ASSIGNED`
Status → `active`	KB must be complete; ≥ 1 channel connected	`KB_INCOMPLETE`, `NO_CHANNELS_CONNECTED`
Delete	Agent must be `inactive` or `draft`	`AGENT_ACTIVE_DELETE_BLOCKED`
KB delete	No agents assigned	`KB_HAS_AGENTS`

Error contract

All validation errors return 422 Unprocessable Entity:

{
  "error": {
    "code": "AGENT_NAME_REQUIRED",
    "message": "Agent name is required.",
    "field": "name"
  }
}

For activation failures:

{
  "error": {
    "code": "KB_INCOMPLETE",
    "message": "The assigned knowledge base must be complete before activating this agent.",
    "field": "knowledgeBaseId"
  }
}

API integration contract

Base URL

https://api-dev.conversioniq.ai/v1

Workspace scoping transport

All agent API calls must include the workspace context header:

X-Workspace-ID: {workspaceId}

The backend uses this header to scope queries and enforce isolation. Requests without a valid X-Workspace-ID that match the authenticated user’s accessible workspaces must return 403 Forbidden.

Endpoint mapping

UI Action	Method	Endpoint	Notes
List agents (global hub)	`GET`	`/live-agents`	No `X-Workspace-ID`; returns all accessible agents
List agents (workspace-scoped)	`GET`	`/live-agents?workspaceId={id}`	Filter by workspace
Create agent	`POST`	`/live-agents`	Requires `X-Workspace-ID`
Get agent detail	`GET`	`/live-agents/{liveAgent}`
Update agent (general/config)	`PUT`	`/live-agents/{liveAgent}`	Full update
Activate / deactivate	`PATCH`	`/live-agents/{liveAgent}/status`	Body: `{ "status": "active" \| "inactive" }`
Update integration config	`PUT`	`/live-agents/{liveAgent}/integration-config`	Web/Messenger/WhatsApp/SMS settings
Upload agent icon	`POST`	`/live-agents/{liveAgent}/integration-icon`	Multipart form; returns `{ iconUrl }`
Delete agent	`DELETE`	`/live-agents/{liveAgent}`	Agent must be inactive/draft
Create session (Chatti Live)	`POST`	`/agents/{agentId}/sessions`	Used by Chatti Live runtime; not from /account/agents UI

Pagination / filter / search contract (list endpoint)

Query parameters for GET /live-agents:

Parameter	Type	Description
`workspaceId`	`string`	Filter to single workspace
`status`	`"draft" \| "inactive" \| "active"`	Filter by lifecycle state
`search`	`string`	Full-text search on agent name
`page`	`number`	1-indexed page number (default: 1)
`perPage`	`number`	Items per page (default: 20, max: 100)
`sortBy`	`"name" \| "status" \| "createdAt" \| "updatedAt"`	Sort field (default: `updatedAt`)
`sortDir`	`"asc" \| "desc"`	Sort direction (default: `desc`)

Response envelope:

{
  "data": [ /* Agent[] */ ],
  "meta": {
    "total": 42,
    "page": 1,
    "perPage": 20,
    "totalPages": 3
  }
}

Account – Agents (/account/agents) — Global hub page spec
Workspace – Agents Tab — Workspace Agents tab spec

Deprecated concepts

Chatti Live – Agents — The /chatti-live/agents route concept is deprecated. Agent management is now exclusively at /account/agents and the workspace Agents tab. The Chatti Live section handles conversation routing only, not agent configuration.

References

API spec: https://api-dev.conversioniq.ai/docs/api/
Workspaces domain: Domain: Workspaces
Knowledge Bases domain: Domain: Knowledge Bases
Channels domain: Domain: Channels
Security/compliance: Security & Compliance
Permissions: Roles & Permissions Model