Best practices

When customers define their own agentic workflows, a few structural rules make the runs faster, more reliable, and easier to audit.

1. Start with data, end with story The first step in the workflow should be an SQL step that pulls the governed data at the right grain. The last step should always be a Summary step that turns the results into a narrative, shows the drivers, and adds recommendations. This pattern (SQL → … → Summary) is what the planner expects.

2. Put Python only where it’s needed If the logic can be done in SQL, do it there. Use Python steps only for things SQL cannot handle easily — changepoints, contribution/variance with volume weighting, cohorts/retention, forecasting, clustering, domain Python functions, and so on. This reduces retry loops and improves latency.

3. Keep to one summary step Each workflow should produce one, clear answer. Multiple summary steps can confuse the UI and the user. Collect all findings in the final summary.

4. Design for the 10,000-row envelope Agentic runs currently fetch up to 10,000 rows per query. Build steps that aggregate early and avoid “give me everything” patterns. If more detail is needed, create a follow-up workflow for drilldown.

5. Clarification is bounded If the workflow asks the user for inputs and they don’t answer within the allowed number of clarification turns, Kaiya will still run the workflow with what it has or with defaults. Tell users that this is expected, not an error.

Ask specific, well-defined questions

• “Compare prescription performance between Q3 and Q4 2024 across top 5 districts” tells Kaiya the period, the measure, and the slice. Weak questions are vague.

• “Analyze all prescription data” has no time window, no intent, and no segment, so the plan will be broad. Good questions also include intent.

• “Identify top 3 underperforming regions in Q4 and recommend reallocation” tells Kaiya to produce an action, not just a chart. Fo example, a weak question like “Show me some charts” gives no business outcome.

Example workflows to model

Standard sales / cancellation deep dive Pull the base series (e.g. weekly cancellation). Pull the same measure by region/product/channel. Run Python to rank contributors. Summarize what changed, where, and who drove it. Output is trends, ranked drivers, and 1–2 charts.

Custom forecasting Load the registration/event data. Build the days-out framework. Calculate historical weights. Generate and backtest the forecast. Summarize with confidence bands and actions. This shows how to embed domain Python.

Risk assessment Validate the material. Retrieve SOP. Calculate risk factors. Produce a risk report with mitigation guidance. This shows how to combine clarification + SQL + Python + summary.

What you must do to trigger agentic runs

• Turn on Deep Insight button before asking, otherwise Kaiya will answer in normal chat mode and won’t build a multi-step plan.

• Make sure to use the trigger phrase the workflow was published with.

• If the dataset is on a source that agentic / text-to-SQL doesn’t support in that environment, the data must be available on a supported source (e.g. Snowflake, Redshift, ClickHouse) for the workflow to execute end-to-end.