> For the complete documentation index, see [llms.txt](https://help.tellius.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.tellius.com/kaiya/kaiya-missions/best-practices.md). # Best practices Learn best practices for designing agentic workflows: SQL-first logic, focused summaries, efficient Python use, bounded clarifications, and questions that guide intent. When you build your own Missions, 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 turn the results into a story: the narrative, the drivers and the recommendations. In Tellius 6.4, new Missions end with a **Rich Summary** step by default, which builds a visual summary page. This pattern (SQL → … → Rich Summary) is what the planner expects. In releases before Tellius 6.4, the last step was a text **Summary** step, and older Missions keep it until you change it. **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, such as 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 for each path**\ Each Mission should produce one clear answer for each path it can take. A Mission without branches ends with one summary step that collects all findings. A branched Mission can end with its own summary or file for each path, so each branch reports its own finding. **4. Put the export details in the export step**\ When a Mission produces a file, such as a PowerPoint deck or a PDF report, write its storyline, contents and design in the export step's instructions: the order of the story, the slides or sections and what each one shows, and the layout, colours and logos. Every run then produces the same file, and you change the file by changing one step. The export step's instructions come first. A custom skill, such as a house deck format, fills in only what the export step leaves open. To find out where a detail in a file came from, ask Kaiya, for example *"Where did the logo on the cover come from?"* **5. 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. **6. 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. **7. Plan for what a Mission can read**\ A Mission reads its data from Business Views, Kaiya Context Models, connected systems and indexed documents. A scheduled run can't search the web, and Python steps can't call outside services. If a Mission needs outside data, bring it into one of those sources first. ### 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. For 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 * **To run a Mission,** ask Kaiya for it by name, and it runs straight away. A question that matches one of the Mission's trigger phrases brings up a **Run saved mission** question, so you can run the Mission now or have Kaiya answer directly. See [Triggering a Kaiya Mission](https://help.tellius.com/kaiya/kaiya-missions/triggering-a-kaiya-mission). * **To run a Deep Insight,** just ask. Kaiya runs one when it decides the question needs a multi-step plan. You can also select the **Deep Insight** tag under the ask box, or ask Kaiya for one. See [Deep Insight](https://help.tellius.com/kaiya/understanding-ai-agents-and-agentic-flows/automated-workflows/deep-insight). * 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. ### **Authoring conversationally** When building a Mission through the conversational interface, a few habits produce better step plans: * **Lead with a complete brief.** Describe the analysis, the slice, and the deliverable in one go. Kaiya drafts a tighter plan from a full brief than from a vague one. * **Answer Kaiya's clarifying questions specifically.** When Kaiya asks about period defaults, metric units, or how many items to surface, give concrete answers. * **Run once before publishing.** Execute the Mission against sample inputs to validate the output, and refine any step that needs adjusting, before exposing it to other users. * **Declare runtime inputs rather than hard-coding.** If a value changes per run (region, quarter, segment), let it be an input the Mission asks for, rather than fixing it in the step. ### **Keep older Missions current** Missions built before Tellius 6.4 keep working without changes. Two updates make them easier to use: * **Replace the text Summary step with a Rich Summary step.** Select **Configure** on the Mission's page and ask, for example *"Replace the summary step with a rich summary."* Check the draft's **Visual summary**, then publish. * **Move export instructions into the export step.** If a Mission's file looks different from run to run, write its storyline, contents and design in the export step. {% hint style="info" %} **Why move to Rich Summary?** A long text briefing with charts in between makes readers scroll up and down to compare figures. A visual summary puts the headline, the key figures and the charts on one page, so the result is quicker to read. The Mission's other steps and its schedule stay as they are. {% endhint %} {% hint style="success" %} **Edit in a draft, or start a new Mission?** Edit the Mission in a draft when you are improving the same job: runs and schedules keep using the published version until you publish, and the run history stays with the Mission. Start a new Mission, or select **Duplicate**, when the result answers a different question or serves a different audience and both should keep running. {% endhint %} See [Missions built before Tellius 6.4](https://help.tellius.com/kaiya/kaiya-missions/missions-built-before-tellius-6-4). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.tellius.com/kaiya/kaiya-missions/best-practices.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.