Our previous article, From Context to Inspectable SQL: The Semantic Compilation Pipeline Behind a Data Agent, covered how Semantic Views work with business knowledge and how MirrorPilot produces SV queries. This time, we will follow one question through the full runtime workflow.

A business leader asks:

Why did sales in East China fall last week, and which channels drove most of the decline?

The answer depends on more than writing SQL. MirrorPilot needs a metric definition, a comparison basis, a channel scope, and proof that the user is allowed to access the data. Treat payment amount as net sales, or compare a complete week with a partial one, and the analysis starts from the wrong numbers.

A typical run moves through seven steps. MirrorPilot may insert more queries, ask a clarifying question, or stop early based on what it finds. The number of model calls varies with the task.

The sales scenario, view names, and numbers in this article are illustrative. The example assumes that the organization has configured a sales analytics Agent, a Semantic View, and the required tools.

Seven steps in the MirrorPilot Data Agent workflow

Figure 1. MirrorPilot runs the question-answering workflow and presents the result. MirrorControl provides the administrative interface and knowledge retrieval service. StarRocks executes data queries. Step 3 retrieves metric definitions when needed, while Step 6 retrieves business context when needed.

Step 1: Validate user and session access

MirrorPilot receives the question with the selected Agent, session identifier, and authentication credentials. The server first verifies permission to use the execution endpoint. It then checks whether a standard user has been assigned to the target Agent. The request proceeds only if both checks pass.

Data Agent mode will not run without an explicit Agent selection. A follow-up question in an existing session must also pass a session access check. Knowing a session ID does not grant access to the session.

Here, the user must be authorized to use the "Sales Analytics Agent." Web and API requests go through the same server-side checks, so changing the entry point does not bypass authorization.

Step 2: Determine the capabilities available for this run

After authorizing the request, MirrorPilot reads the server-side Agent configuration and selects its tool set and Skills. Product-level limits and authorization policies narrow that configuration to the tools, Skills, Semantic Views, and knowledge bases available in this run.

MirrorPilot removes client-supplied overrides for tools, Skills, and Semantic View scope. A caller cannot use those fields to add capabilities to an Agent. MirrorPilot also builds the analysis prompt from the final tool bindings. If no knowledge retrieval tool is available, the prompt omits the corresponding retrieval instructions.

These controls do different jobs. Tool binding and resource-scope validation decide whether a call can run. Role descriptions, prompts, and Skills guide the model's behavior. An attribution Skill, for example, may tell the model to verify the metric definition before querying. That instruction does not expand the Agent's query permissions.

Authorization checks across the Data Agent workflow

Figure 2. The entry point, runtime, and individual tools each enforce the permissions they own. Database execution permissions must also be configured at deployment time.

Step 3: Align on metric definitions and retrieve knowledge when needed

The Agent first maps the user's word "sales" to a metric that exists in the catalog. Business users may use the same word for order value, payment value, or net sales after refunds. The Agent must choose the right definition before it queries data.

A Semantic View catalog defines the metrics and dimensions available for queries. Descriptions and synonyms help the model find the right fields, and the query tool validates every field reference.

For this question, the Agent resolves the comparison basis as follows:

Item

Example definition

Metric

Net sales, with refunds deducted according to the organization's Semantic View

Current window

October 26 to November 1, 2026

Baseline window

October 19 to October 25, 2026

Time zone and grain

UTC+8, two complete calendar weeks

Scope

East China

Initial breakdown

Channel

If week-over-week and year-over-year comparisons could lead to different conclusions and the user has not chosen one, the Agent should ask a clarifying question. It must also check the time zone, unit, reporting grain, and whether both periods are complete.

The catalog may not cover every business rule in enough detail. Consider a refund that crosses a weekly boundary: Which week should contain it? The Agent can call search_starrocks_knowledge for the relevant documentation. The tool accepts a natural-language question and returns document snippets through the MirrorControl knowledge retrieval service. The model can then compare those snippets with the metric definition.

