Implementation Blueprints

This document provides the engineering reference for all 8 River Agent categories. Each blueprint specifies the recommended configuration profile, the runtime execution sequence, backend integration requirements, and non-obvious implementation constraints. These blueprints are the direct input for frontend, backend, and AI engineers implementing or extending each agent category.

Quick Navigation

• Blueprint Reference Index
• Customer Support Agent
• Sales and Lead Qualification Agent
• Finance and Reconciliation Agent
• Risk and Compliance Agent
• Data Analyst and Insights Agent
• Operations Monitoring Agent
• Executive Decision Support Agent
• Custom Enterprise Agent
• Cross-Cutting Implementation Notes

Blueprint Reference Index

Category	Default Action Level	Primary Trigger	Write Authority	Approval Required
Customer Support	Act with Approval	Event	Ticket updates, refunds	Yes -- refunds and responses above confidence threshold
Sales and Lead Qualification	Recommend	Event	CRM record updates	N/A -- no execution, suggestions only
Finance and Reconciliation	Act with Approval	Scheduled	Ledger write-backs	Yes -- always, no auto-approve
Risk and Compliance	Act with Approval	Event + Threshold	Access revocation, incident tickets	Yes -- access changes always gated
Data Analyst and Insights	Read and Respond	Manual + Scheduled	None	N/A -- read-only
Operations Monitoring	Fully Automated	Threshold	Infrastructure operations	None -- time-critical remediation
Executive Decision Support	Read and Respond	Scheduled	None	N/A -- read-only
Custom Enterprise	Configurable	Configurable	Configurable	Configurable

---

Customer Support Agent

Configuration Profile

Field	Value
Name	L1/L2 Technical Support Specialist
Business Function	customer_support
Action Level	Act with Approval
Governance Level	Strict
Triggers	Event: ticket.created, ticket.updated_by_customer / Manual: enabled
Data Sources	Zendesk (read/write), Confluence (read), Stripe (read)
Tools	search_knowledge_base, get_ticket_history, draft_response, escalate_ticket, issue_refund, send_ticket_response
Approval Rules	Always require approval for issue_refund. Require approval for draft_response unless confidence_score > 0.95.

Execution Sequence

The following sequence traces a refund request ticket from Zendesk webhook receipt through knowledge base lookup, Stripe charge verification, approval-gated refund execution, and response dispatch.

Backend Requirements

• Zendesk webhook ingestion endpoint registered for ticket.created and ticket.updated_by_customer event types
• Confluence-to-Qdrant indexing pipeline: crawls Confluence spaces on a schedule and upserts embeddings into the vector store
• get_ticket_history query must aggregate across the Zendesk API and any linked CRM records, then summarize older tickets using a Fast-tier LLM before injecting into context -- raw ticket text from high-volume customers will exceed context budget
• Confidence scoring for draft_response: combine policy match score (cosine similarity to retrieved policy chunks) with LLM self-assessment output; the compound score drives the auto-approve threshold
• Stripe integration requires read scope for charge lookup and write scope for refund dispatch, scoped per workspace credentials

Implementation Notes

Context budget management: The get_ticket_history tool must truncate and summarize ticket histories longer than a configurable token threshold before returning. A customer with 50+ prior tickets will blow the context budget if raw history is injected. The summarization step uses a Fast-tier LLM call inside the tool implementation, not in the reasoning loop.

Confidence score auto-approve path: The auto-approve rule for draft_response (confidence > 0.95) is evaluated by the Governance Service, which receives the confidence score as a field in the tool call arguments. The reasoning engine must populate this field explicitly. If it is absent, governance defaults to requiring approval.

Approval state on draft_response: Even when draft_response is auto-approved, an ApprovalRequest record is still created with status AUTO_APPROVED and immediately resolved. This preserves the full audit trail for every response sent by the agent.

---

Sales and Lead Qualification Agent

Configuration Profile

