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",
);
| Tool | What it does |
|---|---|
run_script | Runs a module in a new sandbox and creates (or replaces) the table name from what it emits. |
list_scripts | Lists the scripts, with their status, table schema, row count, last error and recent log lines. |
stop_script | Stops 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
WebSocketto any server. import()ES modules from a CDN that serves them with permissive CORS, such asesm.sh,cdn.jsdelivr.netorunpkg.com.- Use timers,
TextDecoder,cryptoand the other APIs available to a worker.
A script cannot:
- Read the page’s DOM, cookies,
localStorageor JavaScript state. - Send the page’s cookies or credentials, so same-origin APIs that need a login are unreachable.
- Use
document,windoworDOMParser, 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()orconsole.log(). - A host page whose Content-Security-Policy forbids
blob:workers or sandboxed frames blocks scripts.run_scriptthen 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().
| Member | Behavior |
|---|---|
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:
indexis 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.limitis 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.