Browser extension (Buddy)
Connect the user's browser to the site you deployed, so the Agent can open tabs, read pages, extract images and fill forms. Skip this if your deployment does not need browser capabilities.
What Buddy is
The browser tools (open / switch tabs, read a page, extract images, fill forms, click) do not run on the server. They run in the user's own Chrome: the server sends each instruction to the user's browser, the Buddy extension executes it and sends the result back. That end has to be installed on a desktop, and that tab has to stay open.
Both deployment shapes are supported:
| The user's site | How the extension connects |
|---|---|
agenti.chat (official domain) |
Works after install; the official domain is built into the extension |
| Your own domain (private deployment) | After install, add your domain under "your own sites" in the extension — see below |
Chrome's extension channel is static manifest metadata: whether a domain may talk to the extension is fixed at publish time and cannot be broadened at runtime. A self-hosted domain takes a different path — the extension injects a bridge script into domains the user has explicitly added, and the page relays through it. So adding the domain is not optional; it is the precondition of the whole path. Adding is authorizing: pages on an added site can drive the extension directly, so only add deployments you control.
Prerequisites
- Desktop Chrome or a Chromium-based browser. Phone browsers cannot run it: on iOS only Safari supports extensions and on Android only Firefox; neither hosts Chrome extensions. A phone can send instructions, but execution always happens on the desktop.
- The user installs the extension in their own browser profile (IT can push it).
- The server side has browser tools switched on, see the next section.
Server-side switches
Two of them; both are required:
| Where | Variable | Effect |
|---|---|---|
thia-agent ConfigMap |
BROWSER_TOOLS_ENABLED=true |
Enables browser tools for the model. With false the model does not even see them |
thia-web ConfigMap |
EXTENSION_STORE_URL=https://chromewebstore.google.com/detail/<id> |
The install link on the in-app extension page; the extension id is parsed from it too |
With
BROWSER_TOOLS_ENABLED=falseprobes, logs and conversations all look healthy — the model simply has no browser tools. This is the easiest "installed but not switched on" to miss.
Also set the top-level webBaseUrl in thia-agent's agentic.yaml (mounted from a ConfigMap, see
Manual per-service deployment) to this site's address, e.g. webBaseUrl: 'https://<your-domain>'.
When a browser tool fails, the model uses it to hand out the in-app install page link; leaving it unset only costs
that link, not the tools themselves.
Upgrading an existing thia-agent
A new environment only needs the init script from Database schema. If thia-agent is
already deployed, run one more statement: CREATE TABLE IF NOT EXISTS is a no-op on a table that exists, so it
will not add the column to sse_subscriptions. Run this first, then swap the image:
ALTER TABLE sse_subscriptions
ADD COLUMN IF NOT EXISTS can_execute BOOLEAN NOT NULL DEFAULT TRUE;
Reversing the order does not error — writing that column fails and is swallowed, and the service degrades to "only connections on this pod count", i.e. the behaviour before the change: a page that is connected but cannot run tools is reported as "no page is connected". Run the statement afterwards and it recovers.
Let the extension know your domain
User action, once per computer (the list lives in Chrome's synced storage: with a Chrome account signed in, other computers on the same account pick it up the next time the browser starts; without one it stays on that computer):
- Install Buddy in Chrome.
- Open your site in that same Chrome, e.g.
https://<your-domain>/agent. - Click the Buddy icon in the toolbar to open the side panel → find the "your own sites" section → enter your
address (e.g.
https://<your-domain>) → "Add". - The extension injects the bridge script for that domain and reloads the tab that is already open; the page does not become usable by itself, this reload is what reconnects it.
Details:
- A bare domain is fine (
thia.example.com); it is expanded tohttps://. A full address works too, dropping the path. Onlyhttpsis accepted —http://localhost/http://127.0.0.1are the only exception, for local development — and addresses carrying credentials are rejected. - The official domain always sits at the top of the list (marked "always available") and cannot be removed; a user can add up to 8 of their own.
- If the side panel has no "your own sites" section, the extension is too old — update it in the extensions page.
- Multiple sites on one computer are fine: one entry per domain, each page connects on its own.
Second layer: per-site consent
Adding a domain only lets that page reach the extension; it does not let the Agent read any site at will. The
first time a conversation wants to act on a site, a consent card appears in the chat and the user allows it per site
(read = read-only, interact = may act). Allowed sites are listed under "sites this chat may use" in the side
panel and can be revoked; sites listed under "blocked sites" never get an extract button.
So in a private deployment, the user seeing one consent card on the first task is expected — not a sign of a misconfiguration.
Verification
- In a Chrome that has Buddy installed and your domain added, open
https://<your-domain>/agent. - Ask: "list the tabs I have open".
- Expected: a real list of tabs comes back.
When it fails, what the model says tells you which of three cases you are in — they are different:
| What the model says | Meaning | What to do |
|---|---|---|
| No page is connected (and asks you to open the chat page on that computer) | This page is not connected to the server (tab closed, switched away, signed out) | Open /agent and keep it open |
| The page is open, but it reported it cannot run browser tools | The page is connected but has no bridge: extension missing, disabled, or your domain is not in "your own sites" | Add the domain as above, then reload the page |
| A page is connected but did not answer (looks like it is waiting for you) | The path works; it is stuck on a consent / verification card in the chat | Go back to the chat and check pending cards |
On the server side: the first two are the same log line browser tool dispatch skipped: no capable bridge subscriber,
told apart by its audience field (none / connected-only); the third is a timeout (TIMEOUT).
Troubleshooting
| Symptom | Usual cause |
|---|---|
| The side panel has no "your own sites" section | Extension too old — update it |
| Adding reports "please enter an https address" | An http:// address on a non-local host, credentials inside the URL, or something that is not an address at all |
| The page still says it cannot run tools after adding | The tab was not reloaded; or a different domain was added (www. vs bare domain, test vs production are separate entries) |
| It does not work on another computer | The list syncs with the Chrome account; restart the browser there and check again |
| The model says "no page is connected" while the page is clearly open | That page's SSE dropped (network / reverse-proxy timeout); reload the page |
The reverse proxy must keep /events a long-lived connection and must not buffer it: X-Accel-Buffering: no plus a
generous read timeout, see Edge nginx.