Forem: David Nzagha

Building WebClaw: A Personal Live AI Support Agent That Actually Operates Websites

David Nzagha — Mon, 16 Mar 2026 19:56:41 +0000

What if every website had an intelligent, voice-enabled agent that could actually do things for you, not just answer questions into the void?

How we built a live agent that sees, hears, speaks, and acts on web pages, powered by Google Gemini's bidirectional audio streaming.

The Problem Nobody Talks About

Website support is stuck in 2015. Chat widgets serve canned responses. Users abandon carts because they can't find the checkout button. Support staff asks, "Can you send a screenshot?" because they can't see what the user sees.

Every interaction starts from zero.

We wanted to build something different: an AI agent that doesn't just answer questions about a website, but actually operates it alongside you. Click buttons. Fill forms. Navigate pages. All through natural conversation.

That's WebClaw.

What WebClaw Does

WebClaw is a voice-first AI agent that lives on websites. Site owners add a single <script> tag (the same pattern as Google Analytics), and visitors get an animated avatar they can talk to. The agent can:

See the page through DOM snapshots and screenshots
Hear the user through real-time microphone streaming
Speak back with natural voice (supporting barge-in)
Act on the DOM: clicking, typing, scrolling, navigating, highlighting

Say "help me check out," and the agent navigates to the cart, walks you through the form, and confirms the order. It doesn't paste a link to the checkout page.

There's also a Chrome Extension mode (Personal Agent) that works on any website, not just integrated ones. When a Personal Agent visits a WebClaw-integrated site, the two negotiate: the site shares its knowledge base, and the agent keeps the user's data private. Privacy by architecture, not policy.

The Tech Stack

Gemini Live API: The Core

The entire project hinges on Gemini's bidiGenerateContent method. This isn't request-response; it's a persistent bidirectional stream. Audio flows in both directions simultaneously. The user can interrupt the agent mid-sentence (barge-in). The agent can call functions while speaking.

We use gemini-2.5-flash-native-audio-preview-12-2025 because it supports bidiGenerateContent for live audio with native voice generation and function calling. The native audio model produces higher-quality, more natural voice output than the older experimental models.

Google ADK: Agent Scaffolding

The Agent Development Kit handles the ceremony: session management, function-calling schema generation, and the LiveRequestQueue abstraction for feeding audio and text into the bidi stream. Our agent definition is clean:

root_agent = Agent(
    name="webclaw_agent",
    model="gemini-2.5-flash-native-audio-preview-12-2025",
    instruction=WEBCLAW_SYSTEM_PROMPT,
    tools=DOM_TOOLS,
)

Ten DOM tools are registered as typed Python functions. ADK converts them to Gemini function-calling schemas automatically. When the model decides to click a button, it returns a function_call event that we forward to the browser for execution.

The Gateway: FastAPI + WebSocket

The gateway sits between the browser and Gemini, running on Cloud Run. Each visitor gets a WebSocket connection that spawns two async tasks:

Browser --> Upstream Task --> LiveRequestQueue --> Gemini
                                                    |
Browser <-- Downstream Task <-- runner.run_live() <-+

Full duplex. The user speaks while the agent responds. DOM action results flow back while the agent processes the next thought.

Why not connect the browser directly to Gemini? Four reasons:

Privacy. The gateway enforces asymmetric context sharing. Site JavaScript can't intercept user data.
Security. DOM actions are validated against the site's permission list before execution.
Scalability. Cloud Run auto-scales with session affinity for WebSocket stability.
Analytics. Session history, message counts, and action metrics are all stored in Firestore.

The Embed Script: 26.1KB of TypeScript

The client-side embed script runs in a closed Shadow DOM (complete CSS isolation from the host page) and weighs 26.1KB minified. No runtime dependencies. It includes:

