Using Agent

Use Agent to understand your Bubble project, plan work, and make changes through a conversation.

How Agent works

Buildprint runs the selected provider’s own agent harness behind the scenes. For example, a Codex model runs through the Codex harness, while a Claude model runs through Claude Code.

Each conversation runs inside its own virtual machine. This is a sandboxed cloud environment created specifically for that Agent conversation.

The virtual machine includes:

• Buildprint tools for reading and working with your permitted Bubble project.

• The native agent harness for the selected AI provider.

• Any custom MCP connections you have enabled for that workspace.

• A private filesystem where Agent can create and work with files during the conversation.

This setup gives Agent more than a chat window. It can inspect files, use tools, run commands, and complete multi-step work while the conversation is active.

Agent runtime

The time Agent spends running inside this virtual machine is called Agent runtime.

Runtime includes the time Agent spends thinking, reading files, using Buildprint or MCP tools, and running commands. It is counted whenever Agent is actively working, not only when it writes a reply.

Subagents do not contribute extra runtime, because they run in the main agent's environment.

Your plan includes an amount of Agent runtime. If you use more than the included amount, the extra runtime is charged as a usage-based overage. You can view your included allowance, current usage, and overage details in your workspace billing settings.

Agent runtime is separate from AI model usage. Buildprint models use workspace AI credits, while connected providers use the limits and billing of your provider account. If you use only connected providers like Claude, Codex, and Cursor, then the only cost of using Agent is agent runtime.

Start a conversation

Select the Bubble project you want Agent to work with before you send a message.

1. Open Agent.

2. Select the project shown above the message box.

3. Choose an AI model and reasoning level.

4. Select Plan or Build.

5. Choose which Bubble branches Agent can use.

6. Describe what you want Agent to do, then send the message.

Choose a model

Select the model based on the task and the AI providers connected to your account.

The reasoning setting controls how much thinking the model uses. Higher reasoning can help with difficult tasks, but it can take longer and cost more.

Buildprint models use workspace AI credits. Models from other providers use your existing provider account connected under Integrations → AI Providers. These consume your existing provider's rate limits, and are not limited by Buildprint.

Recommendations

If you do not yet have an AI provider subscription, we currently recommend ChatGPT's $20/mo or $100/mo plan (as of August 12th, 2026). This is because it offers the best value for money in terms of quality and rate limits.

Based on our experience, we recommend the following as a good balance of rate limits:

Choose Plan or Build

Use Plan to investigate and use Build when you are ready for Agent to make changes.

• Plan lets Agent read the permitted project context without changing the Bubble app.

• Build lets Agent change permitted Bubble branches when your Buildprint and Bubble permissions allow it.

You can switch between Plan and Build during a conversation. Check the selected branches before sending work in Build mode.

Add useful context

Agent already has access to the permitted context for the selected project. Add extra context when the task depends on a specific file, skill, page, branch, component, Radar scan, or Linear issue.

Click + to attach a file or select available context. You can also drag files into the message box, paste longer text as an attachment, or record a voice prompt.

Work with Agent

Agent shows its progress inside the conversation while it works.

• Answer any questions Agent asks before it continues.

• If Agent is already working, you can queue another message for the next turn or steer it by sending it immediately

• Review attachments and results before accepting the work.

You can copy a conversation as Markdown, share a read-only link, or fork it into a separate conversation. A fork copies the conversation summary and attachments, but starts with a new Agent environment.

When to start a new conversation

Start a new conversation as soon you change to unrelated work or need a different AI provider. Long conversations can experience degraded performance and hallucinations.

You should also start again if the current conversation has become confused, the Agent environment is errored, or Buildprint tells you that the conversation cannot continue.

Troubleshooting