Browser & Webview Runtimes

Run PraisonAI agents in browsers, Electron, Tauri, and React Native — backed by a CI webview-load guarantee

The Agent module runs anywhere JavaScript runs — browsers, Electron renderers, Tauri webviews, and React Native — because its import graph has no Node.js builtins. praisonai-ts stays loadable in a mobile / browser webview from a dedicated entry point, and CI fails any pull request that breaks it.

Quick Start

1. Create an agent (runs identically in Node and a browser)

   import { Agent } from 'praisonai';
   
   const agent = new Agent({
     instructions: "You are a helpful assistant",
     apiKey: process?.env?.OPENAI_API_KEY ?? window.__OPENAI_KEY,
   });
   
   const reply = await agent.chat("Hello from anywhere!");
   console.log(reply);
   console.log(agent.getRunId()); // RFC-4122 v4 UUID from WebCrypto

2. Import from the mobile entry (webview bundles)

   import { Agent } from 'praisonai/mobile';
   
   const agent = new Agent({ instructions: "You are a helpful assistant" });
   const response = await agent.chat("Hello from a webview!");
   console.log(response);

3. Install

   npm install praisonai

How It Works

A static Node-builtin import (e.g. import { readFile } from 'fs') is evaluated the moment a module loads, so in a webview it kills the whole bundle at import time — before any code runs, with no error boundary and a blank screen. CI bundles the mobile entry for the browser and fails if any forbidden builtin is imported statically.

sequenceDiagram
    participant Dev as Developer
    participant PR as Pull Request
    participant CI as praisonai-ts-webview
    participant Bundle as esbuild (browser target)
    Dev->>PR: add `import { readFile } from 'fs'` to Agent graph
    PR->>CI: workflow triggered (path-filtered)
    CI->>Bundle: build mobile entry for safari16, chrome108
    Bundle-->>CI: FAIL — fs imported STATICALLY
    CI-->>PR: red check "loadable in a webview"
    PR-->>Dev: block merge; regression prevented

The Agent constructs the same way in every runtime — credentials are read at call time, and random IDs come from WebCrypto.

Webview support contract

praisonai-ts is guaranteed by CI to remain loadable in a mobile / browser webview from one dedicated entry point.

Which entry is safe

Two entries are verified by CI to have no static Node-builtin imports: the mobile entry (praisonai/mobile) and the deep agent entry (praisonai/agent/simple). Use praisonai/mobile — it is the curated allowlist of everything that runs in a browser.

// ✅ webview-safe (guaranteed by CI)
import { Agent } from 'praisonai/mobile';

// ✅ also verified by CI (deep agent entry)
import { Agent } from 'praisonai/agent/simple';

// ❌ pulls in CLI + MCP + tool registry; not for mobile
import { Agent } from 'praisonai';

Supported browsers

CI builds for safari16 and chrome108. These are the floors — newer runtimes are fine.

Two floors, one guarantee. CI’s metafile check (Safari 16 / Chrome 108) ensures no forbidden Node builtin is imported; on top of that, a separate chrome58 check (FLOOR_TARGET in scripts/webview-gate.mjs) proves each entry actually parses in a Chrome 58 engine. The two exist because a bundle can be builtin-free and still use syntax (top-level await, most notably) that a device WebView cannot parse. praisonai/mobile is guaranteed both — buildable AND parseable — at Android 8’s WebView floor. See Shipping to iOS and Android → WebView floor for how minSdkVersion: 26 => chrome58 is derived on the mobile-app side.

What CI guarantees absent from your bundle

The Agent graph is guaranteed to have no static import of any of these Node builtins.

Static vs dynamic — the carve-out

A static import { x } from 'fs' kills a webview bundle at import time — that is what the gate blocks. A dynamic await import('readline') inside a function only fails if that function is called. readline is reached only from the CLI approval prompt, which a phone never calls, so it is allowed. Build your own path that calls it in a webview and that is on you — the gate cannot see it.

Which import to use

Reproducing the check locally

cd src/praisonai-ts
npm install --legacy-peer-deps
npm run build
npm run check:webview

Run npm run build first so the gate checks what ships (dist/esm/…), not just the sources. Expected output:

OK   src/mobile.ts:               loadable in a webview
OK   src/mobile.ts:               bundles for chrome58
OK   src/agent/simple.ts:         loadable in a webview
OK   src/agent/simple.ts:         bundles for chrome58
OK   dist/esm/mobile.js:          loadable in a webview
OK   dist/esm/mobile.js:          bundles for chrome58
OK   dist/esm/agent/simple.js:    loadable in a webview
OK   dist/esm/agent/simple.js:    bundles for chrome58

The second line per entry is the syntax-floor check. It fails with esbuild’s own diagnosis (file:line), typically pointing at a top-level await — usually because a file on the graph still uses require()/__dirname and earned the esm-shim createRequire banner.

Bundling & compatibility

The Agent import graph is free of Node.js builtins, so bundlers ship it as-is to any JS runtime.

Random IDs come from WebCrypto (globalThis.crypto.randomUUID, with a getRandomValues fallback), and internal event dispatch uses a small in-tree emitter — the Agent module never imports Node’s crypto or events.

Configuration

Pass credentials per-agent so browsers never depend on environment variables.

import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: "You are a helpful assistant",
  apiKey: window.__OPENAI_KEY,
  baseURL: "https://api.openai.com/v1",
});

Best Practices

Related