Skip to content

Connect your first agent ​

Write an agent plugin that streams replies into a room. Start with an agent that echoes you, then connect a real one running on your own server, with live status, rich cards and approvals.

Preview

The TypeScript SDK is being designed in the open. APIs on this page may change before the first release.

How agent plugins work ​

Agent Playgrounds doesn't run agents. It connects to them, wherever they run. An agent plugin is the adapter: when someone sends a message, the app calls your plugin with the room, and your plugin yields events back, like text as it streams in, a status line, a card or a question for the person.

The app does everything else: drawing the conversation, saving history, showing the agent's status in the sidebar, notifications, approvals and remembered permissions.

1. Create the plugin ​

sh
npm create agent-playgrounds-plugin@latest my-agent

Pick the Agent template, then:

sh
cd my-agent
npm install
npm run dev

2. Declare the agent ​

In package.json, an agents entry adds an agent people can start rooms with:

json
{
  "name": "my-agent",
  "agentPlaygrounds": {
    "id": "acme.my-agent",
    "title": "My Agent",
    "description": "Talk to the agent running on your server.",
    "icon": "icon.png",
    "author": "acme",
    "platforms": ["macOS", "iOS"],
    "agents": [
      {
        "name": "echo",
        "title": "Echo",
        "description": "Repeats whatever you say."
      }
    ]
  }
}

The echo agent's code lives at src/agents/echo.ts.

3. Write the agent ​

An agent is an async generator. The app calls it once for each reply, and every value you yield is an event.

ts
import { text, type AgentContext } from '@agentplaygrounds/sdk'

export default async function* echo({ message }: AgentContext) {
  yield text(`You said: ${message?.text}`)
}

Press ⌘N, choose Echo (it has a Dev badge while you're developing), and say hello. It answers.

Text events append to the reply, so you can stream word by word:

ts
export default async function* echo({ message }: AgentContext) {
  for (const word of (message?.text ?? '').split(' ')) {
    yield text(word + ' ')
    await sleep(100)
  }
}

The app smooths fast streams for you, so yield as often as your agent produces text. message is optional because the app also calls your agent for a button on a surface it sent, with no new message.

4. Connect a real agent ​

Now point the plugin at an agent on your own server. Add settings and a network permission to the agent:

json
"agents": [
  {
    "name": "remote",
    "title": "My Agent",
    "description": "Your agent, running on your server.",
    "preferences": [
      { "name": "endpoint", "type": "url", "title": "Endpoint", "required": true,
        "placeholder": "https://agent.example.com" },
      { "name": "apiKey", "type": "password", "title": "API key", "required": true }
    ]
  }
],
"permissions": {
  "network": [{ "preference": "endpoint" }]
}
  • Required preferences are asked for when someone creates the agent, before its first message.
  • password preferences are stored in the Keychain and never shown again.
  • { "preference": "endpoint" } allows network access to whatever host the person enters, and only that host. They see it when they set the agent up.

src/agents/remote.ts streams from a server that sends server-sent events:

ts
import { text, status, type AgentContext } from '@agentplaygrounds/sdk'
import { streamSSE } from '@agentplaygrounds/utils'

type Preferences = { endpoint: string; apiKey: string }

export default async function* remote({ room, agent, preferences, signal }: AgentContext<Preferences>) {
  yield status('Thinking…')

  const response = await fetch(`${preferences.endpoint}/chat`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${preferences.apiKey}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      instructions: agent.instructions,
      messages: room.messages.map((m) => ({ role: m.author.kind === 'person' ? 'user' : 'assistant', text: m.text })),
    }),
    signal,
  })
  if (!response.ok) throw new Error(`The agent returned ${response.status}`)

  for await (const event of streamSSE(response)) {
    yield text(event.data.delta)
  }
}

A few things the app handles for you:

  • status shows a live line like "Thinking…" under the conversation and in the sidebar. It clears when text starts arriving.
  • signal is aborted when the person presses Stop or sends another message. Pass it to fetch and the request is cancelled. What already arrived stays in the room.
  • Errors you throw mark the reply as failed, show the message, and offer Retry.
  • room.messages has the conversation so far, including the message that was just sent. Each message's text is the plain text of everything in it, using fallback text for rich blocks.

5. Send rich content ​

Text is only the start. Yield a block to put a card in the conversation:

ts
import { text, block } from '@agentplaygrounds/sdk'

