Agent plugins
Build an agent capability as a plugin: it joins the one workbench composer, adds its own cards, panels and operations, and switches on and off at runtime without host changes.
An agent plugin is one folder under src/plugins/<id>/ with two entry points: plugin.server.ts for the agent host and plugin.ts for the browser. The host code contains no plugin names. It reads what each switched-on plugin declares (a scene, a Skill, cards, panels, operations) and validates every value before it reaches the reader. It is a plugin of the console kernel described in Plugins, with kind: "agent". The image agent is a small plugin. scripts/validate/fixtures/agent-plugin-fixture is a reference plugin that uses every join point, and the validator runs it.
Before you begin
- The agent starter installed and runnable.
- An OpenSpec change for the plugin:
openspec-cn new change "<id>-plugin". - A plugin id: a lower-case slug that is also its module key. Every key the plugin declares starts with it.
What the reader sees
There is one workbench at /app/agent and one composer. Beside it, a picker lists Auto, General and every switched-on agent plugin.
- Picking an agent swaps in its composer controls and keeps the typed text. The choice travels inside the message, so retrying an old message runs the agent it was sent to.
- On Auto the server routes the request. The start response and the thread snapshot name the plugin the Run went to, and the workbench uses that plugin for the rest of the thread.
- A plugin's cards render in the transcript and its workspace opens as a tab beside it. Several plugins' Runs can share one thread.
- Switching a plugin off in Settings → Plugins removes it from the picker on the next focus, rejects its new Runs and operations, and shows its old cards by their summary. Switching it back on restores them.
A plugin page such as /app/image is a shortcut into the same workbench with that agent picked.
Choose the join points
Declare only what the plugin needs.
| The plugin needs to | Declare | Where |
|---|---|---|
| Be picked and routed to | scenes, capabilityRoutes (words, file types or both), skills | server |
| Show its own composer controls and landing | agent with a lazily loaded capability | browser |
| Put structured, interactive content in the transcript | cards (payload schema) / cardRenderers | both |
| Open panels beside the thread | surfaces / surfaces | both |
| Let the reader act without a model turn | operations (input, Run state, timeout) | server |
| Bind a confirmation to the content the reader saw | validateUserAnswer (guards, approvals) | server |
| Fix a Run policy on the server | hostPinnedContext | server |
| Store a kind of result of its own | artifactKinds / artifactRenderers (<id>.<kind>) | both |
| Serve downloads or previews over HTTP | api.routes under /api/plugins/<id>/ | server |
Rules every plugin follows
- Namespaced keys. Card, panel, operation and artifact-kind keys are
<id>.<name>. The registry rejects another plugin's prefix, a duplicate, and<id>.workspace, which the host opens for the plugin's workspace. - Checked on both sides. Payload and input schemas live in the plugin's browser-safe
contracts.ts. The server validates before writing or running. The browser validates a card's payload again before rendering it. - Readable without the plugin. Every card carries a plain-text summary. With the plugin switched off or uninstalled, cards show it and artifacts of the plugin's kind are offered for download.
- Isolated. Cards and panels render inside an error boundary. An operation has a timeout, and one operation or answer runs per Run at a time.
Keep plugin.server.ts free of React and icons, because the agent service bundles it. Load the capability, cards and panels with import() so the workbench bundle does not grow with every plugin.
Build the plugin
The examples use a plugin with the id storyboard. Copy the layout of scripts/validate/fixtures/agent-plugin-fixture and keep only the join points you chose above.
Contracts and manifest
contracts.ts holds what both halves agree on: keys and zod schemas, with no React and no server imports.
import { z } from "zod";
export const STORYBOARD_PLUGIN_ID = "storyboard";
export const STORYBOARD_SCENE_KEY = "agent.storyboard";
export const STORYBOARD_SKILL_PACKAGE_ID = "platform.storyboard";
export const STORYBOARD_SKILL_DIRECTORY = "src/plugins/storyboard/skills/storyboard-studio";
export const STORYBOARD_CARD_KEY = `${STORYBOARD_PLUGIN_ID}.summary`;
export const STORYBOARD_CARD_SCHEMA_VERSION = 1;
export const StoryboardSummaryPayload = z
.object({ shots: z.number().int().min(0).max(100) })
.strict();import { defineManifest } from "../kernel/types";
export const storyboardManifest = defineManifest({
id: "storyboard",
version: "0.1.0",
kind: "agent",
requires: ["agent-starter"],
});Add routes when the plugin owns pages under /app or /admin.
Server half
Declare the AgentHostExtension and contribute it to agent.host. Use relative imports, because the agent service bundles this file and cannot resolve @/ aliases.
import type { AgentHostExtension } from "../../../server/agent-extensions/types";
import {
STORYBOARD_CARD_KEY,
STORYBOARD_CARD_SCHEMA_VERSION,
STORYBOARD_SCENE_KEY,
STORYBOARD_SKILL_DIRECTORY,
STORYBOARD_SKILL_PACKAGE_ID,
StoryboardSummaryPayload,
} from "../contracts";
export const storyboardExtension: AgentHostExtension = {
id: "storyboard",
scenes: [{ sceneKey: STORYBOARD_SCENE_KEY, readinessRequired: false }],
capabilityRoutes: [{ scene: STORYBOARD_SCENE_KEY, pattern: /\bstoryboard\b/iu }],
skills: [{ packageId: STORYBOARD_SKILL_PACKAGE_ID, directory: STORYBOARD_SKILL_DIRECTORY }],
cards: {
[STORYBOARD_CARD_KEY]: {
payload: StoryboardSummaryPayload,
schemaVersion: STORYBOARD_CARD_SCHEMA_VERSION,
},
},
};import { defineServerPlugin } from "../kernel/types";
import { storyboardManifest } from "./manifest";
import { storyboardExtension } from "./server/extension";
export const storyboardServerPlugin = defineServerPlugin({
manifest: storyboardManifest,
contributes: { "agent.host": [storyboardExtension] },
});readinessRequired: false keeps a plugin without a configured model from holding up the whole agent service. Add api.routes to the same contributes when the plugin serves HTTP under /api/plugins/storyboard/. Do not check the plugin's own on/off state anywhere. The host rejects its scenes, Skills, operations and API routes while it is switched off.
Browser half
plugin.ts holds only metadata and loaders. The capability, card renderers and panels are imported the first time the workbench needs them.
import { Clapperboard } from "lucide-react";
import { definePlugin } from "../kernel/types";
import {
STORYBOARD_CARD_KEY,
STORYBOARD_CARD_SCHEMA_VERSION,
STORYBOARD_SCENE_KEY,
STORYBOARD_SKILL_PACKAGE_ID,
} from "./contracts";
import { storyboardManifest } from "./manifest";
export const storyboardPlugin = definePlugin({
manifest: storyboardManifest,
contributes: {
"agent.workbench": [
{
id: "storyboard",
agent: {
id: "storyboard",
labelKey: "appConsole.storyboard",
icon: Clapperboard,
order: 30,
scenes: [STORYBOARD_SCENE_KEY],
skillPackageId: STORYBOARD_SKILL_PACKAGE_ID,
load: () =>
import("./workbench/capability").then(({ storyboardCapability }) => storyboardCapability),
},
cardRenderers: {
[STORYBOARD_CARD_KEY]: {
schemaVersion: STORYBOARD_CARD_SCHEMA_VERSION,
load: () => import("./workbench/summary-card").then(({ summaryCard }) => summaryCard),
},
},
},
],
},
});A card or panel acts only through the actions it receives (answer the pending question, open an artifact or panel, quote into the composer, runOperation) or through useWorkbenchOperation from src/components/agent/extension-card.tsx. Add the label key to both dictionaries.
Skill
Put the Skill in the plugin folder, here src/plugins/storyboard/skills/storyboard-studio, with a skill.json and a SKILL.md. In skill.json, list the plugin's scene under scenes and only tools that exist under allowedTools. src/plugins/image-agent/skills/image-studio is a working example. Publish it:
pnpm agent:publish-skillsBecause the extension declares the directory in skills, the command publishes it next to the platform Skills, and the Skill is removed when the plugin is removed.
Register
Add the two halves to the installed lists, each inside a // @module:storyboard … // @end-module:storyboard region, with the import in its own region too:
| File | Entry |
|---|---|
src/plugins/installed.ts | storyboardPlugin |
src/plugins/installed.server.ts | storyboardServerPlugin |
Dictionary entries go in both messages.ts files inside regions with the same marker.
Ship and validate
Write modules/storyboard/module.json: files with src/plugins/storyboard/**, fragments with the two installed lists and both dictionaries, requires: ["agent-starter"], the same version as the manifest, and docs holding the full address of the plugin's guide. Then add scripts/validate/storyboard.ts, which asserts the plugin's behaviour through the real registries, a validate:storyboard script and a segment in validate:all, and run pnpm registry:build. See Build a module.
Verify
pnpm validate:agent-plugin-contractpasses. It also builds the reference plugin and drives every join point through the host.- Your plugin's own validator asserts its behaviour, and
pnpm validate:allturns no check red. - In
/app/agent, the plugin is listed in the picker; a request that matches its route shows Auto · followed by the plugin's name and opens its workspace tab. - Switch the plugin off in Settings → Plugins: it leaves the picker when the page regains focus, and its cards show their summaries.
Troubleshooting
The registry refuses to start with invalid_extension_key
A key does not start with the plugin id, or names <id>.workspace. Rename it in contracts.ts. Both halves read the same constant.
A card shows only its summary
The plugin is switched off, its renderer's schemaVersion is older than the card's, or the payload fails the renderer's schema. Bump both versions together when the payload changes shape.
A message is refused with plugin_disabled
The picked agent was switched off. The composer keeps the text and returns to Auto. The next message is routed without it.