Create and Configure an Agent

Overview

An agent is one of the core capabilities of Data Agent. This module mainly includes agent creation and agent testing. It helps users quickly build business-oriented conversation logic and validate performance, ensuring the accuracy and smooth experience of Data Agent.

Prerequisites

Only users with Dataset Agent(ChatBI) Edit permission can access the Agent Management page and perform agent configuration operations.

Create an Agent

Entry URL: http://<your-domain>/agent/manage/dataset. For private deployments, replace <your-domain> with your actual environment address.

Note

When creating an agent for the first time, we recommend starting with a single table. After the single-table Q&A accuracy reaches 80%, expand to additional tables.

1. On the Data Agent > Agent Management page, click Create Agent.

   

2. Fill in the basic information. If you later need to modify it, see Basic Configuration.

   
   • Name (required): a concise business-oriented summary of the agent. It is provided to the model as training knowledge and supports up to 30 characters.
   • Q&A avatar configuration: by default, the Guandata logo is used. Users can upload their own image to change the frontend Q&A avatar.
   • Welcome message configuration (optional): by default, the first line is the welcome title, and the second line onward is the body text. The welcome message supports a rich-text editor and references to specific attributes.
   • Description (optional): helps business users understand which business scenarios or problems the agent can address. It is also provided to the model as training knowledge.
   • Related datasets (optional): defines the scope of data available for Query. The current version supports some direct database connections and extracted datasets. Dataset descriptions, dataset structures, and field comments are used as model learning knowledge.
   Note

   • Direct database support: MySQL, Postgres, Starrocks, Doris, Hive, Presto, Trino, SQL Server, ClickHouse, and kylin
   • We recommend preparing at least one usable dataset in advance to improve Q&A performance.

3. Complete agent creation.

   • If the knowledge base is not ready yet, click Create Directly to finish creating the agent. You can add knowledge later on the Business Knowledge Library page. For knowledge-related operations, see Business Knowledge Library.

     

   • If the knowledge base is already prepared, click Next to configure the business knowledge collection, then click Finish to complete agent creation. For knowledge-related operations, see Business Knowledge Library.

     

4. After all information is filled in, click Finish to complete agent creation. After creation, the system enters the Agent Detail Settings page by default. For follow-up operations, see Agent Detail Settings.

   

5. (Optional) If you want to reuse the knowledge base of an existing agent, use Save As to quickly create a copy.

   

Agent Testing

After creating a new agent, we recommend testing it. Test accuracy directly affects the accuracy of Data Agent in production, so make sure the test accuracy reaches at least 90% before enabling the agent.

Enter the Test Page

On the Agent Detail Settings page, click Test in the upper-right corner to enter the test page.

Test Q&A Effect

Import Questions

On the test page, you can add test questions in three ways: AI-assisted generation, Batch Import, or Manual Add.

• AI-assisted test questions: the system combines the fields of related datasets in the current topic with user-defined metric/dimension definitions and generation preferences, then uses AI to generate test data and quickly expand the test question library.

  

  If you are not satisfied with the generated questions, click Regenerate.

  

  Select the questions you want to add to the test set, then click Confirm.

  

• Batch Import: download the Excel template, fill in the collected user questions and answer SQL, then upload them in batches.

  Note

  The answer SQL in the sample question list is optional. You can upload only test questions. After the file is uploaded, testing begins for all question entries in the file.

  

• Manual Add: enter questions and answer SQL one by one. After clicking Confirm, testing starts immediately for that question entry.

  Note

  • Answer SQL is optional. You can fill in only the question description.
  • If datasets were already related when the agent was created, the New Question page displays dataset and field information.
  

Question Testing and Review

After questions are uploaded, the system automatically starts testing them. Based on the current tables and knowledge, the model generates SQL for each question in batch, and the system executes the SQL and checks its validity.

When SQL Validity Is Incorrect

If SQL execution fails, the interface displays SQL validity and review result errors.

1. Click Check to the right of the question to view the SQL details generated by the model. On the Q&A detail page, the following operations are supported:

   • View and copy the message ID for troubleshooting with product or engineering teams.
   • Copy Executed SQL: after clicking Copy Executed SQL, the SQL statement actually executed against the database is copied to the clipboard, so it can be pasted into the database for querying.
   • The following error scenarios are displayed:
     • When the AI model cannot generate valid SQL, the system displays a specific failure reason such as Failed to answer the question. Reason: xxxx. This usually relates to model understanding of the question or the data structure.
     • When the model successfully generates SQL but execution fails, the system displays an SQL validation error such as Current SQL validity check failed. Reason: {xxxxx}. Common causes include syntax errors, missing table names or field names, or incorrect filter conditions.
     • When SQL executes successfully but returns no data, the system prompts possible reasons such as No data was returned. Please check whether the data source was updated correctly and whether row- and column-level permission rules are configured correctly.
   

