@three-ws/agent-glance
Put a three.ws agent on any surface that has a slot. Home screen widgets,
README badges, Slack unfurls, terminal dashboards, and a live <agent-glance>
web component.
A glance card is one agent reduced to what fits in a small rectangle: who it is, one live number, and a way back into it. The platform serves that card as JSON, as an SVG image, and as an Adaptive Card. This package is the client for all three, with no dependencies and no build step.
Every function works in a browser, in Node 18+, in a service worker, and in an
edge runtime. The only I/O is fetch.
Install
npm install @three-ws/agent-glance
Read a card
import { fetchGlanceCard } from '@three-ws/agent-glance';
const card = await fetchGlanceCard('0f3a1c22-9b7e-4d51-8a10-2c6f5d90ab34');
console.log(card.name, card.metric.value, card.metric.label);
Put it in a README
import { glanceMarkdown } from '@three-ws/agent-glance';
glanceMarkdown(agentId, { size: 'medium', theme: 'auto' });
// [](https://three.ws/agents/...)
The SVG endpoint is the one for any host that only takes a picture: a README, a
Slack message, an issue comment. glanceImageUrl() gives you the bare URL.
Put it on a page
import { glanceEmbedHtml } from '@three-ws/agent-glance';
glanceEmbedHtml(agentId, { size: 'large', theme: 'dark' });
<script type="module" src="https://three.ws/glance/element.js"></script>
<agent-glance agent="0f3a1c22-9b7e-4d51-8a10-2c6f5d90ab34" size="large" theme="dark"></agent-glance>
The live element updates on its own; the image URL is the no-script fallback.
Put it in a widget board
import { fetchGlanceAdaptiveCard } from '@three-ws/agent-glance';
const adaptive = await fetchGlanceAdaptiveCard(agentId);
For any host that renders an Adaptive Card directly: the Windows widgets board, Teams, or your own renderer.
Put it in a terminal
agent-glance 0f3a1c22-9b7e-4d51-8a10-2c6f5d90ab34
agent-glance <id> --watch 30
agent-glance <id> --markdown
agent-glance <id> --svg card.svg
| Option | Meaning |
|---|---|
--json |
The card model as JSON |
--markdown |
A README snippet, image linked to the agent |
--html |
An embed snippet for a web page |
--svg <file> |
Write the card image to a file |
--watch [seconds] |
Redraw on an interval (default 60) |
--size <s> |
small, medium, large (default medium) |
--theme <t> |
auto, light, dark (default auto) |
--origin <url> |
API origin (default https://three.ws) |
--no-color |
Plain text, no ANSI |
renderGlanceAnsi(card, opts) is exported, so any dashboard that lives in a
shell can draw the same card the CLI does.
API
| Export | What it does |
|---|---|
fetchGlanceCard(id, opts?) |
The card model as JSON |
fetchGlanceAdaptiveCard(id, opts?) |
The same card shaped as an Adaptive Card |
glanceCardUrl(id, opts?) |
The JSON endpoint URL |
glanceImageUrl(id, opts?) |
The <img>-ready SVG URL |
glanceMarkdown(id, opts?) |
A README snippet |
glanceEmbedHtml(id, opts?) |
A page embed snippet |
renderGlanceAnsi(card, opts?) |
The card drawn for a terminal |
GLANCE_ORIGIN, GLANCE_SIZES, GLANCE_THEMES |
The accepted values, as data |
GlanceError |
Thrown with status and agentId attached, so a caller can tell a missing agent from an unreachable API |
All fetching functions take { origin, timeoutMs, signal, fetchImpl }. Pass
fetchImpl to run against a mock-free test server or a custom transport.
Related
- The live playground and install guide: three.ws/glance
- Docs: three.ws/docs/glance
- The wire format: specs/GLANCE_CARD.md
- Embeddable 3D avatars, a different product (the agent's body, on your page): three.ws/widgets
STRUCTURE.md: where every three.ws surface lives.
License
Apache-2.0
Part of three.ws, the open-source platform for 3D AI agents. This repository is exported from the monorepo, which is the source of truth: open issues here, and send larger changes there.