Skip to content

QUICK_START-en.md

Latest commit

 

History

History
379 lines (259 loc) · 13.9 KB

QUICK_START-en.md

File metadata and controls

379 lines (259 loc) · 13.9 KB
Raw

中文 | English

Quick Start

This document will guide you through the installation, configuration, and first run of DataAgent.

Prerequisites

  • JDK: 17 or higher
  • MySQL: 5.7 or higher
  • Node.js: 22 or higher
  • pnpm: 11 or higher
  • Docker: Required when a workflow executes Python steps; optional for SQL-only analysis
  • Vector Database: (Optional) Uses in-memory vector store by default

1. Business Database Preparation

You can get test tables and data from the project repository:

Files are located in: data-agent-management/src/main/resources/sql, which contains 4 files:

  • schema.sql - Table structure for features
  • data.sql - Data for features
  • product_schema.sql - Sample data table structure
  • product_data.sql - Sample data

Import the tables and data into your MySQL database.

# Example: Import using MySQL command line
mysql -u root -p your_database < data-agent-management/src/main/resources/sql/schema.sql
mysql -u root -p your_database < data-agent-management/src/main/resources/sql/data.sql
mysql -u root -p your_database < data-agent-management/src/main/resources/sql/product_schema.sql
mysql -u root -p your_database < data-agent-management/src/main/resources/sql/product_data.sql

2. Configuration

2.1 Configure Management Database

Configure your MySQL database connection in data-agent-management/src/main/resources/application.yml.

Initialization behavior: the default is spring.sql.init.mode: never, so DataAgent does not create tables or insert sample data automatically. Run the SQL files above before the first start, or set DATA_AGENT_DATASOURCE_SQL_INIT=always only when sample initialization is explicitly required.

spring:
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/saa_data_agent?useUnicode=true&characterEncoding=utf-8&zeroDateTimeBehavior=convertToNull&transformedBitIsBoolean=true&allowMultiQueries=true&allowPublicKeyRetrieval=true&useSSL=false&serverTimezone=Asia/Shanghai
    username: ${DATA_AGENT_DATASOURCE_USERNAME:root}
    password: ${DATA_AGENT_DATASOURCE_PASSWORD:root}
    driver-class-name: com.mysql.cj.jdbc.Driver

2.2 Data Initialization Configuration

Auto initialization is disabled by default (spring.sql.init.mode: never).

To change initialization behavior, see Developer Guide - Database Initialization.

2.3 Configure Model

If you need to manually manage model dependencies (not using default Starter), please refer to Developer Guide - Dependency Extension Configuration.

Start the project, click on Model Configuration, add a new model and fill in your API key.

add-model.png

  1. Standard Provider Integration: If you're using a built-in supported AI provider (like OpenAI, Deepseek, etc.), you usually only need to provide the Model Name and API Key.

  2. Custom and Local Model Integration (Ollama/Self-hosted Gateway): This system is based on Spring AI architecture and supports the standard OpenAI interface protocol. If you're connecting to Ollama or other custom gateways, please note the following:

    • Protocol Compatibility: Please refer to the Spring AI official documentation about OpenAI compatibility to ensure your gateway response format meets the standard.

    • Address Configuration: For self-deployed models, please accurately fill in the base-url and completions-path. The system will concatenate them into the complete call address, for example: http://localhost:11434/v1/chat/completions

  3. Troubleshooting: If the configuration doesn't work after setup, we recommend first using Postman to test your interface address to confirm network connectivity and parameter format are correct.

2.4 Embedding Model Batch Processing Strategy Configuration

For detailed configuration parameters, see Developer Guide - Embedding Batch Configuration.

2.5 Vector Store Configuration

The system uses an in-memory vector store by default, and also provides hybrid search support for Elasticsearch.

2.5.1 Vector Store Dependency Import

You can import your preferred persistent vector store. You just need to provide a bean of type org.springframework.ai.vectorstore.VectorStore to the IoC container. For example, directly import the PGvector starter:

<dependency>
	<groupId>org.springframework.ai</groupId>
	<artifactId>spring-ai-starter-vector-store-pgvector</artifactId>
</dependency>

For detailed vector store documentation, refer to: https://springdoc.cn/spring-ai/api/vectordbs.html

2.5.2 Vector Store Schema Setup

Below is the ES schema structure. For other vector stores like Milvus, PG, etc., you can create your own schema based on this ES structure. Pay special attention to the data type of each field in metadata.

{
  "mappings": {
    "properties": {
      "content": {
        "type": "text",
        "fields": {
          "keyword": {
            "type": "keyword",
            "ignore_above": 256
          }
        }
      },
      "embedding": {
        "type": "dense_vector",
        "dims": 1024,
        "index": true,
        "similarity": "cosine",
        "index_options": {
          "type": "int8_hnsw",
          "m": 16,
          "ef_construction": 100
        }
      },
      "id": {
        "type": "text",
        "fields": {
          "keyword": {
            "type": "keyword",
            "ignore_above": 256
          }
        }
      },
      "metadata": {
        "properties": {
          "agentId": {
            "type": "text",
            "fields": {
              "keyword": {
                "type": "keyword",
                "ignore_above": 256
              }
            }
          },
          "agentKnowledgeId": {
            "type": "long"
          },
          "businessTermId": {
            "type": "long"
          },
          "concreteAgentKnowledgeType": {
            "type": "text",
            "fields": {
              "keyword": {
                "type": "keyword",
                "ignore_above": 256
              }
            }
          },
          "vectorType": {
            "type": "text",
            "fields": {
              "keyword": {
                "type": "keyword",
                "ignore_above": 256
              }
            }
          }
        }
      }
    }
  }
}