Field	Value
Name	Inbound Lead Qualifier
Business Function	sales_lead_qualification
Action Level	Recommend
Triggers	Event: form.submitted, lead.created
Data Sources	Salesforce CRM (read/write), Company Enrichment API (read)
Tools	enrich_company_data, query_crm, update_crm_record, generate_lead_summary, assign_lead
Approval Rules	N/A -- Recommend level, all tool calls logged as suggestions, none executed

Execution Sequence

At Recommend level, every tool call that writes data is surfaced as a suggestion card in the UI. The agent never mutates CRM records autonomously -- it produces a structured recommendation that the sales team accepts, modifies, or discards.

Backend Requirements

• Webhook endpoint for marketing form submissions (form.submitted) and CRM-native lead events (lead.created)
• Company enrichment API integration (Clearbit, ZoomInfo, or equivalent) with domain-based lookup
• Salesforce SOQL adapter with read scope for opportunity and contact entities; write scope reserved for accepted recommendations
• Lead scoring model: rule-based implementation (employee count thresholds, industry match, revenue tier) is sufficient for initial deployment; ML-based scoring can be substituted by replacing the scoring logic in the tool implementation

Implementation Notes

Recommend level execution model: At Recommend level, the Governance Service intercepts every write tool call and substitutes a SUGGEST_ONLY observation. The tool is never dispatched to TLO Gateway. The recommendation payload is stored in the AgentExecution.recommendations column and exposed via the API for the frontend to render as suggestion cards.

Accepted recommendation execution: When a sales rep accepts a suggestion, the frontend calls POST /api/v1/agents/recommendations/{id}/accept. This triggers a separate, minimal execution -- not a new full agent run -- that dispatches only the accepted tool call through TLO Gateway with the rep's identity as executed_by. The audit trail records both the agent's recommendation and the human acceptance as separate events.

Enrichment API rate limiting: High-volume lead flows (e.g., conference list imports) can hit enrichment API rate limits. The enrich_company_data tool implementation must cache enrichment results by domain with a configurable TTL (default: 7 days) to avoid redundant API calls and stay within rate limits.

---

Finance and Reconciliation Agent

Configuration Profile

Field	Value
Name	Daily Transaction Reconciliation Auditor
Business Function	finance_reconciliation
Action Level	Act with Approval (ledger writes); Read and Respond (queries)
Triggers	Scheduled: 0 8 * * 1-5 (8 AM, weekdays)
Data Sources	Internal Ledger (PostgreSQL, read), Stripe (API, read), Bank Feed (API, read)
Tools	execute_query, generate_reconciliation_query, generate_report, send_slack_alert, update_ledger_status
Approval Rules	Always require approval for update_ledger_status. No auto-approve path -- financial data always requires human sign-off.

Large Data Architecture

LLMs cannot process 100,000+ rows of ledger data in a single context. This agent uses the semantic SQL generation pattern: the LLM generates targeted SQL that aggregates and compares data at the database level, returning only the mismatch subset (typically under 50 rows) to the reasoning context.

Execution Sequence

Anomaly Classification Rules

These rules are part of the agent's instruction_set and are injected into the AgentContext. The reasoning engine evaluates each mismatch against these criteria to assign a classification and severity.

Classification	Condition	Severity	Recommended Action
Timing Issue	Stripe status = pending AND ledger status = missing	Low	Monitor; likely in-flight transaction; re-check next run
Critical Discrepancy	Stripe amount differs from ledger amount	High	Investigate; flag for manual review
Fraud Risk	Ledger status = settled AND Stripe status = failed	Critical	Immediately flag; notify fraud team
Duplicate Entry	Same transaction_id appears multiple times in ledger	Medium	Data integrity audit; deduplication required

Backend Requirements

• generate_reconciliation_query tool must produce SQL that performs the JOIN and classification in a single pass at the database level; the tool should accept a source schema descriptor and return executable SQL without a separate schema-discovery step
• Bank Feed API adapter (Plaid, TrueLayer, or direct banking API) for a third-leg reconciliation check beyond Stripe
• MinIO write access for report upload; the report path format is reconciliation/{date}/{execution_id}.csv
• The update_ledger_status tool must be idempotent -- re-running a reconciliation for the same date must not create duplicate flagged_for_review records

