Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Letting the agent load data with scripts

The execute_code entitlement lets the agent bring new data into the viewer by writing JavaScript. The agent writes an ES module that fetches or streams data and loads it with psp.emit(), and run_script hosts the result as a named table that panels can display. The feature is experimental and is never granted by default:

viewer.agentConfig({
    ...providers.anthropic,
    apiKey: "sk-ant-...",
    docs,
    entitlements: [
        "read_view",
        "configure_view",
        "manage_layout",
        "read_docs",
        "execute_code",
    ],
});

await viewer.agentPrompt(
    "Create a chart of the NY Giants NFL point record by year",
);
ToolWhat it does
run_scriptRuns a module in a new sandbox and creates (or replaces) the table name from what it emits.
list_scriptsLists the scripts, with their status, table schema, row count, last error and recent log lines.
stop_scriptStops a script, keeping its table unless drop_table is set.

The sandbox

Each script runs in a module Web Worker owned by a hidden <iframe sandbox="allow-scripts">. The iframe gives the script an opaque (null) origin, and the worker keeps it off the page’s main thread so it can be terminated at any time. The script never receives a Perspective object: it posts data to the viewer, and the viewer creates and updates the table.

A script can:

  • fetch() any server whose CORS headers allow every origin (Access-Control-Allow-Origin: *).
  • Open a WebSocket to any server.
  • import() ES modules from a CDN that serves them with permissive CORS, such as esm.sh, cdn.jsdelivr.net or unpkg.com.
  • Use timers, TextDecoder, crypto and the other APIs available to a worker.

A script cannot:

  • Read the page’s DOM, cookies, localStorage or JavaScript state.
  • Send the page’s cookies or credentials, so same-origin APIs that need a login are unreachable.
  • Use document, window or DOMParser, because a worker has no DOM. Read HTML with a parser imported from a CDN instead.

Consider before granting execute_code:

  • The code is written by the model and runs in the user’s browser. It can reach any CORS-open server or WebSocket that the browser can reach, including hosts on the user’s private network.
  • Row data stays in the browser. The model sees each table’s schema and row count, plus anything the script writes with psp.log() or console.log().
  • A host page whose Content-Security-Policy forbids blob: workers or sandboxed frames blocks scripts. run_script then fails with an error naming the policy.

The psp API

A script is a whole ES module, so top-level await and static import both work and psp is a global. It is not a function body: a top-level return is a syntax error, and data reaches the table only through psp.emit().

MemberBehavior
psp.emit(data)Loads rows. data is an array of row objects, an object of column arrays, a CSV string, or Arrow IPC bytes (ArrayBuffer or Uint8Array).
psp.emit(data, {replace: true})Replaces the table’s entire contents with data.
psp.log(...values)Adds a line to the script log returned to the model. console.log and the other console methods do the same.

The first emit creates the table, with column types inferred the same way as client.table(data). Later emits append rows, or update rows in place when the table has an index. An exception thrown after the first emit is recorded as the script’s last_error, and the script keeps running.

run_script takes table options for the created table:

  • index is a column name, or a list of names, keying each row. Re-emitted rows with the same key update the existing row instead of appending.
  • limit is the maximum number of rows kept. The oldest rows are dropped first.

Script lifetime

run_script returns as soon as the first emit has been loaded, reporting the table’s schema and row count. It fails if the script throws or emits nothing within start_timeout_ms (30 seconds by default), and the error includes the script log so the model can fix the module. A module that sets up a socket or timer and returns is not finished: its first emit may come from a callback, so the timeout alone decides.

After that the script keeps running for as long as it has timers or open sockets, so a polling or streaming table stays live. Scripts survive later prompts, agentReset() and agentConfig(), and they stop on stop_script, viewer.delete(), or when run_script is called again with the same name.

Re-running a name replaces the old script and its table. If a panel is still displaying that table, the table cannot be deleted, so its contents are replaced in place and it keeps its original columns. Use a new name to change the columns of a table that is on screen.

Script tables are ordinary hosted tables. saveWorkspace() does not record the scripts that produce them, so a restored workspace that references one shows the table only while its script is running.

Recipes

Polling a JSON endpoint

Fetch the whole document on a timer and re-emit it with replace: true when it is a snapshot with no key column. Map fields to flat, Perspective-friendly rows first.

async function load() {
    const response = await fetch("https://example.com/api/quotes.json");
    const json = await response.json();
    return json.data.items.map((item) => ({
        symbol: item.ticker,
        price: Number(item.quote.last),
        updated: new Date(item.quote.time * 1000),
    }));
}

psp.emit(await load());
setInterval(async () => psp.emit(await load(), { replace: true }), 60_000);

If each row has a stable key, create the table with table: {index: "symbol"} and emit without replace, so rows update in place.

Streaming from a WebSocket

Send any control messages once the socket opens, then emit each decoded frame. Arrow frames can be emitted directly.

const socket = new WebSocket("wss://example.com/feed");
socket.binaryType = "arraybuffer";
socket.onopen = () => {
    socket.send(JSON.stringify({ op: "auth", token: "public" }));
    socket.send(JSON.stringify({ op: "subscribe", channel: "trades" }));
};

socket.onmessage = (event) => {
    if (event.data instanceof ArrayBuffer) {
        psp.emit(event.data);
    } else {
        const message = JSON.parse(event.data);
        if (message.type === "trade") {
            psp.emit([{ id: message.id, price: message.p, size: message.q }]);
        }
    }
};

socket.onerror = () => psp.log("socket error");

run_script waits for the first emit, so a feed that is quiet at first needs a larger start_timeout_ms. Pass table: {limit: 100000} to bound an append-only stream.

Importing a client library from a CDN

Import the library’s browser ES module build, then emit what it returns.

import { createClient } from "https://esm.sh/@example/data-client@2";

const client = createClient({ endpoint: "https://data.example.com" });
const rows = await client.query("SELECT * FROM prices LIMIT 1000");
psp.emit(rows);

Reading an HTML table from Wikipedia

Wikipedia’s article URLs do not allow cross-origin requests, but the MediaWiki API does when it is called with origin=*. Its parse action returns the article HTML as a string. A worker has no DOMParser, so parse the HTML with node-html-parser from a CDN.

import { parse } from "https://esm.sh/node-html-parser@6";

const page = "New_York_Giants_seasons";
const url = `https://en.wikipedia.org/w/api.php?action=parse&page=${page}&prop=text&format=json&formatversion=2&origin=*`;
const json = await (await fetch(url)).json();
const table = parse(json.parse.text).querySelector("table.wikitable");
const cells = table
    .querySelectorAll("tr")
    .map((tr) => tr.querySelectorAll("th, td").map((x) => x.text.trim()));

const [header, ...body] = cells;
psp.log("columns:", header);
const toNumber = (x) => Number(x.replace(/[^0-9.-]/g, "")) || null;
psp.emit(
    body
        .filter((row) => row.length === header.length)
        .map((row) => ({
            Season: toNumber(row[0]),
            "Points For": toNumber(row[header.indexOf("PF")]),
            "Points Against": toNumber(row[header.indexOf("PA")]),
        })),
);

Pages often hold several wikitables, and header rows can span two lines. Logging the header first, as above, shows the model which columns exist when the first attempt picks the wrong table.