The call runs only if the Agent is authorized to use the tool and has an assigned knowledge base scope. The model supplies the search query. The tool reads kb_list from the server-side runtime context and converts it to kb_ids in the request. If no knowledge base has been assigned, the tool returns a notice without sending a retrieval request.

Knowledge retrieval is optional. If the catalog already answers the definition question, the Agent can query the data directly.

Semantic View routing and progressive disclosure

An Agent may have access to several Semantic Views even though a question needs only one. Routing identifies the view most likely to answer the question. Loading every complete view definition at this point would waste context and expose the model to unrelated fields.

MirrorPilot exposes metadata in two passes. A call to discover_starrocks_semantic_views without a view name returns lightweight summaries for views in the authorized scope. A call with a selected view name returns that view's detailed catalog.

Layer

Information returned to the model

Decision it supports

View summary

View name, description, and routing metadata

Which views might cover the current question

Detailed catalog

Metrics, dimensions, expressions, relationships, and other metadata for the selected view

Which fields to use and whether the required metric definition can be expressed

This progressive disclosure keeps the model context focused. It receives summaries first, then detailed catalogs only for the views required in the current run.

Progressive loading applies to the metadata the model reads. During execution, the query tool still reads the target view catalog to validate metrics and dimensions. Semantic View routing is also separate from business knowledge retrieval. Routing selects the data object; retrieval supplies business rules or event context.

Step 3 ends with a defined metric, comparison basis, and candidate view. Any missing definition material has been retrieved, but the sales values must still come from a semantic query.

Step 4: Turn the analytical intent into a query

The model expresses the request as structured parameters: metrics, dimensions, filters, sort order, and a row limit. For supported patterns such as grouped rankings, share calculations, and growth rates, it can select a predefined query shape and supply the required parameters.

The server checks that each field belongs to the view catalog, validates identifiers and operators, escapes filter values, and builds the SQL. For a multi-stage query, code assembles the SQL structure while the underlying data still comes from the Semantic View.

The two-week channel comparison in this example can be sent to query_starrocks_semantic_view with the parameters below. The view and field names are illustrative. A real call must use names present in the catalog.

Code
{
  "semantic_view": "business.sales_overview",
  "metrics": ["sales.net_sales"],
  "dimensions": ["sales.week_start", "sales.channel"],
  "filters": [
    {"field": "sales.region", "operator": "=", "value": "East China"},
    {"field": "sales.week_start", "operator": "IN", "value": ["2026-10-19", "2026-10-26"]}
  ],
  "order_by": [{"field": "sales.week_start", "direction": "asc"}],
  "limit": 100
}	

A reviewer can compare these parameters with the original request: the chosen view, the channel grouping, and the two week-start dates. The generated SQL carries those choices forward.

Staged SQL template selection

Teams can save existing business SQL as reusable templates. If an Agent has both template retrieval and execution tools, the tool descriptions direct it to search for a matching template first. Without a match, the Agent uses another assigned query tool. Templates and Semantic View routing are alternate query paths; a question does not have to pass through both.

search_sql_templates starts with the user's original question and retrieves templates from assigned knowledge bases. It preserves retrieval order and removes results below the minimum relevance requirement. The number of candidates and their score distribution determine whether the tool returns SQL bodies to the model.

Candidate state

Tool response

Agent's next action

No suitable candidate

no_choose, with no SQL returned

Use another authorized query path

One candidate, or a clear score gap between the leading and remaining candidates

choose_from_candidates, with the leading candidates and their SQL

Check whether a candidate matches the question and select one template

Similar scores, or scores that do not support a reliable gap judgment

tier_then_fetch, with names, descriptions, scores, and document IDs

Narrow the set by meaning, then retrieve the selected template bodies

