Skip to content

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 ​

PackageWhat it is
@agentplaygrounds/sdkThe SDK itself: components, agent events, and APIs for rooms, preferences, storage, the network and feedback. Every plugin depends on it.
@agentplaygrounds/utilsOptional helpers built on the SDK, like useFetch, useCachedPromise and streamSSE. Nothing here is special: you could write it yourself.
create-agent-playgrounds-pluginCreates 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   # optional

Import what you need:

ts
import { Card, Metric, text, block, ask, showToast, type BlockProps } from '@agentplaygrounds/sdk'

What's in it ​

AreaWhat you use it forReference
ComponentsDescribing UI for blocks, slots and views: Card, List, Metric, Form and more. Everything they produce is A2UI.Components
Buttons and actionsThings people can do: buttons, menus and shortcutsComponents
Agents and eventsStreaming replies, sending blocks, asking for approval, running tasksAgents and events
RoomReading the conversation and posting to it from commands and actionsRoom
Rooms with several agentsKnowing who's in the room and why your agent was called, handing off work, calling back and passingRooms with several agents
ConnectionsReaching a service once from Settings, pairing with it and keeping only what it issuedConnections and directories
DirectoriesListing the agents on that service, so the app syncs them into the Agent library with New, Edit and DeleteConnections and directories
PreferencesReading the settings declared in your manifestManifest
StorageSaving your plugin's own data, and secrets in the KeychainStorage and secrets
Networkfetch and WebSockets to the hosts you're allowed to reachComing soon
FeedbackToasts and alerts, like showToast and showFailureToastComing soon
EnvironmentThe app version, platform, appearance and what's availableComing soon
NavigationMoving between screens in a surface or inspector tabComing 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, JSON and the rest of the language
  • fetch, WebSocket, URL, TextEncoder, AbortController, timers and crypto.getRandomValues
  • console, 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_process or http
  • The DOM, window and 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:

ScriptRunsWhat it does
npm run devapg devBuilds your plugin, installs it into the app and reloads it when you save
npm run buildapg buildType-checks and builds a release version
npm run lintapg lintChecks your code and manifest against the Store guidelines
npm run publishapg publishSubmits 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 migrate updates your code for you.

During the preview, the SDK is version 0.x, and anything may change between minor versions.

All your Agents, playing nicely in one Playground.