> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emergence.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': {'lineColor': '#555555', 'fontFamily': 'sans-serif', 'edgeLabelBackground': '#ffffff'}}}%%
flowchart TD
    T2D["Talk2Data Service (8080)<br/>user-facing gateway"]
    IA["Insights Agent (8002)<br/>reasoning engine (agentic loop)"]
    SQL["Text2SQL Agent (8001)<br/>SQL generation + execution"]
    CODE["Coding Agent (8004)<br/>Python code generation"]
    MCP["MCP Plotly Server (8000)<br/>visualization tools"]

    T2D -->|A2A| IA
    IA -->|A2A| SQL
    IA -->|A2A| CODE
    IA -->|MCP| MCP

    classDef gateway fill:#56B4E9,stroke:#555555,color:#000
    classDef agent fill:#E69F00,stroke:#555555,color:#000
    classDef tool fill:#009E73,stroke:#555555,color:#000
    class T2D gateway
    class IA,SQL,CODE agent
    class MCP tool
```

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

> [tab] 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.

> [tab] 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
>
> ```python theme={null}
> # 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()]
> ```

> [tab] 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:

```python theme={null}
# 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](https://docs.emergence.ai/guides/langfuse-setup.md) 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

> [card] [Chat With Data](https://docs.emergence.ai/data-insights/chat-with-data.md)
>
> See the full conversational analytics pipeline.

> [card] [Text-to-SQL](https://docs.emergence.ai/data-insights/text-to-sql.md)
>
> Deep dive into the SQL generation agent.

> [card] [Visualizations](https://docs.emergence.ai/data-insights/visualizations.md)
>
> Learn how the Insights Agent generates charts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.