Appearance
The SDK
Every plugin is written in TypeScript against the Agent Playgrounds SDK. It gives you the components to describe UI, the helpers to stream agent replies, and the APIs to work with rooms, settings, storage and the network.
Preview
The TypeScript SDK is being designed in the open, starting from these docs. APIs may change before the first release.
Packages
| Package | What it is |
|---|---|
@agentplaygrounds/sdk | The SDK itself: components, agent events, and APIs for rooms, preferences, storage, the network and feedback. Every plugin depends on it. |
@agentplaygrounds/utils | Optional helpers built on the SDK, like useFetch, useCachedPromise and streamSSE. Nothing here is special: you could write it yourself. |
create-agent-playgrounds-plugin | Creates a new plugin from a template: npm create agent-playgrounds-plugin@latest |
The SDK also includes the apg command-line tool, which every plugin's scripts use.
Install
New plugins come with the SDK already set up. To add it to an existing project:
sh
npm install @agentplaygrounds/sdk
npm install @agentplaygrounds/utils # optionalImport what you need:
ts
import { Card, Metric, text, block, ask, showToast, type BlockProps } from '@agentplaygrounds/sdk'What's in it
| Area | What you use it for | Reference |
|---|---|---|
| Components | Describing UI for blocks, slots and views: Card, List, Metric, Form and more. Everything they produce is A2UI. | Components |
| Buttons and actions | Things people can do: buttons, menus and shortcuts | Components |
| Agents and events | Streaming replies, sending blocks, asking for approval, running tasks | Agents and events |
| Room | Reading the conversation and posting to it from commands and actions | Room |
| Rooms with several agents | Knowing who's in the room and why your agent was called, handing off work, calling back and passing | Rooms with several agents |
| Connections | Reaching a service once from Settings, pairing with it and keeping only what it issued | Connections and directories |
| Directories | Listing the agents on that service, so the app syncs them into the Agent library with New, Edit and Delete | Connections and directories |
| Preferences | Reading the settings declared in your manifest | Manifest |
| Storage | Saving your plugin's own data, and secrets in the Keychain | Storage and secrets |
| Network | fetch and WebSockets to the hosts you're allowed to reach | Coming soon |
| Feedback | Toasts and alerts, like showToast and showFailureToast | Coming soon |
| Environment | The app version, platform, appearance and what's available | Coming soon |
| Navigation | Moving between screens in a surface or inspector tab | Coming soon |
Where it runs
Your plugin runs inside the app, in its own sandbox, using the JavaScript engine built into macOS and iOS. It doesn't run in Node.js or a browser.
Available:
- Modern JavaScript:
async/await,Promise,Map,Intl,JSONand the rest of the language fetch,WebSocket,URL,TextEncoder,AbortController, timers andcrypto.getRandomValuesconsole, which logs to your terminal while you develop
During the preview, fetch in the app delivers a response's body whole rather than streaming it, so server-sent events arrive when the response ends. WebSocket streams as you'd expect.
Not available:
- Node.js modules like
fs,child_processorhttp - The DOM,
windowand CSS - Anything outside your plugin's sandbox, unless your manifest asks for it
Most npm packages that are plain JavaScript work fine. They're bundled into your plugin when you build it. Packages that need Node.js or a browser won't.
TypeScript
The SDK is written in TypeScript and every API is typed. When you run npm run dev or npm run build, the SDK also generates agent-playgrounds-env.d.ts from your manifest, so your preferences and command arguments are typed to match exactly what you declared.
Plugins use strict TypeScript and JSX with the SDK's components. The templates set this up for you.
The apg tool
Every plugin's package.json runs apg through npm scripts:
| Script | Runs | What it does |
|---|---|---|
npm run dev | apg dev | Builds your plugin, installs it into the app and reloads it when you save |
npm run build | apg build | Type-checks and builds a release version |
npm run lint | apg lint | Checks your code and manifest against the Store guidelines |
npm run publish | apg publish | Submits your plugin to the Store |
Versioning
The SDK follows semantic versioning. The version range in your package.json says which SDK your plugin needs:
- When someone installs your plugin, the app checks that it supports that SDK version. If their app is too old, they're asked to update.
- Within a major version, nothing breaks. New components, props and APIs arrive in minor versions.
- When something changes, the old name keeps working with a deprecation warning, and
apg migrateupdates your code for you.
During the preview, the SDK is version 0.x, and anything may change between minor versions.