---

Risk and Compliance Agent

Configuration Profile

Field	Value
Name	Data Policy Compliance Monitor
Business Function	risk_compliance
Action Level	Act with Approval
Triggers	Event: user.exported_data, user.changed_permissions, data.access_anomaly / Threshold: anomaly_score > 0.8
Data Sources	Activity Logs (PostgreSQL, read), Policy Database (read), User Directory (read)
Tools	evaluate_policy, create_incident_ticket, revoke_user_access, send_pagerduty_alert, generate_evidence_package
Approval Rules	Always require approval for revoke_user_access. Auto-approve create_incident_ticket only if severity is below High.

Execution Sequence

Backend Requirements

• Event bus subscription endpoint for system activity events; the event bus must support per-event-type routing to avoid broadcasting all system events to every compliance agent
• Policy evaluation engine: rules stored in a dedicated compliance_policies table, evaluated per-event using a rule matching engine (not the LLM); the LLM interprets the result, it does not evaluate the policy itself
• Evidence packaging service: collects and bundles the triggering event log, the user's activity history from the past 30 days, and the matching policy rule text into a single immutable artifact stored in MinIO
• PagerDuty integration for CISO-tier alerts; severity mapping: Critical events page immediately, High events send Slack only
• Integration with identity management (Active Directory, Okta, or equivalent) for the revoke_user_access tool; the tool must support scope-limited revocation (per-table, per-resource) not just full account suspension

Implementation Notes

Auto-approve threshold boundary: The auto-approve rule for create_incident_ticket (severity < High) means Low and Medium severity tickets are auto-approved; High and Critical always go through the approval gate. The severity value is returned by evaluate_policy -- the Governance Service reads it from the tool call arguments, not from a separate classification step.

Evidence package immutability: The generated evidence package must be written to MinIO with object lock enabled. A compliance officer must not be able to delete or modify evidence after it is created. The MinIO path is embedded in the ApprovalRequest payload so the approver can access it directly from the approval UI without navigating to a separate system.

Event deduplication: The same event (e.g., a large export) may trigger multiple compliance agents if more than one is configured for user.exported_data. Each agent produces its own independent incident. The event bus must stamp each trigger with a unique event_id; the generate_evidence_package tool uses this ID to deduplicate evidence collection if called multiple times for the same event.

---

Data Analyst and Insights Agent

Configuration Profile

Field	Value
Name	Business Intelligence Analyst
Business Function	data_analyst_insights
Action Level	Read and Respond
Triggers	Manual (ad-hoc queries), Scheduled (recurring reports)
Data Sources	Data Warehouse (Snowflake, read), Marketing DB (PostgreSQL, read), Support DB (read)
Tools	execute_query, search_catalog, generate_query, recommend_visualization, explain_results, generate_report
Approval Rules	N/A -- Read and Respond level, no write operations permitted

Execution Sequence

Backend Requirements

• Semantic catalog: a queryable index of all connected data sources with table names, column descriptions, and domain tags; must support fuzzy natural-language search to map user intent to the correct table without schema knowledge from the user
• generate_query tool must validate generated SQL against the actual schema before returning it as an observation; a query with a non-existent column must return a validation error observation, not execute a failing query
• Query result size guard: execute_query must enforce a row limit (default: 500 rows) and return a truncation warning if the result set is larger; the LLM must be prompted to generate more targeted queries if truncation occurs
• Report generation writes to MinIO; the generate_report tool returns a pre-signed URL valid for the workspace's configured download TTL

Implementation Notes

generate_query validation step: The tool implementation must run an EXPLAIN or dry-run parse against the target database before marking the query as valid. This prevents the reasoning loop from consuming a turn on a query that will fail at execution time due to a column name hallucination.

Scheduled report delivery: When triggered by a scheduled cron, the explain_results output and generate_report artifact are delivered to the configured notification channel. The delivery uses the same send_email or send_slack_alert tool as other categories -- there is no separate report delivery mechanism.

---

