# Understanding Kaiya Agent Mode

### What it can do

* **Dynamic analytical planning –** Kaiya reads the user’s question, determines which datasets and time windows are relevant, and then builds a step-by-step analysis plan on its own. The plan can include multiple SQL pulls (baseline plus breakdowns), optional Python analysis, and a final summary step. The user does not have to create this flow beforehand — Kaiya assembles it from the question.\\

* **Multi-agent orchestration –** The steps in that plan are executed by different specialized agents, but all against the same plan. SQL agents fetch and aggregate governed data from the source. Python agents run methods that are not practical in SQL, such as changepoint detection, contribution/variance with volume weighting, cohort/retention, or forecasting. The summary agent then turns those results into a human-readable narrative with visuals.\\

* **Clarification when needed –** Targeted to the missing field. Kaiya will stop briefly only when a required input is missing from the question or workflow. For example, if a step says “analyze risk for material,” and no material was provided, it will ask for the material name and then proceed.\\

* **Error handling and retries –** When a generated SQL or Python step fails during execution, Kaiya does not end the run immediately. It tries to correct the generated code or query and re-executes the step. This allows multi-step analyses to complete even when one generated step was not perfect on the first attempt.\\

* **Executive-ready output –** Final response can contain structured results: a short takeaway, tables, 1–4 visuals depending on the analysis depth, a ranked list of drivers, and recommended next steps. For executive-style questions, it can limit itself to 1–2 charts and a condensed summary.

{% hint style="success" %}
**Custom (user-defined) workflows** – This let you tell Kaiya exactly how to analyze something, step by step. If your team already has a proven sequence. For example, “pull event data → build days-out framework → run forecast → validate → summarize” — you can write those steps once and save them. When a user asks a question that contains the trigger word or phrase you attached to that workflow, Kaiya will execute your saved steps in that order instead of generating a new plan. This is useful for repeatable, domain-specific work where you want the AI to run the analysis, not design it.
{% endhint %}

### A glimpse into the architecture

Agentic Insights uses a multi-agent pipeline. Every run goes through these logical pieces:

**Contextualizer**\
This is the first layer that reads the user’s natural-language question. It decides whether the question should go through the **Agent Mode** (Kaiya’s automated planning path) or whether it matches (or should trigger) a saved, user-defined workflow.

**Planner**\
Used for questions that Kaiya plans and executes automatically. It takes the routed query and turns it into an ordered, executable plan. The plan typically has data-gathering steps (SQL), optional analysis steps (Python), and a final summarization step.

**Workflow Planner**\
Used when the user has already defined the analysis steps. It loads those steps, detects if any step needs a user input (like material, date range, region), asks for those values up to the allowed limit, and then executes the workflow exactly as written.

**SQL Executor**\
This component generates SQL that is valid for the connected datasource and runs it through the governed query layer. It is responsible for pulling the right data at the right grain, honoring security, policies, and calendars.

**Python Executor**\
This runs analysis that cannot be done well in SQL. That includes changepoint detection, contribution or variance with volume weighting and sample-size checks, segmentation or clustering, forecasting with intervals, and basic causal or association probes. It operates on the data returned by the SQL steps.

**Summary Agent**\
This is the last step. It reads the outputs from SQL and Python and turns them into a human-readable answer. It can produce a narrative, highlight timing and magnitude, list ranked drivers, add recommendations, and include the charts generated in the run.

### Standard query flow

* You start with a plain-language question.
* The contextualizer looks at that question and decides which planning path fits best.
* The planner then breaks the question into executable steps (usually one or more SQL pulls, optional Python for deeper logic, and a summary step).
* The SQL agent fetches governed data, the Python agent applies advanced methods if the plan called for them, and finally the summary agent assembles the findings into a clear narrative with visuals.
* Finally, you get one complete, end-to-end answer.

### Custom workflow flow

* Here, your question matches a trigger phrase from a published workflow.
* The **Workflow Planner** loads that workflow and checks whether any step needs user input.
* If something is missing, it asks for it, but only up to the configured clarification limit.
* After that, it runs exactly the steps defined in the workflow (in the order you wrote them) using SQL, Python, and summary agents.

{% hint style="success" %}
Executive summary flow\\

* If the question asks for an “executive summary,” Kaiya still performs the full analysis in the background so the numbers are correct, but the final response is shortened.
* It uses business-level wording, highlights the key metrics and drivers, and shows at most one or two charts to keep the answer presentation-ready.
  {% endhint %}

### How Kaiya gathers requirements for the workflow?

**Dynamic parameter detection:** Our workflow engine actually reads the text of each step and looks for inputs that the user has not supplied yet. If a step is written as “ask material name for risk analysis,” it will mark “material name” as mandatory and pause the workflow to collect it before moving on.

**Follow-up question management** controls how persistent Kaiya is. It will only ask for inputs that are missing or critical to run the next step, and it will do this only up to the configured limit. If the user does not provide everything within that limit, the workflow does not fail; it proceeds with available or safe values so the user still gets a reliable result.

**Default values** give admins or workflow authors a way to pre-fill common fields. A workflow step can say *“If no period is given, use last 12 months”*, and Kaiya will apply the same. In some cases, Kaiya can also infer from the data what a reasonable default is. The user can still override what was prefilled.

**Visualization rules** describe how much output the summary agent should create. Executive-style questions get a short answer with 1–2 charts so the result is easy to read. Standard analyses can return 2–4 visuals. If a chart cannot be rendered for that step, Kaiya will return a text description of the same insight.

**Custom functions** allow you to plug in your own Python logic and let the agentic flow call it like any other step. This is useful for things like event forecasting, RFM segmentation, or time-series decomposition that you have already coded. The output from that function is then included in the final summary.
