Qontak Chatbot | AI Agent | Autonomous AI Agent — Phase 1: New Engine Migration

HEADER BLOCK

Field	Value
PM	Dimas Fauzi Hidayat (Product Manager, Mekari Qontak)
PRD Version	1.3
Status	DRAFT
PRD Type	NEW
Epic	BOT-4191
Squad	BOT — Hadiningbot Squad
Engineering Lead	Eko Aprianto
UI/UX Designer	Wulan Febyazzahra, Rizky Surur
UI/UX Researcher	Devina Amalia
Data Team	Data / ML Platform (noncore-mrag, chatbot-ai, mekari-agent owners)
Commercial Stakeholder	Aviandri Hidayat
Approval	Annisa Nur
RFC Link	RFC — Migration of Autonomous AI Agent Creation to Chatbot BE and FE
Figma Master	N/A — design is exploratory and evolving. The live Vercel prototype is the single canonical source of truth for design: https://qontak-bot.vercel.app/bot-automation/ai-agents. This PRD is a live document — any visual or interaction change in the Vercel app supersedes prior descriptions in S6/S8/S10.6 of this PRD. Engineering and QA must always re-check the current Vercel state before implementing or testing a UI element. D6 design sign-off tracked as Risk in S15.
Anchor	Yes. This PRD anchors the Autonomous AI Agent — New Engine Migration initiative under Epic BOT-4191 ("26Q2 Autonomous Agent Migration", In Progress). Phase 1 = this document — production autonomous-agent List / Create / Config (Behavior · Capabilities · Routing) + Shared Actions, coexisting with the legacy /ai-agent modal; delivered on the existing /v2/ai_agents endpoints in "autonomous agent mode" (BOT-4235, Done) rather than a new FrontendService::V3 namespace (see the Implementation Reconciliation note below + S7). Phase 2 = migrate existing internally-built configurations (legacy Tree-Diagram production config → new engine/config model; picks up this PRD's Non-Goals #1/#3). Phase 3 = new-configuration iteration grounded in the Design Validation research (15 IDIs — visual Logic Map, terminology overhaul, Milestone/Routing fixes). Both authored later as child PRDs under BOT-4191. Handed to sibling initiatives (own ANCHOR + epic, not under BOT-4191): the batch test-runner + /test/improvise + /test/judge (S4 Non-Goals #4–#5) → AI Agent Testing (BOT-3351); the Shared Resources / KB surface (AAA-S09) overlaps AI Agent Knowledge.
Labels	epic:qontak-chatbot | module:ai-agent | feature:autonomous-ai-agent
Last Updated	2026-05-22

⚠️ Implementation Reconciliation (added 2026-06-22 — repo mirror)

This PRD (v1.3) predates the shipped implementation and is out of sync with the code in several places. Verified against chatbot / chatbot-fe and Jira BOT-4191 / BOT-4235 on 2026-06-22:

PRD specifies	Shipped reality	Source
FrontendService::V3 namespace, /api/v3/ai_agents/autonomous*	Built in FrontendService::V2 — /v2/ai_agents in "autonomous agent mode"	BOT-4235 (Done), v2/ai_agent/ai_agents_controller.rb
FE routes /ai-agent/autonomous	FE routes /bot-automation/* (matches S6.0 surface map, not the S6 URL blocks)	chatbot-fe/pages/bot-automation/*
Rollout flag autonomous_ai_agent in BE system_preferences	Gated by org setting ai_agent_engine_version === 2; no such flag exists	system_preference.rb, layouts/bot-automation.vue
No delete in Phase 1 (AAA-S03 AC-4: "no DELETE endpoint mounted")	V2 controller ships hard DELETE + FE deleteAgent()	ai_agents_controller.rb:327
/bot-automation/resources Shared KB module + preview rail (AAA-S04 / S09)	Not built under bot-automation; KB lives under /ai-knowledge/*; no preview rail	overlaps AI Agent Knowledge initiative
Custom error codes (INVALID_AUTONOMOUS_PAYLOAD, INVALID_COMPANY_SCOPE, AUTONOMOUS_UPSTREAM_*, AUTONOMOUS_DETAIL_NOT_FOUND)	Absent — generic HTTP status codes	grep, no matches

Matches spec well: the capability↔skill_pack adapter (skill_pack_mapper.rb), the capability_ref_presence.rb validator, the Behavior / Capabilities / Routing 3-tab editor (AiAgentEditor.vue), Guided-form + Write-prompt create modes, and the Actions catalog.

Open action (tracked separately from the anchor flip): reconcile S5 / S7 / S9 / S14 to the V2 reality, and either build or formally defer Resources + preview (AAA-S04 / S09) and the no-delete constraint (S3). This note is advisory and does not change the ACs below.

Table of Contents

• HEADER BLOCK

• 2. One-liner + Problem

• 3. Target Users + Persona Context

• 4. Non-Goals

• 5. Constraints

  • 5.7. Data Lifecycle

• 6. New Features

  • 6.0. Surface map
  • Feature: List · Create · Config · Resources · Actions

• 7. API & Webhook Behavior

• 8. System Flow + User Stories + ACs

  • 8.1. System Flow
  • 8.2. User Stories (AAA-S01 through AAA-S10)

• 9. Rollout

  • 9.4. Migration Transition Window

• 10. Observability

  • 10.5. Post-Launch Monitoring Cadence

• 11. Success Metrics

• 12. Launch Plan & Stage Gates

• 13. Dependencies

• 14. Key Decisions + Alternatives Rejected

• 15. Open Questions

• PRD CHANGELOG

2. One-liner + Problem

One-liner:
Replace Qontak's prototype-grade Autonomous AI Agent flow with a production /ai-agent/autonomous route family in chatbot-fe + V3 proxy in chatbot BE, coexisting with the legacy AI Agent modal. (24 words)

Problem:
AI Agent is already an established capability inside the Use-Case Package Plus/Ultimate and Qontak 360 tiers via the legacy /ai-agent modal (session-based, Redis-backed, V1 endpoints) — but the autonomous-agent engine is not exposed there and currently only runs in chatbot-ml-dev, a prototype-grade Vue/Vite app calling noncore-mrag, chatbot-ai, and mekari-agent directly with no production-grade FE/BE separation, no rollout controls, no audit trail, and no plan/tier enforcement. Chatbot Specialists and dedicated bot builders responsible for delivering 15 autonomous agents across 15 customer IDs in 26Q2 cannot run the prototype safely against customer workspaces, and the legacy modal cannot serve the autonomous use case because its data model is a different product. This is the second iteration of the AI Agent product line: the first generation did not move the needle for customers on the autonomous use case, and continued market pressure from competitor AI-agent offerings makes shipping the production autonomous flow inside the existing entitled tiers a 26Q2 commitment.

3. Target Users + Persona Context

Persona	Role	Goal	Pain	Workaround
Primary — Chatbot Specialist	Internal Qontak Chatbot Specialist (technical) who configures autonomous AI agents on behalf of, or jointly with, customer accounts. Owns 26Q2 target of 15 agents across 15 client IDs (cid).	Stand up an autonomous AI agent end-to-end (capability_pack drafted from prompt, knowledge files vectorised, direct + full preview validated) inside the production Qontak chatbot stack so the agent can be handed to the customer with audit trail and rollout control.	Today the only autonomous flow lives in chatbot-ml-dev — a prototype app with no plan/tier gating, no session auth surface, no admin introspection, no rollout flag, and no path to expose to customer users. Specialist must run a non-prod URL, manually wire OSS uploads, and cannot demo inside the actual Qontak admin.	(a) Build the agent in chatbot-ml-dev outside the customer's workspace, then describe the configuration to the customer manually; (b) try to approximate the use case inside the legacy /ai-agent modal — fails because the legacy modal is a different product (session-based, no autonomous engine).
Secondary — Dedicated Bot Builder (Customer-side)	A dedicated person at the customer (technical OR non-technical Use-Case Package Plus/Ultimate or Qontak 360 admin) responsible for building and maintaining their company's AI agents.	Self-serve an autonomous AI agent inside their own Qontak admin: draft from a prompt, add knowledge files/URLs, run preview, save, and ship — without depending on a Mekari specialist for every change.	Has no production path today. The legacy /ai-agent modal does not support the autonomous engine. The prototype chatbot-ml-dev is internal-only and not exposed to customers. Non-technical builders cannot read repo-driven prototypes or wire OSS URLs by hand.	Hands the request to a Mekari Chatbot Specialist and waits; or builds a degraded flow inside the legacy modal and accepts limited capability.

4. Non-Goals

1. Legacy /ai-agent modal is not modified or replaced. The existing session-based modal at pages/ai-agent/index.vue (backed by Redis + local Rails tables ai_agents, ai_agent_actions, ai_agent_knowledges) remains untouched. Both products coexist post-launch.
2. No new Rails DDL in Phase 1. BE acts as a proxy/BFF only — no mirroring of autonomous agents into local Rails tables, no new database schema in the chatbot service.
3. No data migration of legacy AI Agents into the autonomous engine. Customers on the legacy modal stay there. No automated migration tool.
4. CSV batch test-runner (ST7) is out of scope. Deferred to Phase 2.
5. /test/improvise and /test/judge endpoints are out of scope. Deferred to Phase 2.
6. No FE-only environment flag for production rollout. Rollout exposure is sourced from BE system_preferences.autonomous_ai_agent only (FE route middleware + nav visibility derive from BE signal).
7. No multi-tab concurrent-edit conflict resolution. Phase 1 accepts last-write-wins; warning shown on detail reload if updated_at changed.
8. No customer-facing analytics or audit history dashboard. Analytics, audit history, and admin introspection remain upstream-only (in noncore-mrag / chatbot-ai) for Phase 1.
9. No Mobile app support. Web (chatbot-fe) only.
10. No raw-file or third-party URL passthrough to ML vector endpoints. All knowledge ingestion must go through Alicloud OSS first.

5. Constraints

Platform:       Web only (chatbot-fe). Modern desktop browsers (Chrome / Edge / Safari current+1).
                Not exposed on Qontak Mobile app in Phase 1.
Performance:    BE list/detail endpoints — p95 < 800 ms (excluding upstream incidents).
                Draft / save / preview — preserve upstream latency with minimal proxy overhead;
                explicit open/read timeouts with normalised timeout errors.
                FE route entry to first meaningful content — within standard chatbot-fe page expectations.
                KB vectorisation status polling — 5-second client-side intervals.
Data limits:    Knowledge base file uploads — limits inherited from existing OSS-first knowledge
                pipeline (reuse limits from `app/core/use_cases/api/frontend_service/v1/ai_assist/
                create_knowledge_source.rb`). KB URL ingestion — `http` / `https` schemes only.
Plan scope:     Use-Case Package — Plus and Ultimate tiers. Qontak 360 platform tier.
                Not available on free / starter / lower Use-Case tiers in Phase 1.
Feature flag:   `autonomous_ai_agent` | default: OFF.
                Source of truth: BE rollout code under existing `system_preferences` rollout group.
                FE consumes BE rollout signal for route middleware + nav visibility.
                No FE-only env flag.
Read/write:     CAN access (read + write): account roles `owner`, `supervisor`, `admin`
                with workspace on Plus / Ultimate / 360 AND `autonomous_ai_agent` rollout = ON.
                CANNOT access: all other roles. Unauthorised role → route middleware redirects /
                nav entry hidden; V3 endpoints return HTTP 403 `INVALID_COMPANY_SCOPE`.
BE error codes: INVALID_AUTONOMOUS_PAYLOAD (400) · INVALID_COMPANY_SCOPE (403) ·
                AUTONOMOUS_UPSTREAM_TIMEOUT (504) · AUTONOMOUS_UPSTREAM_ERROR (502) ·
                AUTONOMOUS_DETAIL_NOT_FOUND (404).
Data integrity: `ai_agent_uuid` is stable after first save. Numeric `id` preserved for
                KB/preview lookups. Agent-level KB vectorisation cannot begin until a saved
                numeric `id` exists. Only OSS-backed knowledge refs may reach vectorisation
                endpoints. Full preview reflects saved state only; warning shown on unsaved changes.

5.7. Data Lifecycle

Artifact Type	Retention Period	Cleanup Trigger	User-Visible Effect
Knowledge file uploaded to Alicloud OSS (pre-vectorisation)	Until parent autonomous agent deleted or KB record removed	OSS lifecycle policy inherited from existing knowledge pipeline	None — file accessed via signed/internal OSS URL
Extracted URL content persisted to OSS	Same as KB file	Same as KB file	None
Vectorisation status record (upstream noncore-mrag)	Upstream-owned	Upstream-owned	"Indexing…" / "Ready" / "Failed" badge in UI
FE-local in-memory editor draft (pre-first-save)	Volatile — cleared on hard refresh or deep-link before first save	Hard refresh, navigation away, tab close	User redirected back to create route; unsaved changes lost
selectedCompanyId persisted client-side	Until user clears browser storage	Manual clear	None — controls scope filter

6. New Features

⚠️ Live design source of truth — read before implementing or testing.
The component trees, UI states, and state diagrams below describe the intended structure as of Last Updated in the header. The actual visual layout, copy, interaction order, and component composition are governed by the live Vercel prototype at https://qontak-bot.vercel.app/bot-automation/ai-agents.
Design is exploratory and will evolve in the Vercel app without re-versioning this PRD for every visual change. Where this section and the Vercel app diverge, the Vercel app wins for visuals; the PRD wins for data contracts, ACs, permissions, and APIs.
PM commits to updating this section only when the divergence is structural (new screen added, screen removed, fundamental flow change). Cosmetic changes (copy, spacing, colour, micro-interactions) are tracked in the Vercel app history, not here.

6.0. Surface map (from prototype walk 2026-05-22)

This PRD covers the following routes inside chatbot-fe's /bot-automation/* namespace:

Route	Purpose	Build status (Phase 1)
/bot-automation/ai-agents	AI Agent List page	✅ In scope
/bot-automation/create-ai-agent	AI Agent Create page (Guided form + Write prompt modes)	✅ In scope
/bot-automation/ai-agent/:slug	AI Agent Config page (Behavior / Capabilities / Routing tabs + Preview rail)	✅ In scope
/bot-automation/resources	Shared Resources (Knowledge Base) module	✅ In scope
/bot-automation/actions	Shared Actions (integration catalog) module	✅ In scope
/bot-automation/testing	Bulk testing / batch eval	❌ Phase 2 (stub in prototype)
/bot-automation/analytics	Agent analytics dashboard	❌ Phase 2 (stub in prototype)
/bot-automation/bot-flow	Legacy bot flow builder	❌ Out of scope (existing Qontak surface)
/bot-automation/settings	Module-level settings	❌ Phase 2 (stub in prototype)

Feature: Autonomous AI Agent List Page

URL:     /ai-agent/autonomous
Access:  Roles owner/supervisor/admin on Plus/Ultimate/360 with autonomous_ai_agent rollout = ON.
Source:  Repo-driven from chatbot-ml-dev prototype + chatbot-fe-ai-agent/app/pages/bot-automation/ai-agents.vue
Canonical reference: https://qontak-bot.vercel.app/bot-automation/ai-agents

Component Tree:

AutonomousAiAgentListPage
├── PageHeader                          — title, [+ Create Autonomous Agent] CTA
├── CompanyScopeFilter                  — selectedCompanyId picker (FE-local persistence)
├── AutonomousAiAgentListTable          — list of capability_packs (paginated)
│   ├── AgentRow                        — name, status, owner, last updated, [Open] action
│   └── EmptyStateBlock                 — shown when no agents exist
└── ListFetchErrorBlock                 — shown when V3 list call fails

UI States:

Empty:    "No Autonomous AI Agents yet." + [+ Create your first agent] CTA. No table rows.
Loading:  Skeleton rows (5) while V3 list call in flight.
Error:    "Could not load Autonomous AI Agents." + [Retry] button. Log event:
          autonomous_ai_agent_list_load_failed with reason: <BE error code>.
Success:  Paginated table of capability_packs scoped to selectedCompanyId.

📊 UI State Diagram — Autonomous AI Agent List Page

stateDiagram-v2
    [*] --> Loading: User opens /ai-agent/autonomous
    Loading --> Empty: V3 list returns 0 records
    Loading --> Success: V3 list returns ≥1 records
    Loading --> Error: V3 list returns 4xx/5xx
    Error --> Loading: User clicks Retry
    Empty --> Loading: User changes CompanyScopeFilter
    Success --> Loading: User changes CompanyScopeFilter
    Empty --> [*]: User clicks [+ Create your first agent] → routes to /create
    Success --> [*]: User clicks AgentRow Open → routes to /:ai_agent_uuid

---

Feature: Autonomous AI Agent Create Page

URL:     /bot-automation/create-ai-agent
Access:  Same as list page.
Modes:   Two creation modes via a top toggle: "Guided form" (default) or "Write prompt"

Guided form mode — fields:

Field	Type	Notes
Agent type	dropdown	Customer support / Sales / Marketing / Custom — pre-populates downstream fields per template
Agent name	text, required	"e.g. Customer service"
What are your agent's main goals?	multi-select chips	Defaults include: Resolve customer issues · Answer FAQ · Process requests (refund, returns) · Reduce time response · Something else (custom)
How should this agent talk?	dropdown	Tone presets: Casual and conversational / Professional and formal / Friendly and empathetic / Direct and concise
Where should this agent get its knowledge from?	source picker (multi)	Pick any combination from 4 source types — see Knowledge Source picker below

Write prompt mode — fields:

Field	Type	Notes
What should this AI agent do?	large textarea, required	Freeform prompt. Placeholder gives a worked example covering scope + tone + guardrails.
Where should this agent get its knowledge from?	source picker (multi)	Same as Guided form

Knowledge Source picker (shared by both modes):

Source type	Behavior
External URL	Opens "Add external URL" panel — paste URL, scan asynchronously (up to ~15 min)
File upload	Upload PDF or image files (OCR'd if image)
Text content	Create source content inline in the app
Conversation history	Learn from past conversations in the Inbox menu

Footer actions: [Cancel] · [Skip this] (proceeds without configuring sources/goals) · [Generate agent] (calls upstream draft endpoint, routes to Config page on success)

Component Tree:

AutonomousAiAgentCreatePage
├── PromptDraftPanel                    — natural-language prompt → /draft_capability_pack
│   └── DraftCapabilityPackButton       — triggers draft, shows draft preview
├── CapabilityPackEditor                — edit drafted capability_pack inline
├── AutonomousKnowledgeDrawer           — upload files / URLs to OSS → vectorise
├── AutonomousActionDrawer              — capability/action configuration
├── AutonomousPreviewRail               — dual-mode preview (direct + full)
│   ├── DirectPreviewTab                — /run via mekari-agent
│   └── FullPreviewTab                  — /predict via chatbot-ai (saved state only)
└── SaveAgentBar                        — first-save creates ai_agent_uuid + numeric id

UI States:

Empty:    Empty prompt panel + drawer placeholders. Save disabled until prompt drafted.
Loading:  Per-action spinners (draft / upload / vectorise / preview).
Error:    Inline error per panel:
          - Draft failure: "Could not draft capability pack. Try again." + Retry.
          - OSS upload failure: "Upload failed (file_name). Try again."
          - Vectorisation failure: "Indexing failed. Retry?" + Retry.
          - Preview failure: "Preview unavailable: <error code>." + Retry.
Success:  Filled editor + KB drawer rows showing "Ready" + preview returning responses.

📊 UI State Diagram — Autonomous AI Agent Create Page

stateDiagram-v2
    [*] --> Empty: User opens /ai-agent/autonomous/create
    Empty --> Drafting: User enters prompt + clicks Draft
    Drafting --> EditorPopulated: Draft 2xx
    Drafting --> DraftError: 400/502/504
    DraftError --> Drafting: User clicks Retry
    EditorPopulated --> KBUploading: User adds file/URL in drawer
    KBUploading --> EditorPopulated: OSS upload + KB record OK (status: Indexing)
    KBUploading --> KBError: OSS or KB record fails
    KBError --> KBUploading: User clicks Retry on row
    EditorPopulated --> Saving: User clicks Save (capability_pack complete)
    Saving --> [*]: First-save success → routes to /:ai_agent_uuid (Config Page)
    Saving --> SaveError: Save fails (502/timeout)
    SaveError --> EditorPopulated: User retries (editor state preserved)
    EditorPopulated --> EditorPopulated: User runs DirectPreview (no state change)

---

Feature: Autonomous AI Agent Config / Detail Page

URL:     /bot-automation/ai-agent/:slug
Access:  Same as list page.
Layout:  Three-tab content area on the left + persistent Preview rail on the right (across all tabs).
Tabs:    Behavior · Capabilities · Routing

Component Tree:

AutonomousAiAgentConfigPage
├── AgentHeaderBar                      — agent name + status + updated_at + [Close] + [Cancel] [Save]
├── UnsavedChangesBanner                — shown when local edits diverge from saved state
├── ConcurrentEditWarning               — shown if updated_at changed since editor loaded
│
├── ConfigTabsContainer                 — three tabs (Behavior default)
│   │
│   ├── BehaviorTab (default)
│   │   ├── AgentNameField              — required, invisible-to-customer name
│   │   ├── AgentResponseDescription    — "How this agent responds" (textarea)
│   │   ├── GoalsAndBehaviorBlock       — large prompt-like textarea, required
│   │   ├── ToneOfVoiceSelector         — 4 presets (Casual / Professional / Friendly / Direct)
│   │   ├── LanguageSelector            — dropdown
│   │   ├── GuidanceList                — repeating rows of named guidance rules
│   │   │   └── GuidanceRow             — name + description; reorder; [+ Add guidance]
│   │   ├── GuardrailsList              — repeating rows of named avoid rules
│   │   │   └── GuardrailRow            — name + description; [+ Add guardrail]
│   │   └── AdvancedSettingsCollapsible — model, response shaping, timing, conversation memory
│   │
│   ├── CapabilitiesTab
│   │   ├── CapabilityCard (repeating)
│   │   │   ├── CapabilityNameAndDescription
│   │   │   ├── UseThisWhen — TriggerPhrasesChips (multi-add)
│   │   │   ├── MilestonesList — checkpoint tokens (e.g. refund_initiated, ticket_created)
│   │   │   ├── InstructionsTextarea — "What to do"
│   │   │   ├── SourcesUsedBlock
│   │   │   │   ├── KnowledgeLinkedList  — picks from shared Resources module
│   │   │   │   └── ActionsLinkedList    — picks from shared Actions catalog
│   │   │   ├── CompletesWhenField — success criteria
│   │   │   ├── ToggleCapabilityActive
│   │   │   └── RemoveCapabilityControl
│   │   └── AddCapabilityCTA
│   │
│   └── RoutingTab
│       ├── RoutingRulesList (repeating)
│       │   └── RoutingRuleRow
│       │       ├── WhenConditionSelect — Select condition / When user says / When action error
│       │       ├── WhenConditionInput   — e.g. "Customer says talk to a human" (textbox when condition needs it)
│       │       ├── ThenActionSelect    — Hand off to human agent / Ask clarification / Resolve conversation / Switch capability / Switch action
│       │       ├── HandoffAgentGroupSelect — Any available agent / Sales division / Support division (shown when ThenAction = Hand off)
│       │       └── RemoveRuleControl
│       └── AddRuleCTA
│
├── PersistentPreviewRail (right column, all tabs)
│   ├── PreviewHeader — agent display name
│   ├── PreviewTranscript
│   ├── PreviewInputBox — "Enter your message"
│   ├── CreditsHint — "Testing in preview does not deduct your AI credits"
│   └── RefreshPreviewControl
│
└── DeleteAgentControl                  — Phase 1: placeholder only, intentionally not implemented

UI States:

Empty:    N/A — agent always exists at this route. 404 redirects to list with toast.
Loading:  Skeleton header + drawer placeholders during V3 detail fetch.
Error:    "Agent not found (AUTONOMOUS_DETAIL_NOT_FOUND)." → redirect to list with toast.
Success:  Editor populated with saved capability_pack and KB rows.

📊 UI State Diagram — Autonomous AI Agent Config Page

stateDiagram-v2
    [*] --> Loading: User opens /ai-agent/autonomous/:uuid
    Loading --> Loaded: V3 detail 2xx
    Loading --> NotFound: 404 AUTONOMOUS_DETAIL_NOT_FOUND
    NotFound --> [*]: Redirect to list with toast
    Loaded --> EditedUnsaved: User edits Behavior / Capabilities / Routing / KB
    EditedUnsaved --> Loaded: User clicks Save → success
    EditedUnsaved --> ConflictWarning: Save returns updated_at conflict
    ConflictWarning --> Loading: User clicks Reload
    EditedUnsaved --> Loaded: User clicks Save → upstream error → editor preserved
    Loaded --> Loaded: User runs DirectPreview / FullPreview (no state change)

---

Feature: Shared Resources (Knowledge Base) Module

URL:     /bot-automation/resources
Access:  Same role/plan/rollout gating as the AI Agent module.
Scope:   Shared across ALL Autonomous AI Agents in the workspace. A Resource added
         here is selectable from any Capability's Sources Used block.

Component Tree:

ResourcesPage
├── PageHeader — title + [Add source] CTA
├── ExistingSourcesSummaryCards
│   ├── UnansweredQuestionsCard — count of agents with unanswered Qs (links to Conv history)
│   ├── ConversationHistoryCard — count of agents trained from conversation history
│   ├── ExternalUrlCard — count of links
│   ├── FileUploadCard — count of uploaded files
│   ├── OcrFileCard — count of OCR'd image files
│   └── TextContentCard — count of inline text contents
├── SourceTypeFilter — All sources / Link / File / OCR file / Document
├── SearchSourceField
├── ResourceListTable
│   └── ResourceRow — name + type + status (Active/Inactive) + last_updated + [Actions] (Edit, Delete, Toggle)
└── Pagination

Add Source modal (4 source types):

Source Type	Sub-form fields	Async behavior
External URL	One URL field; help tips ("page must be public", "scanning takes up to 15 min")	Scan is async — submit returns immediately, status polled until Active/Failed
File upload	Multipart file picker (PDF or image)	Upload → OSS → vectorise → status polled
Text content	Source name + content textarea	Synchronous save; vectorise async
Conversation history	Picks from past Inbox conversations	Async ingest from Inbox API

UI States (List page):

Empty:    "No resources yet." + [Add source] CTA. Summary cards all show 0.
Loading:  Skeleton rows + skeleton summary cards during V3 list call.
Error:    "Could not load resources." + [Retry]. Log: autonomous_resources_list_load_failed.
Success:  Populated summary cards + paginated table.

📊 UI State Diagram — Resources List Page

stateDiagram-v2
    [*] --> Loading: User opens /bot-automation/resources
    Loading --> Empty: 0 resources
    Loading --> Success: ≥1 resources
    Loading --> Error: V3 list 4xx/5xx
    Error --> Loading: User clicks Retry
    Empty --> AddSourceModalOpen: User clicks Add source
    Success --> AddSourceModalOpen: User clicks Add source
    AddSourceModalOpen --> ScanningOrUploading: User picks type + submits
    ScanningOrUploading --> Success: Active status reached
    ScanningOrUploading --> Success: Failed status (row visible with Failed badge)
    Success --> ResourceDetailDrawer: User clicks row Actions → Edit
    Success --> Success: User toggles Active/Inactive

---

Feature: Shared Actions (Integration Catalog) Module

URL:     /bot-automation/actions
Access:  Same role/plan/rollout gating as the AI Agent module.
Scope:   Shared catalog of integrations the Autonomous AI Agent can call as
         part of a Capability's "Sources used → ACTIONS" block.

Component Tree:

ActionsPage
├── PageHeader — title + [Add action] CTA
├── StatusFilter — All / Active / Inactive
├── SearchActionField
├── ActionListTable
│   └── ActionRow — name + description + action_type (Qontak / Talenta / Jurnal / Desty / Google Calendar / Google Sheets / API)
│                  + status + last_updated + [Actions] (Edit, Delete, Toggle)
└── Pagination

Add Action drawer (categorised picker):

Category	Built-in actions exposed
Mekari Qontak	Assign agent · Create deal · Create tag · Create ticket · Resolve conversation · Update deal · Update ticket
Mekari Talenta	Approve reimbursement · Generate payslip
Mekari Jurnal	Create sales order · Create invoice
Mekari Desty	Check product stock · Check payment status · Check voucher
Other integration	API Integrations · Get nearest location · Google Sheets · Google Calendar

UI States (List page):

Empty:    "No actions yet." + [Add action] CTA.
Loading:  Skeleton rows during V3 list call.
Error:    "Could not load actions." + [Retry]. Log: autonomous_actions_list_load_failed.
Success:  Populated table.

📊 UI State Diagram — Actions List Page

stateDiagram-v2
    [*] --> Loading: User opens /bot-automation/actions
    Loading --> Empty: 0 actions
    Loading --> Success: ≥1 actions
    Loading --> Error: V3 list 4xx/5xx
    Error --> Loading: User clicks Retry
    Empty --> AddActionDrawerOpen: User clicks Add action
    Success --> AddActionDrawerOpen: User clicks Add action
    AddActionDrawerOpen --> ConfiguringAction: User picks a built-in (e.g. Create ticket)
    ConfiguringAction --> Success: User saves configured action
    ConfiguringAction --> ConfigError: Validation / upstream error
    ConfigError --> ConfiguringAction: User fixes + retries
    Success --> ActionDetailDrawer: User clicks row Actions → Edit
    Success --> Success: User toggles Active/Inactive

7. API & Webhook Behavior

All endpoints under FrontendService::V3 namespace, session-authenticated, scoped to roles owner / supervisor / admin on Plus / Ultimate / 360 workspaces with autonomous_ai_agent rollout = ON. BE acts as a proxy/BFF to upstream noncore-mrag, chatbot-ai, and mekari-agent — no new Rails DDL. Public FE/BE vocabulary uses capability_pack / capability_id; only the adapter layer translates to upstream skill_pack / skill_id.

#	Behavior	Entity Affected	Triggered By	Expected Behavior	Failure Behavior
1	Draft a capability_pack from a prompt	Upstream skill_pack (no local persistence)	User types a prompt and clicks "Draft" on Create page	BE proxies prompt to noncore-mrag /draft-skill-pack; FE adapter wireCapabilityPackForRuntime maps response to capability_pack; editor populates with draft fields	INVALID_AUTONOMOUS_PAYLOAD (400) → inline form error
AUTONOMOUS_UPSTREAM_TIMEOUT (504) → "Drafting timed out, retry"
AUTONOMOUS_UPSTREAM_ERROR (502) → "Drafting failed, retry"
2	List autonomous AI agents	Upstream noncore-mrag agent list scoped to selectedCompanyId	User opens /ai-agent/autonomous; rollout = ON	BE proxies list call; FE renders paginated table	Upstream error → list error state + Retry; 403 INVALID_COMPANY_SCOPE → redirect with "No access" toast
3	Get a single autonomous agent (detail)	Single upstream agent + its capability_pack + KB refs	User opens /ai-agent/autonomous/:ai_agent_uuid	BE proxies detail call, returns ai_agent_uuid, numeric id, capability_pack, KB list, updated_at	AUTONOMOUS_DETAIL_NOT_FOUND (404) → redirect to list with toast
Timeout → detail error state
4	Create autonomous agent (first save)	New upstream agent	User clicks Save on Create page	BE proxies POST; upstream returns ai_agent_uuid + numeric id (both stable thereafter); FE routes to detail page	Validation error → inline field errors
Upstream failure → "Save failed, retry"; no partial local state created
5	Update autonomous agent	Existing upstream agent	User clicks Save on Config page	BE proxies PUT with full capability_pack; upstream returns updated state + new updated_at	If updated_at is stale (concurrent edit) → BE returns conflict; FE shows ConcurrentEditWarning + offers reload
6	Upload knowledge file (OSS-first)	New OSS object → upstream KB record	User adds a file in AutonomousKnowledgeDrawer	BE multipart upload routed to Alicloud OSS first; OSS-backed URL passed to upstream KB endpoint; KB row appended with status Indexing	OSS upload failure → "Upload failed, retry"
Upstream KB failure after OSS success → row marked "Failed" with Retry; no orphan vector created
7	Ingest knowledge URL	New OSS object (extracted content) → upstream KB record	User adds an http/https URL in drawer	BE extracts URL content server-side, persists to OSS, passes OSS URL to upstream KB endpoint	Non-http(s) scheme rejected with INVALID_AUTONOMOUS_PAYLOAD
Extraction failure → "Could not extract URL content"
Upstream KB failure → row marked "Failed" with Retry
8	Trigger KB vectorisation	Upstream vector index for agent or capability	Automatically after KB upload completes AND agent has saved numeric id	BE proxies vectorisation request with OSS-backed refs only; FE polls status every 5s	Vectorisation cannot start before numeric id exists → FE blocks call and surfaces "Save agent first"
Upstream failure → row "Failed" + Retry
9	Poll KB vectorisation status	Upstream status for agent/capability	FE 5s interval while any KB row is Indexing	BE proxies status call; FE updates row status (Indexing → Ready / Failed)	Transient upstream errors logged silently; UI keeps last known status; status not updated until next successful poll
10	Direct preview (run)	Upstream mekari-agent /run-autonomous-agent	User clicks DirectPreviewTab Run	BE proxies request via new lib/mekari_agent/autonomous_ai_agent.rb client; response streamed back to UI	Missing MEKARI_AGENT_BASE_URL → 502 + "Direct preview unavailable"
Upstream timeout → 504 + retry CTA
Upstream error → 502 + retry CTA
11	Full preview (predict)	Upstream chatbot-ai /predictions	User clicks FullPreviewTab Run on a saved agent	BE proxies predict call; full preview returns AI response based on saved capability_pack + KB	Unsaved changes warning required before call enabled
Upstream failure → 502/504 with retry CTA
12	Generate agent from Guided form OR Write prompt (Create page)	New upstream agent draft (capability_pack)	User clicks Generate agent	BE proxies prompt assembly + draft to noncore-mrag /draft-skill-pack. For Guided form, BE composes the prompt server-side from agent_type, agent_name, goals[], tone, knowledge_sources[]. For Write prompt, BE forwards the user prompt directly. Response is the drafted capability_pack; FE routes to Config page (unsaved)	Validation failure → inline field errors on Create page (Generate button re-enables). Upstream draft failure → 502/504 + "Drafting failed, retry"
13	Read / list Resources (Knowledge Base)	Upstream KB sources scoped to workspace	User opens /bot-automation/resources	BE proxies list call; FE renders summary cards + filtered/searched table	Upstream error → list error state + Retry; 403 INVALID_COMPANY_SCOPE for non-entitled workspaces
14	Add Resource — External URL (async scan)	New Resource record + OSS object (extracted content)	User submits URL in Add source → Scan URL	BE validates http(s) scheme; calls upstream URL extractor; persists extracted content to Alicloud OSS; creates Resource record with status=Scanning; returns immediately. FE polls status until Active (max ~15 min) or Failed	Non-http(s) scheme → INVALID_AUTONOMOUS_PAYLOAD. Extraction timeout > 15 min → row marked Failed with reason; Retry available
15	Add Resource — File upload	New Resource record + OSS object	User uploads file in Add source	BE multipart → Alicloud OSS first → upstream KB record creation; status Indexing then Active	OSS failure → "Upload failed, retry". Upstream KB creation failure after OSS success → row Failed; no orphan vector
16	Add Resource — Text content	New Resource record + OSS object	User saves text content in Add source	BE persists text to OSS, upstream creates KB record + vectorises; status flows Indexing → Active	Validation failure → inline error. Upstream failure → row Failed + Retry
17	Add Resource — Conversation history	Upstream KB record sourced from Inbox conversations	User selects conversations to learn from	BE proxies to upstream conversation-learn endpoint; status flows Ingesting → Active	If Inbox API unavailable → 502 + "Conversation history unavailable, retry"
18	Toggle Resource Active/Inactive	Resource record	User toggles status in row Actions	BE proxies PATCH; upstream marks the source available/unavailable to capabilities	If toggle conflicts with in-flight scan → returns 409 + "Wait for scan to finish"
19	Delete Resource	Resource record + OSS object	User deletes via row Actions → confirm	BE proxies DELETE; OSS object removed; upstream vector reference revoked; all Capability links to this source are stripped silently	If Resource is currently being scanned → 409 + "Cannot delete while scanning"
20	Read / list Actions (integration catalog)	Upstream action catalog scoped to workspace	User opens /bot-automation/actions	BE proxies list; FE renders filtered/searched table	Upstream error → list error state + Retry
21	Add Action from catalog	New Action record (configured integration instance)	User picks an action (e.g. Create ticket) from Add action drawer + completes config form	BE creates Action record with its provider-specific config; status Active by default	Validation failure → inline error per field. If the integration requires a connector not installed (e.g. Google Calendar not connected) → 412 + helper text pointing to integrations settings
22	Toggle / Edit / Delete Action	Action record	User opens row Actions menu	BE proxies PATCH or DELETE; upstream marks action available/unavailable to capabilities	If Action is referenced by any active Capability and user attempts delete → 409 + "In use by N capabilities, remove from those first"
23	Save Behavior block (BehaviorTab fields)	Existing agent's Behavior config	User edits Behavior fields + clicks Save	BE proxies PUT to agent endpoint with updated Behavior block; upstream returns new updated_at	Concurrent edit → 409 + ConcurrentEditWarning. Validation failure → inline field errors
24	Add / Edit / Remove Capability	Existing agent's capabilities	User edits a CapabilityCard or clicks Add capability	BE proxies PUT; upstream stores the capability config including triggers, milestones, instructions, linked KnowledgeIds, linked ActionIds, success criteria; updated_at refreshed	If linked Resource or Action has been deleted out from under it → 409 + "Linked source no longer exists, fix and retry"
25	Toggle Capability Active	Single capability within an agent	User toggles a CapabilityCard	BE proxies PUT; capability is excluded from runtime when Inactive	Same conflict patterns as #24
26	Add / Edit / Remove Routing Rule	Existing agent's routing rules	User edits RoutingRuleRow on RoutingTab	BE proxies PUT with the rules array; for Hand off to human agent rules, BE validates that the named agent group exists in the Inbox routing config	If agent_group_id is invalid or has been removed → 422 + inline error pointing to the rule
27	Hand off to human agent (runtime)	Inbox conversation record	Routing rule fires (When condition met → Then = Hand off to human agent) at runtime	Autonomous engine emits handoff event; BE relays to Inbox routing API which assigns the conversation to the configured agent_group (Any available / Sales division / Support division); conversation transitions to human-handled state	If Inbox routing API unavailable → autonomous engine falls back to Ask clarification behaviour and emits autonomous_handoff_fallback event (operationally avoids dropping the customer)

8. System Flow + User Stories

📊 System Flow — Autonomous AI Agent end-to-end

sequenceDiagram
    autonumber
    actor Specialist as Chatbot Specialist
    participant FE as chatbot-fe<br/>(/ai-agent/autonomous)
    participant BE as chatbot BE<br/>(FrontendService::V3)
    participant Mrag as noncore-mrag
    participant OSS as Alicloud OSS
    participant Mek as mekari-agent
    participant CAI as chatbot-ai

    Specialist->>FE: Open /ai-agent/autonomous
    FE->>BE: Check rollout signal
    BE-->>FE: rollout = ON + role/plan OK
    FE->>BE: GET /ai_agents/autonomous (list)
    BE->>Mrag: proxy list
    Mrag-->>BE: agents
    BE-->>FE: list renders

    Specialist->>FE: Click [+ Create] → enter prompt → Draft
    FE->>BE: POST /draft_capability_pack
    BE->>Mrag: /draft-skill-pack
    alt success
        Mrag-->>BE: skill_pack
        BE-->>FE: capability_pack (mapped)
        Note over FE: Editor populates
    else failure (400/502/504)
        BE-->>FE: error code
        Note over FE: Inline error + Retry
    end

    Specialist->>FE: Upload file / paste URL
    FE->>BE: POST /knowledge_base/files OR /urls
    BE->>OSS: persist file / extracted content
    OSS-->>BE: oss_url
    BE-->>FE: KB row (status: Pending save)

    Specialist->>FE: Click Save (first save)
    FE->>BE: POST /ai_agents/autonomous
    BE->>Mrag: create agent
    Mrag-->>BE: ai_agent_uuid + numeric id
    BE-->>FE: route to /:ai_agent_uuid
    FE->>BE: POST /knowledge_base/vectors (auto)
    BE->>Mrag: vectorise (OSS-backed refs)

    loop every 5s while Indexing
        FE->>BE: GET /knowledge_base/vectors/status
        BE->>Mrag: status
        Mrag-->>BE: Indexing | Ready | Failed
        BE-->>FE: status update
    end

    Specialist->>FE: Open DirectPreview → Run
    FE->>BE: POST /run
    BE->>Mek: /run-autonomous-agent
    alt MEKARI_AGENT_BASE_URL set
        Mek-->>BE: streamed response
        BE-->>FE: stream
    else missing
        BE-->>FE: 502 "Direct preview unavailable"
    end

    Specialist->>FE: Open FullPreview → Run (saved + no unsaved changes)
    FE->>BE: POST /predict
    BE->>CAI: /predictions
    CAI-->>BE: response
    BE-->>FE: full preview response

    Specialist->>FE: Iterate edits + Save (PUT)
    FE->>BE: PUT /:ai_agent_uuid (with updated_at)
    alt updated_at fresh
        BE->>Mrag: update agent
        Mrag-->>BE: new updated_at
        BE-->>FE: saved
    else updated_at stale (concurrent edit)
        BE-->>FE: conflict
        Note over FE: ConcurrentEditWarning + Reload
    end

    Specialist->>Specialist: Hand agent to customer cid

8.1. System Flow

Flow: Chatbot Specialist creates and ships an Autonomous AI Agent
Type: User Journey + API Sequence

1.  Chatbot Specialist (owner/supervisor/admin on Plus/Ultimate/360 with rollout = ON)
    opens /ai-agent/autonomous; FE route middleware checks BE rollout signal.
2.  System calls GET /api/v3/ai_agents/autonomous scoped to selectedCompanyId → list renders.
3.  Specialist clicks [+ Create]; FE routes to /ai-agent/autonomous/create.
4.  Specialist types a prompt and clicks Draft.
5.  System calls POST /api/v3/ai_agents/autonomous/draft_capability_pack;
    BE proxies to noncore-mrag /draft-skill-pack;
    FE adapter wireCapabilityPackForRuntime maps response to capability_pack;
    editor populates.
    → On failure: inline error + Retry, no partial state.
6.  Specialist edits capability_pack fields in the editor.
7.  Specialist opens AutonomousKnowledgeDrawer; uploads a file OR adds an http(s) URL.
8.  System uploads file to Alicloud OSS via POST /knowledge_base/files (or extracts URL via
    POST /knowledge_base/urls and persists to OSS); KB row appears with status "Pending save".
9.  Specialist clicks Save.
10. System calls POST /api/v3/ai_agents/autonomous; BE proxies to noncore-mrag;
    upstream returns ai_agent_uuid + numeric id (both stable thereafter);
    FE routes to /ai-agent/autonomous/:ai_agent_uuid.
    → On failure: "Save failed, retry"; no orphan agent created.
11. With saved numeric id present, FE auto-triggers POST /knowledge_base/vectors
    for the agent's OSS-backed KB refs.
12. FE polls GET /knowledge_base/vectors/status every 5s; rows transition Indexing → Ready/Failed.
13. Specialist opens AutonomousPreviewRail → DirectPreviewTab → Run.
14. System calls POST /api/v3/ai_agents/autonomous/run via new mekari-agent client; response streams to UI.
    → On failure: 502/504 + Retry.
15. Specialist clicks FullPreviewTab → Run (only enabled when no unsaved changes).
16. System calls POST /api/v3/ai_agents/autonomous/predict via chatbot-ai /predictions;
    full preview response returned.
17. Specialist iterates (steps 6–16) until satisfied; final Save updates upstream agent.
18. Specialist hands the agent to the customer; agent is now live for that cid.
    → Concurrent edit path: if upstream updated_at changed between FE load and Save,
      BE returns conflict; FE shows ConcurrentEditWarning + Reload.

8.2. User Stories

User Story	Importance	Mockup / Technical Notes	Acceptance Criteria
[AAA-S01] — Draft a capability_pack from a natural-language prompt

As a Chatbot Specialist (or Dedicated Bot Builder), I want to type a prompt and have the system draft a starter capability_pack, so that I can iterate on a working baseline instead of authoring everything from scratch. | Must Have | Figma: N/A — refer to Prototype — Create AI Agent

Data Fields: • prompt_text (string, required) — source: User input
• selected_company_id (string, required) — source: FE-local persistence
• capability_pack (object, response) — source: noncore-mrag /draft-skill-pack via BE proxy, mapped by wireCapabilityPackForRuntime

Before-After Behavior: Today no autonomous draft flow exists inside Qontak production stacks — specialists used chatbot-ml-dev prototype outside customer workspace. After this story: drafting happens inside /ai-agent/autonomous/create with V3 proxy, plan + rollout gating, and audit-able auth context. | — Happy Path — • AC-1: Given the Specialist is on /ai-agent/autonomous/create with rollout = ON and a non-empty prompt, when they click Draft, then BE calls POST /api/v3/ai_agents/autonomous/draft_capability_pack and the editor populates with the mapped capability_pack within proxy + upstream latency budget.
• AC-2: Given the draft succeeds, when the editor populates, then the Save button remains disabled until the Specialist completes any required capability fields, AND the selectedCompanyId is carried forward in the editor state.
• AC-3: Given the Specialist clears the prompt and clicks Draft, when prompt is empty, then the Draft button is disabled (no call sent).

— Error / Unhappy Path — • ERR-1: Given a draft call returns INVALID_AUTONOMOUS_PAYLOAD (400), when BE returns the error, then the prompt panel shows the validation reason inline AND no editor state is created, AND event autonomous_draft_capability_pack_failed logged with reason invalid_payload.
• ERR-2: Given a draft call returns AUTONOMOUS_UPSTREAM_TIMEOUT (504), when BE times out, then the panel shows "Drafting timed out. Retry?" + Retry button, AND event autonomous_draft_capability_pack_failed logged with reason upstream_timeout.
• ERR-3: Given a draft call returns AUTONOMOUS_UPSTREAM_ERROR (502), when BE returns the error, then the panel shows "Drafting failed. Retry?" + Retry, AND event logged with reason upstream_error.

— Permission Model — • CAN: owner, supervisor, admin on Plus / Ultimate / 360 with rollout = ON
• CANNOT: all other roles and tiers
• Unauthorized: Route middleware redirects to legacy /ai-agent; if URL is forced, V3 returns 403 INVALID_COMPANY_SCOPE and FE shows "No access" toast.

— UI States — • Loading: Draft button shows spinner; prompt field disabled.
• Empty: Empty prompt panel; Draft disabled.
• Error: Inline error block with reason text + Retry.
• Success: Editor populates with drafted capability_pack fields. | | [AAA-S02] — Add knowledge to an autonomous agent (file or URL) via OSS

As a Chatbot Specialist (or Dedicated Bot Builder), I want to upload a knowledge file or paste a URL and have the system persist it to OSS and vectorise it for the agent, so that the autonomous agent can answer grounded questions from my source material. | Must Have | Figma: N/A — refer to Prototype — Knowledge Drawer

Data Fields: • agent_id (numeric, required after first save) — source: V3 save response
• file (multipart, conditional) — source: User input
• url (string http/https, conditional) — source: User input
• oss_url (string, response) — source: BE→OSS
• vector_status (enum: Pending Indexing Ready Failed) — source: GET status poll (5s)

Before-After Behavior: Today KB ingestion in the prototype calls ML endpoints directly with raw files/URLs, violating Qontak's OSS-first invariant. After: BE routes every file/URL through Alicloud OSS first, then sends OSS-backed refs to vectorisation; status polled every 5s. | — Happy Path — • AC-1: Given the Specialist is on Create or Config with a saved agent (numeric id present), when they upload a supported file in AutonomousKnowledgeDrawer, then BE calls POST /knowledge_base/files, the file is persisted to Alicloud OSS, an OSS-backed URL is passed to upstream KB, and the row appears with status Indexing.
• AC-2: Given the Specialist pastes an http(s) URL, when they click Add, then BE calls POST /knowledge_base/urls, content is extracted server-side, persisted to OSS, and the URL row appears with status Indexing.
• AC-3: Given a KB row is Indexing, when 5 seconds elapse, then FE calls GET /knowledge_base/vectors/status and updates the row to Ready or Failed based on response.
• AC-4: Given the agent has not been saved yet (no numeric id), when the Specialist attempts to trigger vectorisation, then FE blocks the call and surfaces "Save the agent before indexing knowledge."
• AC-5: Given an inherited agent-level file, when capability-scoped vectorisation runs, then the agent-level vector store is reused; given a capability-specific file, when vectorisation runs, then it does not reuse the agent-level store.

— Error / Unhappy Path — • ERR-1: Given the OSS upload fails, when BE returns an error, then the row shows "Upload failed" + Retry, AND event autonomous_kb_upload_failed logged with reason oss_upload_failed.
• ERR-2: Given OSS upload succeeds but upstream KB record creation fails, when BE returns the error, then the row is marked Failed with Retry, AND no orphan vector record is created upstream.
• ERR-3: Given the URL scheme is not http/https, when the Specialist clicks Add, then FE rejects client-side AND BE returns INVALID_AUTONOMOUS_PAYLOAD if forced.
• ERR-4: Given vectorisation status polling returns a transient error, when polling fails, then the row keeps its last known status and the error is logged silently; UI does not flash error state on transient failures.

— Permission Model — • CAN (add KB row): owner, supervisor, admin on Plus / Ultimate / 360 with rollout = ON
• CAN (remove KB row): same roles — KB row deletion supported in Phase 1 via a remove action on each row in AutonomousKnowledgeDrawer (Failed and Ready rows both removable; Indexing rows disabled from delete until terminal state). Removing a KB row also removes its OSS object and revokes the upstream vector reference.
• CANNOT: editing the contents of an already-uploaded file or already-extracted URL — to "edit" a KB item the user removes the row and re-adds. This is an intentional Phase-1 constraint, not deferred.
• CANNOT: all other roles, tiers, or rollout = OFF.
• Unauthorized: Drawer not rendered; V3 KB endpoints return 403 INVALID_COMPANY_SCOPE.

— Additional AC for reversibility — • AC-6 (delete KB row): Given a KB row is in Ready or Failed status, when the user clicks remove and confirms, then BE calls DELETE /api/v3/ai_agents/autonomous/knowledge_base/files/:id (or /urls/:id), the OSS object is cleaned up, the upstream vector reference is revoked, and the row disappears from the drawer.
• AC-7 (delete blocked during indexing): Given a KB row is in Indexing, when the user attempts to remove it, then the remove action is disabled with tooltip "Wait for indexing to complete before removing."

— UI States — • Loading: Upload row shows progress; URL field shows spinner during extraction; remove action shows spinner during DELETE call.
• Empty: "No knowledge added yet." + helper text in drawer.
• Error: Per-row error pill with reason + Retry; failed remove shows toast "Could not remove, try again."
• Success: Row shows Ready status with last-updated timestamp; removed rows disappear with toast "Removed". | | [AAA-S03] — Save autonomous agent (first save + update with concurrent-edit handling)

As a Chatbot Specialist (or Dedicated Bot Builder), I want to save the agent so it persists upstream with a stable identifier, and have the system warn me if someone else has edited it, so that I do not silently overwrite another editor's changes. | Must Have | Figma: N/A — refer to Prototype — Save flow

Data Fields: • capability_pack (object, required) — source: editor state
• ai_agent_uuid (string, response on first save) — source: upstream
• id (numeric, response on first save) — source: upstream
• updated_at (timestamp) — source: upstream; used for concurrent-edit detection

Before-After Behavior: Today the prototype has no production save path and no concurrent-edit detection — last-write-wins silently. After: first save calls V3 POST and returns stable ai_agent_uuid + numeric id; subsequent saves compare updated_at; mismatch surfaces a ConcurrentEditWarning before overwrite. | — Happy Path — • AC-1: Given the Specialist is on Create with a complete capability_pack, when they click Save, then BE calls POST /api/v3/ai_agents/autonomous and the response includes both ai_agent_uuid and numeric id, AND FE routes to /ai-agent/autonomous/:ai_agent_uuid.
• AC-2: Given the agent is saved, when the Specialist edits the capability_pack and clicks Save again, then BE calls PUT /api/v3/ai_agents/autonomous/:ai_agent_uuid with the full pack and the current updated_at, AND upstream returns a new updated_at.
• AC-3: Given ai_agent_uuid was issued on first save, when the agent is later updated, then ai_agent_uuid remains stable AND the numeric id is preserved.

— Error / Unhappy Path — • ERR-1: Given the FE-loaded updated_at is older than the upstream updated_at at save time, when BE returns a conflict, then FE shows ConcurrentEditWarning ("Another editor changed this agent. Reload to see latest before saving.") + Reload button AND the editor is not overwritten until Reload is clicked.
• ERR-2: Given the save call fails with AUTONOMOUS_UPSTREAM_ERROR (502) or timeout, when BE returns the error, then the editor state is preserved, save button re-enables, and toast shows "Save failed, retry."
• ERR-3: Given a hard refresh or deep-link before first save, when the FE-local draft is volatile, then the user is redirected to /ai-agent/autonomous/create (no orphan saved upstream).

— Permission Model — • CAN (create + edit/update an autonomous agent): owner, supervisor, admin on Plus / Ultimate / 360 with rollout = ON. Edits go through PUT with updated_at concurrent-edit detection.
• CANNOT (delete a saved autonomous agent in Phase 1): Phase 1 does NOT ship a delete or archive control. DeleteAgentControl in the Config Page component tree is intentionally not implemented; the placeholder exists for Phase 2 wiring only. Customers who need to retire an agent file a request to Hadiningbot Squad in Phase 1. Soft delete / archive is planned for Phase 2 (see Open Q-6).
• CANNOT: all other roles, tiers, or rollout = OFF.
• Unauthorized: Save button not rendered; V3 save endpoints return 403 INVALID_COMPANY_SCOPE.

— Additional AC for reversibility constraint — • AC-4 (no delete in Phase 1): Given any role on any tier, when the user inspects the Config Page, then no delete or archive control is rendered AND no V3 DELETE endpoint exists for /api/v3/ai_agents/autonomous/:ai_agent_uuid in Phase 1. Attempting DELETE against that path returns 404 (route not mounted).
• AC-5 (manual retire path documented): Given a customer needs an agent retired, when they request it, then the Hadiningbot Squad runbook (TBD link, tracked Q-6) describes the upstream delete path via noncore-mrag Ops tooling.

— UI States — • Loading: Save bar spinner; editor read-only while in flight.
• Empty: Save disabled when capability_pack incomplete.
• Error: Toast + persistent inline ConcurrentEditWarning when applicable.
• Success: Toast "Agent saved" + route change to detail page on first save. | | [AAA-S04] — Preview the autonomous agent (direct via mekari-agent, full via chatbot-ai)

As a Chatbot Specialist (or Dedicated Bot Builder), I want to run a direct preview while editing and a full preview against the saved state, so that I can validate the agent's behavior before handing it to the customer. | Should Have (reclassified from Must Have at v1.2 — agent can be saved without preview; direct preview already degrades gracefully if MEKARI_AGENT_BASE_URL missing; full preview adds value but is not strictly required to ship the 15-cid target. If we miss this in Phase 1, customers can still validate via legacy preview tooling outside the autonomous flow.) | Figma: N/A — refer to Prototype — Preview Rail. Reuses interaction rhythm (not components) from chatbot-fe/modules/conversation/views/tree-diagram/diagram-preview-chat.vue.

Data Fields: • capability_pack (object) — source: editor state (direct) OR last saved state (full)
• preview_input (string, required) — source: User input in preview rail
• preview_response (stream/object, response) — source: mekari-agent OR chatbot-ai

Before-After Behavior: Today the prototype calls upstream preview endpoints directly with no auth context, no plan gating, no audit. After: BE proxies both preview channels with auth + rollout enforcement; full preview is locked to saved state with an unsaved-changes warning. | — Happy Path — • AC-1: Given the Specialist is in DirectPreviewTab with a valid capability_pack in the editor, when they enter input and click Run, then BE calls POST /api/v3/ai_agents/autonomous/run via the new lib/mekari_agent/autonomous_ai_agent.rb client, AND the response streams into the preview rail.
• AC-2: Given the Specialist is in FullPreviewTab on a saved agent with no unsaved changes, when they enter input and click Run, then BE calls POST /api/v3/ai_agents/autonomous/predict against chatbot-ai /predictions, AND the response is returned based on the saved state.
• AC-3: Given the Specialist has unsaved changes in the editor, when they open FullPreviewTab, then a warning is shown ("Full preview reflects saved state only. Save first to test latest changes.") AND the Run button is enabled but the warning persists until the user saves or dismisses.

— Error / Unhappy Path — • ERR-1: Given MEKARI_AGENT_BASE_URL is not configured on BE, when DirectPreview Run is triggered, then BE returns 502, FE shows "Direct preview unavailable" + helper text, AND event autonomous_direct_preview_unavailable logged with reason mekari_agent_base_url_missing.
• ERR-2: Given a preview call returns AUTONOMOUS_UPSTREAM_TIMEOUT (504), when BE times out, then preview rail shows "Preview timed out, retry?" + Retry.
• ERR-3: Given a preview call returns AUTONOMOUS_UPSTREAM_ERROR (502), when BE returns the error, then preview rail shows "Preview failed, retry?" + Retry.

— Permission Model — • CAN: same as AAA-S01
• CANNOT: same as AAA-S01
• Unauthorized: Preview rail not rendered; V3 preview endpoints return 403 INVALID_COMPANY_SCOPE.

— UI States — • Loading: Per-tab spinner; Run button disabled.
• Empty: "Enter a message to preview." in transcript area.
• Error: Inline error block with reason + Retry; transcript preserved.
• Success: Streamed response (direct) OR full response (full) appended to transcript. | | [AAA-S05] — Plan / tier and rollout gating for Autonomous AI Agent access

As a Workspace Admin (owner / supervisor / admin), I want to only see the Autonomous AI Agent flow when my workspace is on Plus / Ultimate / 360 AND the autonomous_ai_agent rollout is ON for my workspace, so that the feature stays dark for accounts not entitled or not in the rollout cohort. | Must Have | Figma: N/A — gating is logic + nav, not visual

Data Fields: • rollout.autonomous_ai_agent (boolean) — source: BE system_preferences • workspace_plan (enum: Plus / Ultimate / 360 / other) — source: account context
• role (enum: owner / supervisor / admin / other) — source: auth session

Before-After Behavior: Today the prototype has no plan/role gating — anyone with the URL can use it. After: BE enforces plan + role + rollout at the V3 endpoint layer (403 INVALID_COMPANY_SCOPE on violation); FE route middleware + nav visibility derive from BE rollout signal. | — Happy Path — • AC-1: Given a workspace is on Plus, Ultimate, or 360 AND rollout.autonomous_ai_agent = ON AND the user role is owner / supervisor / admin, when they sign in, then the "Autonomous AI Agent" nav entry is visible AND /ai-agent/autonomous is reachable.
• AC-2: Given the workspace is rolled out, when any V3 /api/v3/ai_agents/autonomous* endpoint is called with a valid session and matching role + plan, then the request is processed normally.

— Error / Unhappy Path — • ERR-1: Given a workspace is NOT on Plus / Ultimate / 360, when the user attempts to visit /ai-agent/autonomous, then FE route middleware redirects to legacy /ai-agent (no error toast for tiers that simply don't have the feature) AND any V3 call returns 403 INVALID_COMPANY_SCOPE.
• ERR-2: Given rollout.autonomous_ai_agent = OFF for the workspace, when the user attempts to visit the route, then FE redirects to legacy /ai-agent AND V3 endpoints return 403 INVALID_COMPANY_SCOPE.
• ERR-3: Given the role is not owner / supervisor / admin, when access is attempted, then nav entry is hidden AND V3 calls return 403 INVALID_COMPANY_SCOPE.
• ERR-4: Given BE is rolled back (rollout = OFF) while FE flag is still ON, when the user visits the route, then FE shows graceful "Feature temporarily unavailable" toast and redirects to legacy /ai-agent. (Operationally the FE flag must be disabled before BE rollback per RFC §7.)

— Permission Model — • CAN: owner / supervisor / admin on Plus / Ultimate / 360 with rollout = ON
• CANNOT: all other roles, plans, or rollout = OFF
• Unauthorized: Nav hidden + route middleware redirect; V3 returns 403 INVALID_COMPANY_SCOPE.

— UI States — • Loading: Brief route-resolution spinner before redirect / render.
• Empty: N/A.
• Error: Optional toast for "temporarily unavailable" rollback scenario.
• Success: Nav entry visible; route renders normally. |

---

Additional stories (v1.3 — from Vercel prototype walkthrough 2026-05-22)

The Vercel prototype walk surfaced five additional first-class flows not captured in v1.0–v1.2. Stories below follow the same structure as AAA-S01–S05.

---

[AAA-S06] — Configure Agent Behavior (name, description, tone, language, guidance, guardrails) · Must Have

As a Chatbot Specialist (or Dedicated Bot Builder), I want to define how the agent talks and behaves — its tone of voice, language, what to do, and what to avoid — so that the agent responds to customers in a way that matches our brand and stays within safe limits.

Mockup / Technical Notes: Refer to Prototype — Behavior tab (default tab on Config page).

• Data Fields: agent_name (string, required) · response_description (text) · goals_and_behavior (text, required) · tone (enum: casual / professional / friendly / direct) · language (enum) · guidance[] (array of {name, description}) · guardrails[] (array of {name, description}) · advanced_settings (object — model, response shaping, timing, memory).
• Before-After: The prototype today exposes these fields without auth/audit/rollout gating. After: same field model is rendered in production chatbot-fe under /bot-automation/ai-agent/:slug Behavior tab; saved via V3 PUT with updated_at concurrency.

Happy Path

• AC-1: Given Specialist on Behavior tab with a valid agent, when they update any field (name, tone, language, guidance, guardrail, advanced setting), then UnsavedChangesBanner appears AND Save button enables.
• AC-2: Given Specialist clicks Save with no concurrent-edit conflict, then BE calls PUT /api/v3/ai_agents/autonomous/:ai_agent_uuid with the full Behavior block + current updated_at, AND upstream returns new updated_at, AND UnsavedChangesBanner clears.
• AC-3: Given Specialist clicks [+ Add guidance], when the modal/inline editor opens, then user enters guidance name + description, AND saving appends a new GuidanceRow at the end of the list AND triggers the same UnsavedChanges state.
• AC-4: Given Specialist clicks [+ Add guardrail], when the inline editor opens, then user enters guardrail name + description, AND saving appends a new GuardrailRow at the end of the list.
• AC-5: Given Specialist removes a guidance or guardrail row, when the remove control is clicked, then the row is removed from the list AND UnsavedChanges state triggers (delete is not persisted until Save).

Error / Unhappy Path

• ERR-1: Given Save returns 409 concurrent-edit conflict, then ConcurrentEditWarning shows ("Another editor changed this agent. Reload to see latest before saving.") + Reload button, editor not overwritten.
• ERR-2: Given the agent_name field is blank on Save, then inline validation shows "Name is required" AND BE call is not made.
• ERR-3: Given upstream returns 502/504 on Save, then editor state is preserved, Save re-enables, toast "Save failed, retry."

Permission Model

• CAN: owner, supervisor, admin on Plus / Ultimate / 360 with rollout = ON.
• CANNOT: all other roles, tiers, rollout = OFF.
• Unauthorized: Behavior tab not rendered (route guarded); V3 PUT returns 403 INVALID_COMPANY_SCOPE if forced.

UI States

• Loading: Skeleton fields during V3 detail fetch · Empty: N/A (form always renders) · Error: Inline field errors + global toast for 502/504 · Success: Save button disabled (no unsaved changes); toast "Agent saved".

---

[AAA-S07] — Configure Agent Capabilities (triggers, milestones, instructions, sources, success criteria) · Must Have

As a Chatbot Specialist (or Dedicated Bot Builder), I want to define each capability the agent can handle — what triggers it, what knowledge and actions it draws on, and when it considers itself done — so that the agent only acts within scoped intents and uses the right resources for each intent.

Mockup / Technical Notes: Refer to Prototype — Capabilities tab (click the Capabilities tab).

• Data Fields per capability: capability_id · name · description · triggers[] (array of phrase strings, e.g. "I want a refund") · milestones[] (array of token strings, e.g. refund_initiated) · instructions (text) · linked_knowledge_ids[] (array of Resource IDs) · linked_action_ids[] (array of Action IDs) · completes_when (text) · active (bool).
• Before-After: Prototype today persists capabilities only inside the prototype's local store. After: capabilities are part of the agent's capability_pack and saved via V3 PUT; references to KnowledgeIds + ActionIds are validated against shared Resources + Actions modules.

Happy Path

• AC-1: Given Specialist on Capabilities tab with a valid agent, when they click [+ Add capability], then a new empty CapabilityCard appears in edit mode with required fields highlighted.
• AC-2: Given Specialist fills capability name + description + at least 1 trigger + instructions + at least 1 success criterion AND clicks Save (page-level), then BE calls PUT /api/v3/ai_agents/autonomous/:ai_agent_uuid with the updated capability_pack including the new capability, AND upstream returns new updated_at.
• AC-3: Given Specialist adds trigger phrases via the chip input, when they hit Enter or click [+], then each phrase is added as a chip below the input AND duplicates are silently deduplicated.
• AC-4: Given Specialist links a Knowledge source via the SourcesUsedBlock → KNOWLEDGE picker, when they pick a Resource (e.g. "How to refund"), then it is appended to linked_knowledge_ids[] AND appears in the Sources Used list with its name.
• AC-5: Given Specialist links an Action via SourcesUsedBlock → ACTIONS picker, when they pick an Action (e.g. "Create ticket"), then it is appended to linked_action_ids[] AND appears in the Sources Used list.
• AC-6: Given Specialist toggles a CapabilityCard's active toggle off, when they Save, then upstream marks the capability as Inactive AND the runtime engine excludes it from intent matching.
• AC-7: Given Specialist clicks Remove on a CapabilityCard, when they confirm, then the capability is removed from the local editor AND on Save the capability is removed upstream.

Error / Unhappy Path

• ERR-1: Given a linked Resource referenced in linked_knowledge_ids[] has been deleted from the Resources module since the editor was loaded, when Save fires, then BE returns 409 with the orphaned reference IDs, AND FE highlights the affected CapabilityCard with "Linked Knowledge no longer exists, remove and retry."
• ERR-2: Given a CapabilityCard has zero triggers when Save fires, then inline validation blocks save: "At least one trigger phrase is required."
• ERR-3: Given a CapabilityCard has zero linked knowledge AND zero linked actions AND no instructions, then a soft warning banner appears on the card ("This capability may not respond accurately") — does not block Save.
• ERR-4: Given Save returns concurrent-edit 409, then ConcurrentEditWarning + Reload (same pattern as AAA-S03 / S06).

Permission Model

• CAN: same as AAA-S06.
• CANNOT: editing capability_id once issued (it is stable across renames) — name/description editable, ID immutable.
• CANNOT: all other roles.
• Unauthorized: Capabilities tab not rendered.

UI States

• Loading: Skeleton CapabilityCards during fetch · Empty: "No capabilities yet." + [+ Add capability] CTA · Error: per-card error pill for orphaned-reference 409 · Success: editor populated; cards collapsed except the one being edited.

---

[AAA-S08] — Configure Agent Routing (rule engine for handoff, clarification, switching) · Must Have

As a Chatbot Specialist (or Dedicated Bot Builder), I want to define rules for what the agent does when it can't or shouldn't continue — hand off to a human, ask clarification, resolve, switch capability/action — so that customers reach the right outcome when the autonomous flow hits an edge.

Mockup / Technical Notes: Refer to Prototype — Routing tab (click the Routing tab).

• Data Fields per rule: rule_id · when_condition (enum: when_user, when_action_error) · when_input (string, used when condition needs a phrase, e.g. "Customer says talk to a human") · then_action (enum: handover, clarification, resolve, switch_capability, switch_action) · handoff_agent_group_id (string, required when then_action = handover; values: any / div-sales / div-support / ...).
• Before-After: Prototype today lets users add/edit rules but does not actually route handoffs. After: rules are persisted on the agent record AND the runtime engine evaluates them; handover rules are wired to the Inbox routing API (see Dependency D11).

Happy Path

• AC-1: Given Specialist on Routing tab with a valid agent, when they click [+ Add rule], then a new empty RoutingRuleRow appears.
• AC-2: Given Specialist selects When user says + types a phrase + selects Hand off to human agent + picks Sales division AND clicks Save, then BE calls PUT with the rules array, AND upstream stores the rule, AND the rule is active at runtime.
• AC-3: Given a runtime conversation matches a when_user rule (e.g. customer types "talk to a human"), when the rule fires, then the autonomous engine emits a handoff event AND BE relays to Inbox routing API which assigns the conversation to the configured handoff_agent_group_id, AND the conversation transitions to human-handled state.
• AC-4: Given a runtime action call fails (e.g. Create ticket returns error), when a when_action_error rule with then_action = clarification exists, then the engine asks the customer to clarify (instead of handing off blindly).
• AC-5: Given Specialist removes a rule, when they click Remove rule on a row, then row is removed from editor AND on Save the rule is removed upstream.

Error / Unhappy Path

• ERR-1: Given a handover rule's handoff_agent_group_id references a group that has been deleted from Inbox routing config since the editor was loaded, when Save fires, then BE returns 422 with the invalid IDs AND FE highlights the affected rule with "Agent group no longer exists, pick a different one."
• ERR-2: Given a rule has then_action = handover but no handoff_agent_group_id selected, then inline validation blocks Save: "Pick an agent group for the handoff."
• ERR-3 (runtime): Given a handover rule fires but the Inbox routing API is unavailable, when the engine attempts handoff, then it falls back to Ask clarification behaviour AND emits autonomous_handoff_fallback event so on-call can investigate (RFC §10 stop condition).
• ERR-4: Given Save returns 409 concurrent-edit, then ConcurrentEditWarning + Reload.

Permission Model

• CAN: same as AAA-S06.
• CANNOT: all other roles.
• Unauthorized: Routing tab not rendered.

UI States

• Loading: Skeleton rule rows · Empty: "No routing rules yet." + [+ Add rule] CTA · Error: per-rule inline error pills · Success: rule list populated; no unsaved-changes banner.

---

[AAA-S09] — Manage shared Resources (Knowledge Base) — add, list, edit, delete, async URL scan · Must Have

As a Chatbot Specialist (or Dedicated Bot Builder), I want a single shared library of knowledge sources I can reuse across multiple autonomous agents and capabilities, so that I don't have to re-upload the same documents for every agent and so customers get consistent answers.

Mockup / Technical Notes: Refer to Prototype — Resources.

• Data Fields per Resource: resource_id · name · type (enum: external_url, file_upload, ocr_file, text_content, conversation_history) · status (enum: scanning / indexing / active / inactive / failed) · oss_url (where applicable) · created_at · updated_at.
• Before-After: Prototype today exposes the Resources module as a UI without production persistence. After: Resources are stored upstream (via noncore-mrag KB endpoints) with OSS-backed content + workspace scoping + auth.

Happy Path

• AC-1: Given Specialist opens /bot-automation/resources, then BE calls GET list (scoped to workspace), summary cards show per-type counts, table renders paginated rows with name + type + status + last_updated.
• AC-2: Given Specialist clicks [Add source] → [Add External URL] + pastes a public URL + clicks Scan URL, then BE validates http(s) scheme, creates Resource with status=scanning, returns immediately, AND FE polls /resources/:id/status every 30s until active (max ~15 min) or failed.
• AC-3: Given Specialist clicks [Add source] → [Add File upload] + selects a PDF or image file, then BE multiparts to Alicloud OSS first, then upstream KB record creation, then vectorisation; row appears with status=indexing then transitions to active.
• AC-4: Given Specialist clicks [Add source] → [Add Text content] + enters name + body, then BE persists text to OSS, creates KB record, vectorises; row appears with status=indexing then active.
• AC-5: Given Specialist clicks [Add source] → [Add Conversation history] + selects past Inbox conversations to learn from, then BE proxies to upstream conversation-learn endpoint, row appears status=ingesting then active.
• AC-6: Given Specialist filters by type (Link / File / OCR file / Document) or searches by name, then the table updates with filtered/searched results client-side over the fetched page.
• AC-7: Given Specialist clicks row Actions → Toggle Active, then BE proxies PATCH, upstream marks the source available/unavailable to capabilities, row status toggles.
• AC-8: Given Specialist clicks row Actions → Delete + confirms, then BE proxies DELETE, OSS object removed, upstream vector reference revoked, AND all Capability links to this source are stripped silently (with audit log).

Error / Unhappy Path

• ERR-1: Given the External URL scheme is not http(s), then FE rejects client-side AND BE returns INVALID_AUTONOMOUS_PAYLOAD if forced.
• ERR-2: Given URL extraction takes longer than 15 minutes, then the Resource transitions to failed with reason scan_timeout, AND a Retry option appears on the row.
• ERR-3: Given OSS upload fails, then row shows "Upload failed" + Retry, event autonomous_resource_add_failed logged with reason oss_upload_failed.
• ERR-4: Given OSS upload succeeds but upstream KB creation fails, then row marked failed, no orphan vector created, Retry available.
• ERR-5: Given Toggle conflicts with an in-flight scan (status is scanning or indexing), then BE returns 409 + "Wait for scan to finish."
• ERR-6: Given Delete is attempted while status = scanning or indexing, then BE returns 409 + "Cannot delete while scanning."
• ERR-7: Given a Resource is currently linked to an active Capability AND user attempts Delete, then BE returns 409 with link count + "In use by N capabilities — remove from those first OR confirm cascade-strip."

Permission Model

• CAN: same as AAA-S06 (owner / supervisor / admin on entitled tiers with rollout = ON).
• CANNOT: all other roles, tiers, rollout = OFF.
• Unauthorized: Resources nav entry hidden; V3 Resources endpoints return 403 INVALID_COMPANY_SCOPE.

UI States

• Loading: Skeleton summary cards + skeleton table during list fetch · Empty: "No resources yet." + [Add source] CTA · Error: list error block + Retry · Success: cards populated + table populated. Per-row: scanning / indexing shows progress spinner; failed shows red pill + Retry; active / inactive show neutral pills.

---

[AAA-S10] — Manage shared Actions (integration catalog) — add from catalog, list, edit, delete · Must Have

As a Chatbot Specialist (or Dedicated Bot Builder), I want to maintain a shared catalog of integration actions (CRM, calendar, ERP, custom API) the agent can call as part of a capability, so that I configure each integration once and reuse it across multiple agents and capabilities.

Mockup / Technical Notes: Refer to Prototype — Actions. Add Action drawer exposes a categorised picker (Mekari Qontak / Talenta / Jurnal / Desty / Other integration).

• Data Fields per Action: action_id · name · description · action_type (enum: qontak, talenta, jurnal, desty, google_calendar, google_sheets, api_integration, get_nearest_location) · provider_config (object — provider-specific fields) · status (enum: active / inactive) · linked_capability_count (computed).
• Before-After: Prototype lists actions without production persistence or per-provider config validation. After: Actions are stored upstream, validated against required connectors (e.g. Google Calendar requires the workspace's Google Calendar integration to be connected), and surfaced in Capability's SourcesUsedBlock ACTIONS list.

Happy Path

• AC-1: Given Specialist opens /bot-automation/actions, then BE proxies list call, FE renders filtered/searched table with name + action_type + status + last_updated.
• AC-2: Given Specialist clicks [Add action] + picks a built-in from a Mekari category (e.g. Create ticket under Mekari Qontak), then a config drawer opens with provider-specific fields pre-filled, user completes optional config + clicks Save, BE creates Action record with status=active.
• AC-3: Given Specialist picks a 3rd-party integration (e.g. Google Calendar → Book appointment), when the required connector is already connected for the workspace, then the action is configured with the connected account.
• AC-4: Given Specialist filters by status (All / Active / Inactive) or searches by name, then the table updates with filtered/searched results.
• AC-5: Given Specialist clicks row Actions → Toggle Active, then BE proxies PATCH; upstream marks the action available/unavailable to capabilities; row status toggles.
• AC-6: Given Specialist clicks row Actions → Delete + confirms, AND the action is NOT referenced by any active Capability, then BE proxies DELETE and row disappears.

Error / Unhappy Path

• ERR-1: Given the integration requires a connector that is not connected (e.g. Google Calendar not connected), when the user opens the Add action config drawer, then a banner shows "Google Calendar is not connected. Connect it in workspace integrations first." + deep-link to integrations settings; Save is disabled.
• ERR-2: Given Save returns validation error on provider_config (e.g. missing required field), then inline error per field; Save re-enables after user fixes.
• ERR-3: Given Delete is attempted AND the Action is referenced by ≥1 active Capability, then BE returns 409 with the linked capability count + names + "In use by N capabilities — remove from those first."
• ERR-4: Given upstream catalog endpoint times out, then [Add action] drawer shows "Could not load action catalog, retry."

Permission Model

• CAN: same as AAA-S06.
• CANNOT: all other roles.
• Unauthorized: Actions nav entry hidden; V3 Actions endpoints return 403 INVALID_COMPANY_SCOPE.

UI States

• Loading: Skeleton table rows · Empty: "No actions yet." + [Add action] CTA · Error: list error block + Retry · Success: populated table. Per-row: active / inactive toggle visible.

---

Negative Scenarios (from Section 4 Non-Goals)

NEG-1: Given a workspace on a tier other than Plus / Ultimate / 360,
       when the user attempts to access /ai-agent/autonomous,
       Then route middleware redirects to /ai-agent (legacy modal),
       And V3 endpoints return 403 INVALID_COMPANY_SCOPE.

NEG-2: Given a user navigates to the legacy /ai-agent modal,
       when they create or edit a legacy AI Agent,
       Then existing behavior is unchanged (Redis sessions, local Rails tables,
       FrontendService::V1 endpoints), and the autonomous engine is never invoked.

NEG-3: Given a Chatbot Specialist requests CSV batch test-runner functionality
       (Phase 2 deferred scope),
       when they attempt to upload a batch CSV in Phase 1,
       Then no CSV upload UI is rendered and no batch endpoint exists.

NEG-4: Given a Specialist attempts to call /test/improvise or /test/judge
       (Phase 2 deferred endpoints),
       when the call is made,
       Then BE returns 404 (endpoint not mounted in V3 namespace in Phase 1).

NEG-5: Given a knowledge URL with a scheme other than http or https,
       when the Specialist attempts to add it,
       Then FE rejects client-side and BE returns
       INVALID_AUTONOMOUS_PAYLOAD if forced.

NEG-6: Given two Specialists edit the same autonomous agent simultaneously,
       when both attempt to save,
       Then last write wins on second save, and the second saver is shown a
       ConcurrentEditWarning before their save overwrites (Phase 1 does not
       implement merge or lock).

NEG-7: Given the user attempts to use the Autonomous AI Agent on the Qontak
       Mobile app,
       when they open the mobile app,
       Then no Autonomous AI Agent entry is rendered (web-only in Phase 1).

9. Rollout

Feature flag:    autonomous_ai_agent (see Section 5 — default OFF)
                 Source of truth: BE rollout code in system_preferences group.
                 FE consumes BE rollout signal for route middleware + nav visibility.

Deploy order:    1. BE (V3 endpoints live but dark while rollout = OFF)
                 2. FE (route + nav code shipped but hidden until rollout flips ON)
                 3. Rollout exposure (flip rollout flag per workspace)

Rollout:         Stage 1 → Internal QA accounts only (Hadiningbot Squad accounts, ~3 workspaces)
                 Stage 2 → Pilot — 3 Chatbot Specialist-led internal workspaces used to build
                           agents for the first 3 customer cids of the 15-agent target
                 Stage 3 → Controlled GA — up to 15 cid on Plus / Ultimate / 360 (target cohort)
                 GA      → All workspaces on Plus / Ultimate / 360 with rollout flipped ON
                           on request

Cross-layer compatibility matrix (from RFC §7):
| Scenario           | FE  | BE  | Works?                              |
| Pre-deploy         | Old | Old | yes                                 |
| Backend first      | Old | New | yes (V3 endpoints dark)             |
| Frontend first     | New | Old | NO — keep FE flag off until BE live |
| Both               | New | New | yes (target)                        |
| BE rollback        | New | Old | NO — disable FE flag before rollback|
| FE rollback        | Old | New | yes                                 |

Rollback recipe: (1) disable FE navigation/middleware → (2) disable BE rollout code →
                 (3) FE code rollback if needed → (4) BE code rollback if needed →
                 (5) re-run legacy /ai-agent smoke tests.

Backward compat: Yes — legacy /ai-agent modal, V1 endpoints, Redis sessions, and local
                 ai_agents / ai_agent_actions / ai_agent_knowledges tables remain unchanged.

Migration:       None required — Phase 1 is proxy-only, no new Rails DDL, no migration of
                 legacy AI Agents into the autonomous engine.

Required envs:   MEKARI_AGENT_BASE_URL (required for direct preview — feature degrades
                 gracefully with 502 + "Direct preview unavailable" if missing)
                 MEKARI_AGENT_SERVICE_TOKEN (required if upstream needs it)

9.4. Migration Transition Window

Applicability:        No data migration is performed in Phase 1 (no Rails DDL, no legacy →
                      autonomous data migration). The "transition window" applies only to
                      product coexistence: autonomous agents (new) and legacy agents (old)
                      live side-by-side indefinitely in Phase 1.

Old record behavior:  Legacy /ai-agent modal continues to work unchanged. Customers and
                      Specialists can keep using V1 AI Agents created against the legacy
                      engine. No automatic conversion to autonomous.

New record behavior:  Autonomous AI Agents created in /ai-agent/autonomous are stored
                      upstream only (noncore-mrag). They do NOT appear in the legacy modal
                      list and do NOT use V1 endpoints.

Coexistence period:   Indefinite within Phase 1. No automated migration is planned for Phase 2;
                      explicit migration tool is itself out of scope.

End state:            Phase 1 end state = both products live concurrently. Phase 2+ scope
                      (CSV batch, improvise/judge, potential admin tooling) does not include
                      retiring or migrating legacy agents.

User communication:   In-product copy on the legacy modal SHOULD reference the new
                      autonomous flow for relevant tiers (Plus / Ultimate / 360 with rollout =
                      ON). Specific copy is TBD — tracked as Open Question Q-2 in S15.

10. Observability

Key Events:

Event Name	Trigger	Properties
autonomous_route_visited	User lands on /ai-agent/autonomous* route	workspace_id, user_id, role, plan, rollout_state, route, timestamp
autonomous_draft_capability_pack_succeeded	Draft call returns 2xx	workspace_id, user_id, prompt_length, draft_latency_ms, timestamp
autonomous_draft_capability_pack_failed	Draft call returns 4xx/5xx	workspace_id, user_id, reason (invalid_payload / upstream_timeout / upstream_error), timestamp
autonomous_agent_saved	First save (POST) returns 2xx	workspace_id, user_id, ai_agent_uuid, id, latency_ms, timestamp
autonomous_agent_updated	Subsequent save (PUT) returns 2xx	workspace_id, user_id, ai_agent_uuid, latency_ms, concurrent_conflict (bool), timestamp
autonomous_kb_upload_succeeded	File or URL ingested to OSS + upstream KB record created	workspace_id, ai_agent_uuid, source_type (file/url), oss_persisted (bool), timestamp
autonomous_kb_upload_failed	OSS upload OR upstream KB record creation failed	workspace_id, ai_agent_uuid, reason (oss_upload_failed / upstream_kb_failed / invalid_scheme), timestamp
autonomous_kb_vector_status_changed	Vectorisation status transition (Indexing → Ready/Failed)	workspace_id, ai_agent_uuid, capability_id (nullable), final_status, polling_attempts, timestamp
autonomous_direct_preview_invoked	DirectPreview Run	workspace_id, ai_agent_uuid, latency_ms, succeeded (bool), reason_if_failed, timestamp
autonomous_full_preview_invoked	FullPreview Run	workspace_id, ai_agent_uuid, latency_ms, succeeded (bool), reason_if_failed, unsaved_changes_warning_shown (bool), timestamp
autonomous_resource_added	Resource (any of 4 source types) successfully created	workspace_id, resource_id, type (external_url/file_upload/ocr_file/text_content/conversation_history), final_status (active/failed), scan_duration_ms_if_url, timestamp
autonomous_resource_add_failed	Resource creation failed	workspace_id, type, reason (invalid_payload/oss_upload_failed/scan_timeout/upstream_kb_failed/extraction_failed), timestamp
autonomous_action_configured	Action successfully added to catalog	workspace_id, action_id, action_type, provider_required_connector (bool), timestamp
autonomous_capability_saved	Capability added or edited on an agent	workspace_id, ai_agent_uuid, capability_id, trigger_count, linked_knowledge_count, linked_action_count, has_milestones (bool), timestamp
autonomous_routing_rule_saved	Routing rule added or edited on an agent	workspace_id, ai_agent_uuid, rule_id, when_condition, then_action, handoff_agent_group_id (nullable), timestamp
autonomous_handoff_invoked	Routing Hand off to human agent rule fires at runtime	workspace_id, ai_agent_uuid, conversation_id, rule_id, handoff_agent_group_id, succeeded (bool), timestamp
autonomous_handoff_fallback	Handoff failed; engine fell back to Ask clarification	workspace_id, ai_agent_uuid, conversation_id, rule_id, reason (inbox_routing_unavailable/agent_group_invalid/etc), timestamp

Dashboard owner: Hadiningbot Squad (PM: Dimas Fauzi Hidayat / Eng Lead: Eko Aprianto)

Alerts:
- BE p95 latency on /api/v3/ai_agents/autonomous list or detail > 800 ms over 15 min
  → Slack #qontak-chatbot-oncall + PagerDuty: Hadiningbot on-call
- autonomous_draft_capability_pack_failed rate > 10% over 30 min
  → Slack #qontak-chatbot-oncall
- autonomous_kb_upload_failed rate > 5% over 1 hour
  → Slack #qontak-chatbot-oncall
- autonomous_direct_preview_invoked success rate < 90% over 1 hour
  → Slack #qontak-chatbot-oncall
- autonomous_full_preview_invoked success rate < 90% over 1 hour
  → Slack #qontak-chatbot-oncall
- Any 5xx from new mekari-agent client > 5 in 5 min
  → PagerDuty: Hadiningbot on-call
- autonomous_handoff_fallback fires > 3 in 10 min (Inbox routing degraded)
  → Slack #qontak-chatbot-oncall + #inbox-squad-oncall
- autonomous_resource_add_failed rate > 10% over 1 hour
  → Slack #qontak-chatbot-oncall

10.5. Post-Launch Monitoring Cadence

Review cadence:    Weekly for the first 4 weeks post-GA, then biweekly until end of 26Q2.
                   Reviewed during Hadiningbot Squad's weekly product review.
Owner:             PM Dimas Fauzi Hidayat (Product Manager) + Hadiningbot Eng Lead (Eko Aprianto).
Review scope:      autonomous_route_visited · autonomous_draft_capability_pack_succeeded/failed
                   autonomous_agent_saved/updated · autonomous_kb_upload_succeeded/failed
                   autonomous_kb_vector_status_changed · autonomous_direct_preview_invoked
                   autonomous_full_preview_invoked
                   Plus BE p95 latency on V3 list/detail.

Trigger thresholds:
  - Draft success rate drops > 10 percentage points week-over-week → investigate within 48 h
  - KB upload failure rate > 5% for 2 consecutive weeks → escalate to Data/ML platform owners
  - Direct or full preview success rate < 90% sustained 1 week → freeze rollout expansion
  - BE p95 latency > 800 ms sustained 1 week → engineering investigation + capacity review
  - Agent-creation count vs 15-cid target trails > 50% at week 8 post-GA → PM convenes
    Commercial Stakeholder review to assess adoption blockers

Rollback consideration:
  If preview success rate drops < 75% for > 24 hours and cannot be resolved, PM disables
  the BE rollout (autonomous_ai_agent = OFF) globally pending root-cause analysis. FE
  flag is disabled first per the cross-layer compatibility matrix.

11. Success Metrics

Adoption & Usage:

⭐ Primary KPI: Number of Autonomous AI Agents successfully built and live
   Definition:  Count of distinct ai_agent_uuid records where at least one autonomous_agent_saved
                event fired AND at least one autonomous_full_preview_invoked succeeded
                (proxy: agent is configured and validated end-to-end)
   Baseline:    0 (no production autonomous agents exist today)
   Target:      ≥ 15 Autonomous AI Agents built across 15 distinct cid (customer IDs)
                by end of 26Q2.

- Activation rate per pilot account
   Definition:  Of Plus / Ultimate / 360 workspaces with rollout = ON, % that complete at
                least one autonomous_agent_saved + autonomous_full_preview_invoked succeeded
   Baseline:    N/A — new feature
   Target:      ≥ 60% within 30 days of workspace rollout flip

Quality & Accuracy:

- Draft capability_pack success rate
   Definition:  succeeded / (succeeded + failed) across autonomous_draft_capability_pack_* events
   Baseline:    N/A — prototype data not comparable
   Target:      ≥ 90% sustained over 7 days within 30 days of GA

- KB upload + vectorisation success rate
   Definition:  autonomous_kb_upload_succeeded + autonomous_kb_vector_status_changed (final_status = Ready)
                divided by total upload attempts
   Baseline:    N/A
   Target:      ≥ 95% within 60 days of GA

- Direct + full preview success rate
   Definition:  succeeded / total invocations across both preview channels
   Baseline:    N/A
   Target:      ≥ 95% within 60 days of GA

Efficiency & Impact:

- Time from /ai-agent/autonomous/create entry to first autonomous_agent_saved
   Definition:  Median minutes between route entry and first successful save for the same
                user + workspace within a single session
   Baseline:    N/A — no production equivalent
   Target:      Median ≤ 30 minutes for Specialist-led builds within 60 days of GA
                (informs Phase 2 self-serve readiness for non-technical builders)

- BE proxy overhead on V3 list / detail endpoints
   Definition:  p95 latency on /api/v3/ai_agents/autonomous list + detail
   Baseline:    N/A
   Target:      p95 < 800 ms (excluding upstream incidents), per RFC §10 SLA

12. Launch Plan & Stage Gates

Stage	Audience	Duration	Success Gate to Advance	Owner
Internal Alpha	Hadiningbot Squad internal QA accounts (~3 workspaces)	2 weeks	0 P0/P1 bugs across S13 user stories. Draft success rate ≥ 90% on internal traffic. BE V3 list/detail p95 < 800 ms. Legacy /ai-agent smoke tests pass post-deploy.	PM + QA
Pilot (Specialist-led)	3 Chatbot Specialist-led internal workspaces building agents for first 3 customer cids	3 weeks	First 3 cid agents autonomous_agent_saved + autonomous_full_preview_invoked succeeded end-to-end. Direct + full preview success rate ≥ 90%. KB upload success rate ≥ 95%. Zero mekari_agent_base_url_missing incidents in production.	PM + Eng Lead
Controlled GA	Up to 15 cid on Plus / Ultimate / 360 with rollout flipped per workspace	4–6 weeks	≥ 8 of 15 target cid have at least one saved + validated agent. Draft success rate ≥ 90% sustained 7 days. Preview success rate ≥ 95% sustained 7 days. No P0/P1 bugs open > 48 h. Legacy /ai-agent regression checks remain green. D6 design sign-off cleared.	PM + Eng Lead + Commercial Stakeholder
GA	All Plus / Ultimate / 360 workspaces with rollout flipped ON on request	Ongoing	All Controlled GA gates sustained 2 weeks. PMM launch approved (copy + enablement). Post-launch monitoring cadence (S10.5) staffed and running.	PM + PMM

13. Dependencies

#	Dependency	Owning Team	Deliverable Needed	Blocking?
D1	Upstream noncore-mrag autonomous endpoints (/ai-agent family, /draft-skill-pack, KB upload + status)	Data / ML Platform	Stable endpoints already used by chatbot-ml-dev — no new work required, but availability + latency SLAs must be confirmed for production proxy traffic	YES (without these, no autonomous flow exists)
D2	Upstream chatbot-ai /predictions endpoint (full preview)	Data / ML Platform	Existing endpoint; confirm capacity for V3 traffic from new flow	YES (no full preview without it)
D3	Upstream mekari-agent /run-autonomous-agent (direct preview)	Data / ML Platform	Endpoint + credentials + timeout expectations + base URL config. New lib/mekari_agent/autonomous_ai_agent.rb client to be built in chatbot BE (ST5)	NO — direct preview degrades gracefully if MEKARI_AGENT_BASE_URL missing; full preview still works
D4	FE route exposure strategy backed by BE rollout signal	FE Team (Hadiningbot)	Route middleware + nav visibility tied to BE system_preferences.autonomous_ai_agent rollout	YES
D5	BE rollout code for autonomous_ai_agent in system_preferences group	BE Team (Hadiningbot)	Rollout entry deployed; toggle path documented for Ops	YES
D6	Design sign-off on adaptation of chatbot-fe-ai-agent / chatbot-ml-dev prototype to Pixel 3 (@mekari/pixel3@1.0.7)	Design / PM / FE	Sign-off on each new screen (List / Create / Config / drawers / preview rail)	NO for Controlled GA entry, but YES (soft blocker) before full GA. Tracked as Risk in S15.
D7	URL extraction contract for KB ingestion	FE + BE + Data	Single autonomous endpoint that extracts + persists URL content server-side (resolved per RFC §10 D7)	YES
D8	OpenAPI updates (docs/openapi/openapi.yaml + dist regen + SESSION-LOG.md)	BE Team	New V3 endpoints documented + validated via swagger-cli and spectral-cli	YES (release blocker)
D9	Alicloud OSS knowledge ingestion pattern reuse	BE Team / Infra	Reuse existing OSS-first pattern from app/core/use_cases/api/frontend_service/v1/ai_assist/create_knowledge_source.rb and create_url_knowledge_source.rb	YES
D10	Commercial alignment on tier scope (Plus / Ultimate / 360)	Commercial Stakeholder (Aviandri Hidayat)	Informational — AI Agent is already entitled in these tiers (iteration, not new entitlement). PMM messaging support for the autonomous flow under the existing AI Agent SKU.	NO (iteration scope; no new entitlement decision required)
D11	Inbox routing API for Hand off to human agent routing rules	Inbox squad / Routing service owner	API contract for: (a) listing available agent groups (Any available agent + named divisions) at config time, (b) accepting a handoff event at runtime that transfers a conversation to the picked agent group, (c) returning failure cleanly so the autonomous engine can fall back to Ask clarification per AAA-S08 ERR-3.	YES
D12	Workspace integration connectors required by some Actions	Integrations squad / per-provider owner (Google Workspace, Mekari Talenta/Jurnal/Desty owners)	API to: (a) read whether a connector is connected for a workspace at Add Action config time (AAA-S10 ERR-1), (b) make connector creds available to action invocations at runtime.	NO — Mekari Qontak built-in actions ship with the platform; only Google Calendar / Google Sheets / API Integrations require explicit connector enablement and they degrade gracefully (Action cannot be created without connector; existing actions remain functional).

14. Key Decisions + Alternatives Rejected

14a — Decisions Made

Date	Decision	Rationale
2026-05-22	Ship Autonomous AI Agent as a new route family /ai-agent/autonomous in chatbot-fe + new FrontendService::V3 namespace in chatbot BE. Legacy /ai-agent modal remains untouched.	The legacy modal is a different product (session-based, Redis, local Rails tables, V1 endpoints) and cannot serve autonomous-engine use cases. Building inside the legacy modal would conflate two products and create regression surface. RFC §3 confirms target architecture.
2026-05-22	Phase 1 is proxy-only (no Rails DDL). BE acts as BFF over noncore-mrag, chatbot-ai, mekari-agent.	Reduces blast radius and accelerates 26Q2 target (15 cid). Audit history / analytics deferred to upstream. RFC §6 confirms intent.
2026-05-22	All knowledge ingestion (files + URL content) goes through Alicloud OSS first, then vectorisation receives OSS-backed refs only.	Preserves Qontak chatbot platform invariant for KB storage and avoids exposing raw files / third-party URLs directly to ML vector endpoints. RFC §1 / §10.
2026-05-22	Rollout source of truth is BE system_preferences.autonomous_ai_agent. FE has no production env flag; FE route middleware + nav visibility derive from BE signal.	Single source of truth prevents FE-only-on / BE-off scenarios (per RFC §7 compatibility matrix).
2026-05-22	FE/BE public vocabulary uses capability_pack / capability_id. Upstream skill_pack / skill_id translation lives in adapter layer only.	Decouples customer-facing language from upstream ML vocabulary; allows ML platform to evolve naming without FE/BE churn.
2026-05-22	Plan/tier scope = Use-Case Package Plus, Ultimate, and Qontak 360.	Aligns with PM-confirmed commercial scoping for 26Q2 (per PM input 2026-05-22).
2026-05-22	Phase 1 accepts last-write-wins on concurrent edits with a ConcurrentEditWarning based on updated_at. No record-level locking or merge.	RFC §8 explicit Phase 1 acceptance; merge / lock would add scope incompatible with the 26Q2 target.
2026-05-22	KB vectorisation status polling = 5-second client-side intervals (FE-owned).	RFC-specified value; aligns with upstream throughput expectations.
2026-05-22	No CSV batch test-runner, no /test/improvise, no /test/judge in Phase 1. Captured as Non-Goals.	Deferred to keep 26Q2 surface area shippable. This PRD is now the program ANCHOR (Epic BOT-4191). The CSV batch test-runner + improvise/judge scope is handed to the separate AI Agent Testing initiative (Epic BOT-3351, own ANCHOR) — not a phase of this anchor. This anchor's Phase 2 = migrate existing internally-built configurations; Phase 3 = new-configuration iteration (Design Validation research). Both authored later as child PRDs under BOT-4191.

14b — Alternatives Rejected

Alternative	Why Rejected	Date
Extend the legacy /ai-agent modal to add an "Autonomous mode" toggle inside the existing screen	Legacy modal is session-based, Redis-backed, V1-only. Bolting the autonomous engine onto it would conflate two distinct data models and create regression risk on a live customer-facing product. RFC §2 confirms the two products are architecturally incompatible.	2026-05-22
Productise chatbot-ml-dev directly by deploying it as the customer-facing app	Prototype-grade — no production auth surface, no plan gating, no rollout control, no audit trail, no OSS-first compliance. Doing this would block the 15-cid target on security/compliance review.	2026-05-22
Mirror autonomous agents into local Rails tables in Phase 1 (full BE persistence)	Adds DDL + migration + dual-source-of-truth risk during the 26Q2 window. Proxy-only Phase 1 ships faster and avoids divergence from upstream noncore-mrag agent state. Local mirroring can be revisited in a later phase under this ANCHOR if admin tooling needs it.	2026-05-22
Add a FE-only env flag for production rollout (in addition to BE rollout)	Creates split-brain scenarios on FE-on / BE-off (per RFC §7 compatibility matrix — "frontend first" = NO). Single BE-sourced signal eliminates an entire class of operational mistakes.	2026-05-22
Send raw files or third-party source URLs directly to ML vectorisation endpoints	Violates Qontak chatbot platform OSS-first invariant; introduces security review burden and breaks consistency with existing KB ingestion patterns.	2026-05-22
Implement record-level locking or operational-transform-style merge for concurrent edits in Phase 1	Out of scope for 26Q2. Adds substantial FE + BE complexity. updated_at-based last-write-wins with a warning is sufficient given Specialist-led traffic patterns expected for the first 15 cid.	2026-05-22
Build a full migration tool for legacy AI Agents → autonomous engine in Phase 1	The two products serve different mental models. Migration would risk silent semantic regression on agents customers depend on, and would compete with the 15-cid creation target for engineering bandwidth.	2026-05-22

15. Open Questions

#	Type	Question	Owner	Deadline
1	Risk	D6 — No dedicated Figma exists; design is exploratory and lives as a live Vercel prototype at https://qontak-bot.vercel.app/bot-automation/ai-agents — declared canonical in the Header. Risk: Engineering or QA implements/tests against a stale snapshot of the prototype rather than the latest deployed Vercel state. Mitigation: (1) PRD Header and S6 both name the Vercel app as live source of truth; (2) Engineering checks Vercel app immediately before starting each S8 story; (3) QA re-checks Vercel app at start of each test pass; (4) Designers (Wulan + Rizky) post #qontak-chatbot Slack notification when a structural change ships to the Vercel app so squad is alerted to re-check. Pixel 3 translation sign-off still required before full GA exit.	Design (Wulan + Rizky) / PM / FE	2026-06-30 (before GA gate)
2	Open Question	What in-product copy should the legacy /ai-agent modal show to nudge eligible workspaces (Plus / Ultimate / 360 with rollout = ON) toward the new autonomous flow?	PM + PMM	2026-06-15
3	Open Question	Header roles confirmed 2026-05-22 (Eng Lead Eko Aprianto; Designers Wulan Febyazzahra + Rizky Surur; Researcher Devina Amalia; Commercial Stakeholder Aviandri Hidayat; Approver Annisa Nur). No outstanding question.	—	—
4	Open Question	Concrete throughput/latency expectations from noncore-mrag, chatbot-ai, and mekari-agent for production proxy traffic across Plus / Ultimate / 360. Needed to confirm BE p95 < 800 ms is sustainable under expected load.	BE Lead + Data/ML Platform	2026-06-10
5	Risk	DR-01 — Direct preview depends on new mekari-agent client + MEKARI_AGENT_BASE_URL config. Risk: misconfiguration in production silently disables direct preview. Mitigation: Health check on BE deploy that pings the mekari-agent base URL; alert in S10 already covers user-facing failures.	BE Lead	2026-06-15
6	Open Question	Soft delete / archive behavior for autonomous agents (and whether DeleteAgentControl ships in Phase 1) — RFC scope is silent.	PM + Eng Lead	2026-06-05
7	Open Question	Multi-tab concurrent edit warning is Phase 1's accepted limitation, but should we also surface a banner on the legacy /ai-agent modal warning that the two products do not share state?	PM	2026-06-15
8	Open Question	Iteration scope confirmed 2026-05-22: AI Agent is already entitled in Use-Case Package Plus/Ultimate and Qontak 360; the autonomous flow ships under the existing AI Agent SKU. No new commercial entitlement required.	—	—
9	Risk	Concurrent edits between Specialist + customer Bot Builder are accepted as last-write-wins. Risk: customers report data loss on busy agents during pilot. Mitigation: Pilot stage is Specialist-led only with ~3 cid; we monitor autonomous_agent_updated.concurrent_conflict event for incidents before broadening access.	PM + Eng Lead	Reassess after Stage 2 (Pilot)
10	Decided	Phase 2 trigger — committed when (A) OR (B), reviewed at (C). (A) Adoption-volume: ≥ 30 live autonomous agents OR ≥ 10 agents with ≥ 20 KB items each. (B) Customer-demand: ≥ 5 formal requests for batch test-runner / automated judging in any rolling 4-week window. (C) Calendar gate: end-of-26Q3 retro contingent on Phase 1 hitting its 15-cid primary KPI; if hit AND (A or B) → commit Phase 2 for 26Q4; if KPI missed → defer until Phase 1 root-cause resolved. This PRD is the program ANCHOR (Header — Anchor = Yes; Epic BOT-4191). The batch test-runner + improvise/judge scope this question deferred is now owned by the separate AI Agent Testing initiative (BOT-3351) — not a phase of this anchor. This anchor's own Phase 2 = migrate existing internally-built configurations onto the new engine; Phase 3 = new-configuration iteration (Design Validation research, 15 IDIs). Each is authored as a child PRD under BOT-4191.	PM Dimas	2026-09-30 (end-of-26Q3 retro)

PRD CHANGELOG

Version	Date	By	Section	Type	Summary
1.0	2026-05-22	Claude	All	CREATED	Initial NEW PRD for Autonomous AI Agent migration — Phase 1. Sourced from RFC 51184074800 (Migration of Autonomous AI Agent Creation to Chatbot BE and FE), Epic BOT-4191 (26Q2 New AI Engine Migration), and prototype reference at qontak-bot.vercel.app/bot-automation/ai-agents. PM-confirmed scope inputs (2026-05-22): persona = Chatbot Specialist + Dedicated Bot Builder; commercial driver = second iteration after first AI Agent product underperformed in market; target = 15 agents across 15 cid in 26Q2; plan/tier = Use-Case Package Plus/Ultimate + Qontak 360.
1.1	2026-05-22	Claude	Header, S2, S13, S15	MODIFIED	Header roles confirmed: PM title corrected to Product Manager; Eng Lead Eko Aprianto; Designers Wulan Febyazzahra + Rizky Surur; Researcher Devina Amalia; Commercial Stakeholder Aviandri Hidayat; Approver Annisa Nur. S2 problem statement reframed as iteration (AI Agent already entitled in Plus/Ultimate/360 — second iteration of the line, not new entitlement). S13 D10 downgraded from blocking sign-off to informational alignment. S15 Q-3 and Q-8 closed (header + commercial scope confirmed). S15 Q-10 decided: Phase 2 trigger = (Adoption-volume OR Customer-demand) gated by end-of-26Q3 KPI retro.
1.2	2026-05-22	Claude	Header, S2, S6, S8, S10, S10.5, S15	MODIFIED	Applied PRD scoring fixes from v1.1 AI-Readiness report + introduced live-document model for design. (1) Header Figma Master field rewritten: Vercel prototype declared canonical live source of truth — PRD treats Vercel app as authoritative for visuals; this PRD is a live document and visual changes in Vercel supersede prior descriptions without re-versioning. (2) S6 prefaced with a "Live design source of truth" callout explaining the divergence rule (Vercel wins for visuals; PRD wins for contracts/ACs/permissions/APIs). (3) S2 one-liner trimmed to 24 words. (4) S8 AAA-S02: Permission Model expanded with explicit KB row delete behaviour (CAN remove Ready/Failed rows, CANNOT edit in-place, CANNOT during Indexing) + AC-6 + AC-7. (5) S8 AAA-S03: Permission Model expanded with explicit CANNOT-delete-in-Phase-1 position + AC-4 + AC-5 (no DELETE endpoint mounted in Phase 1; manual retire via Hadiningbot Squad runbook). (6) S8 AAA-S04 reclassified Must Have → Should Have with reasoning. (7) Tier 1 Mermaid diagrams added: S8 system flow (sequenceDiagram across Specialist / FE / BE / noncore-mrag / OSS / mekari-agent / chatbot-ai) and 3× S6 UI state diagrams (List, Create, Config). (8) S10 dashboard owner and S10.5 monitoring owner — stale role refs synced (Eng Lead = Eko Aprianto; PM title = Product Manager). (9) S15 Q-1 Risk rewritten to reflect live-prototype model (stale-snapshot risk + 4-part mitigation including Slack notification cadence from Wulan + Rizky).
1.3	2026-05-24	Claude	S6, S7, S8, S10, S13	MODIFIED	Major expansion after live walkthrough of Vercel prototype (https://qontak-bot.vercel.app/bot-automation/ai-agents)..) Surface map added at S6.0 listing all 5 in-scope routes + 4 out-of-scope stubs. S6: Create page rewritten to capture both creation modes (Guided form with agent_type / goals / tone presets / multi-source knowledge picker; Write prompt freeform). Config page rewritten with 3-tab architecture (Behavior / Capabilities / Routing) + persistent Preview rail across tabs — replacing the old single capability_pack editor. Two new Feature blocks added: Shared Resources (Knowledge Base) Module at /bot-automation/resources with summary cards + 5 source types + async URL scan + status lifecycle + Mermaid state diagram. Shared Actions (Integration Catalog) Module at /bot-automation/actions with categorised picker (Mekari Qontak / Talenta / Jurnal / Desty / Other) + Mermaid state diagram. S7: API table extended from 11 → 27 behaviours covering Generate-from-Create, Resources CRUD + scan + toggle + delete, Actions CRUD + connector validation, Behavior block save, Capabilities CRUD with linked-source validation, Routing rules CRUD + runtime handoff to Inbox routing. S8: Five new Must-Have stories added (AAA-S06 Behavior config, AAA-S07 Capabilities config, AAA-S08 Routing rules + handoff, AAA-S09 Resources management, AAA-S10 Actions catalog management) — each with full Gherkin ACs, Permission Model, UI states. S10: Eight new observability events covering Resources, Actions, Capabilities, Routing rules, runtime handoff + fallback; two new alerts (handoff_fallback rate, resource_add_failed rate). S13: Two new dependencies — D11 Inbox routing API (blocking, required for AAA-S08 runtime handoff) and D12 Workspace integration connectors (non-blocking, gates AAA-S10 third-party actions).
1.4	2026-06-22	Claude	Header, S14, S15, +Reconciliation note	MODIFIED	Anchor flipped No → Yes, reconciled against Jira + repo + code. This PRD anchors the New Engine Migration initiative (Epic BOT-4191); Phase 1 shipped on /v2/ai_agents autonomous mode (BOT-4235, Done), not a V3 namespace. Phase 2 = this initiative's own deferred test-runner/judge scope, a child PRD under BOT-4191. Clarified that AI Agent Testing (BOT-3351) and AI Agent Knowledge are separate sibling initiatives with their own anchors, not phases of this one (overlap flagged for PM). Added an Implementation Reconciliation table documenting V3→V2, the ai_agent_engine_version flag, the shipped DELETE vs the no-delete AC, and the unbuilt Resources/preview surfaces. Mirrored into the documents repo under chatbot/autonomous-ai-agent/prds/.
1.5	2026-06-22	Claude	Header, S14, S15	MODIFIED	Program phases redefined per PM. This anchor's Phase 2 = migrate existing internally-built configurations (legacy Tree-Diagram config → new model; picks up Non-Goals #1/#3); Phase 3 = new-configuration iteration grounded in the Design Validation research (15 IDIs — Logic Map, terminology overhaul, Milestone/Routing fixes). The deferred CSV batch test-runner + improvise/judge (Non-Goals #4–#5) is handed to the separate AI Agent Testing initiative (BOT-3351), no longer a phase here. Anchor field, S14 decision, and S15 Q-10 updated accordingly.