Animated avatar (Canvas 2D with lip-sync, eye blinks, state transitions)
Action visualizer (avatar flies to target elements via bezier curve with trail particles)
Screenshot capture (Canvas-based viewport rendering for vision context)
Audio pipeline (16kHz mic capture, 24kHz playback, raw PCM, no codecs)
Smart element finder (CSS selector, then aria-label, then text content match)

We chose esbuild for bundling: 2ms build time, zero config. The avatar uses Canvas 2D instead of Lottie (+50KB) or Three.js (+150KB) because every kilobyte matters in an embed script loaded on every page view.

Hard Problems We Solved

The Model Migration

We started development targeting gemini-2.0-flash-live-001. Midway through, we discovered it no longer exists in the API. We queried every available model for bidiGenerateContent support and found several options:

Model	bidi	generate	Notes
`gemini-2.5-flash-native-audio-preview-12-2025`	✅	❌	Current default; native audio with function calling
`gemini-2.5-flash-native-audio-latest`	✅	❌	Tracks latest stable native-audio model
`gemini-2.0-flash-exp-image-generation`	✅	✅	Legacy; broadest capability but older

We chose the native audio model for its superior voice quality and lower latency in real-time conversations.

Token-Efficient DOM Serialization

A typical webpage's full DOM is 50,000+ tokens. We needed to fit page context into the LLM's window without drowning out the conversation. Our serializer:

Includes only interactive elements (buttons, links, inputs) and semantic elements (headings, nav, main)
Excludes scripts, styles, SVGs, and iframes
Caps depth at 3 levels
Caps output at 4,000 characters

The result captures the page's interactive surface area in roughly 500 tokens.

Action Visualization

When the agent clicks a button, users need to see what happened. We built a Bezier flight animation: a glowing indicator launches from the avatar, arcs upward, and lands on the target element with a pulse ring effect. Trail particles follow with a delayed, staggered motion. The whole animation runs in 600ms using requestAnimationFrame with cubic ease-in-out.

This transforms "the agent clicked something" into "I watched the agent fly to that button and click it." Agency you can see.

Asymmetric Privacy

When a Personal Agent (Chrome Extension) visits a WebClaw-integrated site, context flows in one direction:

Site Knowledge ------> Agent Context <------ User Preferences
    (public)              (merged)              (private)
                                                   |
                                             NEVER flows to
                                             ----> Site Owner

This isn't a policy in the terms of service. It's infrastructure. The gateway physically can't leak user data to the site because the data flow is architecturally one-directional. The negotiation protocol (negotiate / negotiate_ack messages) establishes what the site offers and what the agent may do, without exposing who the user is or what they've done on other sites.

What We Built in Numbers

Component	Metric
Gateway	18 REST endpoints, WebSocket bidi streaming
Embed script	26.1KB minified, 8 TypeScript modules
Chrome Extension	MV3, 4 files, negotiation protocol
Dashboard	Vanilla HTML/JS, 5 pages, no build step
Documentation	14 pages, 3,700+ lines, 150KB+
DOM tools	8 operations (click, type, scroll, navigate, highlight, read, select, check)
Firestore collections	4 (sites, sessions, knowledge, stats)

Lessons Learned

Voice-first changes everything. When you design for speech as the primary modality, the entire UX shifts. Text fallback is trivial to add; designing for voice from scratch is not. We built the audio pipeline first and added text second.

Shadow DOM is non-negotiable for embeds. We tried CSS namespacing first. Host pages with * { box-sizing: border-box; margin: 0; } destroyed our overlay. Closed Shadow DOM solves it permanently, and unlike iframes, we can still observe and act on the host page's DOM.

Raw PCM beats codecs for live streaming. Gemini accepts and produces raw PCM. Adding Opus encoding/decoding would introduce latency and complexity for zero benefit. Shortest path wins.

Build the dashboard last. We almost built a React dashboard early on. Instead, we finished all features first, then wrote a single HTML file with vanilla JS that calls the same REST API. 640 lines, no build step, no dependencies, ships in the Docker image. Sometimes the boring solution is the right one.

Try It

WebClaw is open source. Clone the repo, set your GOOGLE_API_KEY, and run:

