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

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 (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 (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 (lines 14-50)
• Action Implementation: ReportGenerationAction (lines 34-84)
• Render Protocol: VisReportGeneration (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:

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:

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:

---
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	Calculates fluctuation rates and anomaly flags
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	Orchestrates final report assembly
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	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 (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}