yield text('Here’s Lisbon right now:')
yield block({
  type: 'acme.weather',
  payload: { city: 'Lisbon', temperature: 21, condition: 'Clear', high: 24, low: 16 },
  fallbackText: 'Lisbon: 21°, clear',
})

Any plugin can render any block type. If the person has the weather plugin, they see the card; if not, they see the fallback text. Core block types like code, terminal, web and map work everywhere.

Your agent can also show its reasoning separately from its answer:

ts
import { thinking } from '@agentplaygrounds/sdk'

yield thinking('The user wants a forecast, so I should check the weather API first…')

6. Ask before acting ​

When your agent wants to do something that matters, ask first. ask.approval puts an approval card in the room, moves the room to Needs You, and waits for an answer:

ts
import { ask, text } from '@agentplaygrounds/sdk'

const answer = await ask.approval({
  title: 'Deploy the pricing page to production?',
  permission: { action: 'deploy', resource: 'pricing' },
})

if (answer.allowed) {
  yield text('Deploying now.')
} else {
  yield text('Okay, I won’t deploy.')
}

If the person chooses Always allow, the room remembers a grant like "My Agent may deploy: pricing", and later matching requests are answered instantly without asking. People can see and revoke every grant in the room's Permissions tab.

There's also ask.choice for picking from options, and ask.text for a short typed answer.

7. Run long tasks ​

Some work takes minutes. Report it as a task, and keep updating it after your reply ends. endReply() marks the reply complete, so the person can keep chatting while your agent keeps working:

ts
import { task, text, endReply } from '@agentplaygrounds/sdk'

const build = task({ title: 'Build the site' })
yield build.start()
yield text('Started the build. I’ll keep you posted.')
yield endReply()

yield build.progress(0.4, 'Compiling')
yield build.progress(0.9, 'Uploading')
yield build.succeed()

Tasks appear as live cards in the conversation and in the room's Tasks tab, with timing. If the person cancels, your signal is aborted.

8. Share the room with other agents ​

A room can hold several agents. Your agent is told who it is (self), why it was called (turn) and what was said since its last turn (unseen). It can hand work to another agent and ask for the result back, or pass when it has nothing to add:

ts
import { text, handOff, pass, type AgentContext } from '@agentplaygrounds/sdk'

export default async function* trip({ turn, message }: AgentContext) {
  if (turn.reason === 'callBack') {
    // Quote the reply, so a line in it that starts with @Handle doesn't hand off again
    yield text(`Points says:\n${(turn.reply?.text ?? 'no answer').replace(/^/gm, '> ')}`)
    return
  }
  if (turn.reason !== 'handOff' && /points|miles/i.test(message?.text ?? '')) {
    yield handOff('Points', 'Is the Hyatt better on points or cash?', { callBack: true })
    return
  }
  if (turn.canPass) {
    yield pass()
    return
  }
  yield text('Here is what I know…')
}

The same code runs unchanged in a room with one agent, where turn.canPass is false. Read Rooms with several agents for the rules, including how an agent that only writes text hands off: a line that starts with @Points.

9. Let people pick an agent on your service ​

If your service runs many agents, don't make people set each one up by hand. Declare a connection, set up once in Settings, and give your agent a directory: the live list of agents on the service. The app syncs that list into the Agent library, keeps it in sync, and offers New, Edit and Delete when your plugin handles them. Each agent gets a DM, and a new one introduces itself there. Read Connections and directories.

Events at a glance ​

HelperWhat it does
text(delta)Appends to the reply's text
connection(state)Reports the connection to the agent's service: online, degraded or offline
block({ type, payload, fallbackText })Adds a card or other rich content
ui(a2ui, { fallbackText })Sends A2UI directly, for agents that already produce it
update(block, payload)Replaces the payload of a block this agent sent, like a card that changes as work progresses
thinking(delta)Streams reasoning, shown collapsed once the answer starts
status(line)Shows live activity, like "Searching the web…"
newMessage()Starts a new message bubble
endReply()Completes the reply while you keep reporting tasks
task({ title })Creates a task you can start, progress, succeed, fail
handOff(to, text, { callBack })Gives another agent in the room something to do, and asks for the result back
pass()Ends the reply without a message; the thread shows a quiet "Trip passed" line, when the turn allows it
note(text)Adds a line to the room from your plugin, never as the agent's words: "Saved to Care's soul and notes."
ask.approval, ask.choice, ask.textAsks the person and waits for the answer

See Agents and events for every signature.

Next steps ​

All your Agents, playing nicely in one Playground.