#AI Agent · Viz: CRM Scenario Configuration Guide

Using the CRM example, learn how to make your AI insight analyst truly understand your business and unleash its full potential.

#1. Introduction: Making Viz Go from "Seeing Data" to "Understanding Business"

In the NocoBase system, Viz is a pre-built AI insight analyst. It can recognize page context (like Leads, Opportunities, Accounts) and generate trend charts, funnel charts, and KPI cards. But by default, it only has the most basic query capabilities:

These tools only allow Viz to "recognize structure," but not yet truly "understand content." To enable it to generate insights, detect anomalies, and analyze trends, you need to extend it with more suitable analysis tools.

In the official CRM Demo, we used two methods:

• Overall Analytics (General-purpose analysis engine): A templated, secure, and reusable solution;
• SQL Execution (Specialized analysis engine): Offers more flexibility but comes with greater risks.

These two are not the only options; they are more like a design paradigm:

You can follow its principles to create an implementation that is better suited to your own business.

#2. Viz's Structure: Stable Persona + Flexible Tasks

To understand how to extend Viz, you first need to understand its layered internal design:

This layered design allows Viz to maintain a stable personality (consistent analysis logic) while quickly adapting to different business scenarios (CRM, hospital management, channel analysis, production operations...).

#3. Pattern One: Templated Analysis Engine (Recommended)

#3.1 Principle Overview

Overall Analytics is the core analysis engine in the CRM Demo. It manages all SQL queries through a data analysis template collection (data_analysis). Viz does not write SQL directly, but instead calls predefined templates to generate results.

The execution flow is as follows:

flowchart TD
    A[Viz receives task] --> B[Calls Overall Analytics workflow]
    B --> C[Matches template based on current page/task]
    C --> D[Executes template SQL (read-only)]
    D --> E[Returns data result]
    E --> F[Viz generates chart + brief interpretation]

This way, Viz can generate secure and standardized analysis results in seconds, and administrators can centrally manage and review all SQL templates.

#3.2 Template Collection Structure (data_analysis)

#Template Examples in the CRM Demo

#3.3 Advantages of This Pattern

📘 This data_analysis collection doesn't have to be called this name. The key is: to store analysis logic in a templated way and have it called uniformly by a workflow.

#3.4 How to Make Viz Use It

In the task definition, you can explicitly tell Viz:

Hi Viz,

Please analyze the data of the current module.

**Priority:** Use the Overall Analytics tool to get analysis results from the template collection.
**If no matching template is found:** State that a template is missing and suggest that the administrator add one.

Output requirements:
- Generate a separate chart for each result;
- Include a brief 2–3 sentence description below the chart;
- Do not fabricate data or make assumptions.

This way, Viz will automatically call the workflow, match the most suitable SQL from the template collection, and generate the chart.

#4. Pattern Two: Specialized SQL Executor (Use with caution)

#4.1 Applicable Scenarios

When you need exploratory analysis, ad-hoc queries, or multi-collection JOIN aggregations, you can have Viz call an SQL Execution tool.

The features of this tool are:

• Viz can directly generate SELECT queries;
• The system executes it and returns the result;
• Viz is responsible for analysis and visualization.

Example task:

"Please analyze the trend of lead conversion rates by region over the last 90 days."

In this case, Viz might generate:

SELECT region, COUNT(id) AS leads, SUM(converted)::float/COUNT(id) AS rate
FROM leads
WHERE created_at > now() - interval '90 day'
GROUP BY region;

#4.2 Risks and Protection Recommendations

General recommendations:

• Regular users should only have templated analysis (Overall Analytics) enabled;
• Only administrators or senior analysts should be allowed to use SQL Execution.

#5. If You Want to Build Your Own "Overall Analytics"

Here is a simple, general approach that you can replicate in any system (not dependent on NocoBase):

#Step 1: Design the Template Collection

The collection name can be anything (e.g., analysis_templates). It just needs to include the fields: name, sql, collection, and description.

#Step 2: Write a "Fetch Template → Execute" Service or Workflow

Logic:

1. Receive the task or page context (e.g., the current collection);
2. Match a template;
3. Execute the template SQL (read-only);
4. Return a standardized data structure (rows + fields).

#Step 3: Have the AI Call This Interface

The task prompt can be written like this:

First, try to call the template analysis tool. If no matching analysis is found in the templates, then use the SQL executor.
Please ensure all queries are read-only and generate charts to display the results.

This way, your AI agent system will have analysis capabilities similar to the CRM Demo, but it will be completely independent and customizable.

#6. Best Practices and Design Recommendations

#7. From the CRM Demo to Your Scenario

Whether you are working with a hospital CRM, manufacturing, warehouse logistics, or educational admissions, as long as you can answer the following three questions, Viz can bring value to your system:

Once you have defined these, you just need to:

• Write the analysis logic into the template collection;
• Attach the task prompt to the page;
• Viz can then "take over" your report analysis.

#8. Conclusion: Take the Paradigm with You

"Overall Analytics" and "SQL Execution" are just two example implementations. What's more important is the idea behind them:

Make the AI agent understand your business logic, not just execute prompts.

Whether you are using NocoBase, a private system, or your own custom workflow, you can replicate this structure:

• Centralized templates;
• Workflow calls;
• Read-only execution;
• AI presentation.

This way, Viz is no longer just an "AI that can generate charts," but a true analyst who understands your data, your definitions, and your business.