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
Python-Based Analysis
Multi-Step 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.

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()]

Agentic Loop

The Insights Agent operates as an iterative reasoning loop:

Receive question

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

Plan analysis

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

Execute tools

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

Evaluate results

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

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., `vertex_ai/gemini-3.5-flash`, `vertex_ai/claude-opus-4-8`, `openai/gpt-5.5`)
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.

Data Insights

Data Governance

Semiconductor

Customer Admin Guide

Analysis Agent

Analysis Agent

Role in the Architecture

Capabilities

Agentic Loop

Tool Orchestration

Event Streaming

LLM Configuration

Error Handling

Conversation State

Next Steps

Chat With Data

Text-to-SQL

Visualizations

​Analysis Agent

​Role in the Architecture

​Capabilities

​Agentic Loop

​Tool Orchestration

​Event Streaming

​LLM Configuration

​Error Handling

​Conversation State

​Next Steps

Chat With Data

Text-to-SQL

Visualizations

Analysis Agent

Role in the Architecture

Capabilities

Agentic Loop

Tool Orchestration

Event Streaming

LLM Configuration

Error Handling

Conversation State

Next Steps