Analysis Agent

How the Insights Agent performs multi-step analysis with LLM-generated Python code, reasoning loops, and tool orchestration.

Analysis Agent

The Insights Agent is the reasoning engine at the center of the Data Insights solution. It receives natural-language questions, determines the optimal analysis approach, and orchestrates tools and sub-agents to produce comprehensive answers.

Role in the Architecture

The Insights Agent sits between the Talk2Data Service (user-facing gateway) and specialized agents like Text2SQL:

It acts as an agentic loop — iteratively reasoning about the question, calling tools, analyzing intermediate results, and deciding whether to continue analysis or return a final answer.

Capabilities

SQL-Based Analysis

For questions that can be answered with database queries, the Insights Agent delegates to the Text2SQL Agent:

• “What were the top 10 products by revenue last quarter?”
• “How many active users do we have per region?”
• “Show me the trend of order values over the past 12 months”

The Insights Agent adds value by interpreting the results, identifying patterns, and generating follow-up analysis suggestions.

Python-Based Analysis

For complex analytical questions, the Insights Agent generates and executes Python code:

• Statistical analysis (correlations, distributions, outlier detection)
• Data transformations and pivots
• Time series forecasting
• Custom calculations not expressible in SQL

# Example: LLM-generated Python for correlation analysis
import pandas as pd
import numpy as np

df = pd.DataFrame(query_results)
correlation = df[['revenue', 'marketing_spend']].corr()
outliers = df[df['revenue'] > df['revenue'].mean() + 2 * df['revenue'].std()]

Multi-Step Analysis

For complex questions requiring multiple data gathering and analysis steps:

1. Query database for raw data
2. Analyze initial results
3. Generate follow-up queries based on findings
4. Synthesize a comprehensive answer
5. Generate visualizations for key findings

Agentic Loop

The Insights Agent operates as an iterative reasoning loop:

1. Receive question

   The agent receives the user’s question along with conversation history (for multi-turn context) and the data connection schema.

2. Plan analysis

   The LLM determines the analysis strategy: direct SQL query, multi-step analysis, Python computation, or visualization.

3. Execute tools

   The agent calls the appropriate tool or sub-agent. Results are captured and fed back into the reasoning loop.

4. Evaluate results

   The LLM evaluates whether the results answer the question completely. If not, it plans additional steps.

5. Generate response

   Once the analysis is complete, the agent formats the final response with text, data, and optional visualizations.

Tool Orchestration

The Insights Agent has access to multiple tools:

Tool	Purpose	Invocation
Text2SQL Agent	Generate and execute SQL queries	A2A delegation (port 8001)
Coding Agent	Run LLM-generated Python code for statistics, transformations, and analysis	A2A delegation (port 8004)
MCP Plotly Server	Generate interactive Plotly charts	MCP tool call (port 8000)
Schema inspector	Retrieve database schema details	Direct database metadata query

Event Streaming

Throughout the analysis, the Insights Agent emits real-time events via the A2A protocol:

# Status events keep the user informed of progress
await event_queue.put(TaskStatusUpdateEvent(
    status="working",
    message="Analyzing your data..."
))

# Artifact events deliver results
await event_queue.put(TaskArtifactUpdateEvent(
    artifact=Artifact(
        parts=[DataPart(data=results), TextPart(text=analysis)]
    )
))

Users see progress messages in the chat interface: “Analyzing schema…”, “Running query…”, “Computing statistics…”, followed by the final answer.

LLM Configuration

The Insights Agent uses LiteLLM for provider-agnostic LLM access:

Setting	Configuration
Client	commons.llm.LLMClient wrapping LiteLLM
Model format	provider/model (e.g., gemini/gemini-2.0-flash, gpt-4o)
Observability	Langfuse LLM tracing auto-enabled when LANGFUSE_HOST is set, traces LLM calls, token usage, and cost. See Langfuse Setup for configuration.
Configuration	pydantic_settings.BaseSettings with .env file support

Error Handling

The Insights Agent handles errors at each stage of the analysis:

Error	Handling
Text2SQL fails	Retry with rephrased prompt or fall back to Python analysis
Python execution error	Return error details to LLM for correction and retry
LLM timeout or rate limit	Retry with exponential backoff via tenacity
Data connection unavailable	Report connection error to the user

Conversation State

The agent maintains state via the Talk2Data Service’s session system:

• Sessions: Persistent conversation containers linked to a data connection
• Messages: Full conversation history with user and assistant messages
• Artifacts: Query results, visualizations, and analysis outputs stored per session
• Feedback: User feedback on answer quality for continuous improvement

Next Steps

Chat With Data

See the full conversational analytics pipeline.

Text-to-SQL

Deep dive into the SQL generation agent.

Visualizations

Learn how the Insights Agent generates charts.