2.5.3 Vector Store Configuration Parameters

For detailed configuration parameters, see Developer Guide - Vector Store Configuration.

2.6 Retrieval Fusion Strategy

For detailed configuration parameters, see Developer Guide - Vector Store Configuration.

2.7 Replace Vector Store Implementation

To replace the default in-memory vector store (for example, with PGVector or Milvus), see Developer Guide - Vector Store Dependency Extension.

The project ships two ready-to-use example profiles, application-milvus.yml and application-elasticsearch.yml. Switch quickly with SPRING_PROFILES_ACTIVE=milvus (or elasticsearch); see Developer Guide - Ready-to-Use Configuration Examples.

2.8 Configure the Python Sandbox

DataAgent uses the Spring AI Alibaba 1.1.2.2 Sandbox to run generated Python code. Every execution gets a task-scoped container; dynamic dependency installation, code execution, and container cleanup all happen inside that task.

Confirm that Docker is available:

docker info

The default configuration uses local Docker discovery, public PyPI, and the AgentScope base image. Development normally needs no override. To select a Docker endpoint, image, or private package index, set:

export DATAAGENT_SANDBOX_DOCKER_HOST=unix:///var/run/docker.sock
export DATAAGENT_SANDBOX_IMAGE=agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-base:latest
export DATAAGENT_PYPI_INDEX_URL=https://pypi.org/simple

Production should use a pinned image digest and an enterprise PyPI proxy, with infrastructure network policy that allows the sandbox to reach only that proxy. See Advanced Features - Python Execution Environment Configuration for the full configuration, dependency contract, and troubleshooting guidance.

3. Start Management Backend

Run the following command from the project root:

./mvnw -pl data-agent-management spring-boot:run

Or run DataAgentApplication.java directly in your IDE.

4. Start Web Frontend

Navigate to the data-agent-frontend-nuxt directory.

4.1 Install Dependencies

pnpm install

4.2 Start Service

pnpm dev

After successful startup, access http://localhost:3000

4.3 Verify Dynamic Python Dependencies

After configuring the agent, models, and data source, submit a request that explicitly includes a Python step:

Query the raw status and total_amount rows from orders, then aggregate them with Python.
Declare and import six==1.17.0 through PEP 723, and report the six version and status totals.

A successful timeline contains “Python Generation”, “Python Execution”, “Python Analysis”, and a final report. The Python output should contain six_version: 1.17.0. No task container should remain after completion:

docker ps --format '{{.Names}}' | grep '^dataagent-sandbox-'

No output means the task sandbox was removed. If dependency installation fails, the workflow feeds the error into the next Python generation attempt. After the configured retry limit, it enters the existing fallback or termination path.

5. System Experience

5.1 Creating and Configuring Data Agent

Visit http://localhost:3000 to see the current list of agents (there are four placeholder agents by default that are not connected to data; you can delete them and create new agents)

homepage-agents.png

Click "Create Agent" in the upper right corner. Here you only need to enter the agent name, and use default settings for other configurations.

agent-create.png

After creation, you can see the agent configuration page.

agent-config.png

Configure Data Source

Go to the data source configuration page and configure the business database (the business database we provided in the first step of environment initialization).

datasource-config.png

After adding, you can verify the data source connection on the list page.

datasource-validation.png

For newly added data sources, you need to select which data tables to use for data analysis.

datasource-tables.png

Then click the "Initialize Data Source" button in the upper right corner.

datasource-init.png

Configure Preset Questions

Preset question management allows you to set preset questions for the agent.

preset-questions.png

Configure Semantic Model

Semantic model management allows you to set semantic models for the agent. The semantic model library defines precise conversion rules from business terms to database physical structures, storing field name mappings. For example, customerSatisfactionScore corresponds to the csat_score field in the database.

semantic-models.png

Configure Business Knowledge

Business knowledge management allows you to set business knowledge for the agent. Business knowledge defines business terms and business rules, such as GMV = Gross Merchandise Volume, including paid and unpaid order amounts. Business knowledge can be set to recall or not recall. After configuration, click the "Sync to Vector Store" button in the upper right corner.

business-knowledge.png

After success, you can click "Go to Run Interface" to use the agent for data queries. After debugging is complete, you can publish the agent.

Note: "Access API" is not fully implemented in the current version and is reserved for secondary development.

5.2 Running the Data Agent

Run Interface

run-page.png

The left side of the run interface shows historical message records, and the right side shows current session records, input box, and request parameter configuration.

Enter a question in the input box and click the "Send" button to start querying.

analyze-question.png

The analysis report is in HTML format. Click the "Download Report" button to download the final report.

analyze-result.png

Run Modes

Besides the default request mode, the agent runtime also supports "Human Feedback", "NL2SQL Only", "Concise Report", and "Show SQL Results" modes.

Default Mode

By default, human feedback mode is not enabled. The agent automatically generates and executes the plan, parses SQL execution results, and generates a report.

Human Feedback Mode

If human feedback mode is enabled, the agent will wait for user confirmation after generating the plan, then modify or execute the plan based on the user's selected feedback result.

feedback-mode.png

NL2SQL Only Mode

"NL2SQL Only Mode" makes the agent only generate SQL and retrieve results without generating a report.

nl2sql-mode.png

Show SQL Results

"Show SQL Results" displays the SQL execution results to the user after generating SQL and retrieving results.

show-sql-result.png

Next Steps