Skip to main content

​
Overview

Plugins extend agent functionality by hooking into the tick lifecycle, exposing actions, and managing state. They’re the primary way to add capabilities like social posting, trading, or custom integrations. Reference: src/plugins/types.ts

​
Plugin Interface

FieldTypeRequiredDescription
namestringYesUnique identifier
versionstringYesSemver version
descriptionstringNoHuman-readable description
dependenciesstring[]NoPlugins that must load first
initfunctionNoCalled once on registration
cleanupfunctionNoCalled when agent stops
onTickfunctionNoCalled after every tick
actionsobjectNoCallable methods

​
Lifecycle Hooks

HookWhen CalledUse For
init(agent)Plugin registrationSetup, connections, validation
onTick(context)After each tickReact to state, execute actions
cleanup(agent)Agent stopsClose connections, flush buffers

​
TickContext

The context passed to onTick:
FieldTypeDescription
stateAgentStateCurrent mood, health, routine
memoriesMemory[]Retrieved memories for tick
knowledgeKnowledge[]Retrieved knowledge items
recentLogsLog[]Recent activity logs
Reference: TickContext interface in src/core/types.ts

​
Creating Plugins

​
Static Plugin

export const myPlugin: Plugin = {
  name: "my-plugin",
  version: "1.0.0",
  onTick(context) {
    console.log(`Tick: ${context.state.mood}`);
  }
};
Use factories when plugins need configuration or internal state: 
export function createMyPlugin(config: MyConfig): Plugin {
  let state = {};  // Internal state
  return {
    name: "my-plugin",
    version: "1.0.0",
    onTick(context) { /* use config and state */ }
  };
}
Reference: See factory examples in the src/plugins directory

​
Plugin Actions

Actions are methods exposed by plugins, callable via the agent: 
actions: {
  async buy(params, agent) {
    return { success: true };
  }
}

// Call from agent
await agent.executeAction("plugin-name", "buy", { symbol: "ETH" });

​
Registration

// Single plugin
agent.use(myPlugin);

// Multiple at construction
new Agent({ backend, plugins: [plugin1, plugin2] });

// Get plugin reference
const plugin = agent.getPlugin("name");
const all = agent.getPlugins();
Reference: agent.use() in src/core/agent.ts

​
Dependencies

Plugins can declare dependencies that must load first: 
{
  name: "enhanced-twitter",
  dependencies: ["twitter", "analytics"],
  init(agent) {
    const twitter = agent.getPlugin("twitter");
  }
}
The agent validates dependency order during registration. Reference: loadPlugins() in src/plugins/loader.ts

​
Configuration Patterns

PatternWhen to Use
Environment variablesAPI keys, feature flags
Factory parametersCooldowns, limits, options
Runtime actionsDynamic reconfiguration

​
Error Handling

Plugins should catch errors to avoid crashing the agent: 
onTick(context) {
  try {
    await this.riskyOperation();
  } catch (error) {
    console.error("Plugin error:", error);
    // Don't re-throw - let agent continue
  }
}

​
Testing

const agent = createAgent({
  backend: new MemoryBackend(),
  plugins: [myPlugin]
});
const result = await agent.tick();
Reference: Test patterns in tests/plugins/

​
Next Steps

Agent SDK

Main agent class reference.

Plugin Guide

Step-by-step plugin development.