Agents

Binexia has eight specialized agents, grouped by when they run.

On-Demand Agents

Triggered by user actions (asking a question, clicking a widget).

OrchestratorAgent

The router. Receives every user query and decides which specialist agent handles it:

• Structured data question ("What's our revenue?") → AnalyticsAgent
• Unstructured knowledge question ("What's our refund policy?") → KnowledgeAgent
• Dashboard context (user clicked a data point) → ContextAgent

Uses the semantic model's schema_context and vocabulary to classify the query.

AnalyticsAgent

Text-to-SQL specialist. Converts natural language questions into SQL queries:

1. Reads schema_context from the semantic model
2. Generates SQL via litellm using the configured provider
3. Executes SQL via ubios_reader (read-only, statement timeout)
4. Returns structured data + chart configuration

Results are cached in Redis (5 min TTL). Repeat queries skip the LLM entirely.

KnowledgeAgent

RAG specialist. Answers questions from uploaded documents:

1. Embeds the question using the same model as document chunks
2. Searches tenant_knowledge.document_chunks with pgvector similarity
3. Passes top-k chunks as context to the LLM
4. Returns a grounded answer with source citations

ContextAgent

Context panel specialist. When a user clicks on any data element:

1. Fetches entity data from Redis (pre-cached by nightly agents)
2. Generates a natural language explanation of what the data means
3. Suggests related metrics and drill-down options

Explanations are cached 5 min TTL.

Scheduled Agents

Triggered by cron schedules defined in tenant_agent_state.scheduled_jobs.

BehavioralScoringAgent

Scores customers on churn risk and upsell probability:

• Analyzes booking frequency, recency, spend trends
• Outputs risk scores (0–1) with recommended actions
• Runs weekly (0 6 * * 1)
• High-risk customers trigger notifications

AnomalyDetectionAgent

Detects statistical anomalies in key metrics:

• Monitors cancellation rates, revenue, booking volume, supplier SLA
• Uses standard deviation thresholds (flags at >2σ)
• Runs daily (0 8 * * *)
• Critical anomalies trigger immediate notifications

ForecastAgent

Generates revenue and booking forecasts:

• Uses historical patterns and seasonal trends
• Outputs projected values with confidence intervals
• Runs monthly (0 7 1 * *)

DocumentExtractionAgent

Extracts structured fields from uploaded documents:

• Works alongside Dify for the chunking/embedding pipeline
• Synthesizes key fields (amounts, dates, parties) from document text
• Triggered on document upload

Agent Outputs

All agent results are stored in tenant_agent_state.agent_outputs:

Agent Sessions

Each conversation with an agent creates a session in agent_sessions. Sessions track context, message history, and token usage across multiple turns.