Get started
Build a usable agent from scratch
From connecting data to handing it to your team, build an agent that answers accurately.
This tutorial starts with connecting data, builds an agent your team can rely on, and verifies it with real questions. It uses store sales analysis as an example; replace it with your own business.
Prepare
- Connecting data sources requires a project owner or project administrator. Regular members can start from step 2 using existing data sources.
- A read-only database account, or tidy Excel / CSV files.
- Five to ten business questions your team really cares about, with reference answers for verification.
Steps
Connect data and select only the tables you need
Add a data source by following Connect data sources. Select only the tables needed to answer the business questions, such as orders, stores, and products. Wait for metadata parsing to complete.
Write table and field notes
Open the data source. For each table, write one sentence on “what one row represents”; for commonly used fields, write the unit, code meanings, and definition, such as “amount: amount paid, in cents, after coupons”. IDs and technical fields unrelated to analysis can be hidden. See Table and field notes and Hidden fields and masking.
This step has the greatest impact on accuracy.
Create the agent and select data sources
In “Agents”, click “Create” and choose a similar template (such as “Store operations analyst”) or start from scratch. Add the data source under “Configuration” → “Data sources”. Write a description that says which questions it can answer. See Create and configure agents.
Write business definitions
Under “Documents”, write a business document for each key metric, such as “Sales = amount paid - refunds, counted by payment date”. Under “Configuration” → “Preferences”, write background and answer style that apply to every question. See Basic settings and knowledge preferences.
Add analysis methods
When your team has a fixed analysis routine (such as a weekly report format or anomaly investigation steps), write it as a skill and attach it to the agent. Make sure “User clarification” stays enabled in Capability settings.
Test with real questions
Select this agent in a conversation, ask the prepared questions one by one, compare the results with the reference answers, and check the executed SQL.
When an answer is wrong, add information according to the cause:
| Cause | Add to |
|---|---|
| Wrong field chosen or code misunderstood | Table and field notes |
| Wrong definition | Business documents |
| Steps or format not as required | Skills |
| Complex query with a fixed pattern | Training set |
After changes, retest with the same questions until the results are reliable.
Set permissions and share
If different people may see only different data, have an administrator configure data permissions first. Then share the agent with specific colleagues or the entire project from the “Agents” list.
Connect your team's tools
As needed, connect the agent to Feishu or Slack, set up scheduled reports, or embed it in a business system.
Check the outcome
- All prepared questions get correct results, with the correct definitions visible in the SQL.
- When colleagues ask with their own accounts, they see only the data their permissions allow.
- After launch, review Logs and user feedback regularly and add notes, documents, or skills for wrong answers.
Next steps
- Methods for writing accurate questions, which you can share with colleagues: How to get accurate results
- Limit data by department and region: Design data permissions by department and region