River Agents
Persistent, governed, autonomous AI workers that inhabit business processes, operate on six trigger types, and enforce governance boundaries across the RiverGen data ecosystem.
Quick Navigation
Overview
A River Agent is a deployed, versioned, stateful worker. It is assigned to a specific business domain, configured with explicit triggers, and governed by policy throughout its operational lifetime.
Each agent run follows the same path: a trigger fires, Backend :8005 assembles the AgentContext (instructions, tools, memory, data source schemas, governance constraints), river-agent :8007 runs the agentic loop turn by turn, governance checks gate or block every write-capable action, and the run record -- including every reasoning turn, tool call, observation, and approval decision -- is written to the immutable audit trail in river_agents.audit_logs.
River Agents add to the core reasoning engine: persistent identity, immutable version snapshots, six trigger types, a 9-state lifecycle state machine, long-term memory accumulated across runs, Temporal-backed approval hibernation, a governance policy engine, and a real-time monitoring and alerting surface.
Platform Context
River Agents is the persistent workforce layer of RiverGen. Where Prompt Studio handles on-demand, session-scoped queries, River Agents are long-lived workers deployed to specific business domains. The key distinction: a River Agent has a persistent identity, a version history, configured triggers, accumulated memory across runs, governance policies, and a 9-state lifecycle -- none of which exist in the on-demand flow.
The three backend services that implement River Agents:
| Service | Port | Role |
|---|---|---|
| Backend (FastAPI) | :8005 | All persistent state, lifecycle management, approval processing, audit |
| TLO Gateway (FastAPI) | :8001 | JWT validation, per-tool ACL, route proxy |
| river-agent (FastAPI) | :8007 | Stateless reasoning: receives AgentContext, returns ReasoningResult |
Key Concepts
| Concept | Description |
|---|---|
| Agentic Loop | The Reason -> Act -> Observe cycle executed by river-agent :8007 per reasoning turn |
| Action Level | One of four enforcement modes (Read and Respond, Recommend, Act with Approval, Fully Automated) applied to every write-capable tool call |
| Trigger | One of six signal types (Manual, Scheduled, Event, Workflow, API, Threshold) that initiate an agent run |
| AgentContext | The complete context bundle assembled by Backend :8005 and passed to river-agent on every reasoning turn: instructions, tools, memory, schema metadata, governance constraints |
| Long-Term Memory | Per-agent summarized learnings written to agent_memory after each successful run; injected into the next run's AgentContext |
| Approval Gate | HITL checkpoint implemented via Temporal workflow.await() -- suspends execution with zero compute cost until a human approves, rejects, or edits the proposed action |
| HITL | Human-in-the-loop approval checkpoint; the approval record is stored in approval_requests, notifications dispatched via Novu |
| State Serialization | Full AgentContext (conversation history, pending tool call, observations) written to agent_executions.context_snapshot at approval gate; deserialized on signal receipt to resume exactly |
| Multi-LLM Routing | Per-turn model tier selection (Fast, Balanced, Reasoning, Coding) via RiverCore across 4+ providers; failover handled within the turn |
| Immutable Versioning | Every deployed configuration snapshot is write-locked in agent_versions; any change to a live agent creates a new version |
Documentation Sections
System Overview
Vision, product positioning, 4 action levels, 6 trigger types, 9 lifecycle states, 8 agent categories, the universal agent object model, and design philosophy.
Architecture Layers
Deep-dive into the 8 core functional layers: Agent Definition, Trigger Ingestion, Runtime Orchestration, Reasoning, Data Access, Tool Execution, Governance, and Observability.
Core Services Specification
Service-by-service specification of all 9 backend microservices with API endpoint definitions, internal component descriptions, and inter-service dependency maps.
Execution Flow and Runtime Lifecycle
The complete 9-step universal runtime flow with sequence diagrams, approval gate mechanics, error handling and recovery, real-time telemetry, and multi-agent pipeline coordination.
Implementation Blueprints
End-to-end blueprints for all 8 agent categories: goal definition, configuration, UX description, execution flow diagrams, backend requirements, and example outputs.
Frontend Integration and UX
Specification of all 12 UI pages including layout diagrams, feature tables, user journey flows, WebSocket integration, and state management architecture.
Data Model and Schema Specification
Complete database schema with ER diagram, 11 core table definitions, 25+ JSONB column specifications, foreign key cascade rules, indexing strategy, and tenant isolation constraints.
Governance, Safety and Security
4-level autonomy model with decision matrix, per-tool ACL, approval gate mechanics, policy enforcement engine, 5-layer defense-in-depth, audit event types, and compliance capabilities.
Backend API Specification
All 61 REST endpoints across 16 groups -- Agent CRUD, Lifecycle, Versions, Triggers, Data Sources, Tools, Policies, Metrics, AI Generation, Templates, Runs, Approvals, Monitoring, Settings, and Audit.
TLO Gateway Routing Specification
JWT authentication flow, context propagation headers, 40+ route registrations, ACL permission matrix for 8 permissions across 7 roles, proxy client configuration, and WebSocket integration.
River-Agent Microservice Architecture
The stateless reasoning service: 6-step agentic loop, multi-LLM routing via RiverCore across 4 model tiers, all 17 tool specifications, error recovery, governance integration, and deployment configuration.
Schema Design Document
Comprehensive river_agents database documentation: 15 tables, 14 schema-scoped enums, design conventions, JSONB patterns, cross-schema references, key query patterns, and Alembic migration strategy.
Frontend-Backend API Contract
TypeScript type definitions, page-by-page API call specifications for all 12 pages, 7 Zustand store designs, 8 WebSocket event types, error handling contracts, and cache invalidation rules.
Agent Categories
River Agents are typed into 8 domain categories, each with a dedicated implementation blueprint, configuration defaults, and example outputs.
| # | Category | Primary Function |
|---|---|---|
| 1 | Customer Support | Autonomous support triage, resolution, and escalation |
| 2 | Sales and Lead Qualification | Lead scoring, enrichment, and pipeline progression |
| 3 | Finance and Reconciliation | Automated reconciliation, anomaly detection, and reporting |
| 4 | Risk and Compliance | Continuous monitoring, violation detection, and audit generation |
| 5 | Data Analyst and Insights | Scheduled analysis, metric tracking, and report generation |
| 6 | Operations Monitoring | Infrastructure health, threshold alerting, and incident response |
| 7 | Executive Decision Support | KPI summarization, trend analysis, and briefing generation |
| 8 | Custom Enterprise | User-defined domain with configurable tools and data sources |
Quick Reference
| Dimension | Specification |
|---|---|
| Agent Categories | 8 |
| Action Levels | 4 -- Read and Respond, Recommend, Act with Approval, Fully Automated |
| Trigger Types | 6 -- Manual, Scheduled, Event, Workflow, API, Threshold |
| Lifecycle States | 9 -- Draft, Configured, Validated, Deployed, Active, Running, Awaiting Approval, Paused, Archived |
| Architecture Layers | 8 |
| Backend Services | 3 -- Backend :8005, TLO Gateway :8001, river-agent :8007 |
| API Endpoints | 61 across 16 endpoint groups |
| Frontend Pages | 12 |
| Database Tables | 15 in the river_agents schema |
| Database Enums | 14 schema-scoped |
| JSONB Schemas | 25+ documented with field-level specifications |
| ACL Permissions | 8 in the agent: namespace |
| WebSocket Events | 8 server-to-client, 1 client-to-server |
| Agent Tools | 17 -- 6 reasoning, 10 execution, 1 interaction |
| Zustand Stores | 7 |
| Security Layers | 5 |
| Documentation Sections | 13 |
Repository Locations
| Component | Path |
|---|---|
| Backend service | /opt/rgen/rgen-repo-backend/rgen-backend/ |
| River-agent microservice | /opt/rgen/rgen-repo-ai/rgen-ai/river-agent/ |
| Database schema file | /opt/rgen/rgen-repo-backend/rgen-backend/db/river-agents-schema.sql |