Agent Flow

The agent flow is the core "Intent to Insights" workflow of the MATIH Platform. A user asks a natural language question, and the AI Service orchestrates a pipeline of specialized agents that classify intent, generate SQL, execute queries, analyze results, and recommend visualizations.

End-to-End Flow

Browser               AI Service           Query Engine    Trino
  |                      |                      |            |
  | POST /api/v1/ai/chat |                      |            |
  | "What was revenue    |                      |            |
  |  last quarter?"      |                      |            |
  |--------------------->|                      |            |
  |                      |                      |            |
  |           1. Establish tenant context        |            |
  |           2. Load/create session             |            |
  |           3. RouterAgent: classify intent    |            |
  |              --> Intent: SQL_QUERY           |            |
  |           4. SQLAgent: generate SQL          |            |
  |              Context: schema from catalog    |            |
  |              Context: MDL from semantic-layer|            |
  |              Context: similar queries (RAG)  |            |
  |                      |                      |            |
  |           5. Execute generated SQL           |            |
  |                      |--------------------->|            |
  |                      |                      |----------->|
  |                      |                      |  Trino     |
  |                      |                      |  executes  |
  |                      |                      |<-----------|
  |                      |  Result set          |            |
  |                      |<---------------------|            |
  |                      |                      |            |
  |           6. AnalysisAgent: interpret results|            |
  |           7. VizAgent: recommend chart       |            |
  |           8. Update session state            |            |
  |           9. Publish audit event (Kafka)     |            |
  |                      |                      |            |
  | Response             |                      |            |
  | {answer, sql,        |                      |            |
  |  data, chart_config} |                      |            |
  |<---------------------|                      |            |

Agent State Machine

The AI Service orchestrator manages the flow as a LangGraph state machine:

START
  |
  v
ROUTE (RouterAgent classifies intent)
  |
  +----> SQL_QUERY ------> GENERATE_SQL (SQLAgent)
  |                            |
  |                            v
  |                         EXECUTE_QUERY (via query-engine)
  |                            |
  |                            v
  |                         ANALYZE (AnalysisAgent)
  |                            |
  |                            v
  |                         VISUALIZE (VizAgent)
  |                            |
  |                            v
  |                         RESPOND
  |
  +----> ANALYSIS -------> ANALYZE (AnalysisAgent)
  |                            |
  |                            v
  |                         RESPOND
  |
  +----> DOCUMENTATION --> DOCS (DocumentationAgent)
  |                            |
  |                            v
  |                         RESPOND
  |
  v
END (session updated)

Agent Responsibilities

Agent	Input	Output	LLM Call
RouterAgent	User message + session context	Intent classification	Yes
SQLAgent	Intent + schema metadata + RAG examples	SQL query	Yes
AnalysisAgent	Query results + original question	Natural language insight	Yes
VizAgent	Results + insight	Chart type and configuration	Rule-based + LLM
DocumentationAgent	Question about data terms	Definition and context	Yes (RAG)

RAG Context Sources

The SQLAgent retrieves context from multiple sources to improve SQL generation accuracy:

Source	Service	Content
Schema metadata	Catalog Service	Table names, column names, data types
Business metrics	Semantic Layer	Metric definitions, dimension hierarchies
Similar queries	Vector Store (Qdrant)	Previously successful SQL for similar questions
Business terms	Ontology Service	Business term definitions and relationships

Timing Breakdown

Step	Typical Duration
Gateway processing	2-5ms
Intent classification (RouterAgent)	200-500ms
SQL generation (SQLAgent)	500-2000ms
Query execution (Trino)	50-5000ms
Result analysis (AnalysisAgent)	300-1000ms
Visualization recommendation (VizAgent)	100-300ms
Total (typical)	1-8 seconds

Streaming Response

For long-running queries, the AI Service streams tokens via Server-Sent Events:

AI Service --> Redis Pub/Sub --> WebSocket Bridge --> Browser

SSE: data: {"token": "Revenue", "index": 0}
SSE: data: {"token": " last", "index": 1}
SSE: data: {"token": " quarter", "index": 2}
SSE: data: {"token": " was", "index": 3}
...
SSE: data: {"done": true, "sql": "SELECT ...", "data": [...]}

Session Management

Each conversation is tracked in a session:

Session Field	Description
`session_id`	Unique session identifier
`tenant_id`	Tenant scope
`user_id`	Authenticated user
`messages`	Conversation history
`context`	Accumulated context (schemas, queries)
`state`	Current state machine state

Follow-up questions use session context to modify queries without re-specifying the full context.

Query Flow -- SQL execution details
Browser to Gateway -- Initial request path
Event-Driven Architecture -- Audit event publishing

Query Flow Pipeline Flow