Appearance
Create your first plugin
Build a weather card that anyone in a room can share with a slash command. You'll learn how a plugin is laid out, how blocks render, and how the development loop works.
Preview
The TypeScript SDK is being designed in the open. APIs on this page may change before the first release.
What you'll build
Type /weather Lisbon in any room, and a live weather card appears in the conversation. Anyone in the room, including agents, can see it, and Refresh updates it in place.
Before you start
- Agent Playgrounds for Mac, with Developer Mode turned on in Settings › Developer
- Node.js 22 or later, for the build tools. Plugins themselves run inside the app, not in Node.
- Some familiarity with TypeScript and React
1. Create the plugin
sh
npm create agent-playgrounds-plugin@latest weatherPick the Block template when asked. You can also start from the app: Settings › Developer › Create Plugin.
You get this:
weather/
├── package.json The manifest: what your plugin is and what it adds
├── assets/
│ └── icon.png 512 × 512, shown in the Store and the app
├── src/
│ ├── blocks/
│ │ └── weather.tsx How a weather block looks
│ ├── commands/
│ │ └── weather.ts The /weather command
│ └── weather.ts Fetching the forecast
└── tsconfig.json2. Run it
sh
cd weather
npm install
npm run devnpm run dev builds your plugin, installs it into the running app and watches for changes. Save a file and the app reloads the plugin in about a second. Logs from console.log appear in your terminal. If a build fails, the last working version keeps running and the error shows in the app, with a button to open the file in your editor.
Try it now: open any room and type /weather Lisbon.
3. The manifest
Your plugin's package.json describes everything it adds, under the agentPlaygrounds key:
json
{
"name": "weather",
"agentPlaygrounds": {
"id": "acme.weather",
"title": "Weather",
"description": "Share live weather cards in any room.",
"icon": "icon.png",
"author": "acme",
"platforms": ["macOS", "iOS"],
"permissions": {
"network": ["geocoding-api.open-meteo.com", "api.open-meteo.com"]
},
"blocks": [
{ "name": "weather", "type": "acme.weather", "title": "Weather card" }
],
"commands": [
{
"name": "weather",
"title": "Share Weather",
"description": "Post the current weather for a city.",
"arguments": [{ "name": "city", "type": "text", "placeholder": "City", "required": true }]
}
]
},
"dependencies": { "@agentplaygrounds/sdk": "^0.1.0" }
}Three things to notice:
- Each contribution has a
name, and its code lives at a matching path: theweatherblock issrc/blocks/weather.tsx, theweathercommand issrc/commands/weather.ts. - The block's
typeis namespaced with your plugin's id. It's how the app, and other plugins, know what a block is. - Network access is declared. Your plugin can only reach the hosts listed under
permissions. People see this list before they install.
See the Manifest reference for every field.
4. Fetch the weather
src/weather.ts uses the standard fetch, which the app provides:
ts
export type Weather = {
city: string
temperature: number
condition: string
high: number
low: number
}
export async function getWeather(city: string): Promise<Weather> {
const geo = await fetch(
`https://geocoding-api.open-meteo.com/v1/search?count=1&name=${encodeURIComponent(city)}`,
).then((r) => r.json())
const place = geo.results?.[0]
if (!place) throw new Error(`Couldn’t find “${city}”`)
const forecast = await fetch(
`https://api.open-meteo.com/v1/forecast?latitude=${place.latitude}&longitude=${place.longitude}` +
`¤t=temperature_2m,weather_code&daily=temperature_2m_max,temperature_2m_min&timezone=auto`,
).then((r) => r.json())
return {
city: place.name,
temperature: Math.round(forecast.current.temperature_2m),
condition: describe(forecast.current.weather_code),
high: Math.round(forecast.daily.temperature_2m_max[0]),
low: Math.round(forecast.daily.temperature_2m_min[0]),
}
}
function describe(code: number): string {
if (code === 0) return 'Clear'
if (code <= 3) return 'Partly cloudy'
if (code <= 48) return 'Fog'
if (code <= 67) return 'Rain'
if (code <= 77) return 'Snow'
return 'Storms'
}5. Render the block
A block renderer is a React component that takes the block's payload and returns SDK components. It's a pure function of the payload: no state, no effects. The SDK turns what it returns into A2UI, and the app draws it natively.
src/blocks/weather.tsx:
tsx
import { Card, Row, Metric, Text, Button, Icon, type BlockProps } from '@agentplaygrounds/sdk'
import { getWeather, type Weather } from '../weather'
export default function WeatherBlock({ payload }: BlockProps<Weather>) {
return (
<Card
title={payload.city}
subtitle={payload.condition}
icon={Icon.CloudSun}
actions={
<Button icon={Icon.ArrowClockwise} onAction={async (block) => block.update(await getWeather(payload.city))}>
Refresh
</Button>
}
>
<Row>
<Metric value={`${payload.temperature}°`} label="Now" />
<Metric value={`${payload.high}°`} label="High" />
<Metric value={`${payload.low}°`} label="Low" />
</Row>
<Text variant="caption" tone="secondary">Open-Meteo</Text>
</Card>
)
}Card, Row, Text and Button are from the A2UI basic catalog; Metric is from ours. Refresh doesn't keep any state of its own. It fetches new weather and calls block.update, which replaces the payload. The app re-renders the card, saves it with the conversation, and shows the update to everyone in the room. Learn why in How UI works.
6. Add the command
Commands appear in the composer when someone types /. A command can do anything a plugin is allowed to do. This one posts a weather block.
src/commands/weather.ts:
ts
import { showFailureToast, type CommandProps } from '@agentplaygrounds/sdk'
import { getWeather } from '../weather'
export default async function ShareWeather({ room, arguments: args }: CommandProps<Arguments.Weather>) {
try {
const weather = await getWeather(args.city)
await room.sendBlock({
type: 'acme.weather',
payload: weather,
fallbackText: `${weather.city}: ${weather.temperature}°, ${weather.condition}`,
})
} catch (error) {
await showFailureToast(error, { title: 'Couldn’t get the weather' })
}
}Arguments.Weather is generated from your manifest when you run npm run dev, so your code always matches what you declared.
Always include fallback text
fallbackText is what people see when your plugin isn't installed: on another device, for a teammate without it, or if the plugin is turned off. Agents read it too. Make it a complete sentence that stands on its own.
7. Try it
- Type
/weather Lisbonin a room. The card appears. - Click Refresh. The numbers update in place.
- Change the
Metriclabels inweather.tsxand save. The card updates without a restart. - Turn the plugin off in Settings › Plugins. The card becomes its fallback text. Turn it back on and the card returns.
Next steps
- Connect your first agent: let an agent send weather cards when someone asks.
- How UI works: why blocks are pure functions, and what that buys you.
- Components: everything you can put in a card.
- Manifest: every field, contribution and permission.
- Room: posting to rooms and updating blocks.