Plugins

Plugins extend the agent lifecycle through a simple hook interface. They provide optional capabilities such as skills, compaction, MCP integration, and UI bridges. Runners and storage backends are separate extension points.

Not yet published

The plugin packages are not published yet. Stay tuned.

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

Using plugins

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

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

Available plugins

Package	Description
@apeira/plugin-compact	Automatic context compaction for long-running agents. See Compact.
@apeira/plugin-mcp	Model Context Protocol integration. See MCP.
@apeira/plugin-roleplay	Character-card-driven, single-character roleplay. See Roleplay.
@apeira/plugin-skills	Filesystem-agnostic skills system. See Skills.
@apeira/plugin-ag-ui	Bridges Apeira events to @ag-ui/core format. See AG-UI.

Building a custom plugin

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

const loggingPlugin: AgentPlugin = {
  init: (agent) => {
    agent.subscribe('apeira', (event) => {
      if (event.type !== 'turn.failed')
        return

      console.error('turn failed:', event.error)
    })
  },
  name: 'logging',
  onTurnFinish: ({ usage }) => {
    console.log('usage:', usage)
  },
}

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