docs(agent): agent-builds-an-app design overview

[mmabrouk]

What this is

The map for the "agent builds an app" initiative. A new agent on Agenta should start useful, then turn itself into a real application through a conversation: find the tools it needs, connect integrations, edit its own instructions, set a trigger or a cron job, and commit. The agent becomes the app. The user never writes config by hand; they have a conversation.

This doc frames the four design docs that ship together, says what is locked, and lists what is still open. Read it first, then read the four.

Aligned to the approved #4917 build-kit overlay model. The build kit is a read-only agent-template overlay the backend serves on the inspect response at additional_context.playground_build_kit.agent_template_overlay; the frontend applies it for a playground run and excludes it on commit, and the agent service never sees it. The advanced-drawer design folded into #4917, so this is now four sub-projects, not five.

The four sub-projects

• Default agent config (docs(agent): default config as a build-kit overlay (inspect_context) #4917): owns the build-kit overlay and now the drawer UI that renders it. The overlay carries the platform tools and the client tools (as @ag.embed references), the authoring skill (an @ag.embed reference), and the build permissions. Published default goes bare.
• Frontend round-trip (docs(agent): frontend round-trip design (client tools, commit refresh, connections) #4920): the generic client-tool pause and resume the agent uses when it needs a person, for config approval and connection requests. The first client tool is request_connection, a non-runnable reference tool the overlay embeds.
• Builder tools (docs(agent): agent builder tools design (triggers, cron, find-triggers) #4919): the trigger, cron, find-triggers, and undo tools the build flow is still missing, plus the agent-driven trigger-test UX.
• Platform skills (docs(agent): platform skills design for agent self-building #4918): the skills that teach the build flow, plus the naming and the embed shape. They ride the overlay as @ag.embed references.

Cross-cutting locked decisions

• The agent becomes the app (self-modification only).
• A read-only overlay the frontend applies, never committed. The agent service stays dumb: no run flag, no service-side merge.
• Ship all the platform tools in the overlay (every PLATFORM_OPS entry, as { "type": "platform", "op": ... }).
• One generic client-tool round-trip carries both config approval and connection requests.
• Connections are frontend-owned and reference-only; the agent never holds the secret.
• Client tools and skills are reference-tool embeds (@ag.embed); request_connection is not a platform op.
• No forced skills. The published default is bare; a skill reaches a run only because the overlay carries its embed.

How to read

Build order: the frontend round-trip is the foundation; default config is independent and can build in parallel; builder tools and skills build on the round-trip. The advanced-drawer drawer folded into #4917, and the collapsible-sections cleanup ships separately. The decided points and the open items are gathered in the doc and do not block this design review.

Scope / risk

Doc only, no code. This PR is the overview; the substance lives in the four linked PRs.

https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jun 28, 2026 9:48pm

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: bf03672c-0bc7-4ccb-94f1-f41e3c414088

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/agent-builds-an-app-overview

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

🤖 The AI agent says:

What this covers. The map for the whole "agent builds an app" initiative. A new agent should start useful, then turn itself into a real application through a conversation: find tools, connect integrations, edit its own instructions, set a trigger or cron, and commit. This page frames the four design PRs (#4917, #4918, #4919, #4920), says what is locked, and lists what is open.

Where to look. The four sub-project summaries, the cross-cutting locked decisions, and the build order.

Feedback needed. Please confirm the framing and the cross-cutting locked decisions:

• The agent becomes the app (self-modification only).
• Opt-out is delete-only.
• One generic client-tool round-trip carries both config approval and connection requests.
• Connections are frontend-owned and reference-only; the agent never holds the secret.
• Skills arrive by embed, not by force.
• Defaults reach the new-agent draft through the catalog template.

This PR is the map; the four linked PRs hold the detail.

[mmabrouk]

🤖 The AI agent says: Aligned the overview to the approved #4917 build-kit overlay model.

What changed:

• The initiative framing, sub-project list, locked decisions, build order, and open items now describe the overlay model: a read-only agent-template overlay the backend serves at additional_context.playground_build_kit.agent_template_overlay, applied by the frontend on a playground run and excluded on commit, with the agent service kept dumb (no run flag, no service-side merge).
• The advanced-build-kit drawer folded into docs(agent): default config as a build-kit overlay (inspect_context) #4917, so this is now four sub-projects, not five. Added a short section noting the fold and that the collapsible-sections change ships separately as a small drawer cleanup.
• Locked decisions updated: overlay; frontend applies and excludes; client tools and skills as @ag.embed reference-tool embeds (with request_connection not a platform op); no forced skills; published default bare. Dropped the old delete-only, catalog-template, and client-executor-platform-op decisions.
• Builder bullet now mentions the new remove_schedule / remove_subscription undo tools. Decided points (toggle ephemeral, drawer fold, kit permissions read-only, builder testing) moved to a "Decided" section; open items trimmed to the four docs.

Please review the locked-decisions list and the four-sub-project structure.

[mmabrouk]

The load-bearing locked decision: the build kit is a read-only overlay the frontend applies and excludes, served at additional_context.playground_build_kit.agent_template_overlay. The agent service stays dumb. This is the pivot that ripples through all four docs.

[mmabrouk]

The advanced build-kit drawer is no longer a separate sub-project: its design folded into #4917, which now owns both the overlay and the drawer. The collapsible-sections change is the one piece that ships independently.