Pearl Upgrade: Code-Based Sandbox Execution

We just gave our AI assistant the ability to write and execute code before building your workflows. Here's why that changes everything.

TL;DR

We've moved from static tool calling to code-based agents, giving Pearl (our AI assistant) the ability to gather context, ask clarifying questions, and build personalized and intelligent workflows for you.

Problem

When we first launched Bubble Lab's AI workflow generator, we were already ahead of the curve. While our competitors relied on rigid JSON infrastructure, Pearl could generate custom TypeScript workflows through intelligent tool calling with our Bubble system. (Note: "Bubbles" are our reusable workflow components (integrations, tools etc))

But we faced some critical bottlenecks. Here's what we observed in production:

Scenario 1:

A user asks: "Help me automate my database reporting"

Pearl generates a workflow... but which database? Which tables? What kind of reports?

Scenario 2:

Another user says: "Scrape product data from my supplier's website"

Pearl creates a scraper... but doesn't know the site's structure, pagination, or what fields to extract.

Oftentimes, Pearl was generating syntactically good code that was contextually useless. It's like hiring a carpenter who builds beautiful cabinets without measuring your kitchen first—the craftsmanship is flawless, but it doesn't fit your space.

The Industry Standard Approach (And Why It Wasn't Enough for Us)

The hot industry response to this challenge is MCP (Model Context Protocol). The pitch is compelling: a universal standard for AI agents to discover and call tools, complete with context-gathering capabilities.

MCP solves real problems and we're planning to add MCP support soon to enable missing integrations and allow users to plug in their own servers. However, for the specific challenge of intelligent context gathering, we needed something more powerful.

As detailed in our previous blog "The Agentic Future is Code-First", some issues with MCP include:

Context Window Pollution: Every tool definition bloats the context, slowing down inference and driving up costs
Abstraction Tax: High-level tool-calling syntax is inherently limited compared to actual programming
Progressive Disclosure Failure: You can't selectively load tools—it's all or nothing

MCP excels at standardization and interoperability. But for dynamic, intelligent context gathering with maximum flexibility, we needed the full expressiveness and reliability of code.

Our Solution: Giving Pearl Code Execution in a Sandboxed Environment

With our new update, Pearl runs a planning agent before code generation to gather context and clarify requirements. But here's the key insight—Pearl doesn't just ask questions. It writes and executes code.

How It Works

When you ask Pearl to build a workflow, it springs into action with a three-phase approach:

Phase 1: Intelligent Context Gathering

Before asking you anything, Pearl can:

1. Search and Scrape the Web

User mentions a website? Pearl scrapes it to understand the structure
Vague request about "job listings sites"? Pearl searches the web to find popular options
Need to understand an API? Pearl researches and reads the documentation

2. Execute BubbleFlow Code for External Context

Here's where it gets interesting. Pearl can write and execute actual BubbleFlow code to gather context from your integrated services:

// Pearl writes this code to understand your database
export class ContextGatheringFlow extends BubbleFlow<'manual'> {
  async run() {
    const schema = new PostgresListTablesTool({
      credentials: { /* Pearl asks for your DB creds */ }
    });
    
    return await schema.action();
    // Returns: { tables: ['users', 'orders', 'products'], ... }
  }
}

Pearl then:

Validates the code (catches errors before execution)
Requests credentials from you through an intuitive UI
Executes the code in a secure sandbox
Uses the results to understand your specific setup

Real-World Examples:

Want to automate Google Sheets workflows? Pearl can:

List all your spreadsheets
Fetch sheet names and column headers
Understand your data structure

Building a database workflow? Pearl can:

Fetch your table schemas
Understand relationships
See sample data

All before generating a single line of your actual workflow.

Phase 2: Targeted Clarification

Armed with context, Pearl asks smart, specific questions (but keeping it as multiple choice):

I found these tables in your database:
- users (id, email, name, created_at)
- orders (id, user_id, total, status, created_at)
- products (id, name, price)

Which data should I include in the daily report?
○ User signups and order totals
○ Product sales breakdown
○ Custom (specify)

Notice the difference? Pearl isn't asking "What database do you have?" - it already knows. It's asking about your specific implementation choices.

Phase 3: Plan Generation

Finally, Pearl generates a detailed plan:

Implementation Plan:

Summary: Daily report workflow that queries your PostgreSQL database
         for order metrics and sends formatted results via email.

Steps:
1. Database Query
   - Use PostgresQueryTool to fetch daily orders from 'orders' table
   - Join with 'users' table for customer information
   - Aggregate by date

2. Data Transformation 
   - Calculate total revenue, order count, average order value
   - Format as HTML table

3. Email Delivery
   - Use ResendEmailTool to send report
   - Recipients: team@company.com
   - Scheduled: Daily at 9 AM

Estimated Bubbles: PostgresQueryTool, ResendEmailTool, Schedule

You approve (or request changes), and then Pearl generates the workflow with full context.

Why Code-Based Context Gathering Wins

Leading AI companies are increasingly validating code-based execution for agents (see our previous blogs)– and for good reason. Here's what this approach gives us:

1. No Context Window Tax

Pearl doesn't load hundreds of tool definitions into context. It imports only what's needed:

import { PostgresListTablesTool } from '@bubblelab/bubble-core';

Clean, efficient, and leveraging TypeScript's module system.

2. Unlimited Expressiveness

Need to gather context about nested data structures? Parse complex schemas? Transform API responses? Just write Typescript:

const tables = await listTables.action();
const relevantTables = tables.data.tables
  .filter(t => t.name.includes('customer'))
  .map(t => ({ name: t.name, columns: t.columns.slice(0, 5) }));

This level of nuance is not possible with MCP tool definitions.

3. Secure and Observable

Every context-gathering flow runs in our secure sandbox. You can:

See exactly what code will execute
Review which credentials it needs
Approve or reject before execution
Debug with full execution logs

4. Composable and Reusable

Context-gathering flows are just BubbleFlows. That means:

They can use any bubble in our ecosystem
They can be saved and reused
They benefit from all our existing tooling (validation, error handling, retry logic)

The workflows Pearl generates are now contextually aware from the start. No more generic database queries that need to be fixed. No more hardcoded values that users need to update. Just workflows that work with their data, their integrations, their requirements.

Pearl doesn't just ask better questions. It runs code to understand your world, then generates code that fits perfectly into it.

Technical Deep Dive (For the Curious)

How Pearl's `runBubbleFlow` Tool Works

When Pearl needs external context, here's what happens:

Code Generation: Pearl writes a BubbleFlow (using get-bubble-details-tool to understand bubble APIs first)
Validation: We parse and validate the code using our existing BubbleFlow runtime
Credential Detection: Extract which credentials the flow needs (PostgreSQL, Google Sheets, etc.)
User Approval: Show you a UI widget with:
- What the flow does (in plain English)
- What credentials it needs
- Option to approve or skip
Secure Execution: Run in our sandboxed environment (same security model as your actual workflows)
Context Integration: Pearl receives the results and uses them to generate better questions and plans

Example Context-Gathering Flow

// Pearl writes this to gather Google Sheets context
export class ListSheetsFlow extends BubbleFlow<'manual'> {
  async run() {
    const listSpreadsheets = new GoogleSheetsListSpreadsheetsTool({
      credentials: {
        google_oauth_cred: this.credentials.google_oauth_cred
      }
    });
    
    const result = await listSpreadsheets.action();
    
    return {
      spreadsheets: result.data.spreadsheets.map(s => ({
        id: s.id,
        name: s.name,
        url: s.url
      }))
    };
  }
}

The flow returns structured data that Pearl can reason about:

{
  "spreadsheets": [
    {
      "id": "abc123",
      "name": "Sales Data 2024",
      "url": "https://docs.google.com/spreadsheets/d/abc123"
    },
    {
      "id": "xyz789",
      "name": "Customer List",
      "url": "https://docs.google.com/spreadsheets/d/xyz789"
    }
  ]
}

Now when Pearl asks "Which spreadsheet should I use?", it can present actual options from your Google account.

Security and Privacy

All context-gathering flows:

Run in the same secure sandbox as production workflows
Require explicit user approval before execution
Use the credentials you provide (never stored by Pearl)
Have full execution logs available for debugging
Are limited to read-only operations by default

You have complete control and visibility into what Pearl executes.

Closing Thoughts

We're excited to see how Pearl's new code-based context gathering transforms the way you build workflows. No more generic templates or guesswork,just intelligent, context-aware automation that understands your specific setup from the start.

Experience the new Pearl now, and if you have any questions or feedback, we're all ears on Discord!