# Leveraging the Data Interpreter for Advanced Data Analysis Tasks in MetaGPT

> Master advanced data analysis with MetaGPT Data Interpreter. This tool autonomously generates and refines Python code using a REACT loop for powerful insights.

- Repository: [FoundationAgents/MetaGPT](https://github.com/FoundationAgents/MetaGPT)
- Tags: how-to-guide
- Published: 2026-03-04

---

**The MetaGPT Data Interpreter autonomously generates, executes, and refines Python analysis code through a REACT-style loop with integrated tool recommendation and reflection capabilities.**

MetaGPT's Data Interpreter transforms natural-language data analysis requests into self-healing Python workflows. By combining a planning engine with notebook-style code execution, this role automates complex pipelines—from preprocessing and feature engineering to model training—without requiring manual boilerplate. This guide examines the interpreter's architecture, implementation patterns, and extension points based on the FoundationAgents/MetaGPT source code.

## What Is the MetaGPT Data Interpreter?

The **Data Interpreter** is a specialized `Role` subclass that orchestrates autonomous data analysis through an iterative think-act-execute cycle. Unlike static code generators, it maintains **working memory** across iterations, validates intermediate results, and can retry failed executions with reflected improvements.

Key capabilities include:

- **Autonomous planning** with task decomposition
- **Tool recommendation** via BM25 retrieval for context-aware tool selection
- **Interactive code execution** in isolated notebook kernels
- **Data validation** with automatic sanity checks on transformed datasets
- **Reflection-based debugging** for self-correcting failed attempts

## Core Architecture and Components

The interpreter's functionality is distributed across specialized actions and roles defined in the `metagpt/roles/di/` and `metagpt/actions/di/` directories.

### DataInterpreter Role

The central orchestrator resides in [`metagpt/roles/di/data_interpreter.py`](https://github.com/FoundationAgents/MetaGPT/blob/main/metagpt/roles/di/data_interpreter.py). This class extends the base `Role` to implement a REACT-style loop with configurable modes:

```python
class DataInterpreter(Role):
    name: str = "David"
    profile: str = "DataInterpreter"
    auto_run: bool = True
    use_plan: bool = True
    react_mode: Literal["plan_and_act", "react"] = "plan_and_act"
    max_react_loop: int = 10

```

*Source:* lines 36-46 of [[`metagpt/roles/di/data_interpreter.py`](https://github.com/FoundationAgents/MetaGPT/blob/main/metagpt/roles/di/data_interpreter.py)](https://github.com/FoundationAgents/MetaGPT/blob/main/metagpt/roles/di/data_interpreter.py#L36-L46)

### WriteAnalysisCode Action

Located in [`metagpt/actions/di/write_analysis_code.py`](https://github.com/FoundationAgents/MetaGPT/blob/main/metagpt/actions/di/write_analysis_code.py), this action handles LLM prompt construction and code generation. It supports an optional reflection step for debugging failed executions through the `_debug_with_reflection` method (lines 23-34).

The action receives:
- User requirements
- Current plan status
- Tool hints from the recommender
- Previous execution history from working memory

### CheckData and ExecuteNbCode Actions

**CheckData** performs post-execution validation on datasets after preprocessing or model training tasks. It injects dataset summaries (`DATA_INFO`) back into memory to inform subsequent planning iterations.

**ExecuteNbCode** manages the Jupyter-like kernel environment, executing generated Python code in isolation and returning output strings with success flags.

## The REACT Loop: How the Data Interpreter Works

The interpreter operates through a structured cognitive cycle that mimics human data analysis workflows.

### Planning and Tool Recommendation

When initialized with tools, the interpreter creates a **BM25ToolRecommender** (lines 55-58 of [`data_interpreter.py`](https://github.com/FoundationAgents/MetaGPT/blob/main/data_interpreter.py)) that suggests relevant tools based on the current task context. This enables dynamic tool selection without hardcoded logic.

### Think and Act Phases

In `react` mode, the `_think` method (lines 65-84) queries the LLM with `REACT_THINK_PROMPT` to generate structured thoughts and determine if additional actions are required. The `_act` phase then invokes `_write_and_exec_code` (lines 107-148), which:

1. Generates Python via `WriteAnalysisCode.run`
2. Executes via `ExecuteNbCode.run`
3. Stores results in working memory
4. Returns structured status messages

### Data Validation and Reflection

Before each iteration, `_check_data` (lines 70-90) validates datasets when the current task involves preprocessing, feature engineering, or model training. If execution fails and `use_reflection` is enabled, `_debug_with_reflection` generates improved code using the previous implementation and error context.

## Practical Implementation: Using the DataAnalyst Role

For end-users, MetaGPT provides the `DataAnalyst` concrete role in [`metagpt/roles/di/data_analyst.py`](https://github.com/FoundationAgents/MetaGPT/blob/main/metagpt/roles/di/data_analyst.py). This wrapper pre-configures the interpreter with the `write_and_exec_code` tool, enabling immediate use without manual setup.

```python
import fire
from metagpt.logs import logger
from metagpt.roles.di.data_analyst import DataAnalyst

async def main():
    # ① Create the role

    analyst = DataAnalyst()

    # ② Define the high-level goal for the planner

    analyst.planner.plan.goal = "construct a two-dimensional array"

    # ③ Append a concrete DATA_ANALYSIS task

    analyst.planner.plan.append_task(
        task_id="1",
        dependent_task_ids=[],
        instruction="construct a two-dimensional array",
        assignee="David",
        task_type="DATA_ANALYSIS",
    )

    # ④ Let the interpreter write and execute the code

    result = await analyst.write_and_exec_code("construct a two-dimensional array")

    # ⑤ Log the final structured output

    logger.info(result)

if __name__ == "__main__":
    fire.Fire(main)

```

*Source:* [[`examples/di/data_analyst_write_code.py`](https://github.com/FoundationAgents/MetaGPT/blob/main/examples/di/data_analyst_write_code.py)](https://github.com/FoundationAgents/MetaGPT/blob/main/examples/di/data_analyst_write_code.py)

**Execution flow:**
1. `write_and_exec_code` constructs a plan status string and retrieves tool hints
2. `WriteAnalysisCode.run` prompts the LLM to generate Python (e.g., `import numpy as np; arr = np.arange(9).reshape(3,3)`)
3. `ExecuteNbCode.run` evaluates the code in an isolated kernel and returns the matrix output
4. The interpreter formats the result with `CODE_STATUS` (e.g., `"Success ✅"`)

## Key Source Files and Their Responsibilities

| File | Purpose |
|------|---------|
| [`metagpt/roles/di/data_interpreter.py`](https://github.com/FoundationAgents/MetaGPT/blob/main/metagpt/roles/di/data_interpreter.py) | Core REACT loop, tool recommendation, memory handling, and error retry logic |
| [`metagpt/actions/di/write_analysis_code.py`](https://github.com/FoundationAgents/MetaGPT/blob/main/metagpt/actions/di/write_analysis_code.py) | LLM prompt templates, code generation, and optional reflection debugging |
| [`metagpt/roles/di/data_analyst.py`](https://github.com/FoundationAgents/MetaGPT/blob/main/metagpt/roles/di/data_analyst.py) | Concrete user-facing role exposing `write_and_exec_code` |
| [`metagpt/prompts/di/write_analysis_code.py`](https://github.com/FoundationAgents/MetaGPT/blob/main/metagpt/prompts/di/write_analysis_code.py) | System messages (`INTERPRETER_SYSTEM_MSG`, `STRUCTUAL_PROMPT`) guiding LLM output |
| [`metagpt/actions/di/execute_nb_code.py`](https://github.com/FoundationAgents/MetaGPT/blob/main/metagpt/actions/di/execute_nb_code.py) | Jupyter-like kernel execution for generated Python |
| [`examples/di/data_analyst_write_code.py`](https://github.com/FoundationAgents/MetaGPT/blob/main/examples/di/data_analyst_write_code.py) | End-to-end demonstration of the DataAnalyst workflow |

## Extending the Data Interpreter

The modular architecture enables customization for specialized analysis workflows.

### Adding Custom Tools

Populate the `custom_tools` list when instantiating `DataAnalyst` (e.g., `"SQL"`, `"PandasProfile"`). The built-in `BM25ToolRecommender` automatically surfaces relevant tool-usage guidance based on the current task context, enabling dynamic tool selection without hardcoded logic.

### Enabling Reflection and Debugging

Set `use_reflection = True` (enabled by default) to activate the `_debug_with_reflection` method in `WriteAnalysisCode`. When execution fails, this triggers a debugging LLM prompt that receives the previous implementation and error context to generate improved code automatically.

## Summary

- The **Data Interpreter** in MetaGPT provides an autonomous REACT-style loop for advanced data analysis, combining planning, code generation, and execution in [`metagpt/roles/di/data_interpreter.py`](https://github.com/FoundationAgents/MetaGPT/blob/main/metagpt/roles/di/data_interpreter.py).
- **WriteAnalysisCode** and **ExecuteNbCode** handle LLM prompt construction and isolated notebook execution, respectively, enabling safe, iterative code refinement.
- The **DataAnalyst** role offers a production-ready wrapper that exposes `write_and_exec_code` for immediate use without manual configuration.
- Built-in **reflection** and **BM25 tool recommendation** support self-healing workflows and dynamic tool selection for complex preprocessing, feature engineering, and modeling tasks.

## Frequently Asked Questions

### How does the Data Interpreter handle execution errors?

When code execution fails, the interpreter checks the `use_reflection` flag (enabled by default). If active, it invokes `_debug_with_reflection` in `WriteAnalysisCode`, which sends the failed implementation and error traceback to the LLM with a debugging prompt. The LLM returns a corrected code snippet, and the interpreter retries execution up to the configured maximum loop count.

### What is the difference between DataInterpreter and DataAnalyst?

`DataInterpreter` is the abstract base class in [`metagpt/roles/di/data_interpreter.py`](https://github.com/FoundationAgents/MetaGPT/blob/main/metagpt/roles/di/data_interpreter.py) that implements the core REACT loop, memory management, and tool recommendation. `DataAnalyst` in [`metagpt/roles/di/data_analyst.py`](https://github.com/FoundationAgents/MetaGPT/blob/main/metagpt/roles/di/data_analyst.py) is a concrete subclass that pre-configures the interpreter with the `write_and_exec_code` tool and default settings, providing a ready-to-use interface for end-users without requiring manual action registration.

### Can I use custom Python libraries in the Data Interpreter?

Yes. The `ExecuteNbCode` action runs generated code in a Jupyter-like kernel environment, which supports any library installed in the Python environment. When extending the interpreter, you can guide the LLM to import specific packages by modifying the system prompts in [`metagpt/prompts/di/write_analysis_code.py`](https://github.com/FoundationAgents/MetaGPT/blob/main/metagpt/prompts/di/write_analysis_code.py) or by providing tool hints through the `custom_tools` parameter to influence code generation patterns.