Plugins

Plugins extend the agent lifecycle through a simple hook interface. Every feature beyond the core runtime — skills, storage, UI bridges — is a plugin.

For the full plugin interface and API details, see Plugin API.

Using plugins

import { skills } from '@apeira/plugin-skills'
import { createAgent } from 'apeira'

const agent = createAgent({
  instructions: 'You are a helpful assistant.',
  name: 'assistant',
  options: {
    apiKey: process.env.OPENAI_API_KEY,
    baseURL: 'https://api.openai.com/v1/',
    model: 'gpt-5.5',
  },
  plugins: [
    skills({
      sets: [mySkillSet],
    }),
  ],
})

Available plugins

Package	Description
@apeira/plugin-common-tools	Common development tools (read, write, edit, bash, fetch, search). See Common Tools.
@apeira/plugin-mcp	Model Context Protocol integration. See MCP.
@apeira/plugin-skills	Filesystem-agnostic skills system. See Skills.
@apeira/plugin-ag-ui	Bridges Apeira events to @ag-ui/core format. See AG-UI.
@apeira/plugin-unstorage	Wraps unstorage for session persistence. See Unstorage.

Building a custom plugin

import type { AgentPlugin } from '@apeira/core'

const loggingPlugin: AgentPlugin = {
  name: 'logging',
  onEvent: event => event.type === 'turn.failed' && console.error(event.error),
  onTurnDone: ({ snapshot, turnId }) => console.log('turn finished:', turnId, snapshot.episodic.length),
  onTurnStart: ({ turnId }) => {
    console.log('turn started:', turnId)
  },
}

Register it by passing it in the plugins array to createAgent().