Frontend Integration
Complete engineering reference for the River Agents frontend -- covering all 12 pages under the /agents route, their layout structures, component specifications, API call patterns, real-time WebSocket contracts, Zustand store definitions, and all four primary user journey flows.
Built with Next.js 15 App Router, React 19, TypeScript, Tailwind CSS, and Zustand for state management. This document is the implementation reference for frontend engineers adding pages, integrating new API endpoints, or extending the real-time layer.
Quick Navigation
- Technology Stack
- Page Map and Navigation Architecture
- Layout Wrapper Components
- Page 1: Agent Library
- Page 2: Creation Entry
- Page 3: AI-Powered Creation
- Page 4: Guided Wizard
- Page 5: Agent Detail View
- Page 6: Template Library
- Page 7: Template Detail
- Page 8: System Monitoring
- Page 9: Runs Management
- Page 10: Run Detail
- Page 11: Workspace Settings
- Page 12: Audit and Logs
- Real-Time Integration Architecture
- State Management Architecture
- API Integration Pattern
- User Journey Flows
Technology Stack
| Layer | Technology | Notes |
|---|---|---|
| Framework | Next.js 15 App Router | All 12 pages use App Router conventions; no Pages Router usage |
| UI Library | React 19 | Concurrent features used for live-streaming log panels |
| Language | TypeScript | Strict mode enabled; all API response shapes are typed |
| Styling | Tailwind CSS | No CSS modules; all component styles via utility classes |
| State | Zustand | 7 stores; no Redux or Context API for agent state |
| Charts | Recharts | Used for time-series, area, and bar charts on monitoring pages |
| Real-Time | WebSocket (native) | Three connection endpoints; see Real-Time Integration Architecture |
| Auth Guard | <ProtectedRoute> | Wraps all 12 pages; redirects to login if session is absent or expired |
| Layout | <AgentLayout> | Sidebar + top nav wrapper applied to all 12 pages |
Page Map and Navigation Architecture
All routes are protected by <ProtectedRoute> and wrapped in <AgentLayout>. The sidebar renders links to all top-level pages. The Agent Detail View (/agents/[id]) and Run Detail (/agents/runs/[id]) are deep-link targets accessed from their respective list pages, not direct sidebar items.
Layout Wrapper Components
| Component | Responsibility |
|---|---|
<ProtectedRoute> | Validates the session on mount. Redirects to /login?redirect={current_path} if the session is absent or expired. Renders a loading skeleton during validation to prevent a flash of unauthenticated content. |
<AgentLayout> | Renders the sidebar (links to all top-level pages), top navigation bar (workspace name, user avatar, notification bell with approvalStore.pendingCount badge), and the page content area. Sidebar collapsed state is persisted in localStorage. |
Page 1: Agent Library
Route: /agents
The workspace home page for River Agents. Loads all agents for the authenticated workspace and provides search, filtering, and management actions.
+---------------------------------------------------------------+
| Header: "River Agents" + description badge |
| [+ Create Agent] [Templates] [Monitor] [Audit Log] |
+---------------------------------------------------------------+
| Metric Cards Row: |
| +----------+ +----------+ +----------+ +----------+ |
| | Total | | Active | | Runs | | Success | |
| | Agents | | Agents | | Today | | Rate | |
| +----------+ +----------+ +----------+ +----------+ |
+---------------------------------------------------------------+
| Search Bar | Status Filter | Category Filter | [Grid/List] |
+---------------------------------------------------------------+
| Agent Cards (Grid View): |
| +------------------+ +------------------+ |
| | Icon Name | | Icon Name | |
| | Status Badge | | Status Badge | |
| | Description... | | Description... | |
| | Health | Level | | Health | Level | |
| | Owner | | Owner | |
| | [View] [Edit] | | [View] [Edit] | |
| | [Delete] | | [Delete] | |
| +------------------+ +------------------+ |
+---------------------------------------------------------------+
Feature Specification
| Feature | Behavior |
|---|---|
| Metric Cards | 4 KPI cards: Total Agents (count), Active Agents (count), Runs Today (24h window), Success Rate (7-day rolling). Loaded via GET /api/v1/agents/metrics/summary. |
| Search | Controlled text input; debounced 300ms. Triggers a server-side refetch with ?search={q} on the name and description fields. |
| Status Filter | ComboBox: All, Active, Paused, Draft, Archived. Maps to agent_status enum values. |
| Category Filter | ComboBox: All plus one entry per agent_category value. Can be combined with Status filter. |
| View Toggle | Grid (card) and List (table row) modes. Selection persisted to agentStore.viewMode. |
| Agent Card -- Grid | Icon with category-colored background, name, status badge (color-coded), 2-line truncated description, health dot, action level tag, owner name, View / Edit / Delete buttons. |
| Agent Row -- List | Same data as grid card in a compact table row; description column truncated to 60 characters. |
| Delete Confirmation | Modal requiring the user to manually type the agent name before DELETE /api/v1/agents/{id} fires. Prevents accidental deletion. |
| Quick Actions | Four header buttons: Create Agent (/agents/create), Templates (/agents/templates), Monitor (/agents/monitoring), Audit Log (/agents/audit). |
Agent Card Data Fields
| Field | Rendering | Source |
|---|---|---|
| Icon | Category-specific icon with a business_function-mapped background color | Static icon + color config keyed on agent.category |
| Name | Bold, truncated to one line | agent.name |
| Status | Color-coded badge: Active (green), Paused (amber), Draft (gray), Running (blue), Archived (red) | agent.status |
| Description | 2-line truncated paragraph, line-clamp-2 | agent.description |
| Health | Colored dot: healthy (green), degraded (amber), critical (red) | Computed from agent.health_status; derived from recent run metrics on a 5-minute evaluation cycle |
| Action Level | Tag: "Read Only", "Recommend", "Approval", "Automated" | agent.action_level mapped to display label |
| Owner | User display name | agent.owner_user_id resolved via user cache in agentStore |
API Calls
| Trigger | Endpoint | Store Update |
|---|---|---|
| Page mount | GET /api/v1/agents?page=1&limit=20&workspace_id={id} | agentStore.agents |
| Page mount | GET /api/v1/agents/metrics/summary | agentStore.summaryMetrics |
| Filter change | GET /api/v1/agents?status={s}&category={c}&search={q} | Replaces agentStore.agents |
| Delete action | DELETE /api/v1/agents/{id} | Removes entry from agentStore.agents; invalidates agentStore.summaryMetrics |
Page 2: Creation Entry
Route: /agents/create
Gateway page presenting the two agent creation paths. Renders a two-column card layout with a generation history sidebar.
+---------------------------------------------------------------+
| Header: "Create Agent" + description |
+---------------------------+-----------------------------------+
| | |
| +---------------------+ | +-----------------------------+ |
| | AI Creation | | | Guided Setup | |
| | | | | | |
| | Describe what you | | | Step-by-step wizard to | |
| | need in natural | | | configure every aspect of | |
| | language and let | | | your agent with full | |
| | AI generate the | | | manual control. | |
| | agent config. | | | | |
| | | | | | |
| | [Start AI Create] | | | [Start Guided Setup] | |
| +---------------------+ | +-----------------------------+ |
| | |
+---------------------------+-----------------------------------+
| Generation History (lazy-loaded sidebar): |
| Previous AI-generated configs -- click to resume a draft |
+---------------------------------------------------------------+
Feature Specification
| Feature | Behavior |
|---|---|
| AI Creation Card | Routes to /agents/create/ai on click. Describes the natural language input path. |
| Guided Setup Card | Routes to /agents/create/guided on click. Describes the manual 5-step wizard path. |
| Generation History Sidebar | Lazy-loaded after main two-card panel renders; not critical path. Calls GET /api/v1/agents/ai-drafts after mount. Each entry shows: prompt summary (truncated 80 chars), timestamp, and draft status (completed / draft). Clicking an entry navigates to /agents/create/ai and restores that draft from agentStore.aiDraft. Renders a loading skeleton while fetching. |
Implementation note: The Generation History sidebar fetch is deferred with a useEffect that fires after the first paint. If the fetch fails (e.g., user has no prior drafts), the sidebar slot renders an empty state message -- it does not show an error state.
Page 3: AI-Powered Creation
Route: /agents/create/ai
Generates a complete agent configuration from a natural language description. The user reviews the generated configuration, edits individual sections inline, and deploys directly.
User Flow
Feature Specification
| Feature | Behavior |
|---|---|
| Prompt Input | Large textarea; min-height 120px; multiline. Submit on Ctrl+Enter or button click. |
| Quick Starter Chips | Pre-written prompt chips for common use cases (e.g., "Monitor customer support tickets", "Reconcile financial records daily"). Clicking a chip populates the textarea; the user can edit before submitting. |
| Generation Animation | 4-stage progress indicator shown during POST /api/v1/agents/generate. Stages: (1) Understanding Requirements, (2) Mapping Data Sources, (3) Configuring Actions, (4) Applying Governance. Stage transitions are driven by SSE progress events from the backend, not client-side timers. |
| Review Panel -- Connected Context | Shows which data sources the AI selected and the reasoning label for each selection. Editable: user can add or remove sources from the generated set. |
| Review Panel -- Action Boundaries | Shows selected tools, the recommended action level, and a per-tool risk assessment label. Editable. |
| Review Panel -- Governance | Shows generated approval rules and any active org-level policies that will apply to this agent. Org policies are read-only; they cannot be overridden here. |
| Inline Editing | Any field in the review panel is editable. Edits apply to the in-memory draft in agentStore.aiDraft and do not trigger a re-generation. |
| Deploy | POST /api/v1/agents with the finalized config from agentStore.aiDraft. The name field must be non-empty before the button activates. On success, redirects to /agents/{new_id}. |
API Calls
| Trigger | Endpoint | Notes |
|---|---|---|
| Submit description | POST /api/v1/agents/generate | Returns SSE stream; each stage emits a progress event; the final complete event contains the full generated config object |
| Deploy | POST /api/v1/agents | Body: finalized config from agentStore.aiDraft; returns 202 with agent_id |
Page 4: Guided Wizard
Route: /agents/create/guided (also /agents/create/guided?template={id})
A 5-step sequential configuration form. When navigated with ?template={id}, all fields are pre-populated from the template record fetched at mount.
Step Flow
Step Specifications
| Step | Name | Fields |
|---|---|---|
| 1 | Identity | Agent Name (required text), Description (required textarea), Domain / Category (dropdown of 8 agent_category values), Admin / Owner (user selector) |
| 2 | Goal | instruction_set large textarea (monospace font); AI Suggest button (calls POST /api/v1/agents/suggest-goal); Example Goals section populated contextually from the Step 1 category selection |
| 3 | Data and Systems | Categorized grid of all available workspace data sources (Databases, APIs, SaaS, Files). Click to select / deselect; selected sources are highlighted. Per-source access level indicator (read-only / read-write). Search filter. |
| 4 | Actions | 4 action level selector cards (see below). Selection updates agentStore.wizardDraft.action_level. |
| 5 | Review and Certify | Full configuration summary; "Edit" links per section navigate back to the relevant step. Certification checkbox must be checked before the Deploy button activates. |
Action Level Selector Cards (Step 4)
+-----------------+ +-----------------+ +-----------------+ +-----------------+
| Read and | | Recommend | | Act with | | Fully |
| Respond | | Actions | | Approval | | Automated |
| | | | | | | |
| Query and | | Suggest actions | | Execute after | | Execute without |
| analyze only. | | but never | | human approves | | human approval. |
| No writes. | | execute them. | | each action. | | |
| | | | | | | |
| Risk: None | | Risk: Low | | Risk: Medium | | Risk: High |
+-----------------+ +-----------------+ +-----------------+ +-----------------+
Each card renders a visual risk indicator: None (green), Low (yellow), Medium (orange), High (red). Selecting a card shows a detailed enforcement summary below the grid explaining exactly what the agent can and cannot do at that level.
Template Pre-Fill
When ?template={id} is present, the page calls GET /api/v1/templates/{id} on mount and populates agentStore.wizardDraft from the template's template_config fields. The user can modify any field. The resulting agent record stores template_id for traceability.
API Calls
| Trigger | Endpoint | Notes |
|---|---|---|
Mount with ?template={id} | GET /api/v1/templates/{id} | Populates agentStore.wizardDraft |
| Step 2 AI Suggest | POST /api/v1/agents/suggest-goal | Body: { name, description, category }; returns suggested instruction_set |
| Step 3 mount | GET /api/v1/workspace/data-sources | Loads available data sources for the selection grid |
| Deploy (Step 5) | POST /api/v1/agents | Returns 202 with agent_id; wizard enters polling mode |
Implementation note: The POST /api/v1/agents returns 202 because agent validation is asynchronous. After receiving the 202, the wizard shows a "Deploying..." state and polls GET /api/v1/agents/{id}/validation-status at 2-second intervals until status transitions to configured or active. On async validation failure, the wizard renders an inline error banner with field-level detail and navigates the user back to the step containing the failing field.
Page 5: Agent Detail View
Route: /agents/[id]
The primary operational workspace for a live agent. A persistent hero header and KPI strip remain fixed above a 7-tab content area.
+---------------------------------------------------------------+
| [<- Back] [Icon] Agent Name [Status Badge] |
| Description text | Owner | Domain | Created date |
| [Run Now] [Pause / Resume] [Edit] [Deploy New Version] |
+---------------------------------------------------------------+
| Total Runs | Success Rate | Avg Latency | Actions Taken |
| Pending Approvals | Uptime |
+---------------------------------------------------------------+
| [Overview] [Activity] [Data Access] [Governance] |
| [Monitoring] [Audit and Logs] [Settings] |
+---------------------------------------------------------------+
| Tab content area (varies by selected tab) |
| |
+---------------------------------------------------------------+
Hero Header
| Element | Behavior |
|---|---|
| Back Button | Navigates to /agents (Agent Library) |
| Action Buttons | Context-sensitive set based on agent.status: Active shows Run Now + Pause; Paused shows Resume; any status shows Edit and Deploy New Version |
| Run Now | Opens a modal for optional payload input (rendered as a form from the agent's trigger_config.input_schema). Calls POST /api/v1/agents/{id}/runs on submit. Disabled when agent.status is not active. |
| Deploy New Version | Opens the Settings tab pre-focused on the instruction set editor; saving creates a new version draft and initiates the deploy flow. |
KPI Strip
| Metric | Description | Source |
|---|---|---|
| Total Runs | Lifetime execution count | agentMetrics.total_runs |
| Success Rate | Completed / Total runs over the 7-day window | agentMetrics.success_rate_7d |
| Avg Latency | Mean execution duration in the 7-day window | agentMetrics.avg_latency_ms |
| Actions Taken | Total tool dispatches across all runs | agentMetrics.total_tool_calls |
| Pending Approvals | Active approval_requests records in pending status | approvalStore.pendingCount -- rendered amber with bold font if count > 0 |
| Uptime | Percentage of time in active status over the rolling 30-day window | agentMetrics.uptime_percent |
Tab Specifications
Tab 1: Overview
Content is dynamic per agent_category. Common elements across all categories: Quick Stats Cards (category-specific KPIs), Recent Activity Preview (last 5 events), Automation Relationship Map (visual diagram of connected data sources, tools, and notification channels), Quick Actions row (Run Now, View Logs, Edit Configuration).
Domain-specific overview components:
| Category | Domain-Specific Components |
|---|---|
customer_support | Ticket resolution feed, CSAT score card, response time metric, escalation rate |
sales_lead_qualification | Lead pipeline visualization, qualification rate, scoring distribution chart |
finance_reconciliation | Reconciliation status indicator, anomaly count, match rate, flagged items count |
risk_compliance | Policy violation feed, severity distribution chart, recent enforcement action log |
data_analyst_insights | Recent queries list, report gallery thumbnails, key insight highlights |
operations_monitoring | System health mini-dashboard, active alert count, remediation action log |
executive_decision_support | Brief gallery, cross-domain KPI summary cards, trend indicators |
custom_enterprise | Configurable widget layout; defaults to standard activity timeline if no widgets configured |
Tab 2: Activity
Chronological event feed across all runs. Supported event types: run_started, run_completed, tool_executed, approval_requested, approval_resolved, config_changed, agent_paused, agent_resumed. Time filters: Last 24h, Last 7 days, Last 30 days, Custom range.
When the agent has an active run, new events append in real time via the /ws/agent-runs/{execution_id} WebSocket. Click any event to expand: full reasoning text, tool call arguments, observation, model used. Each event shows a trace link to the full run log.
Tab 3: Data Access
Grid of all connected data sources. Per-source detail: source name, type (PostgreSQL, Salesforce, REST, etc.), access level (read / read-write), connection status (live health indicator -- green / amber / red), last accessed timestamp. Expandable schema preview shows the table and column tree. Add / Remove source actions create a new draft agent version.
Tab 4: Governance
Current action level with full enforcement description. Active org-level and workspace-level policies listed by name and condition. Approval rules table (tool name, condition, approver group). Approval history table (timestamp, tool, status, approver, decision duration). Access control list (roles permitted to edit / deploy / approve / view this agent). Recent policy violations flagged during runs.
Tab 5: Monitoring
Time-series charts using Recharts: success rate trend (7-day area chart), latency distribution (p50 / p95 / p99 line chart), throughput in runs per hour (bar chart). Current health status indicator with contributing factors. Token consumption breakdown. Period comparison (current vs prior equivalent window).
Tab 6: Audit and Logs
Scoped execution history for this agent only. Same column structure as the global /agents/audit page but pre-filtered to agent_id={id}. Click any run row to drill down to the turn-by-turn log. Export scoped to this agent.
Tab 7: Settings
Editable fields: name, description, domain (saving any of these updates the agent record; does not create a new version). instruction_set editor -- saving creates a new draft version. Trigger configuration (add / edit / remove; includes a cron expression builder for scheduled triggers). Tool binding management (add / remove tools). Notification channel configuration per agent. Version history list with diff view between any two versions. Danger Zone section: Pause, Archive, Delete -- each with a confirmation modal. Archival is blocked if active runs exist unless force=true is passed.
API Calls
| Trigger | Endpoint | Store Update |
|---|---|---|
| Page mount | GET /api/v1/agents/{id} | agentStore.selectedAgent |
| Page mount | GET /api/v1/agents/{id}/metrics?period=7d | agentStore.selectedAgentMetrics |
| Activity tab | GET /api/v1/agents/runs?agent_id={id}&limit=5 | executionStore.recentRuns |
| Governance tab -- Approvals | GET /api/v1/agents/approvals?agent_id={id} | approvalStore.approvals |
| Settings tab -- Versions | GET /api/v1/agents/{id}/versions | agentStore.versions |
| Run Now | POST /api/v1/agents/{id}/runs | Prepends to executionStore.runs |
| Pause / Resume / Archive | POST /api/v1/agents/{id}/{action} | Optimistic update on agentStore.selectedAgent.status; confirmed or rolled back on response |
Page 6: Template Library
Route: /agents/templates
Browsable catalog of built-in and user-defined agent templates.
+---------------------------------------------------------------+
| Header: "Agent Templates" + description |
| [Build from Scratch] |
+---------------------------------------------------------------+
| Search | Category Filter | [Grid / List Toggle] |
+---------------------------------------------------------------+
| Template Cards (Grid View): |
| +------------------+ +------------------+ |
| | Icon Name | | Icon Name | |
| | Category Badge | | Category Badge | |
| | Description | | Description | |
| | Integrations | | Integrations | |
| | Governance Level | | Governance Level | |
| | [View] [Use] | | [View] [Use] | |
| +------------------+ +------------------+ |
+---------------------------------------------------------------+
Feature Specification
| Feature | Behavior |
|---|---|
| Search | Filters templates by name and description. Client-side on the loaded set; server-side refetch with ?search={q} for matches beyond the initial page. |
| Category Filter | ComboBox: All plus one option per agent_category value. Triggers GET /api/v1/templates?category={c}. |
| View Toggle | Grid (card) and List (table) modes. Persisted to templateStore.viewMode. |
| Template Card (Grid) | Icon, name, category badge, 2-line description, integration logos (max 3 shown + "+N more" label), governance level indicator, View Blueprint and Use Template buttons. |
| Template Row (List) | Table columns: name + description, category, integrations, governance level, View Details and Use Template actions. |
| Use Template | Navigates to /agents/create/guided?template={id}. No API call -- the wizard page handles the fetch on mount. |
| Build from Scratch | Header button navigating to /agents/create (Creation Entry). |
Template Card Fields
| Field | Description |
|---|---|
| Icon | Category-specific icon with colored background |
| Name | Template name (e.g., "Customer Support Specialist") |
| Category | Badge showing agent_category display label |
| Description | Short description of what the template configures (2 lines, truncated) |
| Integrations | List of recommended data sources and tools (e.g., "Zendesk, Confluence +2") |
| Governance | Governance level text (e.g., "Act with Approval") with color indicator matching the action level risk scheme |
API Calls
| Trigger | Endpoint | Store Update |
|---|---|---|
| Page mount | GET /api/v1/templates?page=1&limit=20&status=published | templateStore.templates |
| Category filter | GET /api/v1/templates?category={c} | Replaces templateStore.templates |
Page 7: Template Detail
Route: /agents/templates/[id]
Full preview of a single template showing its configuration, capabilities, and connectivity requirements.
+---------------------------------------------------------------+
| Hero Section: |
| [<- Back] [Category Badge] |
| Template Name (large heading) |
| Full description paragraph |
| [Use This Template] |
+---------------------------------------------------------------+
| Mission Architecture: |
| What this agent does + Key objectives list |
+---------------------------------------------------------------+
| Capabilities Grid: |
| +-------------+ +-------------+ +-------------+ |
| | Icon + Name | | Icon + Name | | Icon + Name | |
| | Description | | Description | | Description | |
| +-------------+ +-------------+ +-------------+ |
+---------------------------------------------------------------+
| Connectivity Hub: |
| Data sources and tools organized by type |
+---------------------------------------------------------------+
| Deployment CTA: |
| [Use This Template] -- Est. setup time: ~5 min |
+---------------------------------------------------------------+
Section Specifications
| Section | Content |
|---|---|
| Hero | Template name, category badge, full description paragraph, primary "Use This Template" CTA. |
| Mission Architecture | Detailed purpose statement, key objectives as a bulleted list, explanation of how the agent operates in the target business context. |
| Capabilities Grid | Cards showing specific agent capabilities (e.g., "Ticket Triage", "Knowledge Retrieval", "Response Drafting"). Each card shows: icon, capability name, one-sentence description. |
| Connectivity Hub | All required data sources and tools grouped by type (Databases, APIs, SaaS). Shows required access level per source (read / read-write) and whether the source is already connected in the user's workspace. |
| Deployment CTA | Large "Use This Template" button linking to /agents/create/guided?template={id}, with an estimated setup time derived from the number of fields requiring customization. |
API Calls
| Trigger | Endpoint | Store Update |
|---|---|---|
| Page mount | GET /api/v1/templates/{id} | templateStore.selectedTemplate |
Page 8: System Monitoring
Route: /agents/monitoring
Platform-wide observability dashboard for the entire River Agents execution ecosystem.
+---------------------------------------------------------------+
| Header: "System Monitoring" |
+---------------------------------------------------------------+
| +----------+ +----------+ +----------+ +----------+ |
| | Active | | Total | | Avg | | Failure | |
| | Agents | | Runs 24h | | Latency | | Rate | |
| +----------+ +----------+ +----------+ +----------+ |
+---------------------------------------------------------------+
| System Throughput Chart (Area Chart -- runs/hour, last 24h) |
+---------------------------------------------------------------+
| Alert Stream (WS feed) | Cluster Health Table |
| severity | agent | msg | Instance | Status | CPU | Mem |
| timestamp | Uptime | Active Runs |
+---------------------------------------------------------------+
Feature Specification
| Feature | Behavior |
|---|---|
| Top Metric Cards | 4 cards: Active Agents, Total Runs (24h), Average Latency (ms), Failure Rate (%). Auto-refreshes every 30 seconds via GET /api/v1/monitoring/summary. |
| System Throughput Chart | Recharts AreaChart -- runs per hour over the last 24 hours. Areas stacked by status: completed (green), failed (red), running (blue). Data loaded via GET /api/v1/monitoring/throughput?period=24h. |
| Alert Stream | Real-time feed subscribed via /ws/monitoring. Each alert shows: severity icon (info / warn / error), agent name if agent-scoped, message text, timestamp. Ordered by recency; maximum 50 entries visible before virtualized scrolling. |
| Cluster Health Table | Infrastructure instances: Instance ID, status (healthy / degraded / critical), CPU %, Memory %, uptime, active run count. Loaded via GET /api/v1/monitoring/cluster. Refreshes every 60 seconds. |
WebSocket behavior: This page subscribes to /ws/monitoring on mount and unsubscribes on unmount. Incoming run_started and run_completed events increment the metric card counts directly without triggering a full refetch. On WebSocket disconnect, the page falls back to polling GET /api/v1/monitoring/summary every 15 seconds.
Page 9: Runs Management
Route: /agents/runs
Cross-agent execution run history with filtering, inline approval actions, and the approval review modal.
+---------------------------------------------------------------+
| Header: "Agent Runs" |
+---------------------------------------------------------------+
| +----------+ +----------+ +----------+ +----------+ |
| | Total | | Completed| | Failed | | Pending | |
| | Runs | | | | | | Approval | |
| +----------+ +----------+ +----------+ +----------+ |
+---------------------------------------------------------------+
| Search Bar | Status Filter | Time Range Filter |
+---------------------------------------------------------------+
| Run ID | Agent | Status | Trigger | Duration | Time | Actions|
| (table rows with pagination) |
+---------------------------------------------------------------+
Feature Specification
| Feature | Behavior |
|---|---|
| Stats Cards | 4 cards: Total Runs, Completed (with success %), Failed (with failure %), Pending Approval (count). Loaded via GET /api/v1/agents/runs/summary. |
| Search | Search by run ID prefix or agent name. Triggers server-side refetch. |
| Status Filter | Options: All, Running, Completed, Failed, Pending Approval. Maps to execution_status enum values. |
| Time Range Filter | Presets: Last 24h, Last 7 days, Last 30 days. Custom date range picker. |
| Runs Table | Columns: Run ID (monospace, truncated, copy button), Agent (icon + name), Status badge (color-coded), Trigger type badge, Duration, Timestamp, Actions. |
| Context Actions | Actions per row vary by status; see the Status-Based Action Matrix below. |
| Approval Review Modal | Opened by the "Review" action on approval_pending rows. See modal spec below. |
Status-Based Action Matrix
| Status | Available Actions |
|---|---|
running | Stop (emergency halt via POST /api/v1/agents/runs/{id}/stop) |
completed | View Details (navigates to /agents/runs/{id}) |
failed | Retry (POST /api/v1/agents/runs/{id}/retry), View Details |
approval_pending | Review (opens Approval Modal), View Details |
Approval Review Modal
+----------------------------------------------+
| Approval Required |
| |
| Agent: [Agent Name] |
| Run ID: [EXEC-123] |
| |
| Proposed Action: |
| Tool: update_crm |
| Arguments: { id: 123, status: "high" } |
| |
| Agent Reasoning: |
| "Based on enrichment data, this lead |
| qualifies as high-value enterprise..." |
| |
| Risk Context: |
| No policy violations detected. |
| |
| [Edit Arguments] |
| [Reject] [Approve] |
+----------------------------------------------+
Edit and Approve path: Clicking "Edit Arguments" expands a JSON editor pre-populated with the proposed tool arguments. Saving this path submits PATCH /api/v1/approvals/{id} with { status: "APPROVED", modified_args: {...}, reviewer_note: "..." }. This path is used when the approver agrees with the action but wants to modify specific argument values before execution.
API Calls
| Trigger | Endpoint | Store Update |
|---|---|---|
| Page mount | GET /api/v1/agents/runs?page=1&limit=20 | executionStore.runs |
| Page mount | GET /api/v1/agents/runs/summary | executionStore.summary |
| Filter change | GET /api/v1/agents/runs?status={s}&from={t}&to={t} | Replaces executionStore.runs |
| Approve | PATCH /api/v1/approvals/{id} { status: "APPROVED" } | Updates approvalStore.approvals; updates matching executionStore.runs entry status |
| Reject | PATCH /api/v1/approvals/{id} { status: "REJECTED", reviewer_note } | Same store updates as approve |
| Edit and Approve | PATCH /api/v1/approvals/{id} { status: "APPROVED", modified_args } | Same store updates as approve |
Page 10: Run Detail
Route: /agents/runs/[id]
Full execution trace for a single agent run with a live-streaming, terminal-style log viewer.
+---------------------------------------------------------------+
| Breadcrumb: Agent Runs > [Run ID] |
+---------------------------------------------------------------+
| +-----------------------------+ +-------------------------+ |
| | [Icon] Agent Name | | Run Summary: | |
| | [Status Badge] [Run ID] | | Run ID | |
| | Trigger type | Timestamp | | Agent | |
| | [Retry] / [Stop] | | Status | |
| | | | Trigger | |
| | Duration | Trigger | | | Duration | |
| | Log Lines | Started | | Log Lines | |
| | | +------------------------+ |
| | Execution Log Viewer: | | Status Timeline: | |
| | 00:00.000 INFO [msg] | | [x] Queued | |
| | 00:00.142 INFO [msg] | | [x] Initialised | |
| | 00:01.540 WARN [msg] | | [x] Executing | |
| | 00:02.450 ERROR [msg] | | [ ] Completed | |
| +-----------------------------+ +------------------------+ |
+---------------------------------------------------------------+
Feature Specification
| Feature | Behavior |
|---|---|
| Breadcrumb | "Agent Runs > {run_id_truncated}" with back-navigation link to /agents/runs. |
| Hero Card | Agent icon + name, large status badge, run ID, trigger type + timestamp. Action buttons: Retry (failed runs only), Stop (running runs only). |
| Stats Strip | 4 inline metrics: Duration, Trigger type, Log Lines count, Start time. |
| Execution Log Viewer | Scrollable, virtualized list of log entries. Each row: monospace timestamp (MM:SS.mmm), level badge (INFO -- blue / WARN -- amber / ERROR -- red), message text. Rows are hoverable. During active runs, new entries append at the bottom via WebSocket. |
| Auto-Scroll Behavior | Viewer auto-scrolls to the bottom while the user has not manually scrolled up. If the user scrolls up, auto-scroll suspends and a "Jump to live" button appears pinned at the bottom. |
| Run Summary Sidebar | Key-value card: Run ID, Agent, Status, Trigger, Duration, Log Lines. Fixed position on screens wider than 1280px. |
| Status Timeline | Vertical timeline: Queued, Initialised, Executing, Completed (or Failed / Cancelled / Max Turns Exceeded). Filled circle for complete phases; empty circle for pending. Timestamps shown per phase. |
Live Log Streaming
When selectedRun.status is running or approval_pending, this page subscribes to /ws/agent-runs/{execution_id}. WebSocket events map to log entry types:
| WebSocket Event | Log Entry Appended |
|---|---|
turn_reasoning | reasoning log entry with thinking text and token count |
tool_called | tool_call log entry with tool name and arguments |
tool_result | tool_result log entry with output and duration |
approval_requested | approval_requested log entry; renders an inline approval card in the log viewer |
approval_resolved | approval_resolved log entry |
run_completed | run_completed entry; updates status badge; closes WebSocket |
run_failed | run_failed entry; updates status badge; closes WebSocket |
API Calls
| Trigger | Endpoint | Store Update |
|---|---|---|
| Page mount | GET /api/v1/agents/runs/{id} | executionStore.selectedRun |
| Page mount | GET /api/v1/agents/runs/{id}/logs | executionStore.logs |
| Retry action | POST /api/v1/agents/runs/{id}/retry | Navigates to new run's detail page on 202 response |
| Stop action | POST /api/v1/agents/runs/{id}/stop | Updates executionStore.selectedRun.status to cancelled; closes WebSocket |
Page 11: Workspace Settings
Route: /agents/settings
Workspace-level River Agents configuration organized in 6 tabs.
Tab Structure
Tab Specifications
Tab 1: General
| Section | Fields |
|---|---|
| Workspace Identity | Workspace name, description, region and timezone |
| Preferences | Default view mode (grid / list), default metrics time range, theme preference |
Tab 2: Compute and Limits
| Section | Fields |
|---|---|
| Concurrency | Max concurrent agent runs (slider with numeric input) |
| Turn Limits | Default max_turns per execution |
| Timeouts | Default per-tool timeout (seconds) |
| Rate Limits | API trigger rate limits (requests/minute), webhook ingestion limits |
| Resource Quotas | Max agents per workspace, max runs per day, token budget per month |
Tab 3: Governance
| Section | Fields |
|---|---|
| Default Action Level | Default action_level applied to new agents created in this workspace |
| Global Policies | Org-wide governance policies that apply to all agents (read-only list for non-admins); policy editor for admins with WHEN/THEN condition expression builder |
| Network Perimeters | Allowed outbound domains, IP restrictions |
Tab 4: Access Control
| Section | Fields |
|---|---|
| Members | List of workspace members with current role |
| Role Definitions | Admin (full control), Editor (create and edit agents), Operator (run and approve), Viewer (read-only) |
| Invite | Invite new members by email with role pre-assignment |
| Role Assignment | Change member roles; role changes take effect immediately |
Tab 5: Notifications
| Section | Fields |
|---|---|
| Email Channels | Email targets for agent events |
| Slack Channels | Slack workspace connection and channel mapping |
| Alert Triggers | Which events trigger notifications: run failure, approval needed, health degraded, policy violation, run completed |
| Digest Settings | Daily and weekly digest email schedule |
Tab 6: API and Webhooks
| Section | Fields |
|---|---|
| API Keys | Generate and manage API keys for programmatic agent triggers. Table: key name, created date, last used, status (active / revoked), actions (copy / revoke). The key value is shown once at generation time -- not retrievable again. |
| Webhook Subscriptions | Outbound webhook configuration. Table: URL, subscribed events, status (active / failed / untested), last successful delivery, actions (edit / delete / send test payload). |
API Calls
| Trigger | Endpoint | Notes |
|---|---|---|
| Page mount | GET /api/v1/workspace/settings | Populates all 6 tab sections from a single response |
| Save any tab | PATCH /api/v1/workspace/settings with changed fields | Returns full updated settings; settingsStore.settings is replaced |
| Generate API key | POST /api/v1/workspace/api-keys | Returns key value once; store in browser clipboard immediately |
| Revoke API key | DELETE /api/v1/workspace/api-keys/{id} | Immediately invalidates; no undo |
| Create webhook | POST /api/v1/workspace/webhooks | Requires URL and at least one subscribed event |
| Test webhook | POST /api/v1/workspace/webhooks/{id}/test | Sends a synthetic test payload to the registered URL; response shows delivery status |
Page 12: Audit and Logs
Route: /agents/audit
Immutable audit trail for the workspace with full-text search, filtering, and export. No edit or delete controls are rendered anywhere on this page; the API returns 405 Method Not Allowed for any mutation request against /api/v1/audit.
+---------------------------------------------------------------+
| Header: "Audit Trail" |
+---------------------------------------------------------------+
| +----------+ +----------+ +----------+ +----------+ |
| | Total | | Agent | | Security | | Policy | |
| | Events | | Actions | | Events | |Violations| |
| +----------+ +----------+ +----------+ +----------+ |
+---------------------------------------------------------------+
| Search | Agent Filter | Date Range | Event Type | [Grid/Table]|
| [Export] |
+---------------------------------------------------------------+
| Timestamp | Event Type | Agent | User | Action | Status |
| [Expand Detail -- full JSON payload] |
+---------------------------------------------------------------+
| Pagination |
+---------------------------------------------------------------+
Feature Specification
| Feature | Behavior |
|---|---|
| Stats Cards | 4 cards: Total Events, Agent Actions (tool executions + run transitions), Security Events (auth events, access changes, permission denials), Policy Violations. |
| Search | Full-text search across event description, agent name, and user name. Server-side via ?q={text}. |
| Agent Filter | ComboBox listing all workspace agents. Filters events to a single agent. |
| Date Range | Picker with presets: Last 24h, Last 7 days, Last 30 days, Last 90 days. |
| Event Type Filter | Options: All, Agent Actions, Security, Policy, System, Approvals. Maps to audit_event_type categories. |
| View Toggle | Table view (detailed rows) and Grid view (card layout). Each entry shows the same data; layout only differs. |
| Audit Table | Columns: Timestamp (ISO 8601), Event Type (color-coded badge), Agent, User, Action description, Status (success / failure / blocked). |
| Expandable Row | Click any row to expand: full event payload rendered as formatted JSON, including tool arguments, response data, and reasoning context where available. |
| Export | GET /api/v1/audit/export with current filter state. Small exports (under 10,000 rows): direct file download. Large exports: queued delivery via email with an estimated wait time shown to the user. |
Event Type Color Coding
| Event Type | Badge Color | Examples |
|---|---|---|
| Agent Action | Blue | Tool executed, run started, run completed |
| Security | Red | Authentication event, access control change, permission denied |
| Policy | Orange | Policy evaluated, policy violation, governance override |
| System | Gray | Agent created, agent deployed, configuration changed |
| Approval | Purple | Approval requested, approved, rejected, expired |
API Calls
| Trigger | Endpoint | Store Update |
|---|---|---|
| Page mount | GET /api/v1/audit?page=1&limit=50 | auditStore.entries |
| Filter change | GET /api/v1/audit?type={t}&agent={id}&from={t}&to={t}&q={q} | Replaces auditStore.entries |
| Export | GET /api/v1/audit/export | Triggers direct download or queued email |
Real-Time Integration Architecture
WebSocket Endpoints
| Endpoint | Subscribed By | Events Received |
|---|---|---|
/ws/agent-runs/{execution_id} | Run Detail page, Agent Detail Activity tab (when a run is active) | run_started, turn_reasoning, tool_called, tool_result, approval_requested, approval_resolved, run_completed, run_failed |
/ws/monitoring | System Monitoring page, Agent Library (metric card updates) | run_started, run_completed, alert_triggered, cluster_health_updated |
/ws/approvals | Runs Management page, Agent Detail Governance tab | approval_created, approval_resolved |
All WebSocket connections are authenticated using the JWT subprotocol header: Sec-WebSocket-Protocol: Bearer {access_token}.
Connection Lifecycle
Reconnection policy: All WebSocket connections use exponential backoff on unexpected disconnect: initial retry at 1 second, doubling up to a 30-second maximum. After 5 consecutive failed reconnection attempts, the component renders an "Unable to stream live updates -- retrying..." banner and falls back to polling the equivalent HTTP endpoint at 10-second intervals. Intentional closes (component unmount) do not trigger reconnection.
State Management Architecture
Zustand Store Definitions
| Store | Owns | Key State Fields |
|---|---|---|
agentStore | Agent CRUD, list management, creation drafts | agents[], selectedAgent, selectedAgentMetrics, versions[], filters, viewMode, wizardDraft, aiDraft, summaryMetrics |
executionStore | Run list, active run state, live log stream | runs[], selectedRun, logs[], filters, summary, wsConnected |
approvalStore | Approval request management | approvals[], selectedApproval, pendingCount |
templateStore | Template browsing and selection | templates[], selectedTemplate, filters, viewMode |
monitoringStore | System-wide metrics and alerts | status, activeRuns[], pendingApprovals[], wsConnected |
settingsStore | Workspace settings state | settings, originalSettings, isDirty, saving |
auditStore | Audit log browsing and export | entries[], filters, stats, exporting |
Store Invalidation Rules
| Action | Invalidates |
|---|---|
| Agent lifecycle transition (pause, deploy, archive) | agentStore.selectedAgent, agentStore.agents (update in place) |
Run completed (via WebSocket run_completed event) | executionStore.runs, executionStore.selectedRun, agentStore.selectedAgentMetrics |
| Approval resolved | approvalStore.approvals, approvalStore.pendingCount, executionStore.runs (update matching entry status) |
| Agent configuration updated (new version deployed) | agentStore.selectedAgent, agentStore.versions |
| Settings tab saved | settingsStore.settings, settingsStore.originalSettings |
| Audit log viewed | No invalidation -- audit data is never mutated |
API Integration Pattern
All frontend API calls route through one of three channels. No frontend component calls the Backend service (:8005) or river-agent microservice (:8007) directly. TLO Gateway is the sole entry point for all three channels.
| Channel | Base URL | Auth | Use |
|---|---|---|---|
| HTTP | TLO_GATEWAY_URL/api/v1 | Authorization: Bearer {jwt} | All CRUD and query operations |
| File | STORAGE_GATEWAY_URL | Pre-signed URL embedded in request | Report and export downloads |
| WebSocket | TLO_GATEWAY_URL/ws | Sec-WebSocket-Protocol: Bearer {jwt} | Real-time streaming |
Implementation note: Engineers adding new frontend API calls must ensure the corresponding route is registered at TLO Gateway before the frontend feature ships. The frontend never bypasses TLO Gateway, even for internal service-to-service data (e.g., metrics from the monitoring service are exposed through TLO endpoints, not called directly).