PRDCT-693: Build an app with an AI agent

[Iamfle4ka]

Linear: PRDCT-693 · related AJDA-3380, CLI-15

Why

Michal Ševčík asked on 23.09 to move the agent and CLI install steps out of the Apps UI and into the docs, with Claude Desktop covered. He also asked to document building and running apps with kbagent from different agents. Until now the docs had one 12-line section in build-locally, and no rendered page showed a kbagent data-app command.

What changed

Each reader question now has one page, and the other pages link to it instead of repeating the steps:

Reader question	Page
How do I build an app with my agent?	new data-apps/build-with-an-agent (how-to; tabs for Claude Code, Claude Desktop, Cursor, VS Code, the ChatGPT app and a plain Terminal, syncKey="ai-client")
How do I install the plugins in my client?	cli/for-agents, new "Add the app-building plugin" section
What's in AI Kit?	ai/ai-kit: the Data App Developer description fixed (it said Streamlit only), versions refreshed, other clients linked

Smaller edits:

• data-apps/index.md lists the agent route as the third way to build. The nav gets one entry under Apps › Build.
• what-are-apps points coding assistants at the new page.
• The agent tips in build-locally and getting-started point to the new page. The build-locally section keeps its anchor.
• troubleshooting gets three rows: the managed-repo workspace bug, Promise.withResolvers is not a function from a too-new @keboola/api-client, and Repository not found from a stored Git login.
• operate no longer calls rollback impossible from kbagent: deploy --config-version runs an older configuration once. A real restore stays in the UI.
• cli/getting-started no longer says data apps need a static token. Browser sessions cover them since kbagent 0.94.0 (feat: accept browser-login (session) tokens for the commands whose backend supports them (CLI-13) cli#759).
• One stale /components/data-apps/ link in transformations/mappings now points at /data-apps/.

After Michal's Cursor review (25.09)

• The defaults (managed Git, Python/JS for a dashboard, a shared password, where the password lives) now come before the tabs.
• Agent tabs are setup plus the prompt. The kbagent commands moved to their own Terminal tab.
• "Agent mode" is gone from the Cursor steps.
• The prompt names kbagent and the project, asks the agent to check that the app loads its data, and asks for the link to the app's page in Keboola.
• Before you start links a free project and the tutorial's opportunity.csv, with a prompt of its own, so a reader with no project or data can still follow the page.
• The example prompt doesn't ask for a public app. A public app shows its data to anyone with the URL, so the page explains how to ask for one instead.
• His screenshots show the agent signing in to an MCP server and building a draft in a different project on us-east4, even with "using kbagent" in the prompt. So the page tells readers to decline that sign-in and why, instead of promising that the prompt pins the route.

Evidence

• Claude Code, kbagent route (23.09): an isolated session with only the kbagent and dataapp-developer plugins went from the prompt to a running app in project 264 (App ID 74021867) in about 11 minutes.
• Claude Code, MCP route (23.09): it got as far as the draft preview (prod 74021869, draft 74021870).
• Codex CLI 0.157.0 (25.09): the three codex plugin commands on the page work. With the page's prompt, the agent stayed on kbagent end to end (App ID 74022065). Its data check found the missing git block, and it asked before applying the fix. After the yes, the app ran and loaded its data ("Loaded 1244 daily order counts"), and the agent returned both the app URL and the link to its page in Keboola. Its first push failed with Repository not found until it cleared Git's cached credential helper, and the Terminal tab now pushes that way.
• Checks: fact-checker, guide-tester and an independent checker ran after each round, and every finding was fixed or flagged VERIFY. check-cli-reference: 0 findings. The build is clean, audit-phase2 reports 0 broken links, and docs-link-redirect-check reports 0 blockers.

Known issues the page works around

• CLI-15: an app created with --use-managed-git-repo never gets a workspace, which is still the case in kbagent 0.95.0. The fix is managed-repo data apps never get a workspace on first deploy cli#765 (open). The page shows the config update fix. Remove it, Terminal step 5 and the troubleshooting row once Prefill env checkbox to collect URL #765 ships.
• The dataapp-developer plugin's own MCP server is set to https://mcp.us-east4.gcp.keboola.com/mcp as sse. Claude Code gets HTTP 405 from it, and Cursor and Codex ask the user to sign in. For most users it's the wrong stack. The fix belongs in keboola/ai-kit.
• @keboola/api-client 39.0.0 calls Promise.withResolvers, which the app runtime's Node.js 20.19 lacks. The template's ^27.0.0 works.
• The skill zip in public/data-apps/ is a 09.07 snapshot, flagged VERIFY.

Before merge

• VERIFY items for Michal's runs:
  • the Claude Desktop chat;
  • VS Code;
  • the ChatGPT app's own screens (Developer mode, Personal tab);
  • a Cursor run that stays on kbagent;
  • where exactly the password shows.
• A docs owner decides whether the CLI-15 workaround stays until Prefill env checkbox to collect URL #765 ships.
• The UI's link target, /data-apps/build-with-an-agent/, needs confirming with Michal.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
connection-docs	Ready	Preview	Sep 25, 2026 3:24pm UTC

[linear-code]

PRDCT-693

[keboola-pr-reviewer-bot]

Verdict: needs_human (risk 3/5) · profile connection-docs

Escalating: the PR documents unshipped behavior and carries multiple unresolved VERIFY markers, which is the policy's highest-value human-review trigger.

Impact flags: possible rollback re-introduction — see Check Run summary.

Concerns:

• src/content/docs/data-apps/build-with-an-agent.mdx: Documents workaround for unshipped keboola/cli#765 (open PR); remove once it ships.
• src/content/docs/data-apps/build-with-an-agent.mdx: Claude Desktop/Cursor/VS Code/ChatGPT tabs marked VERIFY; build flow not yet run.
• src/content/docs/data-apps/index.md: New route entry carries VERIFY: run end to end in Claude Code only.

Suggested reviewers: @keboola/docs

[eruveo]

Tested with Grok 4.7

1. Number 4

Open the chat in agent mode and paste the prompt from Describe the app. Approve the terminal commands it asks to run.
I would not mention agent mode since it's enabled by default and would make users unsure. Also, I feel like it's unnecessary you can run it in IDE the same way.

2. Prompt

Weird it's confused what to use, I changed the prompt and it knew immediately and prompted for me to login with oauth and it worked perfectly and fast.

Build a Keboola app using kbagent that shows the number of orders per day as a line chart,
from the orders table in my project. Put the code in a new Keboola-managed Git repository, deploy the app, and give me its URL.

Note: 5. Defaults flag

3. Result
   It's good but same issue as we don't share the settings link and password so I need to login, go to apps, find it, get password, meh.

4. Cursor
   I think the steps and the prompt would be enough. The remaining like commands and stuff is noise to me. If I'm using na agent I don't want to know the commands so I would make another tab for CLI.

5. Defaults flag
   This is for all agents so probs should be before the tabs to say that by default the apps are make with keboola git, JS/Python and most importantly with password. Because for first go it might not be the best and mayeb the test prompt could include make it public. I asked it to remove my password and after like 10 mins it failed, not even make a new app.

cc @MiroCillik

Will do GPT and vscode later today...