On the summary path, the model selects document IDs from the names and descriptions. If it cannot distinguish between candidates, it may select all of them. It then calls do_sql_templates to read the selected SQL bodies. This call retrieves templates only.

Relevance scores narrow the candidate set. The model must still check whether a template matches the requested metric and analytical intent, and it can reject a poor match. Once the template is selected and populated, the Agent enters the execution path with the filled_sql parameter.

A clear candidate can include its SQL immediately, which removes one retrieval round trip. When scores are close, summaries keep several long SQL bodies out of the model context until it has narrowed the set.

Step 5: Validate scope and execute the query

Before execution, the semantic query tool checks once more that the target view appears in the Agent's sv_list. It then validates the metrics and dimensions. A request that names a view outside the Agent's authorized scope is rejected.

After those checks pass, the tool uses the configured database connection for business queries to access StarRocks. It reserves query budget before database access. After execution, it records the number of queries, rows returned, result character count, and cumulative duration for the run. The tool returns an error if any configured limit is exceeded.

sv_list limits views, not rows. "East China" is a business filter in this example. If employees may see data only for their own regions, the deployment must enforce that boundary through data source permissions, controlled views, and the corresponding authorization configuration.

The query tool returns these elements to the model and frontend:

Returned element

Purpose

columns, rows

Query results used by the model for analysis and by the frontend for tables

generated_sql

The SV SQL executed for this semantic query

inlined_sql

Inlined SQL returned when the database can provide it

query_shape

Metrics, dimensions, formats, and chart-selection metadata corresponding to the result columns

Truncation flags, comparison-period warnings, and similar notices

Limits on result coverage or comparison conditions

Where a query outside the authorized scope stops

Assume the server has assigned only business.sales_overview to the Sales Analytics Agent, but the model submits business.inventory_overview. The tool checks the target view before it reads the catalog or constructs SQL.

apex
# In this example, runtime.sv_list is configured by the server
def query_view(request, runtime):
    name = validate_view_name(request["semantic_view"])
    allowed = normalize_all(runtime.sv_list)
    if normalize(name) not in allowed:
        return {"error": "View is outside the current Agent's authorized scope"}

    catalog = read_catalog(name)
    sql = build_semantic_sql(request, catalog)
    return run_sql(sql)

The request ends at the view scope check. The tool does not read the target catalog or query the target data. The sample combines scope validation with the tool-level error response. A real call must also pass the identity, Agent access, and tool authorization checks described earlier.

Each tool owns a different resource boundary. Knowledge retrieval reads kb_list from the runtime and sends it as kb_ids in the retrieval request. Without an assigned knowledge base, the tool does not send that request. Template body retrieval is limited to candidates found in assigned knowledge bases. Template SQL execution has separate statement checks and database permissions. The view scope check does not replace any of them.

Step 6: Reconcile the change and check business context when needed

The channel rows must reconcile to the overall change. MirrorPilot's contribution analysis first reproduces the total difference, then selects a dimension for drill-down analysis and checks whether the breakdown ties out. The model may issue more queries based on the result. Reviewers still need to verify that these steps ran and that the returned values support the analysis.

The illustrative data below uses CNY millions. The three channels are mutually exclusive and together cover all sales.

Channel

Previous week

Last week

Change

Direct e-commerce

6.0

4.2

-1.8

Distributor channel

3.0

3.4

+0.4

In-store retail

1.0

1.2

+0.2

Total

10.0

8.8

-1.2

Net sales fell by CNY 1.2 million, or 12%. Direct e-commerce fell by CNY 1.8 million. Growth of CNY 0.6 million across the distributor and in-store channels offset part of that decline. The channel-level changes reconcile exactly to the overall decline of CNY 1.2 million.

This is why a signed contribution share can exceed 100%. Direct e-commerce contributes -1.8 / -1.2 = 150% of the net change. The other channels grew, so their signed contributions to the decline are negative. All three still sum to 100%. Contribution to the change is not the same as share of sales.