2. Maintain the answer set.

   • If there is no answer set yet, click Copy to Answer Set and Edit, correct the SQL, and save it. The corrected SQL is then stored as the answer for that question.
   
   • If an answer set already exists or the correct SQL has already been maintained there, click Mark as Incorrect and Add to Q&A Sample to add this question to the knowledge base.
   

3. Return to the list page, select the question, and click Start Testing to test again. After SQL validity is correct, click Review and mark the question as Correct.

When SQL Validity Is Correct

• For questions without an answer set, click Review. The same operations as above are supported on the Q&A detail page.

  • If the data result is correct, click Mark as Correct. The test question is marked as passed, and the SQL generated by the model is automatically stored in the answer set.
  • If the data result is incorrect, click Copy to Answer Set and Edit to maintain the answer set, then click Mark as Incorrect and Add to Q&A Sample to maintain knowledge entries.
  

• For questions that already have an answer set, the system compares the execution result of the model-generated SQL with the execution result of the answer-set SQL. Only when the two results are exactly the same is the result automatically marked as correct. Otherwise, the system marks it as incorrect.

  • For questions marked correct by the system, users can still manually verify the data and decide whether the result needs adjustment.
  • For questions marked incorrect by the system, click Edit in the upper-right corner of the Answer Set area to maintain the answer set, then click Mark as Incorrect and Add to Q&A Sample.

Enable an Agent

After all test questions have been reviewed, the list header displays the test accuracy. We recommend enabling the agent only after the test accuracy reaches 90% or above.

Return to the Agent Detail Settings page and click Enable.

Knowledge Quality Check

Knowledge Quality Check runs a global check of the current agent and identifies knowledge conflicts that may affect answers. It checks conflicts in definitions, rules, and SQL logic, not formatting, layout, or minor wording.

On the Agent Detail Settings page, select Knowledge Quality Check in the upper-right corner to open the global-check page.

What It Checks

• Conflicts among general knowledge, general preferences, and business knowledge, such as inconsistent metric definitions, time-range rules, synonyms, or business definitions.
• Consistency between Q&A intent and SQL, including SQL filtering, aggregation, dimensions, time definitions, and compatibility with datasets, tables, fields, meanings, and field types.

Scope

The check covers enabled knowledge in the current agent, enterprise preferences that apply to it, enabled Q&A with valid SQL, and schemas used by Q&A SQL.

Note

The current version does not check duplicate or distracting knowledge, formatting, minor wording, disabled knowledge, or Q&A with empty or invalid SQL.

Steps

1. If no results are available on the global-check page, select Start Check.

   

2. While the check runs, the page shows progress, the number of checked items, and the current stage. The check continues after you close the window; select Cancel Check to stop it.

   

3. When complete, the page shows the number of checked items, conflicts, affected knowledge items, and completion time.

   • If no conflicts are found, the page displays No knowledge conflicts found. Select Check Again to run a new check, or Confirm to close the page.

     

   • If conflicts are found, expand a conflict to view its name, source, and original knowledge text, then update the relevant knowledge.

     

Additional Operations

Click the More icon in the lower-right corner of the agent card to perform additional common operations.

Enable / Disable

After an agent is created and tested for the first time, click Enable to publish it. Business users can then see all enabled agents they are authorized to use on the Query Agent and Insight Agent pages.

If the agent needs to be taken offline, click Disable. Disabled agents show the Disabled status label in the upper-right corner. To reactivate the agent, click Enable again.

Rename

Click Rename to rename the current agent.

Save As

Click Save As to quickly create a new agent based on the current configuration.

Import and Export

Import and export migrate agent configuration between environments or agents. An export contains the current agent's transferable configuration; an import applies the file content to the selected target agent.

The following content is supported:

Content	Details
Dataset associations and configuration	Dataset associations, field enablement, and enumeration configuration.
Q&A sample knowledge	Questions, SQL, and enablement status.
Custom preferences	General knowledge, synonyms, metric definitions, time logic, display preferences, SQL knowledge, and visualization-insight knowledge.
Business knowledge and test sets	Business knowledge, test questions, and reference SQL.
Analysis Specialists and subscriptions	Specialist configuration, recommended questions, report templates, and related subscriptions.
Permissions and Query Guard	User and user-group permissions, and Query Guard rules.
Agent settings and assets	Feature switches, opening messages, agent and specialist avatars, and table relationships.

Import supports two modes:

• Append Import: retains existing target-agent content and adds new content from the import file. Non-appendable content, such as feature switches and opening messages, is overwritten.
• Overwrite Import: clears the corresponding content in the target agent before importing.

Note

Migration focuses on agent configuration and knowledge assets. It does not migrate agent names, descriptions, enabled status, underlying BI datasets or data sources, model bindings, credentials, enterprise-wide configuration, history, generated reports, favorites, feedback, or execution records. If dependencies such as users, groups, attributes, or external avatars are unavailable in the target environment, the system skips them.

After import, verify dataset associations, permissions, subscriptions, table relationships, and Query Guard rules.

Delete

Click Delete to delete the current agent. The system requires a second confirmation to prevent accidental deletion.