cd gateway && pip install -r requirements.txt && uvicorn main:app --port 8081
cd embed && npm install && npm run build
# Open http://localhost:8081/demo

Or deploy to Cloud Run with a single command:

cd infra && ./deploy.sh

The demo site is a fake e-commerce store (TechByte) where you can ask the agent to add products to the cart, find specific items, or navigate the FAQ.

Built by David Nzagha and the Nzagha Ventures team for the Gemini Live Agent Challenge.

WebClaw is a submission to the Gemini API Developer Competition (Live Agents category). Built with Gemini Live API, Google ADK, and Google Cloud Run.

Creating Chainable Methods, Everything You need to Know about The Fluent Interface Design Patterns as a PHP Laravel Developer.

David Nzagha — Mon, 03 Jul 2023 10:20:20 +0000

Have you ever marvelled at the elegance and power of chainable methods in the Laravel framework? Do you wonder how the brilliant mind of Taylor Otwell brought this intuitive and efficient design pattern to applicability in your favourite PHP Framework? Whether you're a beginner developer seeking answers, or an advanced developer seeking explanation, you're in the right place!

In this comprehensive blog post, we'll unravel the concepts of the Fluent Design Pattern and explore how it empowers you to write clean, readable, and highly expressive code in PHP, Laravel and beyond. We'll dive deep into the concept, demystify its inner workings, and equip you with the tools to harness its full potential.

Introduction

Fluent Interface Design Pattern is a popular design pattern in object-oriented programming that allows developers to create more readable and expressive code. This pattern is used to simplify the use of APIs by allowing method chaining and creating a more natural language-like interface. The Fluent Interface Design Pattern provides a concise and expressive way of configuring objects and invoking methods on them.

Quick Example of Fluent Interface Design Pattern in PHP

Here's an example of how you can use the Fluent Interface Design Pattern in PHP to create a simple query builder:

class QueryBuilder
{
    protected $table;
    protected $columns = array();
    protected $where = array();

    public function table($table)
    {
        $this->table = $table;
        return $this;
    }

    public function select($columns)
    {
        $this->columns = is_array($columns) ? $columns : func_get_args();
        return $this;
    }

    public function where($column, $operator, $value)
    {
        $this->where[] = compact('column', 'operator', 'value');
        return $this;
    }

    public function build()
    {
        $columns = implode(', ', $this->columns);
        $where = '';

        if (!empty($this->where)) {
            $where = ' WHERE ';
            foreach ($this->where as $clause) {
                $where .= "{$clause['column']} {$clause['operator']} '{$clause['value']}' AND ";
            }
            $where = rtrim($where, ' AND ');
        }

        return "SELECT {$columns} FROM {$this->table}{$where}";
    }
}

This class provides a fluent API for building SQL queries. You can use it like this:

$query = (new QueryBuilder())
    ->table('users')
    ->select('name', 'email')
    ->where('age', '>', 18)
    ->where('country', '=', 'USA')
    ->build();

echo $query;

This will output the following SQL query:

SELECT name, email FROM users WHERE age > '18' AND country = 'USA'

In this example, each method in the QueryBuilder class returns $this, which allows method chaining. The table method sets the table name, the select method sets the columns to select, and the where method adds WHERE clauses to the query builder, respectively. The build method returns the final SQL query as a string.

Now let's take a deeper dive into the concept, the objective benefits and several examples for better understanding.

What is a Design Pattern?

A design pattern is a reusable solution to a common software design problem. It is a template that can be applied to different situations in software design to solve problems that are similar in nature. Design patterns are not specific to a particular programming language but can be implemented in various programming languages.

Design patterns can be classified into three categories: creational, structural, and behavioral. Creational design patterns deal with object creation mechanisms, trying to create objects in a manner suitable to the situation. Structural design patterns deal with object composition, trying to form large structures of objects. Behavioral patterns focus on communication between objects, and thus provide solutions for communication-related issues.

