@tung-engineering/agent-platform-web-sdk

Embeddable Web SDK for Agent Platform. Drop it into any web page to get a floating capture button that turns any element — or any recorded click-through flow — into an Agent Platform task or planning session, without leaving the page you're looking at.

• 🖱️ Element picker — click the capture button, then click any element on the page to attach it (with surrounding DOM context) to a new task or planning session
• ⏺️ Interaction recorder — record a multi-step click-through flow and turn the whole sequence into a browser-automation task
• 🤖 Automation runner — a floating panel that streams a running task's browser actions live, with per-step approve/answer prompts when the agent needs input
• 📋 Captures list — a running list of everything captured from the current browser, with unread/status badges
• 🔒 Secure by design — connects via a short-lived, OAuth2-style token exchange; your long-lived Agent Platform API token is never entered into or stored by the SDK

Installation

npm install @tung-engineering/agent-platform-web-sdk

Node.js is only used to install the package — the SDK itself is a browser-only, zero-dependency-at-runtime bundle (its few dependencies are bundled in).

Quick start (npm package)

1. Import and initialize. init() needs your project's short code and, to actually connect to a backend, a backendUrl + short-lived token (see Getting a token below — you can skip both and use the built-in connect UI instead, see step 3).

import { init } from '@tung-engineering/agent-platform-web-sdk';

await init({
  projectCode: 'YOUR_PROJECT_CODE',
  backendUrl: 'https://your-agent-platform-instance.example.com',
  token: sdkToken, // short-lived SDK token, see "Getting a token"
});

This injects the SDK's styles and shows a floating capture button (FAB) in the bottom-right corner of the page.

2. Use the picker. Click the FAB, then click any element on the page — a capture panel opens letting you turn that element into a task or planning session in your Agent Platform project. This also works from your own code:

import { activateElementPicker } from '@tung-engineering/agent-platform-web-sdk';

activateElementPicker(); // same as clicking the FAB yourself

3. Or skip the token exchange — use the built-in connect UI. If you don't already have a short-lived token (e.g. building an internal tool, not shipping a hardcoded token to end users), call configure() instead of init(). It opens a small panel where the user enters your backend URL, signs in via a popup, and picks a project — the SDK stores the resulting short-lived token in sessionStorage and initializes itself:

import { configure } from '@tung-engineering/agent-platform-web-sdk';

configure(); // opens the "Connect to Agent Platform" panel

4. Clean up when you're done (e.g. on route change in an SPA):

import { destroy } from '@tung-engineering/agent-platform-web-sdk';

destroy(); // removes the FAB, closes any open panels, tears down listeners

Quick start (script tag, no build step)

You can also load the SDK directly from your Agent Platform backend without installing anything. Pin the URL to a specific published version and verify it with Subresource Integrity so a compromised/mutated host asset can't silently execute in your page:

<!-- TODO(security): CI must compute and inject the real sha384 integrity hash for each
     published web-sdk.min.js version here, regenerated on every rebuild of this package. -->
<script
  src="https://your-agent-platform-instance.example.com/web-sdk/web-sdk-1.0.0.min.js"
  integrity="sha384-REPLACE_WITH_CI_GENERATED_HASH"
  crossorigin="anonymous"
></script>

This self-boots: it looks for a saved connection in sessionStorage and either restores it (showing a ready-to-use FAB) or shows the FAB in "click to connect" mode. Once loaded, the same API is available on window.AgentPlatformWebSdk:

<script>
  // Open the connect panel (same flow as configure() above)
  AgentPlatformWebSdk.configure();

  // Or connect programmatically with a token obtained out-of-band
  AgentPlatformWebSdk.init({
    projectCode: 'YOUR_PROJECT_CODE',
    backendUrl: 'https://your-agent-platform-instance.example.com',
    token: sdkToken,
  });
</script>

Getting a token

The SDK never accepts or stores a long-lived personal API token. There are two ways to get the short-lived token init() expects:

1. Interactive (recommended for most integrations) — call configure() / AgentPlatformWebSdk.configure(). It opens a popup to your Agent Platform instance's own sign-in/consent screen, receives a single-use authorization code via postMessage, and exchanges it for a short-lived SDK token automatically. Nothing to implement on your end.
2. Out-of-band (for pre-authenticated embeds) — have your own backend perform the same authorization-code exchange (POST /auth/tokens/exchange-code on your Agent Platform instance) and pass the resulting token straight into init({ token }).

Either way, the token is short-lived and is only ever persisted to sessionStorage — closing the browser/tab always requires reconnecting.

API reference

| Export | Description | |---|---| | init(options: SdkOptions): Promise<void> | Initializes the SDK and shows the FAB. Safe to call again with the same options (no-op). | | updateCredentials(backendUrl: string, token: string): Promise<void> | Swaps the backend URL / token on an already-initialized SDK (e.g. after a token refresh). | | configure(): void | Opens the built-in "Connect to Agent Platform" panel; saves the result and calls init() for you. | | clearConfig(): void | Clears saved credentials from sessionStorage and tears down the SDK back to setup mode. | | activateElementPicker(): void / deactivateElementPicker(): void | Starts/stops the element picker without clicking the FAB. | | isPickerRunning(): boolean | Whether the element picker is currently active. | | showFab(): void / hideFab(): void | Show/hide the floating buttons without tearing down the rest of the SDK. | | destroy(): void | Fully tears down the SDK: removes the FAB, closes any open panel, stops all listeners. | | autoInit(): void | Runs automatically when the script-tag bundle is loaded; not meant to be called from the npm import. |

SdkOptions:

| Field | Type | Required | Description | |---|---|---|---| | projectCode | string | yes | Short, human-readable project code (e.g. "AP"). | | backendUrl | string | no | Base URL of your Agent Platform backend. Omit to boot in "click to connect" mode. | | token | string | no | Short-lived SDK token (see Getting a token). Omit to boot in "click to connect" mode. |

TypeScript

Type declarations ship with the package — no @types/... package needed.

import { init, type SdkOptions } from '@tung-engineering/agent-platform-web-sdk';

const options: SdkOptions = {
  projectCode: 'YOUR_PROJECT_CODE',
  backendUrl: 'https://your-agent-platform-instance.example.com',
  token: sdkToken,
};

await init(options);

Browser support

The SDK is browser-only — it reads window/document/sessionStorage/localStorage at call time and is a no-op in non-browser environments (safe to import in an SSR/isomorphic build; just don't call init()/configure() on the server).