Appearance
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-agentPick the Agent template, then:
sh
cd my-agent
npm install
npm run dev2. 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.
passwordpreferences 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:
statusshows a live line like "Thinking…" under the conversation and in the sidebar. It clears when text starts arriving.signalis aborted when the person presses Stop or sends another message. Pass it tofetchand 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.messageshas the conversation so far, including the message that was just sent. Each message'stextis 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
| Helper | What 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.text | Asks the person and waits for the answer |
See Agents and events for every signature.
Next steps
- Agents and events: the full API reference.
- Rooms with several agents: moderators, hand off and call back, pass and the turn limit.
- Connections and directories: every agent on your service in the Agent library, with New, Edit and Delete.
- Manifest: agent settings, preferences and permissions.
- Create your first plugin: build the card your agent sends.
- Concepts: rooms, participants, blocks and room status.