What is Fluent Interface Design Pattern?

Fluent Interface Design Pattern is a type of API (Application Programming Interface) design that provides an easy-to-read and expressive interface for configuring objects and invoking methods on them. This pattern is also known as method chaining because it allows you to chain method calls together in a single statement. The result of each method call is an object that can be used to call the next method in the chain.

The Fluent Interface Design Pattern is based on the principle of method chaining. Method chaining is a technique where multiple method calls are chained together in a single statement. Each method in the chain returns an object on which the next method can be called. This creates a fluent and readable interface that makes it easy to configure objects and invoke methods.

The Fluent Interface Design Pattern provides a more natural and intuitive way of using APIs. It makes the code more readable and expressive, which makes it easier to understand and maintain. It also reduces the chances of making errors while using the API.

The Fluent Interface Design Pattern can be used to configure objects, set properties, and invoke methods on them. It can also be used to build complex object hierarchies and create domain-specific languages.

Why use Fluent Interface Design Pattern?

The Fluent Interface Design Pattern has several benefits that make it a popular choice for API design. Here are some of the benefits of using the Fluent Interface Design Pattern:

Readability: The Fluent Interface Design Pattern makes the code more readable and expressive. The chained methods provide a clear and concise way of configuring objects and invoking methods on them.

Intuitiveness: The Fluent Interface Design Pattern provides an intuitive way of using APIs. The fluent syntax makes it easy to understand how to use the API without reading the documentation.

Reduced Errors: The Fluent Interface Design Pattern reduces the chances of making errors while using the API. The chained methods provide a clear and concise way of configuring objects and invoking methods on them, which reduces the chances of making mistakes.

Flexibility: The Fluent Interface Design Pattern provides flexibility in configuring objects and invoking methods on them. It allows you to build complex object hierarchies and create domain-specific languages.

Maintainability: The Fluent Interface Design Pattern makes the code more maintainable. The fluent syntax makes it easy to understand and modify the code, which makes it easier to maintain.

Deep Dive Examples of Fluent Interface Design Pattern

Let's look at more examples of the Fluent Interface Design Pattern.

Example 1: Setting Properties

Suppose you have a class named Person that has two properties, name and age. You want to set the values of these properties using the Fluent Interface Design Pattern. Here's how you can do it in PHP:

class Person {
    private $name;
    private $age;

    public function setName($name) {
        $this->name = $name;
        return $this;
    }

    public function setAge($age) {
        $this->age = $age;
        return $this;
    }
}

// Using Fluent Interface to Set Properties
$person = (new Person())->setName("John")->setAge(30);

In the above example, the setName and setAge methods return the same object on which they are called. This allows the methods to be chained together to set the values of the name and age properties.

Example 2: Invoking Methods

Suppose you have a class named Calculator that has four methods, add, subtract, multiply, and divide. You want to perform a series of calculations using the Fluent Interface Design Pattern. Here's how you can do it in PHP:

class Calculator {
    private $result;

    public function add($num) {
        $this->result += $num;
        return $this;
    }

    public function subtract($num) {
        $this->result -= $num;
        return $this;
    }

    public function multiply($num) {
        $this->result *= $num;
        return $this;
    }

    public function divide($num) {
        $this->result /= $num;
        return $this;
    }

    public function getResult() {
        return $this->result;
    }
}

// Using Fluent Interface to Perform Calculations
$calculator = (new Calculator())
    ->add(10)
    ->subtract(5)
    ->multiply(2)
    ->divide(4);
$result = $calculator->getResult(); // Result is 2

In the above example, the add, subtract, multiply, and divide methods return the same object on which they are called. This allows the methods to be chained together to perform a series of calculations.

Example 3: Creating Domain-Specific Languages

The Fluent Interface Design Pattern can be used to create domain-specific languages (DSLs) that are tailored to specific domains. DSLs are specialized languages that are designed to solve problems in a specific domain.

Suppose you want to create a DSL for building SQL queries. Here's how you can do it in PHP:

