Tips for Building

Your agent is only as good as the guidance you give it. These tips will help you build an agent that behaves the way you expect more of the time.

Purpose & Instructions

• Keep Purpose to the job, Instructions to the method. Purpose is the one thing the agent exists to do; how it should go about the work belongs in Instructions. Splitting them this way keeps both readable as the build grows.
• Put hard constraints in Guardrails. Anything the agent must never do is a rule, not a line buried in your instructions.
• Be concrete about tone. "Friendly but concise, never sarcastic" gives the agent more to work with than "be nice."
• Re-read before you add. Instructions accumulate over the life of a build, and the fastest way to get inconsistent behavior is to stack a new instruction on top of one that contradicts it.

Writing Effective Rules

Your General and Privacy Rules are instructions the agent has to reconcile on every request. A few habits keep them working well:

• Avoid contradictions. Make sure no two rules pull in opposite directions—for example, "always give the user a direct answer" alongside "never discuss pricing." When rules conflict, the agent's behavior becomes unpredictable. Read your list top to bottom and check it hangs together.
• Be specific. "Don't share sensitive info" is vague; "Never reveal a user's email address, phone number, or home address" is something the agent can act on precisely.
• One idea per rule. Keep each rule focused on a single behavior, and give it a clear name. Short, single-purpose rules are easier for both you and the agent to reason about.
• Prefer clear instructions over clever ones. Plain, literal wording leaves less room for misinterpretation than hints or implications.

Describing Your Data

When you set up the Bubble DB Read Tool, your table and column descriptions are how the agent understands your data. Good descriptions lead directly to better answers.

• Keep descriptions to one to three sentences. Enough to convey what a table or column means, without burying the signal. Long, rambling descriptions dilute the important part.
• Describe meaning, not just type. The type field already says a column is a number—your description should say it's "the user's current subscription tier, from 1 to 3."
• Use the language your app actually uses. Match the names and terms your users and your application use, so the agent's answers line up with what people see in your product.
• Only expose what the agent needs. Fewer, well-chosen tables and columns make the agent faster and more accurate—and reduce the chance of surfacing something it shouldn't. Leave out anything irrelevant to the questions it will answer.

Test Before You Ship

• Build in Test first. The editor always edits your Test configuration—deploy there, try it from your app with environment: test, and only deploy to Live once it behaves the way you want.
• Give a deploy a moment to land. A deploy can take up to a minute to reach the agent, so wait before testing a change you just pushed.
• Change one thing at a time. When you adjust several settings at once and behavior shifts, it's hard to tell which change did it. Small, deliberate edits are easier to evaluate.
• Check the Live pane before you deploy to it. It is read-only and shows exactly what your live agent is running, which makes it the quickest way to see what a Live deploy would change.