# How DB-GPT's Generative Business Intelligence (GBI) Generates Analytical Reports from Data

> Discover how DB-GPT's GBI transforms natural language into analytical reports. Learn about automated anomaly detection root-cause attribution and synthesis for actionable business insights.

- Repository: [eosphoros/DB-GPT](https://github.com/eosphoros-ai/db-gpt)
- Tags: how-to-guide
- Published: 2026-02-23

---

**DB-GPT's Generative Business Intelligence (GBI) uses a multi-agent workflow orchestrated by AWEL to transform natural-language questions into structured Markdown reports through automated anomaly detection, root-cause attribution, and synthesis.**

DB-GPT is an open-source AI-native data app development framework that implements GBI as a deterministic pipeline of specialized agents. Unlike traditional BI tools that require manual dashboard creation, the GBI system interprets business questions, retrieves metrics from configured data sources, and automatically produces analytical narratives complete with anomaly detection and volatility analysis.

## The GBI Multi-Agent Architecture

The GBI pipeline consists of three core agents that execute sequentially, each exposing a clear input-output schema via Pydantic models. The orchestration engine reads the `next_speakers` field from each agent's `ActionOutput` to determine the execution chain.

### Anomaly Detection Agent

The **Anomaly Detection Agent** serves as the first analytical layer. It receives raw metric data from the `MetricInfoRetriever` plugin and calculates the fluctuation rate between baseline and current values using the formula `fluctuation_rate = (current - baseline) / baseline`. If the absolute rate exceeds a defined threshold, the agent marks the metric as anomalous and triggers the next stage.

- **Implementation**: [`AnomalyDetectionAction`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/agent/agents/expand/actions/anomaly_detection_action.py) (lines 64-124)
- **Key Logic**: Computes fluctuation rates and returns `is_anomaly` boolean in the output schema

### Volatility (Attribution) Analysis Agent

Triggered only when an anomaly is detected, the **Volatility Analysis Agent** performs drill-down analysis across suggested dimensions such as region, product, or time segments. It calculates contribution rates for each factor to identify root causes, producing a ranked list of attributions that explain why the metric changed.

- **Implementation**: [`VolatilityAnalysisAgent`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/agent/agents/expand/volatility_analysis_agent.py) (lines 14-55)
- **Output**: Dimension-level contribution rates (e.g., `{"APAC": -0.30, "EMEA": -0.10}`)

### Report Generation Agent

The final **Report Generation Agent** consolidates outputs from previous stages into a cohesive Markdown document. It merges the anomaly detection results, attribution analysis, and original user question into a structured narrative. The agent supports visual rendering through the `VisReportGeneration` protocol and configures `max_new_tokens=4096` to accommodate lengthy analytical reports.

- **Agent Implementation**: [`ReportGenerationAgent`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/agent/agents/expand/report_generation_agent.py) (lines 14-50)
- **Action Implementation**: [`ReportGenerationAction`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/agent/agents/expand/actions/report_generation_action.py) (lines 34-84)
- **Render Protocol**: [`VisReportGeneration`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-core/src/dbgpt/vis/tags/vis_report_generation.py) (lines 11-26) returns Markdown content for UI display

## The GBI Data Pipeline Step-by-Step

The complete workflow follows a deterministic sequence orchestrated by DB-GPT's Agentic Workflow Expression Language (AWEL):

1. **Metric Retrieval**: The `MetricInfoRetriever` plugin queries the configured data source (SQL databases, Excel files, or data warehouses) to fetch the numeric series relevant to the user's question.

2. **Anomaly Detection**: The `AnomalyDetectionAgent` processes the metric values and calculates fluctuation rates. If no anomaly is detected, the pipeline may terminate early or skip to report generation with standard metrics.

3. **Attribution Analysis**: When anomalies exist, the `VolatilityAnalysisAgent` executes dimensional drill-downs, computing contribution rates for each factor to determine root causes.

4. **Report Synthesis**: The `ReportGenerationAgent` gathers all analysis results and formats them into a Markdown document with headers, bullet points, and quantitative insights.

5. **Visualization**: The `VisReportGeneration` protocol wraps the final Markdown content into a view object that the Chat Dashboard UI renders directly.

## Implementation Details and Code Examples

### Using the Python SDK

The simplest way to invoke the GBI pipeline is through the DB-GPT client SDK, which automatically handles the AWEL workflow orchestration:

```python
from dbgpt_client.client import DBGPTClient

client = DBGPTClient(base_url="http://localhost:8000")
question = "Why did sales drop in the APAC region last month?"

# Triggers: MetricInfoRetriever → AnomalyDetection → VolatilityAnalysis → ReportGeneration

report = client.chat.ask(question)

print(report)  # Markdown report with anomaly detection & root-cause attribution

```

### Direct Agent Invocation

For unit testing or custom workflows, you can instantiate the agents directly:

```python
from dbgpt_serve.agent.agents.expand.report_generation_agent import ReportGenerationAgent
from dbgpt_serve.agent.agents.expand.actions.report_generation_action import ReportGenerationAction

# Simulate previous analysis results from upstream agents

analysis_results = [
    {
        "metric_name": "sales",
        "baseline_value": 120000,
        "current_value": 95000,
        "fluctuation_rate": -0.1458,
        "is_anomaly": True,
        "anomaly_type": "decrease"
    },
    {
        "dimension": "region",
        "contribution_rate": {"APAC": -0.30, "EMEA": -0.10}
    }
]

# Initialize and execute report generation

action = ReportGenerationAction()
output = await action.run(
    ai_message="Generate a markdown report from the above analysis.",
    rely_action_out=None,
    need_vis_render=True,
    # analysis_results passed via request schema

)

print(output.content)  # JSON string containing markdown report

```

### AWEL Workflow Definition

The orchestration logic can be defined declaratively using AWEL:

```yaml
---
name: gbi_workflow
steps:
  - name: metric_retriever
    plugin: MetricInfoRetriever
  - name: anomaly_detection
    agent: AnomalyDetector
  - name: volatility_analysis
    agent: VolatilityAnalyzer
    when: "{{ anomaly_detection.output.is_anomaly }}"
  - name: report_generation
    agent: ReportGenerator
---

```

## Key Source Files in DB-GPT

| File Path | Component Role |
|-----------|----------------|
| [`packages/dbgpt-serve/src/dbgpt_serve/agent/agents/expand/actions/anomaly_detection_action.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/agent/agents/expand/actions/anomaly_detection_action.py) | Calculates fluctuation rates and anomaly flags |
| [`packages/dbgpt-serve/src/dbgpt_serve/agent/agents/expand/volatility_analysis_agent.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/agent/agents/expand/volatility_analysis_agent.py) | Performs dimensional drill-down and attribution |
| [`packages/dbgpt-serve/src/dbgpt_serve/agent/agents/expand/report_generation_agent.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/agent/agents/expand/report_generation_agent.py) | Orchestrates final report assembly |
| [`packages/dbgpt-serve/src/dbgpt_serve/agent/agents/expand/actions/report_generation_action.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/agent/agents/expand/actions/report_generation_action.py) | Executes Markdown synthesis and view creation |
| [`packages/dbgpt-core/src/dbgpt/vis/tags/vis_report_generation.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-core/src/dbgpt/vis/tags/vis_report_generation.py) | Defines the visualization protocol for report rendering |
| `examples/awel/` | Sample workflow definitions demonstrating agent chaining |

## Summary

- **DB-GPT GBI** implements a three-agent pipeline: Anomaly Detection → Volatility Analysis → Report Generation.
- **AnomalyDetectionAction** in [`anomaly_detection_action.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/anomaly_detection_action.py) (lines 64-124) computes fluctuation rates to identify metric anomalies.
- **VolatilityAnalysisAgent** performs root-cause attribution only when anomalies are detected, calculating dimension-level contribution rates.
- **ReportGenerationAgent** synthesizes outputs into Markdown using `max_new_tokens=4096`, with `VisReportGeneration` handling UI rendering.
- **AWEL orchestration** manages agent sequencing through the `next_speakers` field in `ActionOutput`, enabling deterministic workflow execution from natural language to analytical report.

## Frequently Asked Questions

### What triggers the volatility analysis step in DB-GPT GBI?

The volatility analysis agent executes conditionally based on the `is_anomaly` flag returned by the `AnomalyDetectionAction`. If the calculated fluctuation rate exceeds the threshold (indicating a significant metric change), the AWEL orchestrator routes the workflow to `VolatilityAnalysisAgent` to perform dimensional drill-down; otherwise, the pipeline may proceed directly to report generation or terminate.

### How does DB-GPT GBI handle data source connectivity?

The GBI pipeline uses the `MetricInfoRetriever` plugin to abstract data source connections. This plugin supports SQL databases, Excel files, and data warehouses, fetching numeric time-series data that feeds into the `AnomalyDetectionAgent`. The retrieval happens automatically when using the Python SDK `client.chat.ask()` method.

### What format do GBI reports use for output?

GBI reports are generated as structured Markdown documents. The `ReportGenerationAction` combines analysis results into a cohesive narrative with headers, bullet points, and quantitative insights, then wraps them in a `VisReportGeneration` view object. This allows DB-GPT's Chat Dashboard UI to render the content directly while maintaining the raw Markdown for export or further processing.

### Can I customize the anomaly detection threshold in GBI?

Yes, the anomaly detection threshold is configurable within the `AnomalyDetectionAction` implementation. The agent compares the absolute value of the calculated `fluctuation_rate` against this threshold to determine the `is_anomaly` boolean. For production deployments, you can extend the action class or modify the configuration parameters passed through the AWEL workflow definition.