Skip to content

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 weather

Pick 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.json

2. Run it ​

sh
cd weather
npm install
npm run dev

npm 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: the weather block is src/blocks/weather.tsx, the weather command is src/commands/weather.ts.
  • The block's type is 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}` +
      `&current=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 ​

  1. Type /weather Lisbon in a room. The card appears.
  2. Click Refresh. The numbers update in place.
  3. Change the Metric labels in weather.tsx and save. The card updates without a restart.
  4. Turn the plugin off in Settings › Plugins. The card becomes its fallback text. Turn it back on and the card returns.

Next steps ​

All your Agents, playing nicely in one Playground.