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'
import { responses } from 'apeira/responses'

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-common-tools	Common development tools (read, write, edit, bash, fetch, search). See Common Tools.
@apeira/plugin-hitl	Human-in-the-loop tool approval. See HITL.
@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',
  onFinish: ({ usage }) => {
    console.log('usage:', usage)
  },
}

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