Connects with external services for IMAGE_DESCRIPTION, TRANSCRIPTION, TEXT_GENERATION, SPEECH_GENERATION, VIDEO, PDF, BROWSER, WEB_SEARCH, EMAIL_AUTOMATION, and more
The runtime maintains comprehensive state through the State interface:
interface State {
// Core state data
values: {
[key: string]: any;
};
data: {
[key: string]: any;
};
text: string;
}
// State composition example
async function manageState() {
// Initial state composition with all regular providers
const state = await runtime.composeState(message);
// State with specific providers only
const filteredState = await runtime.composeState(message, ['timeProvider', 'recentMessages']);
// Include private or dynamic providers
const enhancedState = await runtime.composeState(message, null, [
'weatherProvider',
'portfolioProvider',
]);
}
Plugins extend agent functionality through a modular interface. The runtime supports various types of plugins including services, adapters, actions, and more:
Plugins are modular extensions that enhance the capabilities of ElizaOS agents. They provide a flexible way to add new functionality, integrate external services, and customize agent behavior across different platforms.
info
Key Improvements in V2
Unified API: Almost everything is accessible via runtime.methodName() in the agent runtime for simpler development
Enhanced Model System: The new useModel approach allows for flexible model provider registration
Events System: Formal support for event-based programming
Plugin Creation Workflow: Simplified creation and testing via CLI
Testing Infrastructure: Built-in support for plugin testing
No Monorepo Required: Complete plugin development without touching the core codebase
Plugin Registry: Manages the catalog of available plugins and handles their registration with the runtime
Bootstrap Plugin: Initializes core functionality required for all agents to operate
The ElizaOS plugin system maintains the same basic concept as previous versions, with several new extension points (events, routes, tests, models) and features that significantly improve the developer experience.
Browse plugins the elizaOS community made here: Package Showcase
You can create a new ElizaOS plugin using the CLI:
# Using npm
npm create eliza@beta
# Or using npx
npx @elizaos/cli@beta create
When prompted, select "Plugin" as the type to create. The CLI will guide you through the setup process, creating a plugin with the proper structure and dependencies.
If you're a plugin developer, you can publish your plugin to make it available to others. The ElizaOS CLI provides several options for publishing your plugin depending on your needs.
First, make sure your plugin is built and ready for distribution:
# Navigate to your plugin directory
cd my-eliza-plugin
# Build your plugin
npm run build
GitHub Publishing
npm Publishing
Test Mode
Additional Options
Publishing to GitHub is the recommended approach for sharing your plugin with the ElizaOS community:
# Publish to GitHub
npx @elizaos/cli publish
This will:
Build and package your plugin
Create or update a GitHub repository in the elizaos-plugins organization
Add your plugin to the ElizaOS registry (if you're a registry maintainer)
For first-time publishers, the CLI will guide you through setting up GitHub credentials for publishing.
GitHub publishing is ideal for open-source plugins that you want to share with the community and have listed in the official registry.
Eliza uses a unified plugin architecture where everything is a plugin - including services, adapters, actions, evaluators, and providers. This approach ensures consistent behavior and better extensibility.
Services are the core integration points for external platforms. A properly implemented service:
import { Service, IAgentRuntime } from '@elizaos/core';
export class ExampleService extends Service {
// Required: Define the service type (used for runtime registration)
static serviceType = 'example';
// Required: Describe what this service enables the agent to do
capabilityDescription = 'Enables the agent to interact with the Example platform';
// Store runtime for service operations
constructor(protected runtime: IAgentRuntime) {
super();
// Initialize connections, setup event handlers, etc.
}
// Required: Static method to create and initialize service instance
static async start(runtime: IAgentRuntime): Promise<ExampleService> {
const service = new ExampleService(runtime);
// Additional initialization if needed
return service;
}
// Required: Clean up resources when service is stopped
async stop(): Promise<void> {
// Close connections, release resources
}
// Optional: Custom methods for your service functionality
async sendMessage(content: string, channelId: string): Promise<void> {
// Implementation
}
}
// In your service implementation
const apiKey = runtime.getSetting('EXAMPLE_API_KEY');
const debugMode = runtime.getSetting('EXAMPLE_DEBUG_MODE'); // Returns boolean for "true"/"false" strings
The Bootstrap Plugin is a foundational component of ElizaOS that initializes the core functionality required for agents to operate. It's automatically loaded as part of the initialization process, establishing the minimum viable capabilities that all agents need.
The Bootstrap Plugin registers essential components across several categories to provide a foundation for all agents. These components can be extended by custom plugins.
During development, you can test your plugin locally:
# Start with your plugin
npx @elizaos/cli start --plugin=./path/to/plugin
# Or with a specific character
npx @elizaos/cli start --character=./characters/test.character.json --plugin=./path/to/plugin
A plugin is a modular extension that adds new capabilities to ElizaOS agents, such as API integrations, custom actions, or platform connections. Plugins allow you to expand agent functionality and share reusable components with other developers.
When should I create a plugin versus using existing ones?
Create a plugin when you need custom functionality not available in existing plugins, want to integrate with external services, or plan to share reusable agent capabilities with the community.
Plugin dependencies are managed through your project's package.json. You can add plugins directly using npm or the ElizaOS CLI, and they will be automatically loaded when your project starts.
Can I use a plugin in development before publishing?
Yes, you can use the --plugin flag with the start command to include local plugins during development:
npx @elizaos/cli start --plugin=./path/to/plugin
What's the difference between Actions and Services?
Actions handle specific agent responses or behaviors, while Services provide platform integrations (like Discord or Twitter) or ongoing background functionality that multiple actions might use.
Implement proper backoff strategies in your service implementation and consider using a queue system for message handling to respect platform rate limits.
