🧪 Getting Started with Kai

Access

Kai is now in Public Beta and available to all users in supported stacks.

Enabling Kai

Every user can see the Kai button in their project (on supported stacks). To enable Kai:

• Organization Admins can enable the feature directly from the chat screen when first clicking the Kai button.
• Other users need to ask their Organization Admin to enable the feature, or contact Keboola Support for assistance.
• Kai can also be enabled via Settings → Features in your project.

Opening Kai

Click the Kai Agent button in your project’s top bar, or use keyboard shortcuts:

Shortcut	Action
A	Open the chat window (shows recent conversation)
Shift + A	Open a new chat

Example Prompts

Get oriented in an unfamiliar project

• “What is the purpose of this project? Summarize what it does end to end.”
• “What data is being ingested, from which sources, and how often?”
• “What output tables does this project produce, and what feeds each one?”
• “Trace the lineage from the raw source tables to the final output tables.”

Understand a specific part of it

• “Explain what this transformation does and why the joins are shaped this way.”
• “Which configurations write to the orders table, and which read from it?”
• “Is anything here unused? Tables nothing reads, configurations nothing runs.”

Debug a failure

• “Analyze the latest failed job and tell me what went wrong.”
• “This flow started failing last week. What changed in its configuration?”
• “Why did this job take 40 minutes when it usually takes 5?”

Maintain and improve

• “Help me optimize the core pipeline to reduce costs.”
• “Which jobs in this project run longest, and what would you change first?”
• “This transformation full-loads every run. Can it be incremental?”

Build something new

• “Set up a Google Sheets extractor for this spreadsheet and load it into a new bucket.”
• “Create a SQL transformation that calculates monthly revenue per customer from orders.”
• “Build an integration with the Acme API that pulls orders. Its API documentation is attached. Handle authentication and pagination.”

Building an integration for an API that has no ready-made connector is one of the stronger things to hand Kai. For security reasons Kai cannot open links, so give it the API documentation as a file: attach it with Upload files, or add it as a context file if you will be working with that API repeatedly. A URL on its own is not enough unless the API is well known.

For prompts that get better answers, see Effective Prompting in Best Practices.

Action Approval

Before Kai changes anything, it requests your approval: creating a configuration, modifying a transformation, or running a job. Read-only operations do not require approval.

Each request shows the exact parameters Kai will use.

You have three options:

• Approverun this action once.
• Declinedo not run it.
• Always allowrun it, and stop asking for that tool in future.

All actions are logged in your project’s audit trail.

For more granular control, see Tool Permissions in Kai Settings.

Plan Mode

For anything bigger than a single change — setting up a pipeline, restructuring a set of transformations — start in plan mode. Kai explores your project read-only, then shows you what it intends to do and waits. Nothing changes until you approve.

Turn it on with the Plan mode button below the message box, or type /plan in your message. They do the same thing; the button just inserts the command for you. /plan works anywhere in a sentence, so “help me /plan a revenue model” is a valid plan-mode prompt.

When Kai finishes exploring, it presents the plan as a card with three choices:

• ApproveKai leaves plan mode and starts working. Shortcut: Cmd/Ctrl + Enter.
• Request changessay what is wrong and Kai revises the plan, staying in plan mode.
• Dismissclose the plan and do nothing.

Prefer Request changes over dismissing. Kai keeps everything it learned while exploring, so revising a plan costs far less than starting over.

The message box is hidden while a plan card is waiting, so resolve the card before you carry on chatting. Resolving it also switches plan mode back off for you, unless you requested changes — in that case it stays on, because Kai is still planning.

When Kai Asks You a Question

When Kai needs a decision from you — which tables to model, which of two approaches to take — it asks with clickable options instead of a paragraph of prose. Pick one and Kai carries on.

• Some questions take more than one answer; select as many as apply.
• Every question has a free-text Other field, so you are never limited to the options offered.
• Questions can arrive as a short series, one step at a time. The counter in the corner shows how far through you are, and you can step back to change an earlier answer.
• Skip a question and Kai decides for you.

Chat Controls

The chat panel has controls in two places: along the top of the panel, and below the message box.

Panel header

Button	Control	What it does
	New chat	Start a fresh conversation. Kai keeps no context from the previous one.
	Report a bug	Send support ticket opens the support form with the details Keboola support needs — conversation ID, trace link, project, stack — pre-filled in its description. You still write the summary, pick a severity, and send it. Copy debug info puts the same details on your clipboard instead. On stacks without support tickets, Report a bug only copies.
	Settings	Open your Tool Permissions and System Instructions. These are personal to you and apply to this project only. Project-wide settings live in Settings → Kai Agent.
	Expand	Widen the panel. The expanded view also lists your chat history, so you can reopen a previous conversation. Useful when Kai returns a long table or diagram.
	Close	Close the panel. Your conversation is kept.

