Tutorial: Your First Natural Language Query

In this tutorial, you will use the MATIH Agentic Workbench to ask questions about your data in plain English. The platform's multi-agent AI system will interpret your question, generate SQL, execute it against your data source, and return the results -- all through a conversational interface.

What You Will Learn

• How to open the Agentic Workbench and start a conversation session
• How to ask natural language questions and receive structured answers
• How the multi-agent orchestrator routes your question to the right agent
• How to refine queries through follow-up questions
• How to inspect the generated SQL for transparency
• How to export results for further analysis

Prerequisites

Step 1: Open the Agentic Workbench

Navigate to the Agentic Workbench:

• Local development: http://localhost:3003
• Cloud deployment: https://agentic.{your-tenant}.matih.ai

Log in with your tenant credentials. You will see the conversation interface with a text input at the bottom and a sidebar showing your conversation history.

Step 2: Start a New Session

Click New Conversation in the sidebar (or use the keyboard shortcut). A new session is created with a unique identifier. The session maintains conversation context, so follow-up questions reference previous results.

Behind the scenes, this creates a ConversationSession with:

Step 3: Ask Your First Question

Type a natural language question in the input box and press Enter (or click Send).

Example question:

What were our total sales last month?

What Happens Behind the Scenes

The multi-agent orchestrator processes your question through several specialized agents:

Your Question: "What were our total sales last month?"
        |
        v
[Router Agent] -- Classifies intent as DATA_QUERY
        |
        v
[SQL Agent] -- Generates SQL from your question
        |    Uses: schema context from vector store, LLM for generation
        |
        v
[Query Engine] -- Executes the generated SQL
        |
        v
[Analysis Agent] -- Interprets results, generates narrative
        |
        v
[Visualization Agent] -- Suggests chart type for the data
        |
        v
Response displayed in the conversation

The Router Agent classifies your question into one of several intents:

The Response

The workbench displays the answer in a structured format:

Narrative answer:

Total sales last month were $1,247,832.50, representing a 12.3% increase compared to the previous month.

Data table:

Suggested visualization: Bar chart showing monthly sales trend.

Step 4: Inspect the Generated SQL

Click the Show SQL button (or the code icon) beneath the response to see the SQL that was generated:

SELECT
    DATE_TRUNC('month', order_date) AS month,
    SUM(total_amount) AS total_sales,
    COUNT(*) AS order_count,
    AVG(total_amount) AS avg_order_value
FROM orders
WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL '1' MONTH)
  AND order_date < DATE_TRUNC('month', CURRENT_DATE)
GROUP BY DATE_TRUNC('month', order_date)

The SQL generation pipeline:

1. Question parsing -- The QuestionParser extracts entities, time references, and aggregations from your question.
2. Schema retrieval -- The QdrantSchemaStore retrieves relevant table and column metadata using vector similarity search.
3. SQL generation -- The LLMClient generates SQL using the parsed question and schema context.
4. Validation -- The SQLValidator checks the generated SQL for syntax errors and safety issues.
5. Auto-correction -- If validation fails, the system automatically attempts to fix the SQL and regenerate.

Step 5: Ask a Follow-Up Question

Because the conversation maintains context, you can ask follow-up questions that reference previous results:

How does that compare to the same month last year?

The AI understands "that" refers to the total sales figure from your previous question. It generates a comparison query:

SELECT
    DATE_TRUNC('month', order_date) AS month,
    SUM(total_amount) AS total_sales
FROM orders
WHERE DATE_TRUNC('month', order_date) IN (
    DATE_TRUNC('month', CURRENT_DATE - INTERVAL '1' MONTH),
    DATE_TRUNC('month', CURRENT_DATE - INTERVAL '13' MONTH)
)
GROUP BY DATE_TRUNC('month', order_date)
ORDER BY month

Response:

Step 6: Try More Complex Questions

The AI can handle progressively complex analytical questions:

Aggregation with Filtering

What are the top 5 product categories by revenue this quarter?

Multi-Table Joins

Which customers have the highest return rates?

Time-Series Analysis

Show me the daily order trend for the past 30 days

Conditional Logic

What percentage of orders over $500 were returned?

Statistical Questions

What is the average time between a customer's first and second purchase?

Step 7: Request a Visualization

You can ask the AI to visualize results directly:

Show me a bar chart of monthly revenue for the past 12 months

The Visualization Agent interprets this request and generates a chart configuration. The result is rendered directly in the conversation as an interactive chart.

Supported chart types:

Step 8: Export Results

You can export query results in several formats:

Step 9: Manage Sessions

Viewing Session History

The sidebar shows all your conversation sessions. Click any session to resume it:

Clearing a Session

To start fresh with no context, click New Conversation to create a new session. Previous sessions remain available in the history.

Understanding the Agent Architecture

The conversation is powered by a multi-agent system built on the LangGraph pattern:

The agents communicate through a shared AgentState that maintains:

• Conversation history (all messages)
• Current intent classification
• Generated SQL queries
• Query execution results
• Visualization configurations
• Error context for retry logic

Tips for Better Results

Troubleshooting

Next Steps

Now that you can query data conversationally, proceed to Building a Dashboard to learn how to create persistent visualizations from your query results.