Skip to main content

# Data Analysis Tools

Agent Mesh includes a suite of optional built-in tools that enable agents to perform data analysis tasks directly on artifacts. These tools provide functionality for SQL querying, JQ transformations, and Plotly chart generation.

## Setup and Configuration​

Enable the data analysis tool group in the agent's `app_config.yml` file.

    # In your agent's app_config:
    tools:
      - tool_type: builtin-group
        group_name: "data_analysis"

    # Optional: Configure tool behavior
    data_tools_config:
      sqlite_memory_threshold_mb: 100
      max_result_preview_rows: 50
      max_result_preview_bytes: 4096

## Available Tools​

### `query_data_with_sql`​

Enterprise Only

This feature is available in the Enterprise Edition only.

Executes a SQL query against data stored in a CSV or SQLite artifact.

- Parameters:
  - `input_filename` (str): The filename of the input artifact (for example, `'data.csv'`, `'mydatabase.sqlite'`). Supports versioning (for example, `'data.csv:2'`).
  - `sql_query` (str): The SQL query string to execute.
  - `output_format` (str, optional): The desired format for the output artifact (`'csv'` or `'json'`). Defaults to `'csv'`.
- Behavior:
  - For CSV Input: The tool loads the CSV data into a temporary in-memory SQLite database table named `data` and executes the query against it.
  - For SQLite Input: The tool connects directly to the specified SQLite database artifact in read-only mode.
- Returns: A dictionary containing the execution status, a preview of the query result, and the `output_filename` where the full result set is stored.

### `create_sqlite_db`​

Enterprise Only

This feature is available in the Enterprise Edition only.

Converts a CSV or JSON artifact into a persistent SQLite database artifact. This is the recommended approach for executing multiple queries on the same dataset, as it avoids repeated parsing of the source file.

- Parameters:
  - `input_filename` (str): The filename of the input CSV or JSON artifact.
  - `output_db_filename` (str): The desired filename for the output SQLite database artifact (for example, `'queryable_dataset.sqlite'`).
  - `table_name` (str, optional): The name of the table to be created within the SQLite database. Defaults to `'data'`.
- Returns: A dictionary confirming the successful creation of the database artifact and providing its `output_filename`.

### `transform_data_with_jq`​

Enterprise Only

This feature is available in the Enterprise Edition only.

Applies a JQ expression to transform data from a JSON, YAML, or CSV artifact.

- Parameters:
  - `input_filename` (str): The filename of the input artifact.
  - `jq_expression` (str): The JQ filter or transformation expression string (for example, `'.users[] | {name, id}'`).
- Returns: A dictionary containing the execution status, a preview of the transformed data, and the `output_filename` where the full JSON result is stored.

### `create_chart_from_plotly_config`​

Generates a static chart image (for example, PNG, JPG, SVG) from a Plotly configuration provided as a string.

- Parameters:
  - `config_content` (str): A JSON or YAML formatted string representing the Plotly `figure` dictionary.
  - `config_format` (str): Specifies whether `config_content` is `'json'` or `'yaml'`.
  - `output_filename` (str): The desired filename for the output image artifact (for example, `'sales_chart.png'`).
  - `output_format` (str, optional): The desired image format (`'png'`, `'jpeg'`, `'svg'`, etc.). Defaults to `'png'`.
- Returns: A dictionary confirming the chart's creation and providing its `output_filename`.

## Example Workflow: Querying a Large CSV​

The following workflow demonstrates an efficient method for analyzing a large CSV file:

1. User Request: "I need to run several queries on `large_data.csv`."
2. Agent Strategy: The agent determines that converting the CSV to a SQLite database is more performant for subsequent queries.
3. Agent Call 1: The agent calls `create_sqlite_db` to convert `large_data.csv` into a new artifact, `queryable_data.sqlite`.
4. Agent Response: "The data has been prepared for querying. What is your first question?"
5. User Request: "Find all records where the category is 'Sales'."
6. Agent Call 2: The agent calls `query_data_with_sql`, targeting the `queryable_data.sqlite` artifact.
7. Agent Response: The agent provides the results of the query.
8. User Request: "Now, find the average amount for the 'Marketing' category."
9. Agent Call 3: The agent calls `query_data_with_sql` again on the same `queryable_data.sqlite` artifact, avoiding the overhead of reprocessing the original CSV file.

## Technical Considerations​

### Result Handling​

- Previews: For `query_data_with_sql` and `transform_data_with_jq`, the tools return a truncated preview of the result directly to the LLM for immediate context.
- Full Results: The complete, untruncated result sets are always saved as new artifacts. The LLM is provided with the filename and version of these artifacts.
- Accessing Full Results: To utilize the full results, the agent can employ file management tools (`load_artifact`) or Dynamic Embeds (`«artifact_content:...»`).

### Security​

- SQL Execution: Queries against existing SQLite artifacts are performed in read-only mode to prevent data modification. Queries against temporary databases generated from CSVs are isolated.
- JQ Execution: JQ expressions are executed within a sandboxed Python library, not via shell execution.
- Resource Usage: Complex queries or transformations can be resource-intensive. Monitor performance and resource consumption accordingly.