Operations Monitoring Agent

Configuration Profile

Field	Value
Name	Infrastructure Health Guardian
Business Function	operations_monitoring
Action Level	Fully Automated
Triggers	Threshold: cpu_percent > 90 for 5m, error_rate > 5%, workflow_failure_count > 3 in 1h
Data Sources	Monitoring API (Datadog / Prometheus, read), Temporal Metrics (read), Database Metrics (read)
Tools	get_active_queries, kill_query, restart_workflow, scale_infrastructure, send_slack_alert, page_oncall, get_workflow_logs
Approval Rules	None -- Fully Automated; all actions are logged but not gated by any approval

Execution Sequence

At Fully Automated level, the entire execution from threshold breach to remediation and notification is ungated. The resolution path below resolves a runaway query causing CPU saturation; similar logic applies to workflow failures and error rate spikes.

Backend Requirements

• Threshold trigger subscriptions must be configured per workspace with cooldown enforcement to prevent the same alert from firing the same agent multiple times in rapid succession during a sustained incident
• kill_query and restart_workflow tools require elevated database and infrastructure credentials; these must be stored as workspace-scoped secrets in the credential store, not embedded in the tool configuration
• The runbook instruction_set for this agent category defines the decision tree (check queries first, then connection count, then memory) -- this ordering is critical for correct diagnosis and must be defined by the infrastructure team during agent configuration
• page_oncall tool integration with PagerDuty or Opsgenie; only triggered by the agent if automated remediation fails and the issue persists beyond a second assessment turn

Implementation Notes

Fully Automated accountability: Despite having no approval gate, every action taken by this agent is written to audit_logs before execution. The log entry records the tool name, arguments, governance decision (FULLY_AUTOMATED), executing agent version, and execution timestamp. This is the primary accountability mechanism for ungated operations.

Threshold cooldown vs. agent re-trigger: The threshold trigger handler enforces a cooldown period (e.g., 15 minutes) after an agent fires for a given threshold condition. If the CPU remains elevated after the cooldown, a second execution fires. This prevents the agent from taking the same remediation action twice in rapid succession before the first action's effects propagate.

Remediation scope guard: The kill_query and scale_infrastructure tools must reject calls with overly broad scope. For example, kill_query(user="*") should be rejected by the tool implementation; only PID-scoped or max-duration-scoped termination is permitted.

---

Executive Decision Support Agent

Configuration Profile

Field	Value
Name	Weekly Executive Briefing Analyst
Business Function	executive_decision_support
Action Level	Read and Respond
Triggers	Scheduled: 0 7 * * 1 (Monday, 7 AM)
Data Sources	CRM Warehouse (read), Operations Metrics (read), Support DB (read), Financial DB (read)
Tools	execute_query, search_catalog, explain_results, generate_report, send_email
Approval Rules	N/A -- Read and Respond level, no write operations

Multi-Domain Synthesis Sequence

This agent runs four sequential domain queries, synthesizes cross-domain correlations, and produces a traceable executive brief. All domain queries use the same execute_query tool with different source bindings.

Traceability Architecture

Every metric in the executive brief carries an embedded TraceID that links back to the exact query that produced it. This is the primary mechanism for preventing hallucination in executive-facing output.

Step	Behavior
execute_query returns results	Tool implementation stamps each result set with a unique TraceID in the format ts-{execution_id}-{turn}-{source}
explain_results includes TraceIDs	The synthesis prompt instructs the LLM to embed the relevant TraceID next to every numeric metric it cites
Report generation preserves TraceIDs	PDF template renders each metric with a hover-linked footnote pointing to the TraceID
UI trace lookup	Hovering a metric in the UI calls GET /api/v1/agent-logs/{trace_id}, returning the exact SQL query, the data source name, the raw numeric output, and the execution timestamp

Implementation note: The TraceID embedding relies on prompt engineering in the instruction_set -- the agent must be explicitly instructed to include TraceIDs in its synthesis. If this instruction is missing from the template, the LLM will omit them. This is a template configuration requirement, not a runtime enforcement.

