Agents – Migration & Rollout Plan

Last updated: 2026-03-15

---

Context

The Agents feature is being introduced as a first-class workspace-scoped entity. Prior to this spec, agents were referenced only as a count field on KBs (agentsSetCount) with no dedicated management surface. This document defines the backfill strategy, feature flag approach, and compatibility rules.

---

Backfill strategy

Goal

Every existing user account must have at least one agent by the time /account/agents ships. The backfill must be idempotent and non-destructive.

Trigger

The backfill runs server-side at first authenticated page load after the feature ships. It can also be run as a one-time migration job against all existing user records.

Algorithm

for each user account:
  1. Load user data (workspaces, KBs, connections, agents).
  2. Ensure every KB has at least one agent in the same workspace.
  3. For each KB, collect existing Agent-managed channels
     (facebook-messenger, web-chat, whatsapp, sms) linked to that KB.
  4. Assign those channels to KB-scoped agents; if a KB has more than 4 linked
     channels, create additional KB-scoped agents so each agent stays at <= 4.
  5. Normalize status from KB/channel readiness:
     - KB incomplete => draft
     - KB complete + channels => active
     - KB complete + no channels => inactive
  6. Save idempotently (reruns do not duplicate already-covered links).

Idempotency guarantee

• Running the backfill N times produces the same result as running it once.
• Existing valid channel assignments are preserved; only missing coverage is filled.

agentsSetCount field on KnowledgeBase

• This field is currently used by the workspace Agents tab to show summary counts.
• After the Agents feature ships, agentsSetCount must be derived from the actual agent records (count of agents where knowledgeBaseId = kb.id), not stored as a separate field.
• During the transition, agentsSetCount may be kept as a cached/denormalized count but must be kept in sync with agent mutations (create/delete/reassign).

---

Feature flags

No feature flags are required for v1 of the Agents feature. The ComingSoon placeholder in /account/agents/page.tsx has been replaced with the real implementation. The workspace Agents tab has been expanded from summary-only to full CRUD.

If a phased rollout is needed:

Flag	Default	Purpose
agents_global_hub	false	Enable /account/agents real implementation
agents_workspace_crud	false	Enable create/edit/delete in workspace Agents tab

Both flags should be enabled together for the v1 release. Enabling agents_workspace_crud without agents_global_hub is acceptable for internal testing.

---

Compatibility with existing data

Existing data	Compatibility
agentsSetCount on KnowledgeBase	Retained as read field; derived from agent records post-migration
Agent type in src/types/agents.ts	Extend with name, status: "draft" | "inactive" | "active", icon, integrationConfig, createdAt, updatedAt; existing status: "active" | "inactive" maps to the new enum
Workspace Agents tab (current: summary-only)	Replace summary placeholder with full agent list + CRUD
/account/agents (current: ComingSoon)	Replace with global hub implementation
/chatti-live/agents (never shipped)	Deprecated; do not implement

---

Type migration: AgentStatus

Current type in src/types/agents.ts:

export type AgentStatus = "active" | "inactive";

New canonical type:

export type AgentStatus = "draft" | "inactive" | "active";

The draft state is additive. Existing active/inactive values remain valid. No data migration needed for the status field itself — draft is only assigned to newly created agents whose KB is incomplete.

---

Rollout checklist

• Update src/types/agents.ts with canonical Agent entity fields
• Implement local persistence for agents via AgentsContext + /api/user-data
• Replace ComingSoon placeholder in /account/agents/page.tsx with global hub
• Implement workspace Agents tab with full CRUD (replaces summary-only view)
• Implement agent edit modal with General + channel config tabs (Web/Messenger/WhatsApp/SMS/Auto Visibility/Queries)
• Implement activate/deactivate flow with prerequisite checks
• Implement delete flow with confirmation dialog
• Run backfill for existing users (idempotent, triggers on first load via loadUserData)
• Wire agentsSetCount on KnowledgeBase to derive from agent records (deferred — currently stored independently)
• Add deprecation notices to /chatti-live/agents and /chatti-live/agent docs
• Update Agents (Domain) — removed per-type cap, aligned to locked decisions
• Update Account – Agents (/account/agents)
• Update Workspace – Agents Tab — removed per-type cap language
• Add AgentsProvider to app providers tree

---

Risks and mitigations

Risk	Likelihood	Impact	Mitigation
API GET /live-agents returns unexpected shape	Medium	High	Validate response against canonical type; show error state gracefully
X-Workspace-ID header not supported by backend	Low	High	Confirm with backend team before implementation; fallback to query param ?workspaceId=
agentsSetCount drift after agent mutations	Medium	Low	Derive count from agent records on every render; do not cache separately
Users with no default workspace (edge case)	Low	Medium	Backfill creates default workspace idempotently
Concurrent activation (race condition)	Low	Low	Last write wins in v1; optimistic locking deferred to v2
KB deleted while agent is active	Low	Medium	Backend cascades agent to draft; frontend polls or websocket notifies (v2); v1 shows stale state until next fetch