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

<Tabs>
  <Tab title="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>

  <Tab title="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>

  <Tab title="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
  </Tab>
</Tabs>

## Agentic Loop

The Insights Agent operates as an iterative reasoning loop:

<Steps>
  <Step title="Receive question">
    The agent receives the user's question along with conversation history (for multi-turn context) and the data connection schema.
  </Step>

  <Step title="Plan analysis">
    The LLM determines the analysis strategy: direct SQL query, multi-step analysis, Python computation, or visualization.
  </Step>

  <Step title="Execute tools">
    The agent calls the appropriate tool or sub-agent. Results are captured and fed back into the reasoning loop.
  </Step>

  <Step title="Evaluate results">
    The LLM evaluates whether the results answer the question completely. If not, it plans additional steps.
  </Step>

  <Step title="Generate response">
    Once the analysis is complete, the agent formats the final response with text, data, and optional visualizations.
  </Step>
</Steps>

## 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](/guides/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

<CardGroup cols={2}>
  <Card title="Chat With Data" icon="comments" href="/data-insights/chat-with-data">
    See the full conversational analytics pipeline.
  </Card>

  <Card title="Text-to-SQL" icon="code" href="/data-insights/text-to-sql">
    Deep dive into the SQL generation agent.
  </Card>

  <Card title="Visualizations" icon="chart-pie" href="/data-insights/visualizations">
    Learn how the Insights Agent generates charts.
  </Card>
</CardGroup>