class SqlQueryBuilder {
    private $tableName;
    private $columns = array();
    private $whereClauses = array();

    public function select(...$columns) {
        $this->columns = array_merge($this->columns, $columns);
        return $this;
    }

    public function from($tableName) {
        $this->tableName = $tableName;
        return $this;
    }

    public function where($clause) {
        $this->whereClauses[] = $clause;
        return $this;
    }

    public function build() {
        $queryBuilder = new StringBuilder();
        $queryBuilder->append("SELECT ");
        if (empty($this->columns)) {
            $queryBuilder->append("*");
        } else {
            $queryBuilder->append(implode(", ", $this->columns));
        }
        $queryBuilder->append(" FROM ")->append($this->tableName);
        if (!empty($this->whereClauses)) {


 $queryBuilder->append(" WHERE ");
            $queryBuilder->append(implode(" AND ", $this->whereClauses));
        }
        return $queryBuilder->toString();
    }
}

// Using Fluent Interface to Build SQL Queries
$sqlQuery = (new SqlQueryBuilder())
    ->select("id", "name", "email")
    ->from("users")
    ->where("age > 18")
    ->build(); // Result: "SELECT id, name, email FROM users WHERE age > 18"

In the above example, the SqlQueryBuilder class provides a fluent interface for building SQL queries. The select, from, and where methods add columns, table name, and WHERE clauses to the query builder, respectively. The build method returns the final SQL query as a string.

These are just simple examples of how you can use the Fluent Interface Design Pattern to create a DSL. The possibilities are endless, and you can create DSLs for various domains, including configuration files, HTML, XML, JSON, and more.

Here are more complex and advanced examples of using the Fluent Interface Design Pattern in PHP:

Example 4: Database Query Builder

Suppose you want to create a fluent database query builder that supports various query operations like SELECT, INSERT, UPDATE, and DELETE. Here's an example of how you can implement it:

class QueryBuilder
{
    protected $table;
    protected $columns = [];
    protected $where = [];
    protected $values = [];

    public function table($table)
    {
        $this->table = $table;
        return $this;
    }

    public function select(...$columns)
    {
        $this->columns = array_merge($this->columns, $columns);
        return $this;
    }

    public function where($column, $operator, $value)
    {
        $this->where[] = compact('column', 'operator', 'value');
        return $this;
    }

    public function insert(array $values)
    {
        $this->values = $values;
        return $this;
    }

    public function update(array $values)
    {
        $this->values = $values;
        return $this;
    }

    public function delete()
    {
        return $this;
    }

    public function build()
    {
        $query = '';

        if (!empty($this->columns)) {
            $query .= 'SELECT ' . implode(', ', $this->columns) . ' FROM ' . $this->table;
        } elseif (!empty($this->values)) {
            if ($this->table) {
                $query .= 'INSERT INTO ' . $this->table . ' SET ';
            } else {
                $query .= 'UPDATE SET ';
            }

            $values = [];
            foreach ($this->values as $column => $value) {
                $values[] = $column . ' = ' . $value;
            }

            $query .= implode(', ', $values);
        } else {
            $query .= 'DELETE FROM ' . $this->table;
        }

        if (!empty($this->where)) {
            $query .= ' WHERE ';

            $conditions = [];
            foreach ($this->where as $clause) {
                $conditions[] = $clause['column'] . ' ' . $clause['operator'] . ' ' . $clause['value'];
            }

            $query .= implode(' AND ', $conditions);
        }

        return $query;
    }
}

// Example usage
$query = (new QueryBuilder())
    ->table('users')
    ->select('name', 'email')
    ->where('age', '>', 18)
    ->build();

echo $query; // Output: SELECT name, email FROM users WHERE age > 18

In this example, the QueryBuilder class supports building SELECT, INSERT, UPDATE, and DELETE queries. The methods select, where, insert, and update set the desired query components, and the build method constructs the final query string.

Example 5: Fluent API for Configuration