Backend Requirements

• Report template system with a dedicated executive_brief template that renders multi-domain sections, highlights cross-domain correlations in a distinct visual block, and renders TraceID footnotes
• send_email tool must support multi-recipient delivery with PDF attachment; email addresses are drawn from WorkspaceSettings.executive_brief_recipients, not hardcoded in the agent config
• TraceID generation must happen inside the tool implementation, not in the reasoning engine -- the LLM must not generate its own TraceIDs

---

Custom Enterprise Agent

Configuration Profile (Employee Onboarding Example)

Field	Value
Name	New Hire Onboarding Coordinator
Triggers	Event: hr.new_hire_confirmed
Action Level	Act with Approval
Tools	create_ad_account, assign_security_groups, provision_laptop, create_badge_request, add_to_distribution_lists, schedule_orientation, notify_manager
Approval Rules	Always require approval for assign_security_groups (security-sensitive); auto-approve all others

Dynamic Tool Registration

Custom agents can integrate any enterprise API by uploading an OpenAPI specification. The Tool Registry parses the spec and generates typed tools that the agent can call through TLO Gateway.

Execution Sequence (Employee Onboarding)

Backend Requirements for Custom Agents

• OpenAPI specification parser supporting OAS 3.0 and 3.1; must extract operation ID, summary, parameters (path, query, body), and response schemas into the tool registry format
• Dynamic tool schema validation: generated Pydantic schemas must be validated before the agent can be deployed; invalid or ambiguous parameter schemas must block deployment with an explicit error message
• Per-agent webhook endpoint provisioning: each custom agent configured with a Webhook trigger gets a unique inbound URL at /api/v1/webhooks/{agent_id}/{secret}, scoped to the agent's workspace
• Variable tool execution routing: the TLO Gateway must resolve the target service URL from the workspace's registered service endpoints, not from hardcoded configuration in the tool definition
• Template marketplace: the 8 category blueprints are packaged as pre-built templates that pre-fill instruction_set, recommended tools, default action level, trigger configuration, and approval rules; template instantiation reduces configuration time from approximately 30 minutes to approximately 5 minutes

---

Cross-Cutting Implementation Notes

Data Handling at Scale

All agent categories that query large datasets use the semantic SQL generation pattern. The LLM generates targeted queries that filter and aggregate data at the database level, returning only the relevant subset to the reasoning context. Raw bulk data is never loaded into the LLM context.

Constraint	Value	Rationale
Max rows returned per query	500 (configurable)	Prevents context overflow; LLM should generate more targeted SQL if limit is hit
Max token budget for observations	2000 tokens per tool result	Enforced by TLO Gateway response formatter; truncation warning appended if exceeded
Older ticket / record summarization	Required before injection	get_ticket_history and similar tools must pre-summarize with a Fast-tier LLM call inside the tool implementation

Multi-Agent Pipeline Patterns

Agents are chained using Workflow triggers. The three standard pipeline topologies are:

Pattern	Description	Example
Sequential	Agent A completes, signals Agent B with its output	Data Collection -> Reconciliation -> Reporting
Fan-out	One event triggers multiple specialist agents in parallel	ticket.created -> Support Agent + Analytics Agent simultaneously
Conditional	Agent A's output determines which Agent B runs next	Risk Agent determines severity; high severity triggers Compliance Agent, low severity triggers Logging Agent only

All pipeline stages are independent executions. A failure in one stage does not propagate automatically to downstream stages -- the downstream agent never receives its trigger signal. Each stage must be monitored independently.

Template System

Each of the 8 blueprints has a corresponding pre-built template in the template marketplace. Templates pre-fill:

• instruction_set with domain-appropriate goal statements and reasoning guidelines
• Recommended tool bindings with placeholder data source references
• Default action_level and governance_level per the blueprint recommendation
• Common trigger configurations with example cron expressions or event type names
• Approval rule defaults that match the blueprint's compliance posture

Templates are versioned. When a template is updated, existing agents created from that template are not automatically updated -- the version is pinned at agent creation time.