Below the message box

Button	Control	What it does
	Upload files	Attach a file or image to your message — a screenshot of an error, a sample CSV, a spec, or documentation Kai has no other way to read. See Attaching files.
	Plan mode	Kai explores your project read-only, drafts a plan, and waits for your approval before changing anything. See Plan Mode.
	Follow mode	Your browser navigates along as Kai works, so you can watch what it reads and modifies. Toggle it on or off at any time.

Attaching files

Use Upload files, or drag and drop or paste straight into the chat. You can attach several files at once. What happens next depends on the file type.

CSV, TSV, and .gz files become Storage tables. Kai opens the table-creation dialog and loads the file into the in.c-uploads-from-Kai bucket, creating that bucket the first time. Kai then works with the table, so the data is queryable like anything else in your project and outlives the conversation.

Every other file is attached to the conversation. It is uploaded to your project’s File Storage and restored each time you return to that chat, so you can refer back to something you attached much earlier in the same conversation. Images and PDFs are read directly by Kai, so a screenshot of a failing job or a PDF spec works as well as plain text.

Since Kai cannot open links, a file is how you hand it anything that lives on the web.

Two limits are worth knowing:

• 10 MB per file. Anything larger is skipped.
• Attachments are stored as non-permanent files, so they are deleted after 15 days, like any other non-permanent file in Storage. Reopen an older chat and Kai no longer has them.

Do you want the file in every conversation?

An attachment belongs to one chat and is gone after 15 days. To give Kai a document it should read every time, such as an API reference or your naming conventions, add it as a context file instead. Context files are stored permanently and Kai reads them at the start of every conversation, until you remove them.

Slash Commands

Type / in the message box to open a searchable menu. It lists the three built-in commands below plus any skill files uploaded to your project, each with a description, so you can find what is available without memorizing names.

Command	What it does
/plan	Turn on plan mode for this message. The same as the Plan mode button.
/compact	Summarize the conversation so far and continue from that summary. See below.
/feedback	Report a bug or send feedback. Kai copies the debug details to your clipboard by default. Ask it to “open a ticket” and it opens the same support form as Report a bug, pre-filled the same way.

Compacting a long conversation

Kai works from a limited amount of conversation at a time. When a chat gets long, /compact replaces the earlier turns with a summary so there is room to keep going. Kai also compacts on its own when a conversation grows too long, without you asking.

Your messages stay on screen, and that is intended. Compaction adds a Conversation compacted. line and removes nothing above it, so you keep the full transcript.

What changes is what Kai reads. Everything above that line now reaches Kai as a summary, not as the original messages. So you can scroll up and read a detail that Kai no longer has.

Anything you type after the command steers the summary, which is worth doing when you know what matters:

/compact keep the column mapping we worked out for the orders table

Compaction cannot be undone, so name what you need before you run it. For when to compact rather than start a new chat, see Manage Context in Best Practices.

Contextual Awareness

Kai is aware of what you’re currently viewing in the Keboola UI. Every message you send includes your current page location, so Kai understands your context without needing explicit references.

• Automatic context capture — When you send a message, Kai receives your current URL path (e.g., which configuration, job, or table you’re viewing)
• Context-aware responses — Kai uses this information to provide relevant suggestions and can reference “this configuration” or “the current job” naturally

This means you can say “analyze this job” while viewing a job, and Kai knows exactly which job you mean. Turn on Follow mode to watch it move through your project as it works.

Tips for New Users

• Start with read-only operationsexplore data and configurations first
• Be specificreference exact table names and component IDs
• Use dev branchescreate a branch in the UI, then work with Kai in that branch
• Ask for explanations"Explain this SQL query step by step"
• Don’t type secrets in chatKai uses secure forms for credentials. When setting up extractors or connections, tell Kai what you need and it will prompt you through secure configuration interfaces

Rate Limits

Kai is free during the public beta period.

Each user receives 150 turns (messages) per month per project on contracted plans. The limit resets at the beginning of each calendar month.

• Pay-As-You-Go (PAYG) plans have a lower limit of 50 messages per user per month
• Your current usage is displayed in the chat interface
• Need more? Contact Keboola Support to discuss custom limits for your project

Troubleshooting

Issue	Solution
Kai seems slow	Complex operations take time. Look for “Thinking…” indicator.
Kai doesn’t understand	Be more specific with names and IDs. Break complex requests into steps.
Actions fail	Check permissions. Verify components exist. Try “retry the last action”.
Context confused	Start a fresh chat. Keep conversations focused on one task.

Next Steps

• Kai Settings — Configure Tool Permissions and System Instructions
• Use Cases & Examples
• Best Practices