Suppose you want to create a fluent API for configuring various settings in your application. Here's an example:

class AppConfigurator
{
    protected $settings = [];

    public function setDatabaseConfig($host, $username, $password, $database)
    {
        $this->settings['database'] = compact('host', 'username', 'password', 'database');
        return $this;
    }

    public function setCacheConfig($driver, $host, $port)
    {
        $this->settings['cache'] = compact('driver', 'host', 'port');
        return $this;
    }

    public function setLoggingConfig($

enabled, $logLevel)
    {
        $this->settings['logging'] = compact('enabled', 'logLevel');
        return $this;
    }

    public function build()
    {
        return $this->settings;
    }
}

// Example usage
$config = (new AppConfigurator())
    ->setDatabaseConfig('localhost', 'root', 'password', 'my_database')
    ->setCacheConfig('redis', '127.0.0.1', 6379)
    ->setLoggingConfig(true, 'debug')
    ->build();

print_r($config);

In this example, the AppConfigurator class provides fluent methods for setting different configuration options such as the database, cache, and logging settings. The build method returns the final configuration as an array.

Example 6: Fluent Builder for Object Creation

Suppose you have a complex object with many properties and want to simplify the process of creating instances of that object. Here's an example:

class Car
{
    protected $brand;
    protected $model;
    protected $color;
    protected $year;

    public function setBrand($brand)
    {
        $this->brand = $brand;
        return $this;
    }

    public function setModel($model)
    {
        $this->model = $model;
        return $this;
    }

    public function setColor($color)
    {
        $this->color = $color;
        return $this;
    }

    public function setYear($year)
    {
        $this->year = $year;
        return $this;
    }

    public function build()
    {
        return new Car($this->brand, $this->model, $this->color, $this->year);
    }
}

// Example usage
$car = (new Car())
    ->setBrand('Toyota')
    ->setModel('Camry')
    ->setColor('Blue')
    ->setYear(2022)
    ->build();

echo $car->getBrand(); // Output: Toyota
echo $car->getModel(); // Output: Camry
echo $car->getColor(); // Output: Blue
echo $car->getYear(); // Output: 2022

In this example, the Car class has fluent methods for setting the brand, model, color, and year of a car. The build method creates an instance of the Car object with the specified properties.

These examples demonstrate how the Fluent Interface Design Pattern can be used in more complex scenarios, such as building database queries, configuring applications, and simplifying object creation.

Conclusion

In conclusion, the Fluent Interface Design Pattern is a powerful and elegant design pattern that simplifies API usage by allowing method chaining and creating a natural language-like interface. By using the Fluent Interface Design Pattern, developers can write clean, readable, and highly expressive code in PHP, Laravel, and beyond.

The benefits of using the Fluent Interface Design Pattern are numerous. It enhances code readability and intuitiveness, making it easier to understand and maintain. The ability to chain methods together in a single statement reduces errors and provides flexibility in configuring objects and invoking methods. Additionally, the Fluent Interface Design Pattern can be used to create domain-specific languages, allowing developers to build expressive APIs tailored to specific domains.

In the provided examples, we saw how the Fluent Interface Design Pattern can be applied to set properties, invoke methods, and create domain-specific languages. From building SQL queries to performing calculations and configuring application settings, the Fluent Interface Design Pattern proves to be a versatile and valuable tool in software development. By leveraging this pattern, developers can write more expressive and efficient code, enhancing their productivity and the overall quality of their applications.

Furthermore, the Fluent Interface Design Pattern encourages good design practices such as encapsulation, modularity, and separation of concerns. It promotes the creation of reusable and composable code, allowing for flexible and extensible implementations.

Overall, the Fluent Interface Design Pattern is a valuable addition to any developer's toolkit. It brings clarity, expressiveness, and flexibility to code, resulting in code that is more maintainable, readable, and enjoyable to work with. By leveraging the power of method chaining and a fluent API, developers can create elegant and concise code that is both efficient and easy to understand.