The reconciliation works because net sales is additive across these channels. Conversion rates, averages, distinct customer counts, and quantiles require checks of numerators, denominators, weighting, overlap, and distribution.

After the channel contribution is clear, the Agent may retrieve business context. For example:

Which campaigns ended or which rules changed for direct e-commerce in East China between October 26 and November 1, 2026?

The Agent again calls search_starrocks_knowledge. The current Agent's knowledge base configuration still determines the retrieval scope.

Suppose a document says that a campaign ended during the week being analyzed. The Agent must check the timing, applicable channel, and expected direction, then see whether data supports the claimed magnitude. It can issue another Semantic View query if needed. Without supporting data, the explanation remains a hypothesis to validate. A causal conclusion requires suitable experimental or control information.

The answer can now state where the change was concentrated, which explanations have evidence, and what remains unexplained. It should disclose missing metrics, absent comparison data, or a large residual.

Step 7: Deliver the answer with supporting evidence

The Agent can now combine the comparison with the relevant business context. A suitable answer for this example is:

Using the net sales definition and the two complete calendar weeks above, net sales in East China fell from CNY 10.0 million to CNY 8.8 million, a decline of 12%. The drop was concentrated in direct e-commerce, which fell by CNY 1.8 million. The distributor and in-store channels grew by a combined CNY 0.6 million, offsetting part of the decline. The specific business causes still need to be validated against campaign and transaction factors.

The Semantic View query result card lets the user inspect the chart, table, SV SQL, and Inline SQL.

If the result contains a truncation flag or a comparison-period warning, the interface displays it. The warning shows how far the data can support the answer.

How one result produces table, chart, and SQL views

The query tool returns columns, rows, and the SQL executed for the query in one result. query_shape maps result columns back to semantic metrics and dimensions. For channel and net sales, the mapping could look like this:

apex
{
  "dimensions": [
    {"semantic_ref": "sales.channel", "result_column": "channel"}
  ],
  "metrics": [
    {"semantic_ref": "sales.net_sales", "result_column": "net_sales"}
  ]
}

The frontend uses the field mapping and presentation metadata to identify dimension and metric columns, then selects a supported chart. The table, chart, and SQL tabs all read the same tool result:

apex
# The frontend reads from the same query result
result = parse_tool_message(tool_message)
render_table(result.columns, result.rows)

chart_plan = plan_chart(result)
if chart_plan.supported:
    render_chart(chart_plan, result.rows)

render_sql("SV SQL", result.generated_sql)
if result.inlined_sql:
    render_sql("Inline SQL", result.inlined_sql)
render_result_warnings(result)
Data, knowledge, and trace evidence behind the answer

Figure 3. Data and SQL provide the numerical evidence. Knowledge snippets support interpretation. Trace records the execution path for review.

To verify the 12% decline, a reviewer can inspect the view, comparison windows, filters, SQL executed for the query, and returned data. Reviewing a claim about campaign impact requires a different source: the retrieved snippets. Those snippets help distinguish supported explanations from hypotheses that still need validation.

With Trace collection configured, MirrorControl shows the run summary, call tree, and duration. Teams can use those records to locate problems in model or tool calls. A successful Trace does not validate a business conclusion, and the same SQL may return different values after the underlying data changes.

For retention or reporting, the Agent can generate a self-contained HTML report through its available report tools. The report keeps the metric definitions and data used in the analysis, along with unresolved questions, and the user can preview or download it.

In this sales analysis, the data queries establish the size of the decline and its distribution across channels. If the business leader asks, "Exactly how much of the decline was caused by the campaign ending?" the Agent needs the corresponding metrics or control data. Channel changes and a campaign note are not enough. The answer should say that the campaign's impact remains unverified and list the missing data. How far the Agent can go depends on the metrics and business rules already covered by the organization's Semantic Views and knowledge bases. Both need ongoing maintenance as the business changes.