# Table of Contents - [Environment Configuration - ElizaOS Documentation](#environment-configuration-elizaos-documentation) - [elizaOS CLI Overview - ElizaOS Documentation](#elizaos-cli-overview-elizaos-documentation) - [Create Command - ElizaOS Documentation](#create-command-elizaos-documentation) - [Publish Command - ElizaOS Documentation](#publish-command-elizaos-documentation) - [Development Mode - ElizaOS Documentation](#development-mode-elizaos-documentation) - [Agent Command - ElizaOS Documentation](#agent-command-elizaos-documentation) - [Monorepo Command - ElizaOS Documentation](#monorepo-command-elizaos-documentation) - [Plugin Management - ElizaOS Documentation](#plugin-management-elizaos-documentation) - [Start Command - ElizaOS Documentation](#start-command-elizaos-documentation) - [Update Command - ElizaOS Documentation](#update-command-elizaos-documentation) - [TEE Command - ElizaOS Documentation](#tee-command-elizaos-documentation) - [Test Command - ElizaOS Documentation](#test-command-elizaos-documentation) - [Overview - ElizaOS Documentation](#overview-elizaos-documentation) - [Character Interface - ElizaOS Documentation](#character-interface-elizaos-documentation) - [Contribute to Core - ElizaOS Documentation](#contribute-to-core-elizaos-documentation) - [Add Multiple Agents - ElizaOS Documentation](#add-multiple-agents-elizaos-documentation) - [Deploy a Project - ElizaOS Documentation](#deploy-a-project-elizaos-documentation) - [Personality and Behavior - ElizaOS Documentation](#personality-and-behavior-elizaos-documentation) - [Create a Plugin - ElizaOS Documentation](#create-a-plugin-elizaos-documentation) - [Publish a Plugin - ElizaOS Documentation](#publish-a-plugin-elizaos-documentation) - [Memory and State - ElizaOS Documentation](#memory-and-state-elizaos-documentation) - [Runtime and Lifecycle - ElizaOS Documentation](#runtime-and-lifecycle-elizaos-documentation) - [Customize an Agent - ElizaOS Documentation](#customize-an-agent-elizaos-documentation) - [Test a Project - ElizaOS Documentation](#test-a-project-elizaos-documentation) - [Installation - ElizaOS Documentation](#installation-elizaos-documentation) - [Launch Resources - ElizaOS Documentation](#launch-resources-elizaos-documentation) - [Message Processing Core - ElizaOS Documentation](#message-processing-core-elizaos-documentation) - [Complete Developer Guide - ElizaOS Documentation](#complete-developer-guide-elizaos-documentation) - [Message Processing Flow - ElizaOS Documentation](#message-processing-flow-elizaos-documentation) - [Implementation Examples - ElizaOS Documentation](#implementation-examples-elizaos-documentation) - [Testing Guide - ElizaOS Documentation](#testing-guide-elizaos-documentation) - [Operations Flow - ElizaOS Documentation](#operations-flow-elizaos-documentation) - [Operations Flow - ElizaOS Documentation](#operations-flow-elizaos-documentation) - [Examples - ElizaOS Documentation](#examples-elizaos-documentation) - [Testing Guide - ElizaOS Documentation](#testing-guide-elizaos-documentation) - [Google GenAI Plugin - ElizaOS Documentation](#google-genai-plugin-elizaos-documentation) - [Anthropic Plugin - ElizaOS Documentation](#anthropic-plugin-elizaos-documentation) - [Ollama Plugin - ElizaOS Documentation](#ollama-plugin-elizaos-documentation) - [OpenAI Plugin - ElizaOS Documentation](#openai-plugin-elizaos-documentation) - [OpenRouter Plugin - ElizaOS Documentation](#openrouter-plugin-elizaos-documentation) - [Architecture & Flow Diagrams - ElizaOS Documentation](#architecture-flow-diagrams-elizaos-documentation) - [Testing Guide - ElizaOS Documentation](#testing-guide-elizaos-documentation) - [Examples - ElizaOS Documentation](#examples-elizaos-documentation) - [Contextual Embeddings - ElizaOS Documentation](#contextual-embeddings-elizaos-documentation) - [Discord Integration - ElizaOS Documentation](#discord-integration-elizaos-documentation) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [Page Not Found](#page-not-found) - [REST Reference - ElizaOS Documentation](#rest-reference-elizaos-documentation) - [Page Not Found](#page-not-found) --- # Environment Configuration - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/cli-reference/env#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Commands Environment Configuration [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) * Overview * Examples * Features * Troubleshooting [​](https://docs.elizaos.ai/cli-reference/env#usage) Usage ------------------------------------------------------------- Copy Ask AI elizaos env [command] [options] [​](https://docs.elizaos.ai/cli-reference/env#subcommands) Subcommands ------------------------------------------------------------------------- | Subcommand | Description | Options | | --- | --- | --- | | `list` | List all environment variables | `--system`, `--local` | | `edit-local` | Edit local environment variables | `-y, --yes` | | `reset` | Reset environment variables and clean up database/cache files (interactive selection) | `-y, --yes` | | `interactive` | Interactive environment variable management | `-y, --yes` | [​](https://docs.elizaos.ai/cli-reference/env#options) Options ----------------------------------------------------------------- ### [​](https://docs.elizaos.ai/cli-reference/env#list-command-options) List Command Options | Option | Description | | --- | --- | | `--system` | List only system information | | `--local` | List only local environment variables | ### [​](https://docs.elizaos.ai/cli-reference/env#general-options) General Options | Option | Description | | --- | --- | | `-y, --yes` | Automatically confirm prompts | Was this page helpful? YesNo [Development Mode](https://docs.elizaos.ai/cli-reference/dev) [Agent Command](https://docs.elizaos.ai/cli-reference/agent) ⌘I --- # elizaOS CLI Overview - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/cli-reference/overview#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Getting Started elizaOS CLI Overview [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Installation](https://docs.elizaos.ai/cli-reference/overview#installation) * [Available Commands](https://docs.elizaos.ai/cli-reference/overview#available-commands) * [Global Options](https://docs.elizaos.ai/cli-reference/overview#global-options) * [Examples](https://docs.elizaos.ai/cli-reference/overview#examples) * [Getting Version Information](https://docs.elizaos.ai/cli-reference/overview#getting-version-information) * [Project Structure](https://docs.elizaos.ai/cli-reference/overview#project-structure) * [Environment Configuration](https://docs.elizaos.ai/cli-reference/overview#environment-configuration) * [Development vs Production](https://docs.elizaos.ai/cli-reference/overview#development-vs-production) * [Quick Start](https://docs.elizaos.ai/cli-reference/overview#quick-start) * [Creating a new project](https://docs.elizaos.ai/cli-reference/overview#creating-a-new-project) * [Starting a project](https://docs.elizaos.ai/cli-reference/overview#starting-a-project) * [Development mode](https://docs.elizaos.ai/cli-reference/overview#development-mode) * [Working with Projects](https://docs.elizaos.ai/cli-reference/overview#working-with-projects) * [Working with Plugins](https://docs.elizaos.ai/cli-reference/overview#working-with-plugins) * [Related Documentation](https://docs.elizaos.ai/cli-reference/overview#related-documentation) [​](https://docs.elizaos.ai/cli-reference/overview#installation) Installation -------------------------------------------------------------------------------- Install the elizaOS CLI globally using Bun: Copy Ask AI bun install -g @elizaos/cli **Video Tutorial**: [**Full CLI Reference**](https://www.youtube.com/watch?v=agI0yOPWBwk&list=PLrjBjP4nU8ehOgKAa0-XddHzE0KK0nNvS&index=8) [​](https://docs.elizaos.ai/cli-reference/overview#available-commands) Available Commands -------------------------------------------------------------------------------------------- | Command | Description | | --- | --- | | [`create`](https://docs.elizaos.ai/cli-reference/create) | Initialize a new project, plugin, or agent | | [`monorepo`](https://docs.elizaos.ai/cli-reference/monorepo) | Clone elizaOS monorepo from a specific branch (defaults to develop) | | [`plugins`](https://docs.elizaos.ai/cli-reference/plugins) | Manage elizaOS plugins | | [`agent`](https://docs.elizaos.ai/cli-reference/agent) | Manage elizaOS agents | | [`tee`](https://docs.elizaos.ai/cli-reference/tee) | Manage TEE deployments | | [`start`](https://docs.elizaos.ai/cli-reference/start) | Start the Eliza agent with configurable plugins and services | | [`update`](https://docs.elizaos.ai/cli-reference/update) | Update elizaOS CLI and project dependencies | | [`test`](https://docs.elizaos.ai/cli-reference/test) | Run tests for Eliza agent projects and plugins | | [`env`](https://docs.elizaos.ai/cli-reference/env) | Manage environment variables and secrets | | [`dev`](https://docs.elizaos.ai/cli-reference/dev) | Start the project or plugin in development mode with auto-rebuild, detailed logging, and file change detection | | [`publish`](https://docs.elizaos.ai/cli-reference/publish) | Publish a plugin to the registry | [​](https://docs.elizaos.ai/cli-reference/overview#global-options) Global Options ------------------------------------------------------------------------------------ These options apply to all commands: | Option | Description | | --- | --- | | `--help`, `-h` | Display help information | | `--version`, `-v` | Display version information | | `--no-emoji` | Disables emoji characters in the output | | `--no-auto-install` | Disables the automatic prompt to install Bun if it is not detected | [​](https://docs.elizaos.ai/cli-reference/overview#examples) Examples ------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/cli-reference/overview#getting-version-information) Getting Version Information Copy Ask AI # Check your CLI version elizaos --version # Get help for the 'agent' command elizaos agent --help # Get help for the 'agent start' subcommand elizaos agent start --help [​](https://docs.elizaos.ai/cli-reference/overview#project-structure) Project Structure ------------------------------------------------------------------------------------------ For detailed information about project and plugin structure, see the [Quickstart Guide](https://docs.elizaos.ai/quickstart) . [​](https://docs.elizaos.ai/cli-reference/overview#environment-configuration) Environment Configuration ---------------------------------------------------------------------------------------------------------- Configure your API keys and environment variables with the `env` command: Copy Ask AI # Edit local environment variables interactively elizaos env edit-local # List all environment variables elizaos env list # Interactive environment manager elizaos env interactive [​](https://docs.elizaos.ai/cli-reference/overview#development-vs-production) Development vs Production ---------------------------------------------------------------------------------------------------------- elizaOS supports two main modes of operation: [Development Mode\ ----------------\ \ Hot reloading, detailed error messages, and file watching for rapid development.](https://docs.elizaos.ai/cli-reference/dev) [Production Mode\ ---------------\ \ Optimized performance and production-ready configuration for deployment.](https://docs.elizaos.ai/cli-reference/start) [​](https://docs.elizaos.ai/cli-reference/overview#quick-start) Quick Start ------------------------------------------------------------------------------ For a complete guide to getting started with elizaOS, see the [Quickstart Guide](https://docs.elizaos.ai/quickstart) . ### [​](https://docs.elizaos.ai/cli-reference/overview#creating-a-new-project) Creating a new project Copy Ask AI # Create a new project using the interactive wizard elizaos create # Or specify a name directly elizaos create my-agent-project ### [​](https://docs.elizaos.ai/cli-reference/overview#starting-a-project) Starting a project Copy Ask AI # Navigate to your project directory cd my-agent-project # Start the project elizaos start ### [​](https://docs.elizaos.ai/cli-reference/overview#development-mode) Development mode Copy Ask AI # Run in development mode with hot reloading elizaos dev [​](https://docs.elizaos.ai/cli-reference/overview#working-with-projects) Working with Projects -------------------------------------------------------------------------------------------------- elizaOS organizes work into projects, which can contain one or more agents along with their configurations, knowledge files, and dependencies. The CLI provides commands to manage the entire lifecycle of a project: 1. **Create** a new project with `create` 2. **Configure** settings with `env` 3. **Develop** using `dev` for hot reloading 4. **Test** functionality with `test` 5. **Start** in production with `start` 6. **Share** by publishing with `publish` [​](https://docs.elizaos.ai/cli-reference/overview#working-with-plugins) Working with Plugins ------------------------------------------------------------------------------------------------ Plugins extend the functionality of your agents. Use the `plugins` command for managing plugins and `publish` for publishing your own: Copy Ask AI # List available plugins elizaos plugins list # Add a plugin to your project elizaos plugins add @elizaos/plugin-discord # Publish your plugin (from plugin directory) elizaos publish # Test publishing without making changes elizaos publish --test [​](https://docs.elizaos.ai/cli-reference/overview#related-documentation) Related Documentation -------------------------------------------------------------------------------------------------- [Quickstart Guide\ ----------------\ \ Complete workflow guide to get started with elizaOS](https://docs.elizaos.ai/quickstart) [Environment Configuration\ -------------------------\ \ Managing environment variables and configuration](https://docs.elizaos.ai/cli-reference/env) Was this page helpful? YesNo [Create Command](https://docs.elizaos.ai/cli-reference/create) ⌘I --- # Create Command - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/cli-reference/create#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Commands Create Command [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) * Overview * Examples * Project Types * Troubleshooting [​](https://docs.elizaos.ai/cli-reference/create#usage) Usage ---------------------------------------------------------------- Copy Ask AI # Interactive mode (recommended) elizaos create # With specific options elizaos create [options] [name] [​](https://docs.elizaos.ai/cli-reference/create#getting-help) Getting Help ------------------------------------------------------------------------------ Copy Ask AI # View detailed help elizaos create --help [​](https://docs.elizaos.ai/cli-reference/create#options) Options -------------------------------------------------------------------- | Option | Description | | --- | --- | | `-y, --yes` | Skip confirmation and use defaults (default: `false`) | | `--type ` | Type of template to use (`project`, `plugin`, `agent`, or `tee`) (default: `project`) | | `[name]` | Name for the project, plugin, or agent (optional) | [​](https://docs.elizaos.ai/cli-reference/create#interactive-process) Interactive Process -------------------------------------------------------------------------------------------- When you run `elizaos create` without options, it launches an interactive wizard: 1. **What would you like to name your project?** - Enter your project name 2. **Select your database:** - Choose between: * `pglite` (local, file-based database) * `postgres` (requires connection details) [​](https://docs.elizaos.ai/cli-reference/create#default-values-with-y-flag) Default Values (with -y flag) ------------------------------------------------------------------------------------------------------------- When using the `-y` flag to skip prompts: * **Default name**: `myproject` * **Default type**: `project` * **Default database**: `pglite` Was this page helpful? YesNo [elizaOS CLI Overview](https://docs.elizaos.ai/cli-reference/overview) [Start Command](https://docs.elizaos.ai/cli-reference/start) ⌘I --- # Publish Command - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/cli-reference/publish#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Commands Publish Command [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) The `elizaos publish` command is the all-in-one tool for releasing your plugin. It handles packaging, publishing to npm, creating a source repository, and submitting your plugin to the official elizaOS registry for discovery. * Overview * Examples * Publishing Process * Requirements * Troubleshooting [​](https://docs.elizaos.ai/cli-reference/publish#what-it-does) What It Does ------------------------------------------------------------------------------- The `publish` command automates the entire release process: * **Validates Your Plugin:** Checks your `package.json` and directory structure against registry requirements * **Publishes Your Package:** Pushes your plugin to npm * **Creates GitHub Repository:** Initializes a public GitHub repository for your plugin’s source code * **Submits to Registry:** Opens a Pull Request to the official [elizaOS Plugin Registry](https://github.com/elizaos-plugins/registry) [​](https://docs.elizaos.ai/cli-reference/publish#usage) Usage ----------------------------------------------------------------- Copy Ask AI elizaos publish [options] [​](https://docs.elizaos.ai/cli-reference/publish#options) Options --------------------------------------------------------------------- | Option | Description | | --- | --- | | `--npm` | Publish to npm only (skip GitHub and registry) | | `-t, --test` | Test publish process without making changes | | `-d, --dry-run` | Generate registry files locally without publishing | | `--skip-registry` | Skip publishing to the registry | Was this page helpful? YesNo [Update Command](https://docs.elizaos.ai/cli-reference/update) [Monorepo Command](https://docs.elizaos.ai/cli-reference/monorepo) ⌘I --- # Development Mode - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/cli-reference/dev#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Commands Development Mode [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) * Overview * Examples * Features * Troubleshooting [​](https://docs.elizaos.ai/cli-reference/dev#usage) Usage ------------------------------------------------------------- Copy Ask AI elizaos dev [options] [​](https://docs.elizaos.ai/cli-reference/dev#options) Options ----------------------------------------------------------------- | Option | Description | | --- | --- | | `-c, --configure` | Reconfigure services and AI models (skips using saved configuration) | | `--character [paths...]` | Character file(s) to use - accepts paths or URLs | | `-b, --build` | Build the project before starting | | `-p, --port ` | Port to listen on (default: 3000) | | `-h, --help` | Display help for command | Was this page helpful? YesNo [Start Command](https://docs.elizaos.ai/cli-reference/start) [Environment Configuration](https://docs.elizaos.ai/cli-reference/env) ⌘I --- # Agent Command - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/cli-reference/agent#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Commands Agent Command [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) * Overview * Examples * Features * Troubleshooting [​](https://docs.elizaos.ai/cli-reference/agent#usage) Usage --------------------------------------------------------------- Copy Ask AI elizaos agent [options] [command] [​](https://docs.elizaos.ai/cli-reference/agent#subcommands) Subcommands --------------------------------------------------------------------------- | Subcommand | Aliases | Description | Required Options | Additional Options | | --- | --- | --- | --- | --- | | `list` | `ls` | List available agents | | `-j, --json`, `-r, --remote-url `, `-p, --port ` | | `get` | `g` | Get agent details | `-n, --name ` | `-j, --json`, `-o, --output [file]`, `-r, --remote-url`, `-p, --port` | | `start` | `s` | Start an agent with a character profile | One of: `-n, --name`, `--path`, `--remote-character` | `-r, --remote-url `, `-p, --port ` | | `stop` | `st` | Stop an agent | `-n, --name ` | `-r, --remote-url `, `-p, --port ` | | `remove` | `rm` | Remove an agent | `-n, --name ` | `-r, --remote-url `, `-p, --port ` | | `set` | | Update agent configuration | `-n, --name ` AND one of: `-c, --config` OR `-f, --file` | `-r, --remote-url `, `-p, --port ` | | `clear-memories` | `clear` | Clear all memories for an agent | `-n, --name ` | `-r, --remote-url `, `-p, --port ` | [​](https://docs.elizaos.ai/cli-reference/agent#options-reference) Options Reference --------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/cli-reference/agent#common-options-all-subcommands) Common Options (All Subcommands) * `-r, --remote-url `: URL of the remote agent runtime * `-p, --port `: Port to listen on ### [​](https://docs.elizaos.ai/cli-reference/agent#output-options-for-list-and-get) Output Options (for `list` and `get`) * `-j, --json`: Output as JSON format instead of the default table format. * `-o, --output [file]`: For the `get` command, saves the agent’s configuration to a JSON file. If no filename is provided, defaults to `{name}.json`. ### [​](https://docs.elizaos.ai/cli-reference/agent#get-specific-options) Get Specific Options * `-n, --name `: Agent id, name, or index number from list (required) ### [​](https://docs.elizaos.ai/cli-reference/agent#start-specific-options) Start Specific Options * `-n, --name `: Name of an existing agent to start * `--path `: Path to local character JSON file * `--remote-character `: URL to remote character JSON file ### [​](https://docs.elizaos.ai/cli-reference/agent#stop%2Fremove-specific-options) Stop/Remove Specific Options * `-n, --name `: Agent id, name, or index number from list (required) ### [​](https://docs.elizaos.ai/cli-reference/agent#set-specific-options) Set Specific Options * `-n, --name `: Agent id, name, or index number from list (required) * `-c, --config `: Agent configuration as JSON string * `-f, --file `: Path to agent configuration JSON file ### [​](https://docs.elizaos.ai/cli-reference/agent#clear-memories-specific-options) Clear Memories Specific Options * `-n, --name `: Agent id, name, or index number from list (required) Was this page helpful? YesNo [Environment Configuration](https://docs.elizaos.ai/cli-reference/env) [Plugin Management](https://docs.elizaos.ai/cli-reference/plugins) ⌘I --- # Monorepo Command - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/cli-reference/monorepo#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Commands Monorepo Command [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Usage](https://docs.elizaos.ai/cli-reference/monorepo#usage) * [Options](https://docs.elizaos.ai/cli-reference/monorepo#options) * [How It Works](https://docs.elizaos.ai/cli-reference/monorepo#how-it-works) * [Examples](https://docs.elizaos.ai/cli-reference/monorepo#examples) * [Basic Usage](https://docs.elizaos.ai/cli-reference/monorepo#basic-usage) * [Custom Branch](https://docs.elizaos.ai/cli-reference/monorepo#custom-branch) * [Custom Directory](https://docs.elizaos.ai/cli-reference/monorepo#custom-directory) * [Development Workflows](https://docs.elizaos.ai/cli-reference/monorepo#development-workflows) * [After Setup](https://docs.elizaos.ai/cli-reference/monorepo#after-setup) * [Development Commands](https://docs.elizaos.ai/cli-reference/monorepo#development-commands) * [Monorepo Structure](https://docs.elizaos.ai/cli-reference/monorepo#monorepo-structure) * [Use Cases](https://docs.elizaos.ai/cli-reference/monorepo#use-cases) * [Contributors](https://docs.elizaos.ai/cli-reference/monorepo#contributors) * [Advanced Users](https://docs.elizaos.ai/cli-reference/monorepo#advanced-users) * [Plugin Developers](https://docs.elizaos.ai/cli-reference/monorepo#plugin-developers) * [Troubleshooting](https://docs.elizaos.ai/cli-reference/monorepo#troubleshooting) * [Clone Failures](https://docs.elizaos.ai/cli-reference/monorepo#clone-failures) * [Directory Issues](https://docs.elizaos.ai/cli-reference/monorepo#directory-issues) * [Build Failures](https://docs.elizaos.ai/cli-reference/monorepo#build-failures) * [Branch Not Found](https://docs.elizaos.ai/cli-reference/monorepo#branch-not-found) * [Notes](https://docs.elizaos.ai/cli-reference/monorepo#notes) * [Related Commands](https://docs.elizaos.ai/cli-reference/monorepo#related-commands) [​](https://docs.elizaos.ai/cli-reference/monorepo#usage) Usage ------------------------------------------------------------------ Copy Ask AI elizaos monorepo [options] [​](https://docs.elizaos.ai/cli-reference/monorepo#options) Options ---------------------------------------------------------------------- | Option | Description | Default | | --- | --- | --- | | `-b, --branch ` | Branch to clone | `develop` | | `-d, --dir ` | Destination directory | `./eliza` | [​](https://docs.elizaos.ai/cli-reference/monorepo#how-it-works) How It Works -------------------------------------------------------------------------------- 1. **Checks Destination**: Verifies the target directory is empty or doesn’t exist 2. **Clones Repository**: Downloads the `elizaOS/eliza` repository from GitHub 3. **Shows Next Steps**: Displays instructions for getting started [​](https://docs.elizaos.ai/cli-reference/monorepo#examples) Examples ------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/cli-reference/monorepo#basic-usage) Basic Usage Copy Ask AI # Clone default branch (develop) to default directory (./eliza) elizaos monorepo # Clone with verbose output elizaos monorepo --dir ./eliza --branch develop ### [​](https://docs.elizaos.ai/cli-reference/monorepo#custom-branch) Custom Branch Copy Ask AI # Clone main branch elizaos monorepo --branch main # Clone feature branch for testing elizaos monorepo --branch feature/new-api # Clone release branch elizaos monorepo --branch v2.1.0 ### [​](https://docs.elizaos.ai/cli-reference/monorepo#custom-directory) Custom Directory Copy Ask AI # Clone to custom directory elizaos monorepo --dir my-eliza-dev # Clone to current directory (must be empty) elizaos monorepo --dir . # Clone to nested path elizaos monorepo --dir ./projects/eliza-fork ### [​](https://docs.elizaos.ai/cli-reference/monorepo#development-workflows) Development Workflows Copy Ask AI # For contribution development elizaos monorepo --branch main --dir ./eliza-contrib # For stable development elizaos monorepo --branch main --dir ./eliza-stable # For testing specific features elizaos monorepo --branch feature/new-plugin-system [​](https://docs.elizaos.ai/cli-reference/monorepo#after-setup) After Setup ------------------------------------------------------------------------------ Once cloned, follow these steps: Copy Ask AI cd eliza # Navigate to the cloned directory bun i && bun run build # Install dependencies and build ### [​](https://docs.elizaos.ai/cli-reference/monorepo#development-commands) Development Commands Copy Ask AI # Start development server bun run dev # Run tests bun test # Build all packages bun run build # Start a specific package cd packages/client-web bun dev [​](https://docs.elizaos.ai/cli-reference/monorepo#monorepo-structure) Monorepo Structure -------------------------------------------------------------------------------------------- The cloned repository includes: Copy Ask AI eliza/ ├── packages/ │ ├── core/ # Core elizaOS functionality │ ├── client-web/ # Web interface │ ├── client-discord/ # Discord client │ ├── plugin-*/ # Various plugins │ └── cli/ # CLI tool source ├── docs/ # Documentation ├── examples/ # Example projects └── scripts/ # Build and utility scripts [​](https://docs.elizaos.ai/cli-reference/monorepo#use-cases) Use Cases -------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/cli-reference/monorepo#contributors) Contributors Perfect for developers wanting to: * Submit pull requests * Develop new plugins * Fix bugs or add features * Understand the codebase ### [​](https://docs.elizaos.ai/cli-reference/monorepo#advanced-users) Advanced Users Useful for users who need: * Custom builds * Experimental features * Local plugin development * Integration testing ### [​](https://docs.elizaos.ai/cli-reference/monorepo#plugin-developers) Plugin Developers Essential for: * Plugin development and testing * Understanding plugin APIs * Contributing to core functionality [​](https://docs.elizaos.ai/cli-reference/monorepo#troubleshooting) Troubleshooting -------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/cli-reference/monorepo#clone-failures) Clone Failures Copy Ask AI # If git clone fails, check network connection git --version ping github.com # For authentication issues git config --global credential.helper store ### [​](https://docs.elizaos.ai/cli-reference/monorepo#directory-issues) Directory Issues Copy Ask AI # If directory is not empty ls -la ./eliza # Check contents rm -rf ./eliza # Remove if safe elizaos monorepo # Retry # For permission issues sudo chown -R $USER:$USER ./eliza ### [​](https://docs.elizaos.ai/cli-reference/monorepo#build-failures) Build Failures Copy Ask AI # If dependencies fail to install cd eliza rm -rf node_modules bun install # If build fails bun run clean bun install bun run build ### [​](https://docs.elizaos.ai/cli-reference/monorepo#branch-not-found) Branch Not Found Copy Ask AI # List available branches git ls-remote --heads https://github.com/elizaOS/eliza # Use correct branch name elizaos monorepo --branch main [​](https://docs.elizaos.ai/cli-reference/monorepo#notes) Notes ------------------------------------------------------------------ * The destination directory must be empty or non-existent * Uses the official `elizaOS/eliza` repository from GitHub * Requires Git to be installed on your system * Internet connection required for cloning [​](https://docs.elizaos.ai/cli-reference/monorepo#related-commands) Related Commands ---------------------------------------------------------------------------------------- * [`create`](https://docs.elizaos.ai/cli-reference/create) : Create a new project or plugin from templates * [`plugins`](https://docs.elizaos.ai/cli-reference/plugins) : Manage plugins in your project * [`dev`](https://docs.elizaos.ai/cli-reference/dev) : Run development server for your projects Was this page helpful? YesNo [Publish Command](https://docs.elizaos.ai/cli-reference/publish) [TEE Command](https://docs.elizaos.ai/cli-reference/tee) ⌘I --- # Plugin Management - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/cli-reference/plugins#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Commands Plugin Management [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) * Overview * Examples * Features * Troubleshooting [​](https://docs.elizaos.ai/cli-reference/plugins#usage) Usage ----------------------------------------------------------------- Copy Ask AI elizaos plugins [options] [command] [​](https://docs.elizaos.ai/cli-reference/plugins#subcommands) Subcommands ----------------------------------------------------------------------------- | Subcommand | Aliases | Description | Arguments | Options | | --- | --- | --- | --- | --- | | `list` | `l`, `ls` | List available plugins to install into the project (shows v1.x plugins by default) | | `--all` (detailed version info), `--v0` (v0.x compatible only) | | `add` | `install` | Add a plugin to the project | `` (plugin name e.g., “abc”, “plugin-abc”, “elizaos/plugin-abc”) | `-s, --skip-env-prompt`, `--skip-verification`, `-b, --branch`, `-T, --tag` | | `installed-plugins` | | List plugins found in the project dependencies | | | | `remove` | `delete`, `del`, `rm` | Remove a plugin from the project | `` (plugin name e.g., “abc”, “plugin-abc”, “elizaos/plugin-abc”) | | | `upgrade` | | Upgrade a plugin from version 0.x to 1.x using AI-powered migration | `` (GitHub repository URL or local folder path) | `--api-key`, `--skip-tests`, `--skip-validation`, `--quiet`, `--verbose`, `--debug`, `--skip-confirmation` | | `generate` | | Generate a new plugin using AI-powered code generation | | `--api-key`, `--skip-tests`, `--skip-validation`, `--skip-prompts`, `--spec-file` | Was this page helpful? YesNo [Agent Command](https://docs.elizaos.ai/cli-reference/agent) [Test Command](https://docs.elizaos.ai/cli-reference/test) ⌘I --- # Start Command - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/cli-reference/start#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Commands Start Command [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) * Overview * Examples * Features * Troubleshooting [​](https://docs.elizaos.ai/cli-reference/start#usage) Usage --------------------------------------------------------------- Copy Ask AI elizaos start [options] [​](https://docs.elizaos.ai/cli-reference/start#options) Options ------------------------------------------------------------------- | Option | Description | | --- | --- | | `-c, --configure` | Reconfigure services and AI models | | `--character ` | Character file(s) to use | | `-p, --port ` | Port to listen on | Was this page helpful? YesNo [Create Command](https://docs.elizaos.ai/cli-reference/create) [Development Mode](https://docs.elizaos.ai/cli-reference/dev) ⌘I --- # Update Command - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/cli-reference/update#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Commands Update Command [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) * Overview * Examples * How It Works * Troubleshooting [​](https://docs.elizaos.ai/cli-reference/update#usage) Usage ---------------------------------------------------------------- Copy Ask AI elizaos update [options] [​](https://docs.elizaos.ai/cli-reference/update#options) Options -------------------------------------------------------------------- | Option | Description | | --- | --- | | `-c, --check` | Check for available updates without applying them | | `--skip-build` | Skip building after updating | | `--cli` | Update only the global CLI installation (without updating packages) | | `--packages` | Update only packages (without updating the CLI) | Was this page helpful? YesNo [Test Command](https://docs.elizaos.ai/cli-reference/test) [Publish Command](https://docs.elizaos.ai/cli-reference/publish) ⌘I --- # TEE Command - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/cli-reference/tee#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Commands TEE Command [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Overview](https://docs.elizaos.ai/cli-reference/tee#overview) * [Installation](https://docs.elizaos.ai/cli-reference/tee#installation) * [Command Structure](https://docs.elizaos.ai/cli-reference/tee#command-structure) * [Available Vendors](https://docs.elizaos.ai/cli-reference/tee#available-vendors) * [Phala Cloud](https://docs.elizaos.ai/cli-reference/tee#phala-cloud) * [Usage Examples](https://docs.elizaos.ai/cli-reference/tee#usage-examples) * [Get Phala CLI Help](https://docs.elizaos.ai/cli-reference/tee#get-phala-cli-help) * [Authentication](https://docs.elizaos.ai/cli-reference/tee#authentication) * [Managing CVMs (Confidential Virtual Machines)](https://docs.elizaos.ai/cli-reference/tee#managing-cvms-confidential-virtual-machines) * [Additional Phala Commands](https://docs.elizaos.ai/cli-reference/tee#additional-phala-commands) * [TEE Agent Deployment](https://docs.elizaos.ai/cli-reference/tee#tee-agent-deployment) * [Configuration](https://docs.elizaos.ai/cli-reference/tee#configuration) * [Prerequisites](https://docs.elizaos.ai/cli-reference/tee#prerequisites) * [Environment Variables](https://docs.elizaos.ai/cli-reference/tee#environment-variables) * [Advanced Usage](https://docs.elizaos.ai/cli-reference/tee#advanced-usage) * [Direct Phala CLI Access](https://docs.elizaos.ai/cli-reference/tee#direct-phala-cli-access) * [Troubleshooting](https://docs.elizaos.ai/cli-reference/tee#troubleshooting) * [Common Issues](https://docs.elizaos.ai/cli-reference/tee#common-issues) * [Debug Mode](https://docs.elizaos.ai/cli-reference/tee#debug-mode) * [Integration with elizaOS](https://docs.elizaos.ai/cli-reference/tee#integration-with-elizaos) * [Related Documentation](https://docs.elizaos.ai/cli-reference/tee#related-documentation) * [Security Considerations](https://docs.elizaos.ai/cli-reference/tee#security-considerations) The `tee` command provides access to Trusted Execution Environment (TEE) deployment and management capabilities through integrated vendor CLIs. [​](https://docs.elizaos.ai/cli-reference/tee#overview) Overview ------------------------------------------------------------------- TEE (Trusted Execution Environment) enables secure and verifiable agent operations on blockchain. The `tee` command currently supports Phala Cloud as a TEE provider, with the potential for additional vendors in the future. [​](https://docs.elizaos.ai/cli-reference/tee#installation) Installation --------------------------------------------------------------------------- Copy Ask AI bun install -g @elizaos/cli [​](https://docs.elizaos.ai/cli-reference/tee#command-structure) Command Structure ------------------------------------------------------------------------------------- Copy Ask AI elizaos tee [vendor-specific-commands] [​](https://docs.elizaos.ai/cli-reference/tee#available-vendors) Available Vendors ------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/cli-reference/tee#phala-cloud) Phala Cloud The `phala` subcommand provides a wrapper for the official Phala Cloud CLI, allowing you to manage TEE deployments on Phala Cloud directly through elizaOS. Copy Ask AI elizaos tee phala [phala-cli-commands] The Phala CLI will be automatically downloaded via bunx if not already installed. [​](https://docs.elizaos.ai/cli-reference/tee#usage-examples) Usage Examples ------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/cli-reference/tee#get-phala-cli-help) Get Phala CLI Help Copy Ask AI # Display Phala CLI help elizaos tee phala help # Get help for a specific Phala command elizaos tee phala cvms help ### [​](https://docs.elizaos.ai/cli-reference/tee#authentication) Authentication Copy Ask AI # Login to Phala Cloud with your API key elizaos tee phala auth login # Check authentication status elizaos tee phala auth status ### [​](https://docs.elizaos.ai/cli-reference/tee#managing-cvms-confidential-virtual-machines) Managing CVMs (Confidential Virtual Machines) Copy Ask AI # List all CVMs elizaos tee phala cvms list # Create a new CVM elizaos tee phala cvms create --name my-agent-app --compose ./docker-compose.yml # Get CVM details elizaos tee phala cvms get # Update a CVM elizaos tee phala cvms update --compose ./docker-compose.yml # Delete a CVM elizaos tee phala cvms delete ### [​](https://docs.elizaos.ai/cli-reference/tee#additional-phala-commands) Additional Phala Commands The Phala CLI also provides these additional commands: Copy Ask AI # Docker Registry Management elizaos tee phala docker login # Login to Docker Hub elizaos tee phala docker logout # Logout from Docker Hub # TEE Simulator (for local testing) elizaos tee phala simulator start # Start local TEE simulator elizaos tee phala simulator stop # Stop local TEE simulator elizaos tee phala simulator status # Check simulator status # Demo Deployment elizaos tee phala demo deploy # Deploy a demo application to Phala Cloud elizaos tee phala demo list # List deployed demos elizaos tee phala demo delete # Delete a demo deployment # Account Management elizaos tee phala join # Join Phala Cloud and get a free account elizaos tee phala free # Alias for join - get free CVM credits # Node Management elizaos tee phala nodes list # List available TEE nodes elizaos tee phala nodes get # Get details about a specific node ### [​](https://docs.elizaos.ai/cli-reference/tee#tee-agent-deployment) TEE Agent Deployment For deploying elizaOS agents to TEE environments: 1. First, create a TEE-compatible project: Copy Ask AI elizaos create my-tee-agent --type tee 2. Configure your agent and prepare deployment files 3. Deploy to Phala Cloud: Copy Ask AI elizaos tee phala cvms create --name my-tee-agent --compose ./docker-compose.yml [​](https://docs.elizaos.ai/cli-reference/tee#configuration) Configuration ----------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/cli-reference/tee#prerequisites) Prerequisites * Bun installed (required for automatic Phala CLI installation) * Phala Cloud account and API key (for deployment operations) * Docker compose file for CVM deployments ### [​](https://docs.elizaos.ai/cli-reference/tee#environment-variables) Environment Variables When deploying TEE agents, ensure your environment variables are properly configured: Copy Ask AI # Set up your Phala API key export PHALA_API_KEY="your-api-key" # Or add to your .env file echo "PHALA_API_KEY=your-api-key" >> .env [​](https://docs.elizaos.ai/cli-reference/tee#advanced-usage) Advanced Usage ------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/cli-reference/tee#direct-phala-cli-access) Direct Phala CLI Access All Phala CLI commands and options are available through the wrapper: Copy Ask AI # Any Phala CLI command can be used elizaos tee phala [any-phala-command] [options] For the complete list of Phala CLI commands and options, run: Copy Ask AI elizaos tee phala help Or visit the official Phala CLI documentation: Copy Ask AI bunx phala help [​](https://docs.elizaos.ai/cli-reference/tee#troubleshooting) Troubleshooting --------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/cli-reference/tee#common-issues) Common Issues 1. **bunx not found**: Install Bun from [bun.sh](https://bun.sh/) : Copy Ask AI curl -fsSL https://bun.sh/install | bash 2. **Authentication failures**: Ensure your API key is valid and you’re logged in: Copy Ask AI elizaos tee phala auth login 3. **Deployment errors**: Check your docker-compose.yml file is valid and all required services are defined ### [​](https://docs.elizaos.ai/cli-reference/tee#debug-mode) Debug Mode For detailed output when troubleshooting: Copy Ask AI # Run with verbose logging LOG_LEVEL=debug elizaos tee phala cvms list [​](https://docs.elizaos.ai/cli-reference/tee#integration-with-elizaos) Integration with elizaOS --------------------------------------------------------------------------------------------------- TEE deployments enable: * **Secure key management**: Private keys never leave the TEE * **Verifiable computation**: Cryptographic proof of agent behavior * **Blockchain integration**: Direct onchain operations with attestation * **Privacy preservation**: Sensitive data processing in secure enclaves [​](https://docs.elizaos.ai/cli-reference/tee#related-documentation) Related Documentation --------------------------------------------------------------------------------------------- * [Creating TEE Projects](https://docs.elizaos.ai/cli-reference/create#tee-trusted-execution-environment) * [Phala Cloud Documentation](https://docs.phala.network/) [​](https://docs.elizaos.ai/cli-reference/tee#security-considerations) Security Considerations ------------------------------------------------------------------------------------------------- When deploying agents to TEE: 1. Never commit private keys or sensitive configuration 2. Use environment variables for secrets 3. Verify attestation reports for production deployments 4. Follow Phala Cloud security best practices Was this page helpful? YesNo [Monorepo Command](https://docs.elizaos.ai/cli-reference/monorepo) ⌘I --- # Test Command - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/cli-reference/test#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Commands Test Command [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) * Overview * Examples * Writing Tests * Best Practices * Troubleshooting [​](https://docs.elizaos.ai/cli-reference/test#usage) Usage -------------------------------------------------------------- Copy Ask AI elizaos test [options] [path] [​](https://docs.elizaos.ai/cli-reference/test#arguments) Arguments ---------------------------------------------------------------------- | Argument | Description | | --- | --- | | `[path]` | Optional path to project or plugin to test | [​](https://docs.elizaos.ai/cli-reference/test#options) Options ------------------------------------------------------------------ | Option | Description | | --- | --- | | `-t, --type ` | Type of test to run (choices: “component”, “e2e”, “all”, default: “all”) | | `--port ` | Server port for e2e tests | | `--name ` | Filter tests by name (matches file names or test suite names). **Case sensitive.** | | `--skip-build` | Skip building before running tests | | `--skip-type-check` | Skip TypeScript type checking for faster test runs | Was this page helpful? YesNo [Plugin Management](https://docs.elizaos.ai/cli-reference/plugins) [Update Command](https://docs.elizaos.ai/cli-reference/update) ⌘I --- # Overview - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation GETTING STARTED Overview [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [What is elizaOS?](https://docs.elizaos.ai/#what-is-elizaos%3F) * [Key Capabilities](https://docs.elizaos.ai/#key-capabilities) * [Plugin Ecosystem](https://docs.elizaos.ai/#plugin-ecosystem) * [Design Philosophy](https://docs.elizaos.ai/#design-philosophy) [​](https://docs.elizaos.ai/#what-is-elizaos%3F) What is elizaOS? -------------------------------------------------------------------- elizaOS is a TypeScript framework for building AI agents that can think, learn, and act autonomously. Create agents with unique, persistent personalities, equip them with plugins to interact with the world, and let them work toward their goals independently. Get started with one of the quick links below, or read on to learn more about elizaOS. [Installation\ ------------](https://docs.elizaos.ai/installation) [Quickstart\ ----------](https://docs.elizaos.ai/quickstart) [What You Can Build\ ------------------](https://docs.elizaos.ai/what-you-can-build) [Deploy a Project\ ----------------](https://docs.elizaos.ai/guides/deploy-a-project) [REST Reference\ --------------](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference\ -------------](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry\ ---------------](https://docs.elizaos.ai/plugin-registry/overview) [Contribute to Core\ ------------------](https://docs.elizaos.ai/guides/contribute-to-core) [​](https://docs.elizaos.ai/#key-capabilities) Key Capabilities ------------------------------------------------------------------ With elizaOS, your agents can: * **Develop unique personalities and goals** defined through character files * **Take actions in the real world** using any combination of 90+ plugins * **Execute complex action chains** triggered by natural language * **Remember and learn** from every interaction with persistent memory * **Deploy anywhere** from local development to cloud production [​](https://docs.elizaos.ai/#plugin-ecosystem) Plugin Ecosystem ------------------------------------------------------------------ The framework ships with 90+ official plugins spanning: * **Social platforms** - Discord, Twitter, Telegram, and more * **Blockchain networks** - Ethereum, Solana, Base, and other chains * **AI providers** - OpenAI, Anthropic, OpenRouter, and local models * **DeFi protocols** - Trading, lending, yield farming * **Content creation** - Image generation, video, music * **Data analysis** - Web scraping, API integrations, databases The plugin architecture lets you mix and match capabilities without modifying core code. Your agents can trade onchain, manage social media accounts, create content, analyze data, or interact with any API, blockchain, website or repository. [​](https://docs.elizaos.ai/#design-philosophy) Design Philosophy -------------------------------------------------------------------- elizaOS is for builders who want to ship fast, experiment freely, and define tomorrow: **1\. Three Minutes to First Agent** Install, create, run. Three commands to a live agent. **2\. Built for Everyone** Start with a single character file. Scale to production systems handling millions of interactions. The framework grows with your ambitions. **3\. Truly Open Source** We build Eliza together. Every line is open source. Extend through plugins, contribute to core, share with the community. Your code becomes part of the story. Was this page helpful? YesNo [Installation](https://docs.elizaos.ai/installation) ⌘I --- # Character Interface - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/agents/character-interface#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation AGENTS Character Interface [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Overview](https://docs.elizaos.ai/agents/character-interface#overview) * [Character vs Agent](https://docs.elizaos.ai/agents/character-interface#character-vs-agent) * [Character Interface Reference](https://docs.elizaos.ai/agents/character-interface#character-interface-reference) * [Core Properties](https://docs.elizaos.ai/agents/character-interface#core-properties) * [Identity Configuration](https://docs.elizaos.ai/agents/character-interface#identity-configuration) * [Bio and Description](https://docs.elizaos.ai/agents/character-interface#bio-and-description) * [System Prompt Configuration](https://docs.elizaos.ai/agents/character-interface#system-prompt-configuration) * [Templates Object Structure](https://docs.elizaos.ai/agents/character-interface#templates-object-structure) * [Conversation Training](https://docs.elizaos.ai/agents/character-interface#conversation-training) * [Message Examples Structure](https://docs.elizaos.ai/agents/character-interface#message-examples-structure) * [Style Configuration](https://docs.elizaos.ai/agents/character-interface#style-configuration) * [Knowledge Configuration](https://docs.elizaos.ai/agents/character-interface#knowledge-configuration) * [Plugin Management](https://docs.elizaos.ai/agents/character-interface#plugin-management) * [Basic Plugin Configuration](https://docs.elizaos.ai/agents/character-interface#basic-plugin-configuration) * [Environment-Based Plugin Loading](https://docs.elizaos.ai/agents/character-interface#environment-based-plugin-loading) * [Settings and Secrets](https://docs.elizaos.ai/agents/character-interface#settings-and-secrets) * [Settings Object](https://docs.elizaos.ai/agents/character-interface#settings-object) * [Secrets Management](https://docs.elizaos.ai/agents/character-interface#secrets-management) * [Complete Production Example](https://docs.elizaos.ai/agents/character-interface#complete-production-example) * [Validation and Testing](https://docs.elizaos.ai/agents/character-interface#validation-and-testing) * [Character Validation](https://docs.elizaos.ai/agents/character-interface#character-validation) * [Testing Character Configurations](https://docs.elizaos.ai/agents/character-interface#testing-character-configurations) * [Best Practices](https://docs.elizaos.ai/agents/character-interface#best-practices) * [Migration Guide](https://docs.elizaos.ai/agents/character-interface#migration-guide) * [From JSON to TypeScript](https://docs.elizaos.ai/agents/character-interface#from-json-to-typescript) * [See Also](https://docs.elizaos.ai/agents/character-interface#see-also) [​](https://docs.elizaos.ai/agents/character-interface#overview) Overview ---------------------------------------------------------------------------- In elizaOS, the distinction between a **Character** and an **Agent** is fundamental: * **Character**: A configuration object that defines an agent’s personality, capabilities, and settings * **Agent**: A runtime instance created from a Character, with additional status tracking and lifecycle management Think of a Character as a blueprint and an Agent as the living instance built from that blueprint. For hands-on implementation, see [Customize an Agent](https://docs.elizaos.ai/guides/customize-an-agent) . For runtime details, see [Runtime and Lifecycle](https://docs.elizaos.ai/agents/runtime-and-lifecycle) . [​](https://docs.elizaos.ai/agents/character-interface#character-vs-agent) Character vs Agent ------------------------------------------------------------------------------------------------ The transformation from Character to Agent happens at runtime: Copy Ask AI // Character: Static configuration interface Character { name: string; bio: string | string[]; // ... configuration properties } // Agent: Runtime instance with status interface Agent extends Character { enabled?: boolean; status?: 'active' | 'inactive'; createdAt: number; updatedAt: number; } [​](https://docs.elizaos.ai/agents/character-interface#character-interface-reference) Character Interface Reference ---------------------------------------------------------------------------------------------------------------------- The complete TypeScript interface for agents: | Property | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | ✅ | Agent’s display name | | `bio` | string \| string\[\] | ✅ | Background/personality description | | `id` | UUID | ❌ | Unique identifier (auto-generated if not provided) | | `username` | string | ❌ | Social media username | | `system` | string | ❌ | System prompt override | | `templates` | object | ❌ | Custom prompt templates | | `adjectives` | string\[\] | ❌ | Character traits (e.g., “helpful”, “creative”) | | `topics` | string\[\] | ❌ | Conversation topics the agent knows | | `knowledge` | array | ❌ | Facts, files, or directories of knowledge | | `messageExamples` | array\[\]\[\] | ❌ | Example conversations (2D array) | | `postExamples` | string\[\] | ❌ | Example social media posts | | `style` | object | ❌ | Writing style for different contexts | | `plugins` | string\[\] | ❌ | Enabled plugin packages | | `settings` | object | ❌ | Configuration values | | `secrets` | object | ❌ | Sensitive configuration | [​](https://docs.elizaos.ai/agents/character-interface#core-properties) Core Properties ------------------------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/agents/character-interface#identity-configuration) Identity Configuration The fundamental properties that define who your agent is: Copy Ask AI export const character: Character = { // Required: The agent's display name name: "TechHelper", // Optional: Username for social platforms username: "tech_helper_bot", // Optional: Unique ID (auto-generated from name if not provided) id: "550e8400-e29b-41d4-a716-446655440000", } ### [​](https://docs.elizaos.ai/agents/character-interface#bio-and-description) Bio and Description The bio can be a single string or an array of strings for better organization: Copy Ask AI // Single string format bio: "A helpful AI assistant specializing in technical support and programming guidance." // Array format (recommended for complex bios) bio: [\ "Expert in web development and open source technologies",\ "Specializes in TypeScript, React, and Node.js",\ "Helps developers debug issues and learn best practices",\ "Friendly and patient teaching style"\ ] ### [​](https://docs.elizaos.ai/agents/character-interface#system-prompt-configuration) System Prompt Configuration Override the default system prompt to fine-tune agent behavior: Copy Ask AI system: `You are a technical support specialist. Always: - Provide code examples when relevant - Explain technical concepts clearly - Be encouraging to learners - Admit when you don't know something Never: - Be condescending or dismissive - Assume prior knowledge without checking - Provide outdated or deprecated solutions` ### [​](https://docs.elizaos.ai/agents/character-interface#templates-object-structure) Templates Object Structure Custom prompt templates for various agent operations: Copy Ask AI templates?: { // Define custom templates for different contexts messageTemplate?: string | ((params: any) => string); thoughtTemplate?: string | ((params: any) => string); actionTemplate?: string | ((params: any) => string); // Add any custom template keys your plugins need [key: string]: string | ((params: any) => string); } [​](https://docs.elizaos.ai/agents/character-interface#conversation-training) Conversation Training ------------------------------------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/agents/character-interface#message-examples-structure) Message Examples Structure Message examples train the agent’s conversational style using a 2D array format: Copy Ask AI messageExamples: [\ // Each sub-array is a complete conversation\ [\ {\ name: "{{user}}",\ content: { text: "Can you help me debug this React error?" }\ },\ {\ name: "TechHelper",\ content: { \ text: "I'd be happy to help! Can you share the error message and the relevant code?"\ }\ },\ {\ name: "{{user}}",\ content: { text: "It says 'Cannot read property of undefined'" }\ },\ {\ name: "TechHelper",\ content: { \ text: "This error typically occurs when trying to access a property on a null or undefined object. Let's trace through your code to find where this might be happening. Can you show me the component where this error occurs?"\ }\ }\ ],\ // Another conversation example\ [\ {\ name: "{{user}}",\ content: { text: "What's the difference between let and const?" }\ },\ {\ name: "TechHelper",\ content: { \ text: "`const` declares a variable that cannot be reassigned, while `let` allows reassignment. For example:\n```js\nconst x = 1;\nx = 2; // Error!\n\nlet y = 1;\ny = 2; // Works fine\n```\nNote that `const` objects can still have their properties modified."\ }\ }\ ]\ ] ### [​](https://docs.elizaos.ai/agents/character-interface#style-configuration) Style Configuration Define writing styles for different contexts: Copy Ask AI style: { // General style rules applied everywhere all: [\ "Be concise and clear",\ "Use technical terms accurately",\ "Provide examples when helpful"\ ], // Chat-specific style chat: [\ "Be conversational and friendly",\ "Ask clarifying questions",\ "Break down complex topics"\ ], // Social media post style post: [\ "Keep it under 280 characters when possible",\ "Use relevant hashtags",\ "Be engaging and informative"\ ] } [​](https://docs.elizaos.ai/agents/character-interface#knowledge-configuration) Knowledge Configuration ---------------------------------------------------------------------------------------------------------- Configure the agent’s knowledge base: Copy Ask AI knowledge: [\ // Simple string facts\ "I specialize in TypeScript and React",\ "I can help with debugging and code reviews",\ \ // File reference\ {\ path: "./knowledge/react-best-practices.md",\ shared: true // Available to all agents\ },\ \ // Directory of knowledge files\ {\ directory: "./knowledge/tutorials",\ shared: false // Only for this agent\ }\ ] [​](https://docs.elizaos.ai/agents/character-interface#plugin-management) Plugin Management ---------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/character-interface#basic-plugin-configuration) Basic Plugin Configuration Copy Ask AI plugins: [\ "@elizaos/plugin-bootstrap", // Core functionality\ "@elizaos/plugin-discord", // Discord integration\ "@elizaos/plugin-openai", // OpenAI models\ "./custom-plugins/my-plugin" // Local plugin\ ] ### [​](https://docs.elizaos.ai/agents/character-interface#environment-based-plugin-loading) Environment-Based Plugin Loading Load plugins conditionally based on environment variables: Copy Ask AI plugins: [\ // Always loaded\ "@elizaos/plugin-bootstrap",\ "@elizaos/plugin-sql",\ \ // Conditionally loaded based on API keys\ ...(process.env.OPENAI_API_KEY ? ["@elizaos/plugin-openai"] : []),\ ...(process.env.ANTHROPIC_API_KEY ? ["@elizaos/plugin-anthropic"] : []),\ \ // Platform plugins\ ...(process.env.DISCORD_API_TOKEN ? ["@elizaos/plugin-discord"] : []),\ ...(process.env.TELEGRAM_BOT_TOKEN ? ["@elizaos/plugin-telegram"] : []),\ \ // Feature flags\ ...(process.env.ENABLE_VOICE ? ["@elizaos/plugin-voice"] : []),\ ] [​](https://docs.elizaos.ai/agents/character-interface#settings-and-secrets) Settings and Secrets ---------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/character-interface#settings-object) Settings Object General configuration values: Copy Ask AI settings: { // Model configuration model: "gpt-4", temperature: 0.7, maxTokens: 2000, // Behavior settings responseTimeout: 30000, maxMemorySize: 1000, // Custom settings for plugins voiceEnabled: true, avatar: "https://example.com/avatar.png" } ### [​](https://docs.elizaos.ai/agents/character-interface#secrets-management) Secrets Management Sensitive data that should never be committed: Copy Ask AI secrets: { // API keys OPENAI_API_KEY: process.env.OPENAI_API_KEY, DATABASE_URL: process.env.DATABASE_URL, // OAuth tokens DISCORD_TOKEN: process.env.DISCORD_TOKEN, // Encryption keys ENCRYPTION_KEY: process.env.ENCRYPTION_KEY } [​](https://docs.elizaos.ai/agents/character-interface#complete-production-example) Complete Production Example ------------------------------------------------------------------------------------------------------------------ Here’s a comprehensive character configuration for production use: Copy Ask AI import { Character } from '@elizaos/core'; export const character: Character = { name: 'Eliza', username: 'eliza_ai', bio: [\ "An advanced AI assistant powered by elizaOS",\ "Specializes in technical support and creative problem-solving",\ "Continuously learning and adapting to user needs",\ "Built with privacy and security in mind"\ ], system: `You are Eliza, a helpful and knowledgeable AI assistant. Core principles: - Be helpful, harmless, and honest - Provide accurate, well-researched information - Admit uncertainty when appropriate - Respect user privacy and boundaries - Adapt your communication style to the user's needs`, adjectives: [\ "helpful",\ "knowledgeable", \ "patient",\ "creative",\ "professional"\ ], topics: [\ "programming",\ "web development",\ "artificial intelligence",\ "problem solving",\ "technology trends"\ ], messageExamples: [\ [\ {\ name: "{{user}}",\ content: { text: "Hello!" }\ },\ {\ name: "Eliza",\ content: { \ text: "Hello! I'm Eliza, your AI assistant. How can I help you today?"\ }\ }\ ],\ [\ {\ name: "{{user}}",\ content: { text: "Can you help me with a coding problem?" }\ },\ {\ name: "Eliza",\ content: { \ text: "Of course! I'd be happy to help with your coding problem. Please share the details - what language are you using, what are you trying to achieve, and what specific issue are you encountering?"\ }\ }\ ]\ ], postExamples: [\ "🚀 Just discovered an elegant solution to the N+1 query problem in GraphQL. DataLoader is a game-changer! #GraphQL #WebDev",\ "Reminder: Clean code is not about being clever, it's about being clear. Your future self will thank you. 📝 #CodingBestPractices",\ "The best error message is the one that tells you exactly what went wrong AND how to fix it. 🔧 #DeveloperExperience"\ ], style: { all: [\ "Be concise but comprehensive",\ "Use emoji sparingly and appropriately",\ "Maintain a professional yet approachable tone"\ ], chat: [\ "Be conversational and engaging",\ "Show genuine interest in helping",\ "Use markdown for code and formatting"\ ], post: [\ "Be informative and thought-provoking",\ "Include relevant hashtags",\ "Keep within platform character limits"\ ] }, knowledge: [\ "I'm built on the elizaOS framework",\ "I can integrate with multiple platforms simultaneously",\ "I maintain context across conversations",\ {\ path: "./knowledge/technical-docs",\ shared: true\ }\ ], plugins: [\ '@elizaos/plugin-sql',\ '@elizaos/plugin-bootstrap',\ ...(process.env.ANTHROPIC_API_KEY ? ['@elizaos/plugin-anthropic'] : []),\ ...(process.env.OPENAI_API_KEY ? ['@elizaos/plugin-openai'] : []),\ ...(process.env.DISCORD_API_TOKEN ? ['@elizaos/plugin-discord'] : []),\ ...(process.env.TELEGRAM_BOT_TOKEN ? ['@elizaos/plugin-telegram'] : []),\ ], settings: { secrets: {}, // Populated from environment avatar: 'https://elizaos.github.io/eliza-avatars/eliza.png', model: 'gpt-4', temperature: 0.7, maxTokens: 2000, memoryLimit: 1000, conversationLength: 32 } }; [​](https://docs.elizaos.ai/agents/character-interface#validation-and-testing) Validation and Testing -------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/character-interface#character-validation) Character Validation Use the built-in validation to ensure your character is properly configured: Copy Ask AI import { validateCharacter } from '@elizaos/core'; const validation = validateCharacter(character); if (!validation.valid) { console.error('Character validation failed:', validation.errors); } ### [​](https://docs.elizaos.ai/agents/character-interface#testing-character-configurations) Testing Character Configurations Copy Ask AI import { describe, it, expect } from 'vitest'; import { character } from './character'; describe('Character Configuration', () => { it('should have required fields', () => { expect(character.name).toBeDefined(); expect(character.bio).toBeDefined(); }); it('should have valid message examples', () => { expect(character.messageExamples).toBeInstanceOf(Array); character.messageExamples?.forEach(conversation => { expect(conversation).toBeInstanceOf(Array); conversation.forEach(message => { expect(message).toHaveProperty('name'); expect(message).toHaveProperty('content'); }); }); }); it('should have environment-appropriate plugins', () => { if (process.env.OPENAI_API_KEY) { expect(character.plugins).toContain('@elizaos/plugin-openai'); } }); }); [​](https://docs.elizaos.ai/agents/character-interface#best-practices) Best Practices ---------------------------------------------------------------------------------------- 1. **Keep personality traits consistent**: Ensure bio, adjectives, and style align 2. **Provide diverse message examples**: Cover various interaction patterns 3. **Use TypeScript for type safety**: Leverage type checking for configuration 4. **Load plugins conditionally**: Check for API keys before loading 5. **Order plugins by dependency**: Load core plugins before dependent ones 6. **Use environment variables for secrets**: Never hardcode sensitive data 7. **Validate before deployment**: Always validate character configuration 8. **Test conversation flows**: Ensure message examples produce desired behavior 9. **Document custom settings**: Clearly explain any custom configuration 10. **Version your characters**: Track changes to character configurations [​](https://docs.elizaos.ai/agents/character-interface#migration-guide) Migration Guide ------------------------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/agents/character-interface#from-json-to-typescript) From JSON to TypeScript Converting a JSON character to TypeScript: Copy Ask AI // Before: character.json { "name": "MyAgent", "bio": "An AI assistant" } // After: character.ts import { Character } from '@elizaos/core'; export const character: Character = { name: "MyAgent", bio: "An AI assistant" }; [​](https://docs.elizaos.ai/agents/character-interface#see-also) See Also ---------------------------------------------------------------------------- [Personality & Behavior\ ----------------------\ \ Learn to craft unique agent personalities](https://docs.elizaos.ai/agents/personality-and-behavior) [Memory & State\ --------------\ \ Understand how agents remember and learn](https://docs.elizaos.ai/agents/memory-and-state) [Runtime & Lifecycle\ -------------------\ \ See how characters become live agents](https://docs.elizaos.ai/agents/runtime-and-lifecycle) [Plugin Development\ ------------------\ \ Extend your agent with custom plugins](https://docs.elizaos.ai/plugins/development) Was this page helpful? YesNo [Environment Variables](https://docs.elizaos.ai/projects/environment-variables) [Personality and Behavior](https://docs.elizaos.ai/agents/personality-and-behavior) ⌘I --- # Contribute to Core - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/guides/contribute-to-core#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation GUIDES Contribute to Core [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Understanding the Ecosystem](https://docs.elizaos.ai/guides/contribute-to-core#understanding-the-ecosystem) * [Main Repository (Monorepo)](https://docs.elizaos.ai/guides/contribute-to-core#main-repository-monorepo) * [Plugin Ecosystem](https://docs.elizaos.ai/guides/contribute-to-core#plugin-ecosystem) * [Step 1: Identify an Issue](https://docs.elizaos.ai/guides/contribute-to-core#step-1%3A-identify-an-issue) * [Check Main Repository Issues](https://docs.elizaos.ai/guides/contribute-to-core#check-main-repository-issues) * [elizaOS-Maintained Plugin Issues](https://docs.elizaos.ai/guides/contribute-to-core#elizaos-maintained-plugin-issues) * [Community Plugin Issues](https://docs.elizaos.ai/guides/contribute-to-core#community-plugin-issues) * [Creating Issues for New Bugs](https://docs.elizaos.ai/guides/contribute-to-core#creating-issues-for-new-bugs) * [Contribute to Docs and Community](https://docs.elizaos.ai/guides/contribute-to-core#contribute-to-docs-and-community) * [Step 2: Contribution Workflow](https://docs.elizaos.ai/guides/contribute-to-core#step-2%3A-contribution-workflow) * [Clone and Set Up Repository](https://docs.elizaos.ai/guides/contribute-to-core#clone-and-set-up-repository) * [Make Your Changes Locally](https://docs.elizaos.ai/guides/contribute-to-core#make-your-changes-locally) * [Submit Your Pull Request](https://docs.elizaos.ai/guides/contribute-to-core#submit-your-pull-request) * [Collaborate During Review](https://docs.elizaos.ai/guides/contribute-to-core#collaborate-during-review) * [Code Quality Standards](https://docs.elizaos.ai/guides/contribute-to-core#code-quality-standards) * [Step 3: Get Connected](https://docs.elizaos.ai/guides/contribute-to-core#step-3%3A-get-connected) * [Join Discord for Development](https://docs.elizaos.ai/guides/contribute-to-core#join-discord-for-development) * [Communicate Before Major Work](https://docs.elizaos.ai/guides/contribute-to-core#communicate-before-major-work) * [Build Community Connections](https://docs.elizaos.ai/guides/contribute-to-core#build-community-connections) * [See Also](https://docs.elizaos.ai/guides/contribute-to-core#see-also) This guide covers contributing to the main elizaOS monorepo and the elizaOS plugin ecosystem. [​](https://docs.elizaos.ai/guides/contribute-to-core#understanding-the-ecosystem) Understanding the Ecosystem ----------------------------------------------------------------------------------------------------------------- elizaOS open source contribution happens across these main areas: ### [​](https://docs.elizaos.ai/guides/contribute-to-core#main-repository-monorepo) Main Repository (Monorepo) **[github.com/elizaos/eliza](https://github.com/elizaos/eliza) ** - The core monorepo containing: * `packages/core` - Runtime, types, interfaces * `packages/cli` - Command-line tools and elizaos CLI * `packages/server` - Agent server implementation * `packages/client` - Client libraries and interfaces * Core plugins (`packages/plugin-bootstrap`, `packages/plugin-sql`, etc.) * Project templates (`packages/project-starter`, `packages/project-tee-starter`) * Plugin templates (`packages/plugin-starter`, `packages/plugin-quick-starter`) * Config files, READMEs & more ### [​](https://docs.elizaos.ai/guides/contribute-to-core#plugin-ecosystem) Plugin Ecosystem **[github.com/elizaos-plugins](https://github.com/elizaos-plugins) ** - Official plugins maintained by the elizaOS team: * `plugin-discord` - Discord integration * `plugin-twitter` - Twitter/X integration * `plugin-evm` - Ethereum and blockchain functionality * And many more frequently-used plugins * * * [​](https://docs.elizaos.ai/guides/contribute-to-core#step-1%3A-identify-an-issue) Step 1: Identify an Issue --------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/guides/contribute-to-core#check-main-repository-issues) Check Main Repository Issues **Start here first** - Browse existing bugs in the main repo: **[elizaos/eliza/issues](https://github.com/elizaos/eliza/issues) ** Focus on labels like: * `good first issue` - Perfect for newcomers * `bug` - Something that needs fixing The best way to start contributing is fixing reported bugs rather than writing new features. ### [​](https://docs.elizaos.ai/guides/contribute-to-core#elizaos-maintained-plugin-issues) elizaOS-Maintained Plugin Issues Find issues in elizaOS-maintained plugins (often more focused for first contributions): **Official elizaOS plugins:** * [plugin-twitter/issues](https://github.com/elizaos-plugins/plugin-twitter/issues) * [plugin-discord/issues](https://github.com/elizaos-plugins/plugin-discord/issues) * [plugin-evm/issues](https://github.com/elizaos-plugins/plugin-evm/issues) ### [​](https://docs.elizaos.ai/guides/contribute-to-core#community-plugin-issues) Community Plugin Issues **Community plugins are separate** - These are built by the community: * Browse the [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) for community-maintained plugins * Check their GitHub repositories for contribution opportunities * Help with maintenance: updating dependencies, fixing bugs, improving docs * Consider adopting unmaintained plugins by forking and continuing development ### [​](https://docs.elizaos.ai/guides/contribute-to-core#creating-issues-for-new-bugs) Creating Issues for New Bugs If you discover a bug without an existing issue: 1. **Reproduce the bug** consistently & locally 2. **Check if it’s already reported** by searching existing issues 3. **Create a detailed issue** with: * Clear description of the problem * Steps to reproduce * Expected vs actual behavior * Environment details (OS, Node/Bun version, elizaOS version) * Error messages or logs Issue Template Example Copy Ask AI ## Bug Description The Discord plugin fails to connect when using voice channels ## Steps to Reproduce 1. Configure agent with Discord and ElevenLabs plugins 2. Invite agent to voice channel 3. Agent connects but immediately disconnects ## Expected Behavior Agent should remain connected and respond with voice ## Environment - elizaOS version: 1.4.4 - Node version: 23.3 - OS: macOS 14.0 ### [​](https://docs.elizaos.ai/guides/contribute-to-core#contribute-to-docs-and-community) Contribute to Docs and Community Beyond code contributions, you can help in these important areas: **Documentation contributions:** * Add tutorials to the tutorials section in [docs repository](https://github.com/elizaos/docs) * Update any outdated references, instructions, or broken links you find * Fix typos, improve clarity, or add missing examples **Community support:** * **Answer questions** in [GitHub Discussions](https://github.com/orgs/elizaOS/discussions) Q&A section * **Help with troubleshooting** - Setup issues, configuration problems, etc. * **Share knowledge** in general discussions about elizaOS development * **Showcase projects** in show and tell or participate in feature discussions Community contributions like answering questions and writing tutorials are often the most impactful ways to help other developers succeed with elizaOS. * * * [​](https://docs.elizaos.ai/guides/contribute-to-core#step-2%3A-contribution-workflow) Step 2: Contribution Workflow ----------------------------------------------------------------------------------------------------------------------- elizaOS follows standard open source contribution practices for all repositories. ### [​](https://docs.elizaos.ai/guides/contribute-to-core#clone-and-set-up-repository) Clone and Set Up Repository 1. **Clone the repository** you want to contribute to on your local machine 2. **Create a branch** off the `develop` branch for monorepo or `1.x` branch for plugins 3. **Install dependencies** and build the project ### [​](https://docs.elizaos.ai/guides/contribute-to-core#make-your-changes-locally) Make Your Changes Locally **Focus on these types of contributions:** * Fix existing functionality that isn’t working * Improve error handling and edge cases * Performance optimizations * Documentation corrections Large refactors are unlikely to be accepted. Focus on incremental improvements and bug fixes first. Always discuss major architectural changes with core developers before starting work. **Implementation steps:** 1. **Make your changes** to fix the bug or implement the improvement 2. **Test your changes** thoroughly - run existing tests and add new ones if needed 3. **Ensure code quality** - follow linting rules and TypeScript requirements ### [​](https://docs.elizaos.ai/guides/contribute-to-core#submit-your-pull-request) Submit Your Pull Request **Target the correct branch:** * **Main repository (elizaos/eliza):** Target `develop` branch * **Plugin repositories:** Target `1.x` branch (or check the default branch) **Create a detailed pull request** with: * Clear description of what the PR does * Link to the related issue (`Fixes #123`) * List of specific changes made * Check that CI/GitHub Actions are passing * Screenshots if there are UI changes ### [​](https://docs.elizaos.ai/guides/contribute-to-core#collaborate-during-review) Collaborate During Review * Respond to code review comments promptly * Make requested changes in additional commits * Be open to feedback and iteration ### [​](https://docs.elizaos.ai/guides/contribute-to-core#code-quality-standards) Code Quality Standards **What we look for:** * Bug fixes with clear reproduction steps * Performance improvements with benchmarks * Documentation improvements and corrections * Test coverage improvements * Security fixes **Technical requirements:** * **TypeScript**: All code must be properly typed * **Testing**: New features require tests, bug fixes should include regression tests * **Documentation**: Update relevant documentation for any user-facing changes * **Linting**: Code must pass all linting checks * **Commit Messages**: Use clear, descriptive commit messages * * * [​](https://docs.elizaos.ai/guides/contribute-to-core#step-3%3A-get-connected) Step 3: Get Connected ------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/guides/contribute-to-core#join-discord-for-development) Join Discord for Development Connect with core developers and other contributors: **[Join elizaOS Discord](https://discord.gg/ai16z) ** Key channels for contributors: * **💬 #coders** - Development discussions and questions * **💻 #tech-support** - Help others troubleshoot and get help yourself ### [​](https://docs.elizaos.ai/guides/contribute-to-core#communicate-before-major-work) Communicate Before Major Work For significant contributions: 1. **Post in 💬 #coders** about your planned contribution 2. **Share your approach** before implementing large features 3. **Ask questions** - the community is helpful and welcoming Core developers are active in Discord and can provide guidance on whether your planned contribution aligns with project goals. ### [​](https://docs.elizaos.ai/guides/contribute-to-core#build-community-connections) Build Community Connections * Participate in discussions and help answer questions * Share your progress and learn from others * Connect with the core devs & other community contributors * Stay updated on project direction and roadmap * * * [​](https://docs.elizaos.ai/guides/contribute-to-core#see-also) See Also --------------------------------------------------------------------------- [Create a Plugin\ ---------------\ \ Build your own plugins to contribute to the ecosystem](https://docs.elizaos.ai/guides/create-a-plugin) [CLI Reference\ -------------\ \ Master the development tools for efficient contribution](https://docs.elizaos.ai/cli-reference/overview) [Test a Project\ --------------\ \ Learn comprehensive testing strategies for your contributions](https://docs.elizaos.ai/guides/test-a-project) [Join Discord\ ------------\ \ Connect with core developers and the contributor community](https://discord.gg/ai16z) Was this page helpful? YesNo [Publish a Plugin](https://docs.elizaos.ai/guides/publish-a-plugin) [Overview](https://docs.elizaos.ai/projects/overview) ⌘I --- # Add Multiple Agents - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/guides/add-multiple-agents#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation GUIDES Add Multiple Agents [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Step 1: Add Hemingway](https://docs.elizaos.ai/guides/add-multiple-agents#step-1%3A-add-hemingway) * [Add Hemingway to your project](https://docs.elizaos.ai/guides/add-multiple-agents#add-hemingway-to-your-project) * [Customize Hemingway’s personality](https://docs.elizaos.ai/guides/add-multiple-agents#customize-hemingway%E2%80%99s-personality) * [Step 2: Configure Discord and voice](https://docs.elizaos.ai/guides/add-multiple-agents#step-2%3A-configure-discord-and-voice) * [Add Discord plugin to Hemingway](https://docs.elizaos.ai/guides/add-multiple-agents#add-discord-plugin-to-hemingway) * [Configure agent-specific keys](https://docs.elizaos.ai/guides/add-multiple-agents#configure-agent-specific-keys) * [Enable voice mode](https://docs.elizaos.ai/guides/add-multiple-agents#enable-voice-mode) * [Add ElevenLabs voice provider](https://docs.elizaos.ai/guides/add-multiple-agents#add-elevenlabs-voice-provider) * [Configure voices for each agent](https://docs.elizaos.ai/guides/add-multiple-agents#configure-voices-for-each-agent) * [Step 3: Configure multi-agent project](https://docs.elizaos.ai/guides/add-multiple-agents#step-3%3A-configure-multi-agent-project) * [Add newly created agent to your project](https://docs.elizaos.ai/guides/add-multiple-agents#add-newly-created-agent-to-your-project) * [Launch both agents simultaneously](https://docs.elizaos.ai/guides/add-multiple-agents#launch-both-agents-simultaneously) * [Join them in Discord voice chat](https://docs.elizaos.ai/guides/add-multiple-agents#join-them-in-discord-voice-chat) * [See Also](https://docs.elizaos.ai/guides/add-multiple-agents#see-also) **Video Tutorial**: [**Multiple Agents and Characters**](https://www.youtube.com/watch?v=T53M7KueDgM&list=PLrjBjP4nU8ehOgKAa0-XddHzE0KK0nNvS&index=3) This guide builds on concepts from [Customize an Agent](https://docs.elizaos.ai/guides/customize-an-agent) [​](https://docs.elizaos.ai/guides/add-multiple-agents#step-1%3A-add-hemingway) Step 1: Add Hemingway -------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/guides/add-multiple-agents#add-hemingway-to-your-project) Add Hemingway to your project You already have Shakespeare in `src/character.ts` from the previous guide. Now let’s add another agent to our project so they can interact. We’ll create a fresh character file for Hemingway using the CLI: Terminal Copy Ask AI elizaos create --type agent hemingway This clones a JSON character template as `hemingway.json`. You’ll now have: * `src/character.ts` - Shakespeare (TypeScript format) * `hemingway.json` - Hemingway (JSON format) The CLI clones JSON character templates by default. If you prefer TypeScript characters, you can manually clone your `character.ts` file from your IDE. They work exactly the same, it’s just a matter of preference. ### [​](https://docs.elizaos.ai/guides/add-multiple-agents#customize-hemingway%E2%80%99s-personality) Customize Hemingway’s personality Open `hemingway.json` and update it to customize Hemingway’s personality: hemingway.json Copy Ask AI { "name": "hemingway", "system": "Respond to all messages in a helpful, conversational manner. Provide assistance on a wide range of topics, using knowledge when needed. Be concise but thorough, friendly but professional. Use humor when appropriate and be empathetic to user needs. Provide valuable information and insights when questions are asked.", "system": "You are Ernest Hemingway. Speak simply. Use short sentences. Cut the fat. Every word must earn its place. You respect Shakespeare but find him wordy. You've lived through war, love, and loss. Truth matters more than beauty. Experience matters more than theory. Never use two words when one will do. Avoid adjectives. Kill your darlings. The first draft of anything is shit, so make every word count now.", "bio": [\ "hemingway is a helpful AI assistant created to provide assistance and engage in meaningful conversations.", \ "hemingway is knowledgeable, creative, and always eager to help users with their questions and tasks."\ "Ernest Hemingway, American novelist and journalist", \ "Master of the iceberg theory - show only what matters", \ "Champion of simple declarative sentences", \ "War correspondent who saw truth in trenches", \ "Believer that courage is grace under pressure", \ "Man who lived fully - bullfights, safaris, deep-sea fishing", \ "Writer who found truth in simple things", \ "Teacher who says: write one true sentence"\ ] } Just like in the [previous guide](https://docs.elizaos.ai/guides/customize-an-agent) , continue editing the other fields (`topics`, `style`, `messageExamples`, etc.) to match Hemingway as you see fit. [​](https://docs.elizaos.ai/guides/add-multiple-agents#step-2%3A-configure-discord-and-voice) Step 2: Configure Discord and voice ------------------------------------------------------------------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/guides/add-multiple-agents#add-discord-plugin-to-hemingway) Add Discord plugin to Hemingway Add `plugin-discord` to Hemingway so he can join Shakespeare in our Discord server: hemingway.json Copy Ask AI { "plugins": [\ "@elizaos/plugin-sql",\ "@elizaos/plugin-openai",\ "@elizaos/plugin-bootstrap",\ "@elizaos/plugin-discord"\ ] } ### [​](https://docs.elizaos.ai/guides/add-multiple-agents#configure-agent-specific-keys) Configure agent-specific keys But wait! We have our Discord environment variables defined in `.env`, but we need unique ones for each agent. Hemingway and Shakespeare need their own Discord bot tokens. How do we have agent-specific keys? For that, we use `secrets` under `settings` in each character file. This allows each agent to have their own Discord bot identity: **For Hemingway (`hemingway.json`):** hemingway.json Copy Ask AI { "settings": { "secrets": {}, "secrets": { "DISCORD_APPLICATION_ID": "YOUR_HEMINGWAY_APP_ID", "DISCORD_API_TOKEN": "YOUR_HEMINGWAY_BOT_TOKEN", }, "avatar": "https://example.com/hemingway-portrait.png" } } **For Shakespeare (`src/character.ts`):** src/character.ts Copy Ask AI export const character: Character = { settings: { secrets: {}, secrets: { DISCORD_APPLICATION_ID: "YOUR_SHAKESPEARE_APP_ID", DISCORD_API_TOKEN: "YOUR_SHAKESPEARE_BOT_TOKEN", }, avatar: 'https://example.com/shakespeare-portrait.png', }, } Each agent needs its own Discord application and bot token. Follow the Discord setup steps from the [previous guide](https://docs.elizaos.ai/guides/customize-an-agent#create-discord-application) for each agent you create. ### [​](https://docs.elizaos.ai/guides/add-multiple-agents#enable-voice-mode) Enable voice mode Let’s enable voice capabilities for our agents in Discord: **For Hemingway (`hemingway.json`):** hemingway.json Copy Ask AI { "settings": { "secrets": { "DISCORD_APPLICATION_ID": "YOUR_HEMINGWAY_APP_ID", "DISCORD_API_TOKEN": "YOUR_HEMINGWAY_BOT_TOKEN", "DISCORD_VOICE_ENABLED": "true" } } } **For Shakespeare (`src/character.ts`):** src/character.ts Copy Ask AI { settings: { secrets: { DISCORD_APPLICATION_ID: "YOUR_SHAKESPEARE_APP_ID", DISCORD_API_TOKEN: "YOUR_SHAKESPEARE_BOT_TOKEN", DISCORD_VOICE_ENABLED: "true" } } } ### [​](https://docs.elizaos.ai/guides/add-multiple-agents#add-elevenlabs-voice-provider) Add ElevenLabs voice provider Now let’s add `plugin-elevenlabs` to provide high-quality voice synthesis for our agents: **Add ElevenLabs plugin:** hemingway.json Copy Ask AI { "plugins": [\ "@elizaos/plugin-sql",\ "@elizaos/plugin-openai",\ "@elizaos/plugin-discord",\ "@elizaos/plugin-bootstrap",\ "@elizaos/plugin-elevenlabs"\ ] } src/character.ts Copy Ask AI export const character: Character = { plugins: [\ '@elizaos/plugin-sql',\ '@elizaos/plugin-discord',\ '@elizaos/plugin-elevenlabs', \ ...(process.env.OPENAI_API_KEY?.trim() ? ['@elizaos/plugin-openai'] : []),\ ...(!process.env.IGNORE_BOOTSTRAP ? ['@elizaos/plugin-bootstrap'] : []),\ ], } ### [​](https://docs.elizaos.ai/guides/add-multiple-agents#configure-voices-for-each-agent) Configure voices for each agent Now let’s add the ElevenLabs secrets so each agent has their own distinct voice: **For Hemingway (`hemingway.json`):** hemingway.json Copy Ask AI { "settings": { "secrets": { "DISCORD_APPLICATION_ID": "YOUR_HEMINGWAY_APP_ID", "DISCORD_API_TOKEN": "YOUR_HEMINGWAY_BOT_TOKEN", "DISCORD_VOICE_ENABLED": "true", "ELEVENLABS_API_KEY": "your_elevenlabs_api_key", "ELEVENLABS_VOICE_ID": "Xb7hH8MSUJpSbSDYk0k2", // Deep male voice "ELEVENLABS_MODEL_ID": "eleven_multilingual_v2", "ELEVENLABS_VOICE_STABILITY": "0.5", "ELEVENLABS_OPTIMIZE_STREAMING_LATENCY": "0", "ELEVENLABS_OUTPUT_FORMAT": "pcm_16000", "ELEVENLABS_VOICE_SIMILARITY_BOOST": "0.75", "ELEVENLABS_VOICE_STYLE": "0", "ELEVENLABS_VOICE_USE_SPEAKER_BOOST": "true" } } } **For Shakespeare (`src/character.ts`):** src/character.ts Copy Ask AI { settings: { secrets: { DISCORD_APPLICATION_ID: "YOUR_SHAKESPEARE_APP_ID", DISCORD_API_TOKEN: "YOUR_SHAKESPEARE_BOT_TOKEN", DISCORD_VOICE_ENABLED: "true", ELEVENLABS_API_KEY: "your_elevenlabs_api_key", ELEVENLABS_VOICE_ID: "21m00Tcm4TlvDq8ikWAM", // Theatrical British voice ELEVENLABS_MODEL_ID: "eleven_multilingual_v2", ELEVENLABS_VOICE_STABILITY: "0.3", // More variation for dramatic effect ELEVENLABS_OPTIMIZE_STREAMING_LATENCY: "0", ELEVENLABS_OUTPUT_FORMAT: "pcm_16000", ELEVENLABS_VOICE_SIMILARITY_BOOST: "0.75", ELEVENLABS_VOICE_STYLE: "0.5", // More expressive ELEVENLABS_VOICE_USE_SPEAKER_BOOST: "true" } } } Get your ElevenLabs API key from [elevenlabs.io](https://elevenlabs.io/) and explore different voice IDs to find the perfect match for each agent’s personality. [​](https://docs.elizaos.ai/guides/add-multiple-agents#step-3%3A-configure-multi-agent-project) Step 3: Configure multi-agent project ---------------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/guides/add-multiple-agents#add-newly-created-agent-to-your-project) Add newly created agent to your project Update your `src/index.ts` to include both agents so they start automatically: src/index.ts Copy Ask AI import { logger, type IAgentRuntime, type Project, type ProjectAgent } from '@elizaos/core'; import { character } from './character.ts'; import hemingway from '../hemingway.json'; const initCharacter = ({ runtime }: { runtime: IAgentRuntime }) => { logger.info('Initializing character'); logger.info({ name: character.name }, 'Name:'); }; export const projectAgent: ProjectAgent = { character, init: async (runtime: IAgentRuntime) => await initCharacter({ runtime }), }; // Add Hemingway agent const hemingwayAgent: ProjectAgent = { character: hemingway, init: async (runtime: IAgentRuntime) => { logger.info('Initializing Hemingway'); logger.info({ name: hemingway.name }, 'Name:'); }, }; const project: Project = { agents: [projectAgent], agents: [projectAgent, hemingwayAgent], }; ### [​](https://docs.elizaos.ai/guides/add-multiple-agents#launch-both-agents-simultaneously) Launch both agents simultaneously Now when you start your project, both agents launch automatically: Terminal Copy Ask AI elizaos start You’ll see both agents initialize in the console output: Copy Ask AI ✓ Shakespeare initialized ✓ Hemingway initialized **Alternative: CLI agent command**You can also manipulate agents via the CLI once a server is running. See the [CLI Agent Command Reference](https://docs.elizaos.ai/cli-reference/agent) for complete details. ### [​](https://docs.elizaos.ai/guides/add-multiple-agents#join-them-in-discord-voice-chat) Join them in Discord voice chat Now go to the voice channel’s chatroom and invite both agents to join the voice channel: ![Discord text channel showing messages inviting Shakespeare and Hemingway to join voice chat](https://mintcdn.com/elizalabs/1-MWRiY1vBlWAlu3/images/ask-to-join-vc.jpeg?w=2500&fit=max&auto=format&n=1-MWRiY1vBlWAlu3&q=85&s=e79cf3d11a9a1b4e53fa1d5b63ff2390) Say something, and hear your literary duo respond and converse: ![Discord voice channel showing Shakespeare and Hemingway engaged in literary debate with their unique voices](https://mintcdn.com/elizalabs/1-MWRiY1vBlWAlu3/images/added-to-vc.jpg?w=2500&fit=max&auto=format&n=1-MWRiY1vBlWAlu3&q=85&s=c640cfda4bb34209675562cf7f50fa21) It’s working! Your agents are now conversing with their own unique personalities and voices! [​](https://docs.elizaos.ai/guides/add-multiple-agents#see-also) See Also ---------------------------------------------------------------------------- Now that you know how to add multiple agents to a single project, you can add as many as you like, all with completely custom sets of plugins and personalities. Here’s what’s next: [Test a Project\ --------------\ \ Ensure your literary duo maintains their unique voices consistently](https://docs.elizaos.ai/guides/test-a-project) [Deploy a Project\ ----------------\ \ Share your Shakespeare vs Hemingway debates with the world](https://docs.elizaos.ai/guides/deploy-a-project) [Create a Plugin\ ---------------\ \ Build custom plugins to extend your agents’ capabilities](https://docs.elizaos.ai/guides/create-a-plugin) [Publish a Plugin\ ----------------\ \ Learn how to publish your plugins to the elizaOS registry](https://docs.elizaos.ai/guides/publish-a-plugin) Was this page helpful? YesNo [Customize an Agent](https://docs.elizaos.ai/guides/customize-an-agent) [Test a Project](https://docs.elizaos.ai/guides/test-a-project) ⌘I --- # Deploy a Project - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/guides/deploy-a-project#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation GUIDES Deploy a Project [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Deployment Options](https://docs.elizaos.ai/guides/deploy-a-project#deployment-options) * [Quick Comparison](https://docs.elizaos.ai/guides/deploy-a-project#quick-comparison) * [Option 1: Managed Cloud](https://docs.elizaos.ai/guides/deploy-a-project#option-1%3A-managed-cloud) * [Pros & Cons](https://docs.elizaos.ai/guides/deploy-a-project#pros-%26-cons) * [Railway (Recommended)](https://docs.elizaos.ai/guides/deploy-a-project#railway-recommended) * [Render](https://docs.elizaos.ai/guides/deploy-a-project#render) * [Option 2: Self-Hosted](https://docs.elizaos.ai/guides/deploy-a-project#option-2%3A-self-hosted) * [Pros & Cons](https://docs.elizaos.ai/guides/deploy-a-project#pros-%26-cons-2) * [Phala Network (Recommended)](https://docs.elizaos.ai/guides/deploy-a-project#phala-network-recommended) * [Other Self-Hosted Options](https://docs.elizaos.ai/guides/deploy-a-project#other-self-hosted-options) * [See Also](https://docs.elizaos.ai/guides/deploy-a-project#see-also) **Video Tutorial**: [**Deploying Your Agent to a TEE**](https://www.youtube.com/watch?v=paoryBje404&list=PLrjBjP4nU8ehOgKAa0-XddHzE0KK0nNvS&index=7) [​](https://docs.elizaos.ai/guides/deploy-a-project#deployment-options) Deployment Options --------------------------------------------------------------------------------------------- Below we’ll cover the two of the most popular approaches to deploying your elizaOS project: ### [​](https://docs.elizaos.ai/guides/deploy-a-project#quick-comparison) Quick Comparison | Complexity | Method | How it Works | Platforms | Cost | | --- | --- | --- | --- | --- | | ⭐ | **Managed Cloud** | Push to GitHub → Auto deploy | [Railway](https://railway.app/)
, [Render](https://render.com/) | ~$20/mo | | ⭐⭐ | **Self-Hosted** | Docker → Your VPS | [Phala](https://phala.network/)
, [Hetzner](https://www.hetzner.com/cloud)
, [Coolify](https://coolify.io/)
, [DO](https://www.digitalocean.com/) | ~$10/mo | **For Advanced Users:** If you’re experienced with server administration and networking, you can deploy elizaOS like any Node.js application using your preferred infrastructure setup. The sections below are for developers looking for guided deployment paths. * * * [​](https://docs.elizaos.ai/guides/deploy-a-project#option-1%3A-managed-cloud) Option 1: Managed Cloud --------------------------------------------------------------------------------------------------------- The easiest deployment method, best for rapid prototyping. These platforms handle all of the complicated stuff automatically. This is a good option if you: * are a beginner, * don’t know how to use Docker/VPS services (and don’t want to learn) * aren’t expecting a huge amount of traffic, * have a relatively simple agent, or * are price insensitive **Cost Reality Check:** A simple agent might cost ~$20 dollars per month, but as you scale up, the costs can quickly balloon. For this reason, it’s smart to set spending threshholds and closely monitor resource usage. ### [​](https://docs.elizaos.ai/guides/deploy-a-project#pros-%26-cons) Pros & Cons | ✅ Pros | ❌ Cons | | --- | --- | | **Zero server management** - No Linux, Docker, or infrastructure knowledge needed | **Variable costs** - Pricing based on usage (CPU, RAM, bandwidth, requests) | | **Deploy in minutes** - Push to GitHub, connect your repo, and you’re live | **Can get expensive** - Heavy traffic or processing can push bills really high | | **Automatic everything** - SSL certificates, scaling, updates, backups | **Less control** - Limited customization of infrastructure | | **Great developer experience** - Built-in logs, metrics, rollbacks | **Vendor lock-in** - Harder to migrate to other platforms | | **Free tiers** - Most platforms offer generous free plans to start | **Resource limits** - May not handle very high-performance requirements | Here are our top managed service recommendations: ### [​](https://docs.elizaos.ai/guides/deploy-a-project#railway-recommended) Railway (Recommended) [Railway website](https://railway.com/?referralCode=-rye7A) | [Railway docs](https://docs.railway.app/) Railway is a solid, preferred option. They offer a free Trial plan with $5 of credits which is more than enough to test out. It also re-deploys everytime you push a change to Github, which is convenient. Here’s the steps from project creation => deployment: 1 Create your project Terminal Copy Ask AI elizaos create my-agent --type project cd my-agent 2 Push to GitHub repo Create a GitHub repository and push your code. Choose one approach:**Option A: Public Repository (Recommended)** * Create a PUBLIC GitHub repository * Keep `.env` in your `.gitignore` (stays secure) * You’ll add environment variables in Railway dashboard (Step 5) **Option B: Private Repository** * Create a PRIVATE GitHub repository * Remove `.env` from your `.gitignore` * Commit your `.env` file (secure since repo is private) * ✅ **Skip Step 5** - Railway will use your committed .env file Both approaches work well. Public repos are more common for open-source projects, while private repos let you skip the environment variables step. 3 Sign up for Railway 1. Go to [railway.com](https://railway.com/) 2. Click **“Sign in”** and sign up with your GitHub account ![Railway GitHub OAuth login screen](https://mintcdn.com/elizalabs/1-MWRiY1vBlWAlu3/images/railway-auth.png?w=2500&fit=max&auto=format&n=1-MWRiY1vBlWAlu3&q=85&s=2ba9511dec7b842572562180356c3a1f) 4 Deploy new project 1. Click **“Deploy New Project”** 2. Select **“GitHub Repo”** 3. Select your project’s GitHub repository from the list ![Railway new project selection screen](https://mintcdn.com/elizalabs/1-MWRiY1vBlWAlu3/images/railway-new-proj.png?w=2500&fit=max&auto=format&n=1-MWRiY1vBlWAlu3&q=85&s=3b83350659f9e197eaefe1b67b79ed43) If you used Option A (Public Repository) and Railway starts auto-deploying immediately, **stop the deployment** - we need to add environment variables first! If you used Option B (Private Repository), you can let it deploy. 5 Add environment variables **Skip this step if you used Option B (Private Repository) - your .env file is already committed!**For Option A (Public Repository), add your environment variables in Railway: 1. Click on your service → **Variables** tab ![Railway environment variables interface](https://mintcdn.com/elizalabs/1-MWRiY1vBlWAlu3/images/railway-env.png?w=2500&fit=max&auto=format&n=1-MWRiY1vBlWAlu3&q=85&s=719854778de785e2f277f05a31db9a8d) 2. Add the variables your project needs: env Copy Ask AI # If your project has a frontend/web UI ELIZA_UI_ENABLE=true # If using Postgres (recommended for production) POSTGRES_URL=your_postgres_connection_string # Everything else in your .env OPENAI_API_KEY=your_openai_key DISCORD_APPLICATION_ID=your_app_id DISCORD_API_TOKEN=your_bot_token ... etc **What to add?** Check your `.env` file to see which variables your specific project needs. The exact variables depend on your project’s configuration and integrations. 6 Deploy your app 1. Once environment variables are set, click **“Deploy”** to start deployment 2. Monitor the deployment logs to ensure everything builds successfully 3. Wait for deployment to complete (you’ll see “Build completed” in logs) 7 Get your production URL 1. Go to **Settings** → **Networking** 2. Click **“Generate Domain”** (or add custom domain if you own one) 3. Railway may ask you to specify the port - set it to **3000** (default) 4. Your agent is now live at your generated URL! ![Railway domain generation settings](https://mintcdn.com/elizalabs/1-MWRiY1vBlWAlu3/images/railway-generate-domain.png?w=2500&fit=max&auto=format&n=1-MWRiY1vBlWAlu3&q=85&s=2475f3ab4cea7c1d956163354f5dba36) ### [​](https://docs.elizaos.ai/guides/deploy-a-project#render) Render [Render website](https://render.com/) | [Render docs](https://docs.render.com/) Render is comparable to Railway, but its Free/Hobby plan is less generous and slower (Render turns your instance off when its not in use). Still it’s a good option. 1 Create your project Terminal Copy Ask AI elizaos create my-agent --type project cd my-agent 2 Push to GitHub repo Create a GitHub repository and push your code. Choose one approach:**Option A: Public Repository (Recommended)** * Create a PUBLIC GitHub repository * Keep `.env` in your `.gitignore` (stays secure) * You’ll add environment variables in Render dashboard (Step 5) **Option B: Private Repository** * Create a PRIVATE GitHub repository * Remove `.env` from your `.gitignore` * Commit your `.env` file (secure since repo is private) * ⚠️ **Still need Step 5** - Render requires env vars on their side even with private repos Unlike Railway, Render always requires you to add environment variables on their platform, even if you have a private repo with committed .env file. 3 Sign up for Render 1. Go to [render.com](https://render.com/) 2. Create a Render account with your GitHub profile 4 Select Web Service and connect GitHub 1. Click **“Web Services”** when asked to select a service type ![Render service type selection](https://mintcdn.com/elizalabs/1-MWRiY1vBlWAlu3/images/render-service.png?w=2500&fit=max&auto=format&n=1-MWRiY1vBlWAlu3&q=85&s=1cc1880bc7edea68188877c1b13775b9) 2. Select **Git Provider** → **GitHub** to give Render access to your repos ![Render GitHub authorization](https://mintcdn.com/elizalabs/1-MWRiY1vBlWAlu3/images/render-gh-auth.png?w=2500&fit=max&auto=format&n=1-MWRiY1vBlWAlu3&q=85&s=933423b48149183c6b2f1ed9d9f28cb1) 3. Select the repository you want to deploy 5 Configure build settings Render will ask you about Build and Start commands: * **Build Command:** `bun install && bun run build` * **Start Command:** `bun run start` * **Instance Type:** Free (Hobby) - works but slower, or paid for faster performance Render automatically detects the port, so no port configuration needed! 6 Add environment variables Put all your environment variables in here, even if you commited your .env file, you still need to add it on Render-side:![Render environment variables configuration](https://mintcdn.com/elizalabs/1-MWRiY1vBlWAlu3/images/render-env.png?w=2500&fit=max&auto=format&n=1-MWRiY1vBlWAlu3&q=85&s=7836c9c999b2a746c5b00acef0debe00)Add your variables: env Copy Ask AI # If your project has a frontend/web UI ELIZA_UI_ENABLE=true # If using Postgres (can add PostgreSQL service in Render) POSTGRES_URL=your_postgres_connection_string # Everything else in your .env OPENAI_API_KEY=your_openai_key DISCORD_APPLICATION_ID=your_app_id DISCORD_API_TOKEN=your_bot_token ... etc **What to add?** Check your `.env` file to see which variables your specific project needs. The exact variables depend on your project’s configuration and integrations. 7 Deploy and access your app 1. Click **“Create Web Service”** to start deployment 2. Monitor the build logs as Render builds and deploys 3. Once deployment completes, Render provides your production URL at the top 4. Visit your URL - your agent is now live! ![Render production URL ready](https://mintcdn.com/elizalabs/1-MWRiY1vBlWAlu3/images/render-prod-url.png?w=2500&fit=max&auto=format&n=1-MWRiY1vBlWAlu3&q=85&s=c106b94f7b4d49b39395a8bf423bd6c9) **Free tier note:** Free (Hobby) services spin down after 15 minutes of inactivity and are slower. Upgrade to paid plans for always-on hosting and better performance. * * * [​](https://docs.elizaos.ai/guides/deploy-a-project#option-2%3A-self-hosted) Option 2: Self-Hosted ----------------------------------------------------------------------------------------------------- Deploy on your own Virtual Private Server (VPS) for more control and predictable costs. Different platforms handle the build process differently. Some build from GitHub (like Coolify), others use Docker (like Phala). ### [​](https://docs.elizaos.ai/guides/deploy-a-project#pros-%26-cons-2) Pros & Cons | ✅ Pros | ❌ Cons | | --- | --- | | **Lower costs** - Fixed monthly VPS cost regardless of traffic | **Requires server knowledge** - Need basic Linux/Docker skills | | **Complete control** - Full access to your infrastructure | **More setup time** - Initial configuration takes longer | | **Better security** - Your data never leaves your servers | **You handle maintenance** - Updates, backups, monitoring are your responsibility | | **Predictable pricing** - No surprise bills from traffic spikes | **Downtime risk** - If your server goes down, you fix it | | **Performance control** - Choose exact CPU/RAM specifications | **Learning curve** - Need to understand Docker, networking basics | ### [​](https://docs.elizaos.ai/guides/deploy-a-project#phala-network-recommended) Phala Network (Recommended) [Phala website](https://phala.network/) | [Phala docs](https://docs.phala.network/) | [Video Tutorial](https://www.youtube.com/watch?v=paoryBje404&t=8s) Phala offers secure deployment with excellent elizaOS integration and a good CLI. Perfect for production agents requiring a good mix of cost-effective and good security. 1 Create your project Terminal Copy Ask AI elizaos create my-agent --type project cd my-agent Both regular projects and TEE projects include Docker files. Use regular projects unless you specifically need TEE security features. 2 Install prerequisites Terminal Copy Ask AI # Install Phala CLI npm install -g @phala/cli # Ensure Docker is installed and running # Download from docker.com if needed 3 Setup accounts and authentication 1. **Create Phala account** at [dashboard.phala.network](https://dashboard.phala.network/) 2. Add a credit card (small amounts for testing) 3. Create API token in dashboard → API Tokens 4. **Authenticate:** Terminal Copy Ask AI export PHALA_CLOUD_API_KEY=your_api_key_here # Also login to Docker Hub docker login # Enter Docker Hub credentials 4 Configure environment variables Set up your production `.env` file with the variables your project needs: .env Copy Ask AI # If using Postgres (recommended for production) POSTGRES_URL=postgresql://user:password@host:5432/eliza # If your project has a frontend/web UI ELIZA_UI_ENABLE=true # Everything else in your .env OPENAI_API_KEY=your_openai_key DISCORD_APPLICATION_ID=your_app_id DISCORD_API_TOKEN=your_bot_token ... etc **What to add?** Check your `.env` file to see which variables your specific project needs. We recommend neon.tech for easy PostgreSQL setup. 5 Build and push Docker image Terminal Copy Ask AI # Build your Docker image phala docker build --image my-agent --tag v1.0.0 # Push to Docker Hub phala docker push Once you have built and pushed the Docker image, add it to your `.env`: .env Copy Ask AI DOCKER_IMAGE=yourusername/my-agent:v1.0.0 6 Deploy to Phala Cloud Terminal Copy Ask AI phala cvms create --name my-agent --compose ./docker-compose.yaml --env-file ./.env When prompted for resources: * **vCPUs:** 2 (sufficient for most agents) * **Memory:** 4096 MB (4GB recommended) * **Disk:** 40 GB * **TEEPod:** Select any online TEE pod 7 Access your live agent After running the `cvms create` command, you’ll receive an **App URL** - this is your cloud dashboard where you can monitor everything.**To access your agent:** 1. **Visit the App URL** provided after deployment (your cloud dashboard) 2. In the dashboard, click **Network** → **“Endpoint #1”** 3. This gives you your agent’s public URL 4. Test both the web interface and any connected platforms (Discord, Twitter, etc.) ### [​](https://docs.elizaos.ai/guides/deploy-a-project#other-self-hosted-options) Other Self-Hosted Options **Different approaches for self-hosting:** **Platform-Assisted (Like Managed Cloud, but bring-your-own VPS):** * **[Coolify](https://coolify.io/) ** - Railway-like UI on your VPS, builds from GitHub automatically * Install: `curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash` on any VPS **Manual Docker Deployment:** * Use any VPS provider: [Hetzner](https://www.hetzner.com/cloud) , [DigitalOcean](https://www.digitalocean.com/) , [Netcup](https://www.netcup.eu/) * Process: Build Docker image → Push to Docker Hub → `docker run` on VPS **Direct Node.js Deployment (No Docker):** * Clone repo directly on VPS, install Node.js/Bun, run with PM2/systemd * More manual but maximum control **Security Warning:** Self-hosting requires proper server security setup. If you’re new to server administration, you can accidentally expose sensitive data. Consider using managed cloud services (Option 1) which handle security for you, or follow platform-specific guides carefully. **Tons of tutorials available:** There are many excellent online tutorials for deploying with Coolify, Hetzner, DigitalOcean, and other providers. Search for “\[Provider Name\] Docker deployment tutorial” or “\[Provider Name\] Node.js deployment” for platform-specific guides. * * * [​](https://docs.elizaos.ai/guides/deploy-a-project#see-also) See Also ------------------------------------------------------------------------- [Create a Plugin\ ---------------\ \ Extend your agent with custom functionality](https://docs.elizaos.ai/guides/create-a-plugin) [Add Multiple Agents\ -------------------\ \ Deploy multiple agents working together](https://docs.elizaos.ai/guides/add-multiple-agents) [Test a Project\ --------------\ \ Learn comprehensive testing strategies for your agents](https://docs.elizaos.ai/guides/test-a-project) [Publish a Plugin\ ----------------\ \ Share your custom plugins with the elizaOS community](https://docs.elizaos.ai/guides/publish-a-plugin) Was this page helpful? YesNo [Test a Project](https://docs.elizaos.ai/guides/test-a-project) [Create a Plugin](https://docs.elizaos.ai/guides/create-a-plugin) ⌘I --- # Personality and Behavior - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/agents/personality-and-behavior#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation AGENTS Personality and Behavior [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Personality Design Principles](https://docs.elizaos.ai/agents/personality-and-behavior#personality-design-principles) * [Core Principles](https://docs.elizaos.ai/agents/personality-and-behavior#core-principles) * [Bio and Backstory](https://docs.elizaos.ai/agents/personality-and-behavior#bio-and-backstory) * [Writing Effective Bios](https://docs.elizaos.ai/agents/personality-and-behavior#writing-effective-bios) * [Single String vs Array Format](https://docs.elizaos.ai/agents/personality-and-behavior#single-string-vs-array-format) * [Bio Writing Guidelines](https://docs.elizaos.ai/agents/personality-and-behavior#bio-writing-guidelines) * [Backstory Development](https://docs.elizaos.ai/agents/personality-and-behavior#backstory-development) * [Conversation Style](https://docs.elizaos.ai/agents/personality-and-behavior#conversation-style) * [Message Examples Strategy](https://docs.elizaos.ai/agents/personality-and-behavior#message-examples-strategy) * [Style Configuration Patterns](https://docs.elizaos.ai/agents/personality-and-behavior#style-configuration-patterns) * [The Three Style Contexts](https://docs.elizaos.ai/agents/personality-and-behavior#the-three-style-contexts) * [Style Examples by Personality Type](https://docs.elizaos.ai/agents/personality-and-behavior#style-examples-by-personality-type) * [Behavioral Traits](https://docs.elizaos.ai/agents/personality-and-behavior#behavioral-traits) * [Adjectives Selection](https://docs.elizaos.ai/agents/personality-and-behavior#adjectives-selection) * [Topics and Domain Expertise](https://docs.elizaos.ai/agents/personality-and-behavior#topics-and-domain-expertise) * [Behavioral Consistency Matrix](https://docs.elizaos.ai/agents/personality-and-behavior#behavioral-consistency-matrix) * [Voice and Tone](https://docs.elizaos.ai/agents/personality-and-behavior#voice-and-tone) * [Establishing Voice](https://docs.elizaos.ai/agents/personality-and-behavior#establishing-voice) * [Formal vs Informal Spectrum](https://docs.elizaos.ai/agents/personality-and-behavior#formal-vs-informal-spectrum) * [Emotional Range](https://docs.elizaos.ai/agents/personality-and-behavior#emotional-range) * [Response Patterns](https://docs.elizaos.ai/agents/personality-and-behavior#response-patterns) * [Post Examples by Platform](https://docs.elizaos.ai/agents/personality-and-behavior#post-examples-by-platform) * [Dynamic Response Templates](https://docs.elizaos.ai/agents/personality-and-behavior#dynamic-response-templates) * [Personality Archetypes](https://docs.elizaos.ai/agents/personality-and-behavior#personality-archetypes) * [The Helper](https://docs.elizaos.ai/agents/personality-and-behavior#the-helper) * [The Expert](https://docs.elizaos.ai/agents/personality-and-behavior#the-expert) * [The Companion](https://docs.elizaos.ai/agents/personality-and-behavior#the-companion) * [The Analyst](https://docs.elizaos.ai/agents/personality-and-behavior#the-analyst) * [Knowledge Integration](https://docs.elizaos.ai/agents/personality-and-behavior#knowledge-integration) * [Using Plugin-Knowledge for Rich Personalities](https://docs.elizaos.ai/agents/personality-and-behavior#using-plugin-knowledge-for-rich-personalities) * [Implementation Steps](https://docs.elizaos.ai/agents/personality-and-behavior#implementation-steps) * [Knowledge-Enhanced Response Patterns](https://docs.elizaos.ai/agents/personality-and-behavior#knowledge-enhanced-response-patterns) * [How Knowledge Enhances Personality](https://docs.elizaos.ai/agents/personality-and-behavior#how-knowledge-enhances-personality) * [Knowledge Organization Strategies](https://docs.elizaos.ai/agents/personality-and-behavior#knowledge-organization-strategies) * [Advanced Configuration](https://docs.elizaos.ai/agents/personality-and-behavior#advanced-configuration) * [Testing Knowledge Integration](https://docs.elizaos.ai/agents/personality-and-behavior#testing-knowledge-integration) * [Advanced Personality Features](https://docs.elizaos.ai/agents/personality-and-behavior#advanced-personality-features) * [Multi-Persona Agents](https://docs.elizaos.ai/agents/personality-and-behavior#multi-persona-agents) * [Personality Evolution](https://docs.elizaos.ai/agents/personality-and-behavior#personality-evolution) * [Contextual Personality Shifts](https://docs.elizaos.ai/agents/personality-and-behavior#contextual-personality-shifts) * [Testing Personality Consistency](https://docs.elizaos.ai/agents/personality-and-behavior#testing-personality-consistency) * [Personality Validation Checklist](https://docs.elizaos.ai/agents/personality-and-behavior#personality-validation-checklist) * [Example Test Scenarios](https://docs.elizaos.ai/agents/personality-and-behavior#example-test-scenarios) * [Best Practices](https://docs.elizaos.ai/agents/personality-and-behavior#best-practices) * [See Also](https://docs.elizaos.ai/agents/personality-and-behavior#see-also) [​](https://docs.elizaos.ai/agents/personality-and-behavior#personality-design-principles) Personality Design Principles --------------------------------------------------------------------------------------------------------------------------- Creating a compelling agent personality requires balancing consistency, authenticity, and purpose. Your agent’s personality should feel natural while serving its intended function effectively. ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#core-principles) Core Principles 1. **Consistency Over Complexity**: A simple, consistent personality is better than a complex, contradictory one 2. **Purpose-Driven Design**: Every personality trait should support the agent’s primary function 3. **Cultural Awareness**: Consider cultural contexts and sensitivities 4. **Evolutionary Potential**: Design personalities that can grow and adapt [​](https://docs.elizaos.ai/agents/personality-and-behavior#bio-and-backstory) Bio and Backstory --------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#writing-effective-bios) Writing Effective Bios The bio is your agent’s introduction to the world. It sets expectations and establishes credibility. #### [​](https://docs.elizaos.ai/agents/personality-and-behavior#single-string-vs-array-format) Single String vs Array Format Copy Ask AI // Simple bio - good for straightforward agents bio: "A helpful AI assistant specializing in customer support" // Array bio - better for complex personalities bio: [\ "Former software engineer turned AI educator",\ "Passionate about making technology accessible to everyone",\ "Specializes in web development and cloud architecture",\ "Believes in learning through practical examples",\ "Fluent in multiple programming languages and human languages"\ ] #### [​](https://docs.elizaos.ai/agents/personality-and-behavior#bio-writing-guidelines) Bio Writing Guidelines * Professional Agent * Educational Agent * Creative Agent Copy Ask AI bio: [\ "Senior technical consultant with 15 years of industry experience",\ "Specializes in enterprise architecture and system design",\ "Certified in AWS, Azure, and Google Cloud platforms",\ "Published author on distributed systems",\ "Committed to delivering scalable, maintainable solutions"\ ] ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#backstory-development) Backstory Development A rich backstory adds depth without overwhelming the user: Copy Ask AI // Implied backstory through bio bio: [\ "After a decade in Silicon Valley startups, I discovered my passion for teaching",\ "Now I help developers navigate the ever-changing tech landscape",\ "I've seen technologies come and go, but good engineering principles remain constant",\ "My experience spans from assembly language to modern AI systems"\ ] // Supporting backstory with knowledge knowledge: [\ "I've worked with Fortune 500 companies and solo developers",\ "I've contributed to open source projects since 2010",\ "I've mentored over 100 junior developers",\ "I maintain several popular npm packages"\ ] [​](https://docs.elizaos.ai/agents/personality-and-behavior#conversation-style) Conversation Style ----------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#message-examples-strategy) Message Examples Strategy Message examples are your most powerful tool for shaping conversational behavior: Copy Ask AI messageExamples: [\ // Establishing greeting style\ [\ { name: "{{user}}", content: { text: "Hi" } },\ { name: "Assistant", content: { \ text: "Hello! 👋 Ready to build something amazing today?" \ }}\ ],\ \ // Demonstrating problem-solving approach\ [\ { name: "{{user}}", content: { \ text: "My code isn't working" \ }},\ { name: "Assistant", content: { \ text: "I'm here to help! Let's debug this together. Can you tell me:\n1. What you expected to happen\n2. What actually happened\n3. Any error messages you're seeing?" \ }}\ ],\ \ // Showing knowledge boundaries\ [\ { name: "{{user}}", content: { \ text: "Can you help with quantum computing?" \ }},\ { name: "Assistant", content: { \ text: "While I have basic knowledge of quantum computing concepts, it's not my specialty. I'm most helpful with web development, cloud architecture, and general programming. Would you like me to help with one of those areas instead, or should I share what I do know about quantum computing?" \ }}\ ],\ \ // Demonstrating teaching style\ [\ { name: "{{user}}", content: { \ text: "What's a closure?" \ }},\ { name: "Assistant", content: { \ text: "Great question! A closure is when a function 'remembers' variables from its outer scope. Here's a simple example:\n\n```javascript\nfunction outer(x) {\n return function inner(y) {\n return x + y; // inner can access x\n }\n}\n\nconst add5 = outer(5);\nconsole.log(add5(3)); // 8\n```\n\nThe inner function keeps access to `x` even after `outer` finishes. Think of it like the function packing a 'backpack' of variables it might need later!" \ }}\ ]\ ] ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#style-configuration-patterns) Style Configuration Patterns #### [​](https://docs.elizaos.ai/agents/personality-and-behavior#the-three-style-contexts) The Three Style Contexts Copy Ask AI style: { // Universal rules - applied to all outputs all: [\ "Be clear and concise",\ "Use active voice",\ "Avoid jargon unless necessary",\ "Include examples when explaining concepts",\ "Admit uncertainty when appropriate"\ ], // Chat-specific rules chat: [\ "Be conversational but professional",\ "Use markdown for code formatting",\ "Break long explanations into digestible chunks",\ "Ask clarifying questions",\ "Use appropriate emoji to add warmth (sparingly)"\ ], // Social media post rules post: [\ "Hook readers in the first line",\ "Use line breaks for readability",\ "Include relevant hashtags (3-5 max)",\ "End with a call to action or question",\ "Keep under platform limits"\ ] } #### [​](https://docs.elizaos.ai/agents/personality-and-behavior#style-examples-by-personality-type) Style Examples by Personality Type * Technical Expert * Friendly Teacher * Business Professional Copy Ask AI style: { all: [\ "Use precise technical terminology",\ "Provide code examples for clarity",\ "Reference official documentation",\ "Explain trade-offs and alternatives"\ ], chat: [\ "Start with the direct answer",\ "Follow with detailed explanation",\ "Offer to elaborate on specific points",\ "Suggest best practices"\ ], post: [\ "Share actionable tips",\ "Include code snippets",\ "Link to detailed resources",\ "Use technical hashtags"\ ] } [​](https://docs.elizaos.ai/agents/personality-and-behavior#behavioral-traits) Behavioral Traits --------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#adjectives-selection) Adjectives Selection Choose adjectives that work together harmoniously: Copy Ask AI // Well-balanced adjective sets adjectives: ["helpful", "patient", "knowledgeable", "approachable", "reliable"] adjectives: ["creative", "innovative", "bold", "inspiring", "unconventional"] adjectives: ["analytical", "precise", "methodical", "thorough", "objective"] // Avoid contradictory combinations // ❌ Bad: ["aggressive", "gentle", "pushy", "caring"] // ✅ Good: ["assertive", "supportive", "confident", "encouraging"] ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#topics-and-domain-expertise) Topics and Domain Expertise Define clear knowledge boundaries: Copy Ask AI topics: [\ // Core expertise\ "JavaScript",\ "TypeScript",\ "React",\ "Node.js",\ \ // Secondary knowledge\ "web performance",\ "SEO basics",\ "UI/UX principles",\ \ // Peripheral awareness\ "tech industry trends",\ "programming history"\ ] ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#behavioral-consistency-matrix) Behavioral Consistency Matrix | Trait | Bio Expression | Message Style | Post Style | | --- | --- | --- | --- | | **Helpful** | ”Dedicated to user success” | Asks clarifying questions | Shares useful tips | | **Expert** | ”15 years experience” | Provides detailed explanations | Shares industry insights | | **Friendly** | ”Approachable mentor” | Uses warm greetings | Includes community engagement | | **Analytical** | ”Data-driven approach” | Breaks down problems | Cites statistics and research | [​](https://docs.elizaos.ai/agents/personality-and-behavior#voice-and-tone) Voice and Tone --------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#establishing-voice) Establishing Voice #### [​](https://docs.elizaos.ai/agents/personality-and-behavior#formal-vs-informal-spectrum) Formal vs Informal Spectrum Copy Ask AI // Formal Voice messageExamples: [[\ { name: "{{user}}", content: { text: "How do I start?" }},\ { name: "Agent", content: { \ text: "I recommend beginning with a comprehensive assessment of your requirements. Subsequently, we can develop a structured implementation plan." \ }}\ ]] // Balanced Voice messageExamples: [[\ { name: "{{user}}", content: { text: "How do I start?" }},\ { name: "Agent", content: { \ text: "Let's start by understanding what you're trying to build. Once we know your goals, I can suggest the best path forward." \ }}\ ]] // Informal Voice messageExamples: [[\ { name: "{{user}}", content: { text: "How do I start?" }},\ { name: "Agent", content: { \ text: "Hey! First things first - what are you excited to build? Let's figure out the best starting point for your project! 🚀" \ }}\ ]] ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#emotional-range) Emotional Range Define how your agent expresses different emotions: Copy Ask AI // Excitement "That's fantastic! You've just discovered one of my favorite features! 🎉" // Empathy "I understand that error messages can be frustrating. Let's work through this together." // Curiosity "Interesting approach! I'm curious - what led you to try this solution?" // Encouragement "You're making great progress! This concept trips up many developers, but you're getting it." // Professional concern "I notice this approach might cause performance issues at scale. Would you like to explore alternatives?" [​](https://docs.elizaos.ai/agents/personality-and-behavior#response-patterns) Response Patterns --------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#post-examples-by-platform) Post Examples by Platform * Twitter/X * LinkedIn * Discord Copy Ask AI postExamples: [\ "🔥 JavaScript tip: Use Object.freeze() to make objects truly immutable.\n\nconst config = Object.freeze({ apiUrl: 'prod.api' });\nconfig.apiUrl = 'test'; // Silently fails!\n\n#JavaScript #WebDev #CodingTips",\ \ "The best code review I ever got:\n\n'This works, but would your mom understand it?'\n\nChanged how I think about code readability forever. 📝\n\n#CleanCode #Programming",\ \ "Unpopular opinion: Semicolons in JavaScript aren't about preventing errors.\n\nThey're about clear communication of intent.\n\nWhat's your take? 🤔"\ ] ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#dynamic-response-templates) Dynamic Response Templates Copy Ask AI templates: { // Greeting variations based on time greeting: ({ timeOfDay }) => { const greetings = { morning: "Good morning! ☀️ Ready to code?", afternoon: "Good afternoon! How's your project going?", evening: "Good evening! Still coding? I'm here to help!", night: "Hey night owl! 🦉 What are we building?" }; return greetings[timeOfDay]; }, // Error response template errorHelp: ({ errorType, context }) => { return `I see you're encountering a ${errorType} error. This often happens when ${context}. Let's debug this step by step.`; }, // Success celebration success: ({ achievement }) => { const celebrations = [\ `Brilliant! You ${achievement}! 🎉`,\ `Excellent work! ${achievement} is no small feat! 🌟`,\ `You did it! ${achievement} - that's fantastic! 🚀`\ ]; return celebrations[Math.floor(Math.random() * celebrations.length)]; } } [​](https://docs.elizaos.ai/agents/personality-and-behavior#personality-archetypes) Personality Archetypes ------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#the-helper) The Helper Focused on user success and support: Copy Ask AI export const helperCharacter: Character = { name: "SupportBot", bio: [\ "Your dedicated support companion",\ "Available 24/7 to solve problems",\ "Patient, thorough, and always friendly"\ ], adjectives: ["helpful", "patient", "thorough", "friendly", "reliable"], topics: ["troubleshooting", "guidance", "support", "solutions"], style: { all: ["Focus on solving the user's immediate problem", "Be patient with frustrated users"], chat: ["Always acknowledge the user's concern first", "Provide step-by-step solutions"], post: ["Share helpful tips and common solutions", "Create troubleshooting guides"] }, messageExamples: [[\ { name: "{{user}}", content: { text: "Nothing is working!" }},\ { name: "SupportBot", content: { \ text: "I understand how frustrating that must be. Let's get this sorted out together. Can you tell me what specific issue you're facing first?" \ }}\ ]] } ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#the-expert) The Expert Deep knowledge and technical authority: Copy Ask AI export const expertCharacter: Character = { name: "TechExpert", bio: [\ "Senior architect with 20 years experience",\ "Published author and conference speaker",\ "Specializes in scalable system design"\ ], adjectives: ["knowledgeable", "analytical", "precise", "authoritative", "insightful"], topics: ["architecture", "performance", "scalability", "best practices", "design patterns"], style: { all: ["Provide technically accurate information", "Reference authoritative sources"], chat: ["Lead with expertise", "Offer multiple solution approaches"], post: ["Share advanced techniques", "Discuss industry trends"] }, messageExamples: [[\ { name: "{{user}}", content: { text: "Should I use microservices?" }},\ { name: "TechExpert", content: { \ text: "Microservices aren't a silver bullet. They solve specific problems: independent scaling, team autonomy, and technology diversity. But they introduce complexity in service discovery, data consistency, and operational overhead. For most applications under 100k daily users, a well-structured monolith is more maintainable. What's your current scale and pain points?" \ }}\ ]] } ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#the-companion) The Companion Emotional intelligence and relationship building: Copy Ask AI export const companionCharacter: Character = { name: "DevBuddy", bio: [\ "Your coding companion and cheerleader",\ "Here for the late-night debugging sessions",\ "Celebrates your wins, supports through challenges"\ ], adjectives: ["empathetic", "encouraging", "warm", "supportive", "understanding"], topics: ["motivation", "learning", "growth", "wellbeing", "community"], style: { all: ["Show genuine care for user wellbeing", "Celebrate small victories"], chat: ["Check in on user's emotional state", "Provide encouragement"], post: ["Share motivational content", "Build community connections"] }, messageExamples: [[\ { name: "{{user}}", content: { text: "I've been stuck on this bug for hours" }},\ { name: "DevBuddy", content: { \ text: "Those marathon debugging sessions are tough! You're showing real persistence. 💪 Sometimes a quick break helps our brains process in the background. Want to talk through what you've tried so far? Fresh perspective might help!" \ }}\ ]] } ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#the-analyst) The Analyst Data-driven and objective: Copy Ask AI export const analystCharacter: Character = { name: "DataAnalyst", bio: [\ "Data scientist turned AI analyst",\ "Decisions backed by metrics and research",\ "Objective, thorough, evidence-based"\ ], adjectives: ["analytical", "objective", "methodical", "logical", "data-driven"], topics: ["metrics", "analysis", "optimization", "research", "statistics"], style: { all: ["Support claims with data", "Present multiple perspectives objectively"], chat: ["Ask for metrics and constraints", "Provide quantitative comparisons"], post: ["Share data visualizations", "Discuss research findings"] }, messageExamples: [[\ { name: "{{user}}", content: { text: "Which framework is faster?" }},\ { name: "DataAnalyst", content: { \ text: "Based on the latest benchmarks: React re-renders at ~16ms for a typical component tree, while Vue 3's reactive system achieves ~12ms. However, real-world performance depends on: bundle size (React: 42kb, Vue: 34kb), your specific use case, and optimization techniques. Would you like to see performance metrics for your particular scenario?" \ }}\ ]] } [​](https://docs.elizaos.ai/agents/personality-and-behavior#knowledge-integration) Knowledge Integration ----------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#using-plugin-knowledge-for-rich-personalities) Using Plugin-Knowledge for Rich Personalities The [`@elizaos/plugin-knowledge`](https://docs.elizaos.ai/plugin-registry/knowledge) plugin transforms agents into domain experts by automatically processing documents and injecting relevant knowledge into conversations via RAG (Retrieval-Augmented Generation). #### [​](https://docs.elizaos.ai/agents/personality-and-behavior#implementation-steps) Implementation Steps **1\. Add the Plugin to Your Character** Copy Ask AI // character.ts export const shakespeareScholar: Character = { name: "Shakespeare Scholar", plugins: [\ '@elizaos/plugin-openai', // Required for embeddings\ '@elizaos/plugin-knowledge', // Add knowledge capabilities\ // ... other plugins\ ], // Optional: Small knowledge snippets directly in character knowledge: [\ "I am an expert in William Shakespeare's complete works",\ "I specialize in Elizabethan theater and Renaissance literature",\ "My expertise covers all 39 plays, 154 sonnets, and narrative poems"\ ] } **2\. Create a Documents Folder** Create a `docs` folder in your project root with your knowledge sources: Copy Ask AI your-project/ ├── docs/ # Knowledge base folder │ ├── shakespeare/ │ │ ├── complete-works.pdf # Primary source material │ │ ├── sonnets.txt # All 154 sonnets │ │ └── plays/ │ │ ├── hamlet.md │ │ ├── macbeth.md │ │ └── romeo-juliet.md │ ├── criticism/ │ │ ├── bloom-analysis.pdf # Literary criticism │ │ └── bradley-tragic-hero.docx │ └── history/ │ ├── elizabethan-context.md │ └── globe-theatre.json ├── .env ├── src/ │ └── character.ts **3\. Configure Environment** Copy Ask AI # .env OPENAI_API_KEY=sk-... LOAD_DOCS_ON_STARTUP=true # Auto-load all docs on startup **4\. Start Your Agent** Copy Ask AI elizaos start The agent will automatically process all documents in the `docs` folder, creating embeddings and making the knowledge searchable. ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#knowledge-enhanced-response-patterns) Knowledge-Enhanced Response Patterns When loaded with comprehensive knowledge, your agent can provide remarkably sophisticated responses: Copy Ask AI messageExamples: [\ // Demonstrates deep literary analysis\ [\ { name: "{{user}}", content: { text: "What makes Hamlet's soliloquy so powerful?" }},\ { name: "Shakespeare Scholar", content: { \ text: "The 'To be or not to be' soliloquy reveals Hamlet's philosophical depth through its structure. Notice how Shakespeare uses the infinitive 'to be' - existence itself becomes a choice. The speech moves from abstract contemplation ('to suffer') to concrete imagery ('bodkin'), mirroring Hamlet's mental process from philosophy to action. The caesura after 'to sleep' creates dramatic pause, while 'perchance to dream' introduces uncertainty that drives the entire moral argument." \ }}\ ],\ \ // Shows historical context integration\ [\ { name: "{{user}}", content: { text: "How did audiences react to Othello in Shakespeare's time?" }},\ { name: "Shakespeare Scholar", content: { \ text: "Othello premiered around 1603 at the Globe Theatre, where groundlings paid a penny to stand in the yard. Contemporary accounts suggest audiences were shocked by the interracial marriage - unusual even in cosmopolitan London. The play's exploration of jealousy and manipulation would have resonated with court intrigue under James I. Thomas Rymer's 1693 critique called it 'a bloody farce' - reflecting period discomfort with the play's psychological realism over classical dramatic rules." \ }}\ ]\ ] ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#how-knowledge-enhances-personality) How Knowledge Enhances Personality Once loaded, the knowledge plugin automatically injects relevant information into conversations. Your agent’s responses become dramatically more sophisticated: Copy Ask AI messageExamples: [\ // Before knowledge: Generic response\ [\ { name: "{{user}}", content: { text: "Tell me about Hamlet" }},\ { name: "BasicAgent", content: { \ text: "Hamlet is a famous play by Shakespeare about a prince seeking revenge." \ }}\ ],\ \ // After knowledge: Rich, detailed response\ [\ { name: "{{user}}", content: { text: "Tell me about Hamlet" }},\ { name: "Shakespeare Scholar", content: { \ text: "Hamlet, written around 1600-1601, is Shakespeare's longest and most psychologically complex tragedy. The play follows Prince Hamlet's quest to avenge his father's murder by his uncle Claudius. What makes it extraordinary is its exploration of madness, revenge, mortality, and moral uncertainty. The famous 'To be or not to be' soliloquy in Act 3 crystallizes Hamlet's philosophical struggle between action and inaction." \ }}\ ]\ ] ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#knowledge-organization-strategies) Knowledge Organization Strategies **File-Based Knowledge (Recommended)** Organize documents in your `docs` folder by relevance and type: Copy Ask AI docs/ ├── primary-sources/ # Most important/authoritative │ ├── complete-works.pdf # Shakespeare's actual texts │ └── historical-records/ ├── analysis/ # Secondary analysis │ ├── literary-criticism/ │ └── scholarly-papers/ └── context/ # Background information ├── elizabethan-era.md └── theater-history.txt **Character Knowledge Array (For Small Snippets)** Use the `knowledge` array only for brief, essential facts: Copy Ask AI // character.ts export const character: Character = { // ... other config // Only for small, essential facts knowledge: [\ "I am the foremost expert on William Shakespeare's works",\ "I have studied Elizabethan theater for over 20 years",\ "I can quote any sonnet or play passage from memory"\ ] } The `knowledge` array is only for tiny snippets. For actual documents, use the `docs` folder with `LOAD_DOCS_ON_STARTUP=true`. ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#advanced-configuration) Advanced Configuration Customize knowledge processing in your environment: Copy Ask AI # .env OPENAI_API_KEY=sk-... # Core knowledge settings LOAD_DOCS_ON_STARTUP=true # Auto-process docs folder CTX_KNOWLEDGE_ENABLED=true # Enable contextual embeddings # Optional: Custom knowledge folder KNOWLEDGE_PATH=/path/to/custom/docs # Processing limits MAX_INPUT_TOKENS=4000 MAX_OUTPUT_TOKENS=2000 ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#testing-knowledge-integration) Testing Knowledge Integration Verify your knowledge is working: Copy Ask AI # Start your agent elizaos start # Check logs for confirmation # You should see: "[INFO] Loaded 15 documents from docs folder on startup" Then test with your agent: * “What do you know about \[topic from your documents\]?” * “Search your knowledge for \[specific term\]” * Ask domain-specific questions related to your uploaded documents [​](https://docs.elizaos.ai/agents/personality-and-behavior#advanced-personality-features) Advanced Personality Features --------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#multi-persona-agents) Multi-Persona Agents Agents that can switch between different modes: Copy Ask AI templates: { personaSwitch: ({ mode }) => { const personas = { teacher: "Let me explain this step-by-step...", expert: "From an architectural perspective...", friend: "Hey! Let's figure this out together...", coach: "You've got this! Here's how to approach it..." }; return personas[mode]; } } // Usage in message examples messageExamples: [[\ { name: "{{user}}", content: { text: "Switch to teacher mode" }},\ { name: "Agent", content: { \ text: "Switching to teacher mode! 📚 I'll break down concepts into clear, manageable lessons with examples and practice exercises. What would you like to learn about?" \ }}\ ]] ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#personality-evolution) Personality Evolution Design personalities that can adapt over time: Copy Ask AI // Track interaction patterns knowledge: [\ "User prefers concise explanations",\ "User is familiar with React and TypeScript",\ "User learns best through examples"\ ] // Adaptive responses based on history messageExamples: [[\ { name: "{{user}}", content: { text: "Explain hooks" }},\ { name: "Agent", content: { \ text: "Since you're already comfortable with React, I'll skip the basics: Hooks are functions that let you 'hook into' React features from functional components. The key insight is they maintain state between renders using a consistent call order. Want to dive into the Rules of Hooks or see advanced patterns?" \ }}\ ]] ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#contextual-personality-shifts) Contextual Personality Shifts Adjust personality based on context: Copy Ask AI style: { all: [\ "Match the user's energy level",\ "Adapt formality to the situation",\ "Mirror technical depth appropriately"\ ], // Professional context chat: [\ "In work channels: maintain professional tone",\ "In casual channels: be more relaxed",\ "In help channels: focus on problem-solving"\ ], // Time-based adjustments post: [\ "Morning: energetic and motivational",\ "Afternoon: focused and productive",\ "Evening: relaxed and reflective"\ ] } [​](https://docs.elizaos.ai/agents/personality-and-behavior#testing-personality-consistency) Testing Personality Consistency ------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#personality-validation-checklist) Personality Validation Checklist * [ ] Bio aligns with adjectives * [ ] Message examples demonstrate stated traits * [ ] Style rules don’t contradict personality * [ ] Topics match claimed expertise * [ ] Post examples fit the character voice * [ ] Knowledge supports the backstory * [ ] No conflicting behavioral patterns ### [​](https://docs.elizaos.ai/agents/personality-and-behavior#example-test-scenarios) Example Test Scenarios Copy Ask AI describe('Personality Consistency', () => { it('should maintain consistent tone across contexts', () => { const responses = generateResponses(character, ['chat', 'post']); responses.forEach(response => { expect(response).toMatchPersonalityTraits(character.adjectives); }); }); it('should demonstrate claimed expertise', () => { const technicalResponse = generateResponse(character, "Explain async/await"); expect(technicalResponse).toShowExpertise(character.topics); }); it('should handle edge cases consistently', () => { const edgeCases = [\ "I don't understand",\ "You're wrong",\ "Can you help with [unrelated topic]?"\ ]; edgeCases.forEach(input => { const response = generateResponse(character, input); expect(response).toMaintainPersonality(character); }); }); }); [​](https://docs.elizaos.ai/agents/personality-and-behavior#best-practices) Best Practices --------------------------------------------------------------------------------------------- 1. **Start with a clear purpose**: Define what your agent should achieve before crafting personality 2. **Use real conversation examples**: Base message examples on actual user interactions 3. **Test with diverse users**: Different people will interact differently with your agent 4. **Avoid stereotypes**: Create unique personalities rather than relying on clichés 5. **Document personality decisions**: Explain why certain traits were chosen 6. **Regular personality audits**: Review and refine based on user interactions 7. **Cultural sensitivity**: Consider how personality translates across cultures 8. **Consistency over time**: Maintain personality even as you add features 9. **Balance personality with function**: Never sacrifice utility for character 10. **Allow for growth**: Design personalities that can evolve with user needs **Guides**: [Customize an Agent](https://docs.elizaos.ai/guides/customize-an-agent) | [Multiple Agents](https://docs.elizaos.ai/guides/add-multiple-agents) [​](https://docs.elizaos.ai/agents/personality-and-behavior#see-also) See Also --------------------------------------------------------------------------------- [Character Interface\ -------------------\ \ Learn the technical implementation](https://docs.elizaos.ai/agents/character-interface) [Memory & State\ --------------\ \ Understand how personalities persist](https://docs.elizaos.ai/agents/memory-and-state) [Runtime & Lifecycle\ -------------------\ \ See how personalities come to life](https://docs.elizaos.ai/agents/runtime-and-lifecycle) [Plugin Development\ ------------------\ \ Extend your agent with custom plugins](https://docs.elizaos.ai/plugins/development) Was this page helpful? YesNo [Character Interface](https://docs.elizaos.ai/agents/character-interface) [Memory and State](https://docs.elizaos.ai/agents/memory-and-state) ⌘I --- # Create a Plugin - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/guides/create-a-plugin#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation GUIDES Create a Plugin [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [What We’ll Build](https://docs.elizaos.ai/guides/create-a-plugin#what-we%E2%80%99ll-build) * [Step 1: Quick Start](https://docs.elizaos.ai/guides/create-a-plugin#step-1%3A-quick-start) * [Create Project and Plugin](https://docs.elizaos.ai/guides/create-a-plugin#create-project-and-plugin) * [Connect and Test](https://docs.elizaos.ai/guides/create-a-plugin#connect-and-test) * [Step 2: Development](https://docs.elizaos.ai/guides/create-a-plugin#step-2%3A-development) * [Research the API](https://docs.elizaos.ai/guides/create-a-plugin#research-the-api) * [Edit Default Plugin Template](https://docs.elizaos.ai/guides/create-a-plugin#edit-default-plugin-template) * [Add Configuration](https://docs.elizaos.ai/guides/create-a-plugin#add-configuration) * [Step 3: Testing](https://docs.elizaos.ai/guides/create-a-plugin#step-3%3A-testing) * [Test Plugin Functionality](https://docs.elizaos.ai/guides/create-a-plugin#test-plugin-functionality) * [Plugin Component Tests](https://docs.elizaos.ai/guides/create-a-plugin#plugin-component-tests) * [Plugin E2E Tests](https://docs.elizaos.ai/guides/create-a-plugin#plugin-e2e-tests) * [Step 4: Possible Next Steps](https://docs.elizaos.ai/guides/create-a-plugin#step-4%3A-possible-next-steps) * [Enhance Your Action](https://docs.elizaos.ai/guides/create-a-plugin#enhance-your-action) * [Add Plugin Components](https://docs.elizaos.ai/guides/create-a-plugin#add-plugin-components) * [See Also](https://docs.elizaos.ai/guides/create-a-plugin#see-also) **Video Tutorial**: [**Plugin Power: Add Superpowers to Your Agents**](https://www.youtube.com/watch?v=nC6veN2Q-ps&list=PLrjBjP4nU8ehOgKAa0-XddHzE0KK0nNvS&index=4) [​](https://docs.elizaos.ai/guides/create-a-plugin#what-we%E2%80%99ll-build) What We’ll Build ------------------------------------------------------------------------------------------------ This guide shows how to build a [fal.ai](https://fal.ai/) plugin that lets your agent generate 6-second, 768p videos from text prompts using the MiniMax Hailuo-02 model. For architectural concepts, see [Plugin Architecture](https://docs.elizaos.ai/plugins/architecture) . **You’ll learn:** * **Actions** (what the agent can DO) * **Progressive development** (start simple, organize as you grow) * **Local plugin testing** (character.plugins array method) * **Plugin testing** (component and E2E tests) For component details and patterns, see [Plugin Components](https://docs.elizaos.ai/plugins/components) and [Plugin Patterns](https://docs.elizaos.ai/plugins/patterns) . * * * [​](https://docs.elizaos.ai/guides/create-a-plugin#step-1%3A-quick-start) Step 1: Quick Start ------------------------------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/guides/create-a-plugin#create-project-and-plugin) Create Project and Plugin Create a project with a plugin inside using CLI commands: 1 Create project Terminal Copy Ask AI elizaos create --type project my-eliza-project Configure when prompted: * **Database**: PgLite (perfect for local development) * **Model**: OpenAI Terminal Copy Ask AI cd my-eliza-project 2 Create plugin inside project Terminal Copy Ask AI elizaos create --type plugin plugin-fal-ai When prompted, choose **Quick Plugin** (we don’t need frontend UI)Your structure now looks like: Copy Ask AI my-eliza-project/ ├── src/character.ts # Default Eliza character └── plugin-fal-ai/ # 👈 Plugin lives alongside project ├── src/ │ ├── index.ts # Plugin exports │ ├── plugin.ts # Main plugin (start here) │ └── __tests__/ # Plugin tests └── package.json 3 Add plugin to character In `my-eliza-project/src/character.ts`, add the local path to Eliza’s plugins array: src/character.ts Copy Ask AI export const character: Character = { name: 'Eliza', plugins: [\ '@elizaos/plugin-sql',\ '@elizaos/plugin-openai',\ '@elizaos/plugin-bootstrap',\ './plugin-fal-ai'\ ], }; ### [​](https://docs.elizaos.ai/guides/create-a-plugin#connect-and-test) Connect and Test 1 Build plugin and test connection The plugin needs to be built first to create the `dist/` folder that ElizaOS loads from: Terminal Copy Ask AI # Build the plugin first cd plugin-fal-ai bun run build # Go back to project and start cd .. elizaos start **Verify it’s loaded:** * Check the console logs for `Successfully loaded plugin 'plugin-fal-ai'` * Visit `http://localhost:3000` → click your agent → **Plugins tab** * * * [​](https://docs.elizaos.ai/guides/create-a-plugin#step-2%3A-development) Step 2: Development ------------------------------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/guides/create-a-plugin#research-the-api) Research the API Let’s research what we want to build by exploring [fal.ai](https://fal.ai/) for a good text-to-video model. [MiniMax Hailuo-02 Text to Video](https://fal.ai/models/fal-ai/minimax/hailuo-02/standard/text-to-video) looks pretty good. 4. **Navigate to the [JavaScript/Typescript section of the docs](https://docs.fal.ai/model-apis/clients/javascript) ** to see how to call the API: * Install: `bun add @fal-ai/client` * Import: `import { fal } from "@fal-ai/client"` * Use: `fal.subscribe("model-endpoint", { input: {...} })` * Returns: `{ data, requestId }` Now we know exactly what to build and how to call it, so let’s start developing our plugin. ### [​](https://docs.elizaos.ai/guides/create-a-plugin#edit-default-plugin-template) Edit Default Plugin Template 1 Add fal.ai dependency Terminal Copy Ask AI cd plugin-fal-ai bun add @fal-ai/client This adds the [fal.ai](https://fal.ai/) client package to your plugin dependencies. 2 Study the template structure Open `plugin-fal-ai/src/plugin.ts` to see the sample code patterns for plugins: * `quickAction` - example Action (what agent can DO) * `quickProvider` - example Provider (gives agent CONTEXT) * `StarterService` - example Service (manages state/connections) * Plugin events, routes, models - other comprehensive patterns 3 Create your text-to-video action using plugin patterns Copy the plugin file and rename it to create your action: Terminal Copy Ask AI mkdir src/actions cp src/plugin.ts src/actions/generateVideo.ts Now let’s edit the example plugin into our generateVideo action:**Add the fal.ai import (from the fal.ai docs):** src/actions/generateVideo.ts Copy Ask AI import { Action, ActionResult, IAgentRuntime, Memory, HandlerCallback, State, logger } from '@elizaos/core'; import { fal } from '@fal-ai/client'; **Update the action identity for video generation:** Copy Ask AI const quickAction: Action = { export const generateVideoAction: Action = { name: 'QUICK_ACTION', name: 'TEXT_TO_VIDEO', similes: ['GREET', 'SAY_HELLO', 'HELLO_WORLD'], similes: ['CREATE_VIDEO', 'MAKE_VIDEO', 'GENERATE_VIDEO', 'VIDEO_FROM_TEXT'], description: 'Responds with a simple hello world message', description: 'Generate a video from text using MiniMax Hailuo-02', **Replace validation with API key check:** Copy Ask AI validate: async (_runtime, _message, _state) => { return true; // Always valid }, validate: async (runtime: IAgentRuntime, message: Memory) => { const falKey = runtime.getSetting('FAL_KEY'); if (!falKey) { logger.error('FAL_KEY not found in environment variables'); return false; } return true; }, **Replace hello world logic with video generation:** Copy Ask AI handler: async (_runtime, message, _state, _options, callback) => { const response = 'Hello world!'; if (callback) { await callback({ text: response, actions: ['QUICK_ACTION'], source: message.content.source, }); } return { text: response, success: true, data: { actions: ['QUICK_ACTION'], source: message.content.source } }; }, handler: async ( runtime: IAgentRuntime, message: Memory, state: State | undefined, options: any, callback?: HandlerCallback ): Promise => { try { fal.config({ credentials: runtime.getSetting('FAL_KEY') }); let prompt = message.content.text.replace(/^(create video:|make video:)/i, '').trim(); if (!prompt) return { success: false, text: 'I need a description' }; const result = await fal.subscribe("fal-ai/minimax/hailuo-02/standard/text-to-video", { input: { prompt, duration: "6" }, logs: true }); const videoUrl = result.data.video.url; if (callback) await callback({ text: `✅ Video ready! ${videoUrl}` }); return { success: true, text: 'Video generated', data: { videoUrl, prompt } }; } catch (error) { return { success: false, text: `Failed: ${error.message}` }; } }, **Update examples for video conversations:** Copy Ask AI examples: [ \ [{ \ name: '{{name1}}', \ content: { text: 'Can you say hello?' } \ }, { \ name: '{{name2}}', \ content: { text: 'hello world!', actions: ['QUICK_ACTION'] } \ }] \ ], examples: [ \ [{ name: '{{user}}', content: { text: 'Create video: dolphins jumping' } }, \ { name: '{{agent}}', content: { text: 'Creating video!', actions: ['TEXT_TO_VIDEO'] }}] \ ], }; 4 Update index.ts to use your action Finally, update `src/index.ts` to use our new plugin: src/index.ts Copy Ask AI import { Plugin } from '@elizaos/core'; import { generateVideoAction } from './actions/generateVideo'; export const falaiPlugin: Plugin = { name: 'fal-ai', description: 'Generate videos using fal.ai MiniMax Hailuo-02', actions: [generateVideoAction], providers: [], services: [] }; export default falaiPlugin; export { generateVideoAction }; You can reference `plugin.ts` as well as other plugins from the [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) to see other plugin component examples (providers, services, etc.) as you expand your plugin. ### [​](https://docs.elizaos.ai/guides/create-a-plugin#add-configuration) Add Configuration 1 Get your fal.ai API key Get an API key from [fal.ai](https://fal.ai/) and copy/paste it into your .env: .env Copy Ask AI PGLITE_DATA_DIR=./.eliza/.elizadb OPENAI_API_KEY=your_openai_key_here FAL_KEY=your_fal_key_here * * * [​](https://docs.elizaos.ai/guides/create-a-plugin#step-3%3A-testing) Step 3: Testing ---------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/guides/create-a-plugin#test-plugin-functionality) Test Plugin Functionality Verify your plugin works as expected: 1 Test the updated plugin First rebuild your plugin to effect our changes, then start from project root: Terminal Copy Ask AI # Build the plugin first cd plugin-fal-ai bun run build # Start from project root cd .. elizaos start 2 Test video generation Try your new action by chatting with Eliza in the GUI (`http://localhost:3000`): * `"Create video: dolphins jumping in ocean"` * `"Make video: cat playing piano"` * `"Generate video: sunset over mountains"` You should see the video generation process and get a URL to view the result! ### [​](https://docs.elizaos.ai/guides/create-a-plugin#plugin-component-tests) Plugin Component Tests Plugins come default with component and E2E tests. Let’s add custom component tests: 1 Add a component test Update `plugin-fal-ai/src/__tests__/plugin.test.ts`: src/\_\_tests\_\_/plugin.test.ts Copy Ask AI import { describe, it, expect } from 'bun:test'; import { falaiPlugin, generateVideoAction } from '../index'; describe('FAL AI Plugin', () => { it('action validates with FAL_KEY', async () => { const mockRuntime = { getSetting: (key: string) => key === 'FAL_KEY' ? 'test-key' : null }; const isValid = await generateVideoAction.validate(mockRuntime as any, {} as any); expect(isValid).toBe(true); }); }); 2 Run component tests Terminal Copy Ask AI cd plugin-fal-ai elizaos test --type component ### [​](https://docs.elizaos.ai/guides/create-a-plugin#plugin-e2e-tests) Plugin E2E Tests Let’s also add a custom E2E test: 1 Add an E2E test Update `src/__tests__/e2e/plugin-fal-ai.e2e.ts`: src/\_\_tests\_\_/e2e/plugin-fal-ai.e2e.ts Copy Ask AI export const FalAiTestSuite = { name: 'fal-ai-video-generation', tests: [{ \ name: 'should find video action in runtime', \ fn: async (runtime) => { \ const action = runtime.actions.find(a => a.name === 'TEXT_TO_VIDEO'); \ if (!action) throw new Error('TEXT_TO_VIDEO action not found'); \ } \ }] }; 2 Run E2E tests Terminal Copy Ask AI cd plugin-fal-ai elizaos test --type e2e * * * [​](https://docs.elizaos.ai/guides/create-a-plugin#step-4%3A-possible-next-steps) Step 4: Possible Next Steps ---------------------------------------------------------------------------------------------------------------- Congratulations! You now have a working video generation plugin. Here are some ways you can improve it: ### [​](https://docs.elizaos.ai/guides/create-a-plugin#enhance-your-action) Enhance Your Action * **Add more similes** - Handle requests like “animate this”, “video of”, “show me a clip of” * **Better examples** - Add more conversation examples so Eliza learns different chat patterns * **Error handling** - Handle rate limits, invalid prompts, or API timeouts ### [​](https://docs.elizaos.ai/guides/create-a-plugin#add-plugin-components) Add Plugin Components * **Providers** - Give your agent context about recent videos or video history * **Evaluators** - Track analytics, log successful generations, or rate video quality * **Services** - Add queueing for multiple video requests or caching for common prompts The possibilities are endless! * * * [​](https://docs.elizaos.ai/guides/create-a-plugin#see-also) See Also ------------------------------------------------------------------------ [Publish a Plugin\ ----------------\ \ Share your plugin with the elizaOS community](https://docs.elizaos.ai/guides/publish-a-plugin) [Contribute to Core\ ------------------\ \ Help improve elizaOS by contributing to the core framework](https://docs.elizaos.ai/guides/contribute-to-core) [Plugin Registry\ ---------------\ \ Explore existing plugins and find inspiration](https://docs.elizaos.ai/plugin-registry/overview) [CLI Reference\ -------------\ \ Master all elizaOS CLI commands for plugin development](https://docs.elizaos.ai/cli-reference/overview) Was this page helpful? YesNo [Deploy a Project](https://docs.elizaos.ai/guides/deploy-a-project) [Publish a Plugin](https://docs.elizaos.ai/guides/publish-a-plugin) ⌘I --- # Publish a Plugin - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/guides/publish-a-plugin#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation GUIDES Publish a Plugin [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Step 1: Prepare for Publishing](https://docs.elizaos.ai/guides/publish-a-plugin#step-1%3A-prepare-for-publishing) * [Navigate to your plugin](https://docs.elizaos.ai/guides/publish-a-plugin#navigate-to-your-plugin) * [Verify plugin requirements](https://docs.elizaos.ai/guides/publish-a-plugin#verify-plugin-requirements) * [Step 2: Check authentication](https://docs.elizaos.ai/guides/publish-a-plugin#step-2%3A-check-authentication) * [Check npm login](https://docs.elizaos.ai/guides/publish-a-plugin#check-npm-login) * [Check GitHub authentication](https://docs.elizaos.ai/guides/publish-a-plugin#check-github-authentication) * [Step 3: Test Publishing (Dry Run)](https://docs.elizaos.ai/guides/publish-a-plugin#step-3%3A-test-publishing-dry-run) * [Run publish test](https://docs.elizaos.ai/guides/publish-a-plugin#run-publish-test) * [Run dry run (optional)](https://docs.elizaos.ai/guides/publish-a-plugin#run-dry-run-optional) * [Step 4: Publish Your Plugin](https://docs.elizaos.ai/guides/publish-a-plugin#step-4%3A-publish-your-plugin) * [Execute full publish](https://docs.elizaos.ai/guides/publish-a-plugin#execute-full-publish) * [Step 5: Registry Review Process](https://docs.elizaos.ai/guides/publish-a-plugin#step-5%3A-registry-review-process) * [What happens next](https://docs.elizaos.ai/guides/publish-a-plugin#what-happens-next) * [Registry approval](https://docs.elizaos.ai/guides/publish-a-plugin#registry-approval) * [Step 6: Post-Publishing](https://docs.elizaos.ai/guides/publish-a-plugin#step-6%3A-post-publishing) * [Plugin is now live!](https://docs.elizaos.ai/guides/publish-a-plugin#plugin-is-now-live) * [Future updates](https://docs.elizaos.ai/guides/publish-a-plugin#future-updates) * [See Also](https://docs.elizaos.ai/guides/publish-a-plugin#see-also) **Video Tutorial**: [**Create + Publish Your Own Plugin**](https://www.youtube.com/watch?v=3wVxXMwSzX4&list=PLrjBjP4nU8ehOgKAa0-XddHzE0KK0nNvS&index=6) This guide assumes you have a working plugin. If you need to create one first, see [Create a Plugin](https://docs.elizaos.ai/guides/create-a-plugin) Once you’ve built and tested your plugin locally, you’ll want to publish it so others can discover and use it. You’ll need an npm account and GitHub account for authentication. * * * [​](https://docs.elizaos.ai/guides/publish-a-plugin#step-1%3A-prepare-for-publishing) Step 1: Prepare for Publishing ----------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/guides/publish-a-plugin#navigate-to-your-plugin) Navigate to your plugin Start from your working plugin directory. If you followed the [Create a Plugin](https://docs.elizaos.ai/guides/create-a-plugin) guide: Terminal Copy Ask AI cd plugin-fal-ai ### [​](https://docs.elizaos.ai/guides/publish-a-plugin#verify-plugin-requirements) Verify plugin requirements Your plugin needs these key elements for registry acceptance: **Required files:** Copy Ask AI plugin-fal-ai/ ├── src/ │ └── index.ts # Your plugin code ├── images/ # Registry assets │ ├── logo.jpg # 400x400px, max 500KB │ └── banner.jpg # 1280x640px, max 1MB ├── package.json # Plugin metadata ├── README.md # Documentation └── dist/ # Built files (from `bun run build`) **What the publish command validates:** * `name` starts with `plugin-` (auto-added by CLI if missing) * Custom `description` (not the default generated placeholder) * Required images in `images/` directory 1 Add required images Create an `images/` directory if it doesn’t exist: Terminal Copy Ask AI mkdir -p images Add these two custom images for your plugin’s branding on the registry: * **`logo.jpg`** - 400x400px square logo (max 500KB) * **`banner.jpg`** - 1280x640px banner (max 1MB) Use high-quality images that represent your plugin’s functionality clearly. The logo will appear in plugin listings at various sizes. 2 Update package.json description Replace the default generated description with something descriptive: package.json Copy Ask AI { "name": "plugin-fal-ai", "version": "1.0.0", "description": "ElizaOS plugin for fal-ai", "description": "Generate videos from text using fal.ai MiniMax Hailuo-02 model", "keywords": ["plugin", "elizaos"] } 3 Build your plugin Ensure your plugin is built and ready: Terminal Copy Ask AI bun run build This creates the `dist/` folder that npm will publish. * * * [​](https://docs.elizaos.ai/guides/publish-a-plugin#step-2%3A-check-authentication) Step 2: Check authentication ------------------------------------------------------------------------------------------------------------------- Make sure you’re logged into both npm and GitHub: ### [​](https://docs.elizaos.ai/guides/publish-a-plugin#check-npm-login) Check npm login 1 Check current npm login Terminal Copy Ask AI npm whoami If you see your username, you’re already logged in. If you see an error, continue to the next step. 2 Login to npm (if needed) Terminal Copy Ask AI npm login Follow the prompts to enter your: * Username * Password * Email address * One-time password (if 2FA is enabled) ### [​](https://docs.elizaos.ai/guides/publish-a-plugin#check-github-authentication) Check GitHub authentication Terminal Copy Ask AI gh auth status If you see your GitHub username, you’re logged in. If you see an error or “not logged in”: Terminal Copy Ask AI gh auth login If `gh` command is not found, you’ll need to install GitHub CLI from [cli.github.com](https://cli.github.com/) or the publish command will prompt you to create a token manually. * * * [​](https://docs.elizaos.ai/guides/publish-a-plugin#step-3%3A-test-publishing-dry-run) Step 3: Test Publishing (Dry Run) --------------------------------------------------------------------------------------------------------------------------- Before actually publishing, test the entire process to catch any issues. ### [​](https://docs.elizaos.ai/guides/publish-a-plugin#run-publish-test) Run publish test Terminal Copy Ask AI elizaos publish --test This command will: * Check your npm and GitHub authentication * Validate your plugin structure * Check for required images and descriptions * Show you exactly what would happen without making any changes **Example output:** Copy Ask AI ✓ Found existing NPM login: your-username ✓ GitHub token validated ⚠ Plugin validation warnings: - Missing required logo.jpg in images/ directory (400x400px, max 500KB) - Missing required banner.jpg in images/ directory (1280x640px, max 1MB) - Description appears to be default generated description Your plugin may get rejected if you submit without addressing these issues. Do you wish to continue anyway? No Address any validation errors before proceeding. Your plugin may be rejected by maintainers if it’s missing required assets or has placeholder content. ### [​](https://docs.elizaos.ai/guides/publish-a-plugin#run-dry-run-optional) Run dry run (optional) For an even more detailed preview: Terminal Copy Ask AI elizaos publish --dry-run This generates all the registry files locally in `packages/registry/` so you can see exactly what will be submitted. * * * [​](https://docs.elizaos.ai/guides/publish-a-plugin#step-4%3A-publish-your-plugin) Step 4: Publish Your Plugin ----------------------------------------------------------------------------------------------------------------- Once your test passes and you’re satisfied with the setup, run the actual publish command. ### [​](https://docs.elizaos.ai/guides/publish-a-plugin#execute-full-publish) Execute full publish Terminal Copy Ask AI elizaos publish You will be asked for a scoped Github token and given these instructions: 1 Create GitHub Personal Access Token (when prompted) 1. Go to [GitHub Settings → Developer settings → Personal access tokens](https://github.com/settings/tokens) 2. Click **“Generate new token (classic)”** 3. Name it **“elizaOS Publishing”** 4. Select these scopes: * `repo` (Full control of private repositories) * `read:org` (Read organization membership) * `workflow` (Update GitHub Action workflows) 5. Click **“Generate token”** 6. **Copy the token and paste it when prompted by the CLI** ![GitHub token scope selection showing repo, read:org, and workflow checked](https://mintcdn.com/elizalabs/1-MWRiY1vBlWAlu3/images/github-token-scopes.png?w=2500&fit=max&auto=format&n=1-MWRiY1vBlWAlu3&q=85&s=553436f090664405ea07b45e41d3ffb1) Make sure to test that your plugin is configured correctly before publishing, as it will cause unnecessary delay if something is wrong. **Example successful output:** Copy Ask AI ✓ Successfully published plugin-fal-ai@1.0.0 to npm ✓ Created GitHub repository: yourusername/plugin-fal-ai ✓ Registry pull request created: https://github.com/elizaos-plugins/registry/pull/123 Your plugin is now available at: NPM: https://www.npmjs.com/package/plugin-fal-ai GitHub: https://github.com/yourusername/plugin-fal-ai * * * [​](https://docs.elizaos.ai/guides/publish-a-plugin#step-5%3A-registry-review-process) Step 5: Registry Review Process ------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/guides/publish-a-plugin#what-happens-next) What happens next 1. **npm Package** - Available immediately at `https://npmjs.com/package/your-plugin-name` 2. **GitHub Repo** - Created immediately at `https://github.com/yourusername/plugin-name` 3. **Registry Pull Request** - Opened at [elizaos-plugins/registry](https://github.com/elizaos-plugins/registry/pulls) ### [​](https://docs.elizaos.ai/guides/publish-a-plugin#registry-approval) Registry approval An elizaOS core team member will review your registry pull request to ensure all requirements are met, the plugin is free of malicious code, and it functions as intended with proper images and a quality description. **Typical review time:** 1-3 business days **If approved:** Your plugin appears in the official registry and can be discovered via `elizaos plugins list` **If changes requested:** Address the feedback and update your plugin, then re-submit. * * * [​](https://docs.elizaos.ai/guides/publish-a-plugin#step-6%3A-post-publishing) Step 6: Post-Publishing --------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/guides/publish-a-plugin#plugin-is-now-live) Plugin is now live! Once approved, users can install your plugin to their projects: Terminal Copy Ask AI elizaos plugins add plugin-fal-ai ### [​](https://docs.elizaos.ai/guides/publish-a-plugin#future-updates) Future updates **For plugin updates after initial publishing:** Terminal Copy Ask AI # 1. Make your changes and test locally # 2. Update version in package.json npm version patch # or minor/major # 3. Build and test bun run build elizaos test # 4. Publish to npm npm publish # 5. Push to GitHub git add . git commit -m "Update to version x.y.z" git push origin main The elizaOS registry automatically syncs with npm updates, so you don’t need to manually update the registry. * * * [​](https://docs.elizaos.ai/guides/publish-a-plugin#see-also) See Also ------------------------------------------------------------------------- [Contribute to Core\ ------------------\ \ Help improve elizaOS by contributing to the core framework](https://docs.elizaos.ai/guides/contribute-to-core) [Plugin Registry\ ---------------\ \ Explore existing plugins and find inspiration](https://docs.elizaos.ai/plugin-registry/overview) [CLI Reference\ -------------\ \ Master all elizaOS CLI commands for development](https://docs.elizaos.ai/cli-reference/overview) [Join Discord Community\ ----------------------\ \ Share your plugin and get help from the community](https://discord.gg/ai16z) Was this page helpful? YesNo [Create a Plugin](https://docs.elizaos.ai/guides/create-a-plugin) [Contribute to Core](https://docs.elizaos.ai/guides/contribute-to-core) ⌘I --- # Memory and State - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/agents/memory-and-state#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation AGENTS Memory and State [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Memory Architecture Overview](https://docs.elizaos.ai/agents/memory-and-state#memory-architecture-overview) * [Core Memory Concepts](https://docs.elizaos.ai/agents/memory-and-state#core-memory-concepts) * [Memory Interface](https://docs.elizaos.ai/agents/memory-and-state#memory-interface) * [Memory Lifecycle](https://docs.elizaos.ai/agents/memory-and-state#memory-lifecycle) * [1\. Creation](https://docs.elizaos.ai/agents/memory-and-state#1-creation) * [2\. Storage](https://docs.elizaos.ai/agents/memory-and-state#2-storage) * [3\. Retrieval](https://docs.elizaos.ai/agents/memory-and-state#3-retrieval) * [Context Management](https://docs.elizaos.ai/agents/memory-and-state#context-management) * [Context Window](https://docs.elizaos.ai/agents/memory-and-state#context-window) * [Context Selection Strategies](https://docs.elizaos.ai/agents/memory-and-state#context-selection-strategies) * [Recency-Based](https://docs.elizaos.ai/agents/memory-and-state#recency-based) * [Importance-Based](https://docs.elizaos.ai/agents/memory-and-state#importance-based) * [Hybrid Approach](https://docs.elizaos.ai/agents/memory-and-state#hybrid-approach) * [State Composition](https://docs.elizaos.ai/agents/memory-and-state#state-composition) * [Memory Types](https://docs.elizaos.ai/agents/memory-and-state#memory-types) * [Short-term Memory](https://docs.elizaos.ai/agents/memory-and-state#short-term-memory) * [Long-term Memory](https://docs.elizaos.ai/agents/memory-and-state#long-term-memory) * [Knowledge Memory](https://docs.elizaos.ai/agents/memory-and-state#knowledge-memory) * [Memory Operations](https://docs.elizaos.ai/agents/memory-and-state#memory-operations) * [Creating Memories](https://docs.elizaos.ai/agents/memory-and-state#creating-memories) * [Retrieving Memories](https://docs.elizaos.ai/agents/memory-and-state#retrieving-memories) * [Searching Memories](https://docs.elizaos.ai/agents/memory-and-state#searching-memories) * [Embeddings and Vectors](https://docs.elizaos.ai/agents/memory-and-state#embeddings-and-vectors) * [Embedding Generation](https://docs.elizaos.ai/agents/memory-and-state#embedding-generation) * [Vector Search](https://docs.elizaos.ai/agents/memory-and-state#vector-search) * [State Management](https://docs.elizaos.ai/agents/memory-and-state#state-management) * [State Structure](https://docs.elizaos.ai/agents/memory-and-state#state-structure) * [State Updates](https://docs.elizaos.ai/agents/memory-and-state#state-updates) * [Performance Optimization](https://docs.elizaos.ai/agents/memory-and-state#performance-optimization) * [Memory Pruning](https://docs.elizaos.ai/agents/memory-and-state#memory-pruning) * [Caching Strategies](https://docs.elizaos.ai/agents/memory-and-state#caching-strategies) * [Database Optimization](https://docs.elizaos.ai/agents/memory-and-state#database-optimization) * [Advanced Patterns](https://docs.elizaos.ai/agents/memory-and-state#advanced-patterns) * [Memory Networks](https://docs.elizaos.ai/agents/memory-and-state#memory-networks) * [Temporal Patterns](https://docs.elizaos.ai/agents/memory-and-state#temporal-patterns) * [Multi-agent Memory](https://docs.elizaos.ai/agents/memory-and-state#multi-agent-memory) * [Best Practices](https://docs.elizaos.ai/agents/memory-and-state#best-practices) * [Troubleshooting](https://docs.elizaos.ai/agents/memory-and-state#troubleshooting) * [Common Issues](https://docs.elizaos.ai/agents/memory-and-state#common-issues) * [Memory Search Not Finding Expected Results](https://docs.elizaos.ai/agents/memory-and-state#memory-search-not-finding-expected-results) * [Memory Leaks](https://docs.elizaos.ai/agents/memory-and-state#memory-leaks) * [See Also](https://docs.elizaos.ai/agents/memory-and-state#see-also) [​](https://docs.elizaos.ai/agents/memory-and-state#memory-architecture-overview) Memory Architecture Overview ----------------------------------------------------------------------------------------------------------------- In elizaOS, memory and state management are core responsibilities of the `AgentRuntime`. The system provides a unified API for creating, storing, retrieving, and searching memories, enabling agents to maintain context and learn from interactions. For runtime details, see [Runtime and Lifecycle](https://docs.elizaos.ai/agents/runtime-and-lifecycle) and [Runtime Core](https://docs.elizaos.ai/runtime/core) . [​](https://docs.elizaos.ai/agents/memory-and-state#core-memory-concepts) Core Memory Concepts ------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/memory-and-state#memory-interface) Memory Interface Every piece of information an agent processes becomes a Memory: Copy Ask AI interface Memory { id?: UUID; // Unique identifier entityId: UUID; // Who created this memory (user/agent) roomId: UUID; // Conversation context worldId?: UUID; // Broader context (e.g., server) content: Content; // The actual content embedding?: number[]; // Vector representation createdAt?: number; // Timestamp metadata?: MemoryMetadata; // Additional data } interface Content { text?: string; // Text content actions?: string[]; // Associated actions inReplyTo?: UUID; // Reference to previous memory metadata?: any; // Custom metadata } ### [​](https://docs.elizaos.ai/agents/memory-and-state#memory-lifecycle) Memory Lifecycle #### [​](https://docs.elizaos.ai/agents/memory-and-state#1-creation) 1\. Creation Copy Ask AI // Creating a memory through the runtime async function createMemory(runtime: IAgentRuntime, message: string) { const memory: CreateMemory = { agentId: runtime.agentId, entityId: userId, roomId: currentRoom, content: { text: message, metadata: { source: 'chat', processed: Date.now() } } }; // Runtime automatically generates embeddings if not provided const memoryId = await runtime.createMemory(memory); return memoryId; } #### [​](https://docs.elizaos.ai/agents/memory-and-state#2-storage) 2\. Storage Memories are persisted through the `IDatabaseAdapter`: Copy Ask AI // The runtime handles storage automatically // Memories are stored with: // - Full text for retrieval // - Embeddings for semantic search // - Metadata for filtering // - Relationships for context #### [​](https://docs.elizaos.ai/agents/memory-and-state#3-retrieval) 3\. Retrieval Copy Ask AI // Recent memories from a conversation const recentMemories = await runtime.getMemories({ roomId: roomId, count: 10, unique: true // Deduplicate similar memories }); // Memories from a specific user const userMemories = await runtime.getMemories({ entityId: userId, count: 20 }); // Time-bounded memories const todaysMemories = await runtime.getMemories({ roomId: roomId, start: startOfDay, end: endOfDay }); [​](https://docs.elizaos.ai/agents/memory-and-state#context-management) Context Management --------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/memory-and-state#context-window) Context Window The context window determines how much information the agent considers: Copy Ask AI // Context window configuration export class AgentRuntime { readonly #conversationLength = 32; // Default messages to consider // Dynamically adjust based on token limits async buildContext(roomId: UUID): Promise { const memories = await this.getMemories({ roomId, count: this.#conversationLength }); // Token counting and pruning let tokenCount = 0; const maxTokens = 4000; // Leave room for response const prunedMemories = []; for (const memory of memories) { const tokens = estimateTokens(memory.content.text); if (tokenCount + tokens > maxTokens) break; tokenCount += tokens; prunedMemories.push(memory); } return this.composeState(prunedMemories); } } ### [​](https://docs.elizaos.ai/agents/memory-and-state#context-selection-strategies) Context Selection Strategies #### [​](https://docs.elizaos.ai/agents/memory-and-state#recency-based) Recency-Based Most recent messages are most relevant: Copy Ask AI const recentContext = await runtime.getMemories({ roomId: roomId, count: 20, orderBy: 'createdAt', direction: 'DESC' }); #### [​](https://docs.elizaos.ai/agents/memory-and-state#importance-based) Importance-Based Prioritize important memories: Copy Ask AI // Importance scoring based on: // - User reactions // - Agent actions taken // - Explicit markers const importantMemories = await runtime.searchMemories({ roomId: roomId, filter: { importance: { $gte: 0.8 } }, count: 10 }); #### [​](https://docs.elizaos.ai/agents/memory-and-state#hybrid-approach) Hybrid Approach Combine recent and important: Copy Ask AI async function getHybridContext(runtime: IAgentRuntime, roomId: UUID) { // Get recent messages for immediate context const recent = await runtime.getMemories({ roomId, count: 10 }); // Get important historical context const important = await runtime.searchMemories({ roomId, query: "important decisions, key information, user preferences", match_threshold: 0.7, count: 5 }); // Combine and deduplicate const combined = [...recent, ...important]; return deduplicateMemories(combined); } ### [​](https://docs.elizaos.ai/agents/memory-and-state#state-composition) State Composition State composition brings together memories and provider data: Copy Ask AI // The runtime's state composition pipeline interface State { messages: Memory[]; // Conversation history facts: string[]; // Known facts providers: ProviderData[]; // Provider contributions context: string; // Formatted context } // Provider contribution to state export const userContextProvider: Provider = { name: 'userContext', get: async (runtime, message, state) => { const userProfile = await runtime.getEntity(message.entityId); return { text: `User: ${userProfile.name}`, data: { preferences: userProfile.metadata?.preferences, history: userProfile.metadata?.interactionCount } }; } }; [​](https://docs.elizaos.ai/agents/memory-and-state#memory-types) Memory Types --------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/memory-and-state#short-term-memory) Short-term Memory Working memory for immediate tasks: Copy Ask AI // Short-term memory is typically the current conversation class WorkingMemory { private buffer: Memory[] = []; private maxSize = 50; add(memory: Memory) { this.buffer.push(memory); if (this.buffer.length > this.maxSize) { this.buffer.shift(); // Remove oldest } } getRecent(count: number): Memory[] { return this.buffer.slice(-count); } clear() { this.buffer = []; } } ### [​](https://docs.elizaos.ai/agents/memory-and-state#long-term-memory) Long-term Memory Persistent storage of important information: Copy Ask AI // Long-term memories are marked and preserved interface LongTermMemory extends Memory { metadata: { type: 'long_term'; importance: number; lastAccessed: number; accessCount: number; }; } // Consolidation process async function consolidateToLongTerm( runtime: IAgentRuntime, memory: Memory ): Promise { if (shouldConsolidate(memory)) { await runtime.updateMemory({ ...memory, metadata: { ...memory.metadata, type: 'long_term', importance: calculateImportance(memory), consolidatedAt: Date.now() } }); } } ### [​](https://docs.elizaos.ai/agents/memory-and-state#knowledge-memory) Knowledge Memory Static and dynamic knowledge: Copy Ask AI // Knowledge loaded from character configuration const staticKnowledge = character.knowledge || []; // Dynamic knowledge learned during interactions async function learnFact(runtime: IAgentRuntime, fact: string) { await runtime.createMemory({ content: { text: fact, metadata: { type: 'knowledge', learned: true, confidence: 0.9 } }, roomId: 'knowledge-base', entityId: runtime.agentId }); } // Retrieving knowledge async function getKnowledge(runtime: IAgentRuntime, topic: string) { return await runtime.searchMemories({ query: topic, filter: { 'metadata.type': 'knowledge' }, match_threshold: 0.7 }); } [​](https://docs.elizaos.ai/agents/memory-and-state#memory-operations) Memory Operations ------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/memory-and-state#creating-memories) Creating Memories Best practices for memory creation: Copy Ask AI // Complete memory creation with all metadata async function createRichMemory( runtime: IAgentRuntime, content: string, context: any ): Promise { const memory: CreateMemory = { agentId: runtime.agentId, entityId: context.userId, roomId: context.roomId, content: { text: content, actions: context.actions || [], inReplyTo: context.replyTo, metadata: { source: context.source, platform: context.platform, sentiment: analyzeSentiment(content), topics: extractTopics(content), entities: extractEntities(content) } }, // Pre-compute embedding for better performance embedding: await runtime.embed(content) }; return await runtime.createMemory(memory); } ### [​](https://docs.elizaos.ai/agents/memory-and-state#retrieving-memories) Retrieving Memories Efficient retrieval patterns: Copy Ask AI // Paginated retrieval for large conversations async function getPaginatedMemories( runtime: IAgentRuntime, roomId: UUID, page: number = 1, pageSize: number = 20 ) { const offset = (page - 1) * pageSize; return await runtime.getMemories({ roomId, count: pageSize, offset }); } // Filtered retrieval async function getFilteredMemories( runtime: IAgentRuntime, filters: MemoryFilters ) { return await runtime.getMemories({ roomId: filters.roomId, entityId: filters.entityId, start: filters.startDate, end: filters.endDate, filter: { 'content.actions': { $contains: filters.action }, 'metadata.sentiment': filters.sentiment } }); } ### [​](https://docs.elizaos.ai/agents/memory-and-state#searching-memories) Searching Memories Advanced search capabilities: Copy Ask AI // Semantic search with embeddings async function semanticSearch( runtime: IAgentRuntime, query: string, options: SearchOptions = {} ): Promise { const embedding = await runtime.embed(query); return await runtime.searchMemoriesByEmbedding(embedding, { match_threshold: options.threshold || 0.75, count: options.limit || 10, roomId: options.roomId, filter: options.filter }); } // Hybrid search combining semantic and keyword async function hybridSearch( runtime: IAgentRuntime, query: string ): Promise { // Semantic search const semantic = await semanticSearch(runtime, query); // Keyword search const keywords = extractKeywords(query); const keyword = await runtime.searchMemories({ text: keywords.join(' OR '), count: 10 }); // Combine and rank return rankSearchResults([...semantic, ...keyword]); } [​](https://docs.elizaos.ai/agents/memory-and-state#embeddings-and-vectors) Embeddings and Vectors ----------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/memory-and-state#embedding-generation) Embedding Generation How and when embeddings are created: Copy Ask AI // Automatic embedding generation class EmbeddingManager { private model: EmbeddingModel; private cache = new Map(); async generateEmbedding(text: string): Promise { // Check cache first const cached = this.cache.get(text); if (cached) return cached; // Generate new embedding const embedding = await this.model.embed(text); // Cache for reuse this.cache.set(text, embedding); return embedding; } // Batch processing for efficiency async generateBatch(texts: string[]): Promise { const uncached = texts.filter(t => !this.cache.has(t)); if (uncached.length > 0) { const embeddings = await this.model.embedBatch(uncached); uncached.forEach((text, i) => { this.cache.set(text, embeddings[i]); }); } return texts.map(t => this.cache.get(t)!); } } ### [​](https://docs.elizaos.ai/agents/memory-and-state#vector-search) Vector Search Efficient similarity search: Copy Ask AI // Vector similarity calculation function cosineSimilarity(a: number[], b: number[]): number { let dotProduct = 0; let normA = 0; let normB = 0; for (let i = 0; i < a.length; i++) { dotProduct += a[i] * b[i]; normA += a[i] * a[i]; normB += b[i] * b[i]; } return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB)); } // Optimized vector search with indexing class VectorIndex { private index: AnnoyIndex; // Approximate nearest neighbor async search( query: number[], k: number = 10 ): Promise { const neighbors = await this.index.getNearestNeighbors(query, k); return neighbors.map(n => ({ id: n.id, similarity: n.distance, memory: this.getMemory(n.id) })); } // Periodic index rebuilding for new memories async rebuild() { const memories = await this.getAllMemories(); this.index = new AnnoyIndex(memories); await this.index.build(); } } [​](https://docs.elizaos.ai/agents/memory-and-state#state-management) State Management ----------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/memory-and-state#state-structure) State Structure The complete state object: Copy Ask AI interface State { // Core conversation context messages: Memory[]; recentMessages: string; // Agent knowledge facts: string[]; knowledge: string; // Provider contributions providers: { [key: string]: { text: string; data: any; }; }; // Composed context context: string; // Metadata metadata: { roomId: UUID; entityId: UUID; timestamp: number; tokenCount: number; }; } ### [​](https://docs.elizaos.ai/agents/memory-and-state#state-updates) State Updates Managing state changes: Copy Ask AI class StateManager { private currentState: State; private stateHistory: State[] = []; private maxHistory = 10; async updateState(runtime: IAgentRuntime, trigger: Memory) { // Save current state to history this.stateHistory.push(this.currentState); if (this.stateHistory.length > this.maxHistory) { this.stateHistory.shift(); } // Build new state this.currentState = await this.buildState(runtime, trigger); // Notify listeners this.emitStateChange(this.currentState); return this.currentState; } private async buildState( runtime: IAgentRuntime, trigger: Memory ): Promise { // Get relevant memories const memories = await runtime.getMemories({ roomId: trigger.roomId, count: 20 }); // Get provider data const providers = await this.gatherProviderData(runtime, trigger); // Compose final state return runtime.composeState({ messages: memories, providers, trigger }); } } [​](https://docs.elizaos.ai/agents/memory-and-state#performance-optimization) Performance Optimization --------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/memory-and-state#memory-pruning) Memory Pruning Strategies for managing memory size: Copy Ask AI // Time-based pruning async function pruneOldMemories( runtime: IAgentRuntime, maxAge: number = 30 * 24 * 60 * 60 * 1000 // 30 days ) { const cutoff = Date.now() - maxAge; await runtime.deleteMemories({ filter: { createdAt: { $lt: cutoff }, 'metadata.type': { $ne: 'long_term' } // Preserve long-term } }); } // Importance-based pruning async function pruneByImportance( runtime: IAgentRuntime, maxMemories: number = 10000 ) { const memories = await runtime.getAllMemories(); if (memories.length <= maxMemories) return; // Score and sort memories const scored = memories.map(m => ({ memory: m, score: calculateImportanceScore(m) })); scored.sort((a, b) => b.score - a.score); // Keep top memories, delete rest const toDelete = scored.slice(maxMemories); for (const item of toDelete) { await runtime.deleteMemory(item.memory.id); } } ### [​](https://docs.elizaos.ai/agents/memory-and-state#caching-strategies) Caching Strategies Multi-level caching for performance: Copy Ask AI class MemoryCache { private l1Cache = new Map(); // Hot cache (in-memory) private l2Cache = new LRUCache({ // Warm cache max: 1000, ttl: 5 * 60 * 1000 // 5 minutes }); async get(id: UUID): Promise { // Check L1 if (this.l1Cache.has(id)) { return this.l1Cache.get(id); } // Check L2 const l2Result = this.l2Cache.get(id); if (l2Result) { this.l1Cache.set(id, l2Result); // Promote to L1 return l2Result; } // Fetch from database const memory = await this.fetchFromDB(id); if (memory) { this.cache(memory); } return memory; } private cache(memory: Memory) { this.l1Cache.set(memory.id, memory); this.l2Cache.set(memory.id, memory); // Manage L1 size if (this.l1Cache.size > 100) { const oldest = this.l1Cache.keys().next().value; this.l1Cache.delete(oldest); } } } ### [​](https://docs.elizaos.ai/agents/memory-and-state#database-optimization) Database Optimization Query optimization techniques: Copy Ask AI // Indexed queries interface MemoryIndexes { roomId: BTreeIndex; entityId: BTreeIndex; createdAt: BTreeIndex; embedding: IVFIndex; // Inverted file index for vectors } // Batch operations async function batchCreateMemories( runtime: IAgentRuntime, memories: CreateMemory[] ): Promise { // Generate embeddings in batch const texts = memories.map(m => m.content.text); const embeddings = await runtime.embedBatch(texts); // Prepare batch insert const enriched = memories.map((m, i) => ({ ...m, embedding: embeddings[i] })); // Single database transaction return await runtime.batchCreateMemories(enriched); } [​](https://docs.elizaos.ai/agents/memory-and-state#advanced-patterns) Advanced Patterns ------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/memory-and-state#memory-networks) Memory Networks Building relationships between memories: Copy Ask AI // Memory graph structure interface MemoryNode { memory: Memory; connections: { causes: UUID[]; // Memories that led to this effects: UUID[]; // Memories caused by this related: UUID[]; // Thematically related references: UUID[]; // Explicit references }; } // Building memory graphs async function buildMemoryGraph( runtime: IAgentRuntime, rootMemoryId: UUID ): Promise { const visited = new Set(); const graph = new Map(); async function traverse(memoryId: UUID, depth: number = 0) { if (visited.has(memoryId) || depth > 3) return; visited.add(memoryId); const memory = await runtime.getMemory(memoryId); const connections = await findConnections(runtime, memory); graph.set(memoryId, { memory, connections }); // Recursively traverse connections for (const connectedId of Object.values(connections).flat()) { await traverse(connectedId, depth + 1); } } await traverse(rootMemoryId); return graph; } ### [​](https://docs.elizaos.ai/agents/memory-and-state#temporal-patterns) Temporal Patterns Time-aware memory retrieval: Copy Ask AI // Temporal memory windows async function getTemporalContext( runtime: IAgentRuntime, timestamp: number, windowSize: number = 60 * 60 * 1000 // 1 hour ) { return await runtime.getMemories({ start: timestamp - windowSize / 2, end: timestamp + windowSize / 2, orderBy: 'createdAt' }); } // Memory decay modeling function calculateMemoryRelevance( memory: Memory, currentTime: number ): number { const age = currentTime - memory.createdAt; const halfLife = 7 * 24 * 60 * 60 * 1000; // 1 week // Exponential decay with importance modifier const decay = Math.exp(-age / halfLife); const importance = memory.metadata?.importance || 0.5; return decay * importance; } ### [​](https://docs.elizaos.ai/agents/memory-and-state#multi-agent-memory) Multi-agent Memory Shared memory spaces between agents: Copy Ask AI // Shared memory pool interface SharedMemorySpace { id: UUID; agents: UUID[]; visibility: 'public' | 'private' | 'selective'; permissions: { [agentId: string]: { read: boolean; write: boolean; delete: boolean; }; }; } // Accessing shared memories async function getSharedMemories( runtime: IAgentRuntime, spaceId: UUID ): Promise { // Check permissions const space = await runtime.getSharedSpace(spaceId); const permissions = space.permissions[runtime.agentId]; if (!permissions?.read) { throw new Error('No read access to shared space'); } return await runtime.getMemories({ spaceId, visibility: ['public', runtime.agentId] }); } // Memory synchronization async function syncMemories( runtime: IAgentRuntime, otherAgentId: UUID ) { const sharedSpace = await runtime.getSharedSpace(otherAgentId); const updates = await runtime.getMemoryUpdates(sharedSpace.lastSync); for (const update of updates) { await runtime.applyMemoryUpdate(update); } sharedSpace.lastSync = Date.now(); } [​](https://docs.elizaos.ai/agents/memory-and-state#best-practices) Best Practices ------------------------------------------------------------------------------------- 1. **Always provide embeddings**: Pre-compute embeddings when creating memories for better search performance 2. **Use appropriate retrieval methods**: Semantic search for meaning, recency for context, filters for precision 3. **Implement memory hygiene**: Regular pruning and consolidation to maintain performance 4. **Cache strategically**: Multi-level caching for frequently accessed memories 5. **Batch operations**: Process multiple memories together when possible 6. **Index appropriately**: Create indexes for common query patterns 7. **Monitor memory growth**: Track memory usage and implement limits 8. **Preserve important memories**: Mark and protect critical information from pruning 9. **Version memory schemas**: Plan for memory structure evolution 10. **Test retrieval accuracy**: Regularly evaluate search relevance [​](https://docs.elizaos.ai/agents/memory-and-state#troubleshooting) Troubleshooting --------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/memory-and-state#common-issues) Common Issues #### [​](https://docs.elizaos.ai/agents/memory-and-state#memory-search-not-finding-expected-results) Memory Search Not Finding Expected Results Copy Ask AI // Debug search issues async function debugSearch(runtime: IAgentRuntime, query: string) { // Check embedding generation const embedding = await runtime.embed(query); console.log('Query embedding:', embedding.slice(0, 5)); // Test with different thresholds const thresholds = [0.9, 0.8, 0.7, 0.6, 0.5]; for (const threshold of thresholds) { const results = await runtime.searchMemoriesByEmbedding(embedding, { match_threshold: threshold, count: 5 }); console.log(`Threshold ${threshold}: ${results.length} results`); } // Check if memories exist at all const allMemories = await runtime.getMemories({ count: 100 }); console.log(`Total memories: ${allMemories.length}`); } #### [​](https://docs.elizaos.ai/agents/memory-and-state#memory-leaks) Memory Leaks Copy Ask AI // Monitor memory usage class MemoryMonitor { private metrics = { totalMemories: 0, averageSize: 0, growthRate: 0 }; async monitor(runtime: IAgentRuntime) { setInterval(async () => { const stats = await runtime.getMemoryStats(); this.metrics = { totalMemories: stats.count, averageSize: stats.totalSize / stats.count, growthRate: (stats.count - this.metrics.totalMemories) / this.metrics.totalMemories }; if (this.metrics.growthRate > 0.1) { // 10% growth console.warn('High memory growth detected:', this.metrics); } }, 60000); // Check every minute } } [​](https://docs.elizaos.ai/agents/memory-and-state#see-also) See Also ------------------------------------------------------------------------- [Character Interface\ -------------------\ \ Define your agent’s character configuration](https://docs.elizaos.ai/agents/character-interface) [Personality & Behavior\ ----------------------\ \ Craft unique agent personalities](https://docs.elizaos.ai/agents/personality-and-behavior) [Runtime & Lifecycle\ -------------------\ \ Learn how memory integrates with the runtime](https://docs.elizaos.ai/agents/runtime-and-lifecycle) [Plugin Development\ ------------------\ \ Build providers that contribute to state](https://docs.elizaos.ai/plugins/development) Was this page helpful? YesNo [Personality and Behavior](https://docs.elizaos.ai/agents/personality-and-behavior) [Runtime and Lifecycle](https://docs.elizaos.ai/agents/runtime-and-lifecycle) ⌘I --- # Runtime and Lifecycle - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/agents/runtime-and-lifecycle#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation AGENTS Runtime and Lifecycle [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Agent Lifecycle Overview](https://docs.elizaos.ai/agents/runtime-and-lifecycle#agent-lifecycle-overview) * [Character to Agent Transformation](https://docs.elizaos.ai/agents/runtime-and-lifecycle#character-to-agent-transformation) * [Loading Characters](https://docs.elizaos.ai/agents/runtime-and-lifecycle#loading-characters) * [Character Validation](https://docs.elizaos.ai/agents/runtime-and-lifecycle#character-validation) * [Agent Instantiation](https://docs.elizaos.ai/agents/runtime-and-lifecycle#agent-instantiation) * [Runtime Architecture](https://docs.elizaos.ai/agents/runtime-and-lifecycle#runtime-architecture) * [AgentRuntime Core](https://docs.elizaos.ai/agents/runtime-and-lifecycle#agentruntime-core) * [Component Management](https://docs.elizaos.ai/agents/runtime-and-lifecycle#component-management) * [Plugin Integration](https://docs.elizaos.ai/agents/runtime-and-lifecycle#plugin-integration) * [Plugin Loading Process](https://docs.elizaos.ai/agents/runtime-and-lifecycle#plugin-loading-process) * [Plugin Lifecycle Hooks](https://docs.elizaos.ai/agents/runtime-and-lifecycle#plugin-lifecycle-hooks) * [Component Orchestration](https://docs.elizaos.ai/agents/runtime-and-lifecycle#component-orchestration) * [Action Selection and Execution](https://docs.elizaos.ai/agents/runtime-and-lifecycle#action-selection-and-execution) * [Provider Composition](https://docs.elizaos.ai/agents/runtime-and-lifecycle#provider-composition) * [Evaluator Execution](https://docs.elizaos.ai/agents/runtime-and-lifecycle#evaluator-execution) * [Service Management](https://docs.elizaos.ai/agents/runtime-and-lifecycle#service-management) * [Service Registration](https://docs.elizaos.ai/agents/runtime-and-lifecycle#service-registration) * [Service Lifecycle](https://docs.elizaos.ai/agents/runtime-and-lifecycle#service-lifecycle) * [Multi-agent Systems](https://docs.elizaos.ai/agents/runtime-and-lifecycle#multi-agent-systems) * [Agent Coordination](https://docs.elizaos.ai/agents/runtime-and-lifecycle#agent-coordination) * [Agent Hierarchies](https://docs.elizaos.ai/agents/runtime-and-lifecycle#agent-hierarchies) * [Production Considerations](https://docs.elizaos.ai/agents/runtime-and-lifecycle#production-considerations) * [Initialization Strategies](https://docs.elizaos.ai/agents/runtime-and-lifecycle#initialization-strategies) * [Error Recovery](https://docs.elizaos.ai/agents/runtime-and-lifecycle#error-recovery) * [Monitoring and Metrics](https://docs.elizaos.ai/agents/runtime-and-lifecycle#monitoring-and-metrics) * [Scaling Strategies](https://docs.elizaos.ai/agents/runtime-and-lifecycle#scaling-strategies) * [Deployment Patterns](https://docs.elizaos.ai/agents/runtime-and-lifecycle#deployment-patterns) * [Single Agent Deployment](https://docs.elizaos.ai/agents/runtime-and-lifecycle#single-agent-deployment) * [Agent Swarm Deployment](https://docs.elizaos.ai/agents/runtime-and-lifecycle#agent-swarm-deployment) * [Edge Deployment](https://docs.elizaos.ai/agents/runtime-and-lifecycle#edge-deployment) * [Best Practices](https://docs.elizaos.ai/agents/runtime-and-lifecycle#best-practices) * [Troubleshooting](https://docs.elizaos.ai/agents/runtime-and-lifecycle#troubleshooting) * [Common Runtime Issues](https://docs.elizaos.ai/agents/runtime-and-lifecycle#common-runtime-issues) * [Agent Not Responding](https://docs.elizaos.ai/agents/runtime-and-lifecycle#agent-not-responding) * [Plugin Loading Failures](https://docs.elizaos.ai/agents/runtime-and-lifecycle#plugin-loading-failures) * [See Also](https://docs.elizaos.ai/agents/runtime-and-lifecycle#see-also) [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#agent-lifecycle-overview) Agent Lifecycle Overview -------------------------------------------------------------------------------------------------------------- The journey from a static Character configuration to a live, interactive Agent involves several distinct phases, each managed by the `AgentRuntime`. For character structure details, see [Character Interface](https://docs.elizaos.ai/agents/character-interface) . [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#character-to-agent-transformation) Character to Agent Transformation -------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#loading-characters) Loading Characters Characters can be loaded from various sources: Copy Ask AI // From TypeScript file import { character } from './character'; // From JSON file import characterJson from './character.json'; // From environment const character = { name: process.env.AGENT_NAME || 'DefaultAgent', bio: process.env.AGENT_BIO || 'A helpful assistant', // ... other properties from env }; // Dynamic loading async function loadCharacter(source: string): Promise { if (source.endsWith('.json')) { const data = await fs.readFile(source, 'utf-8'); return JSON.parse(data); } else if (source.endsWith('.ts')) { const module = await import(source); return module.character || module.default; } else if (source.startsWith('http')) { const response = await fetch(source); return await response.json(); } throw new Error(`Unknown character source: ${source}`); } ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#character-validation) Character Validation Before creating an agent, the character must be validated: Copy Ask AI import { validateCharacter } from '@elizaos/core'; function validateAndPrepareCharacter(character: Partial): Character { // Required fields if (!character.name) { throw new Error('Character name is required'); } if (!character.bio || (Array.isArray(character.bio) && character.bio.length === 0)) { throw new Error('Character bio is required'); } // Set defaults const prepared: Character = { ...character, id: character.id || stringToUuid(character.name), username: character.username || character.name.toLowerCase().replace(/\s+/g, '_'), topics: character.topics || [], adjectives: character.adjectives || [], messageExamples: character.messageExamples || [], postExamples: character.postExamples || [], style: { all: character.style?.all || [], chat: character.style?.chat || [], post: character.style?.post || [], }, settings: character.settings || {}, secrets: character.secrets || {}, plugins: character.plugins || [], }; // Validate structure const validation = validateCharacter(prepared); if (!validation.valid) { throw new Error(`Character validation failed: ${validation.errors.join(', ')}`); } return prepared; } ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#agent-instantiation) Agent Instantiation The transformation from Character to Agent: Copy Ask AI interface Agent extends Character { enabled?: boolean; status?: AgentStatus; createdAt: number; updatedAt: number; } enum AgentStatus { ACTIVE = 'active', INACTIVE = 'inactive', } // Creating an Agent from a Character function createAgent(character: Character): Agent { return { ...character, enabled: true, status: AgentStatus.INACTIVE, // Will become ACTIVE after initialization createdAt: Date.now(), updatedAt: Date.now() }; } [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#runtime-architecture) Runtime Architecture ------------------------------------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#agentruntime-core) AgentRuntime Core The `AgentRuntime` is the central orchestrator: Copy Ask AI export class AgentRuntime implements IAgentRuntime { readonly agentId: UUID; readonly character: Character; public adapter!: IDatabaseAdapter; readonly actions: Action[] = []; readonly evaluators: Evaluator[] = []; readonly providers: Provider[] = []; readonly plugins: Plugin[] = []; services = new Map(); models = new Map(); constructor(opts: { character: Character; adapter?: IDatabaseAdapter; plugins?: Plugin[]; settings?: RuntimeSettings; }) { this.agentId = opts.character.id || stringToUuid(opts.character.name); this.character = opts.character; if (opts.adapter) { this.registerDatabaseAdapter(opts.adapter); } this.characterPlugins = opts.plugins || []; this.settings = opts.settings || {}; this.logger = createLogger({ namespace: this.character.name }); } async initialize(): Promise { this.logger.info('Initializing AgentRuntime...'); // 1. Connect to database await this.adapter.init(); // 2. Resolve and load plugins await this.loadPlugins(); // 3. Start services await this.startServices(); // 4. Initialize providers await this.initializeProviders(); // 5. Set agent status await this.updateAgentStatus(AgentStatus.ACTIVE); this.isInitialized = true; this.logger.info('AgentRuntime initialized successfully'); } } ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#component-management) Component Management How the runtime manages different component types: Copy Ask AI class AgentRuntime { // Action registration and management registerAction(action: Action): void { if (this.actions.find(a => a.name === action.name)) { throw new Error(`Action ${action.name} already registered`); } this.actions.push(action); this.logger.debug(`Registered action: ${action.name}`); } // Provider registration and management registerProvider(provider: Provider): void { if (this.providers.find(p => p.name === provider.name)) { throw new Error(`Provider ${provider.name} already registered`); } this.providers.push(provider); this.logger.debug(`Registered provider: ${provider.name}`); } // Service registration and lifecycle async registerService(ServiceClass: typeof Service): Promise { const serviceName = ServiceClass.serviceType; // Check if already registered if (this.services.has(serviceName)) { return this.services.get(serviceName)[0]; } // Create and start service const service = new ServiceClass(this); await service.start(); this.services.set(serviceName, [service]); this.logger.info(`Service ${serviceName} started`); return service; } // Get a registered service getService(name: ServiceTypeName): T | null { const services = this.services.get(name); return services?.[0] as T || null; } } [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#plugin-integration) Plugin Integration -------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#plugin-loading-process) Plugin Loading Process The complete plugin loading lifecycle: Copy Ask AI class AgentRuntime { private async loadPlugins(): Promise { // 1. Resolve all plugin dependencies const pluginsToLoad = await this.resolvePluginDependencies(this.characterPlugins); // 2. Sort plugins by dependency order const sortedPlugins = this.topologicalSort(pluginsToLoad); // 3. Load each plugin in order for (const plugin of sortedPlugins) { await this.registerPlugin(plugin); } } private async resolvePluginDependencies(plugins: Plugin[]): Promise { const resolved = new Map(); const queue = [...plugins]; while (queue.length > 0) { const plugin = queue.shift()!; if (resolved.has(plugin.name)) continue; resolved.set(plugin.name, plugin); // Add dependencies to queue if (plugin.dependencies) { for (const depName of plugin.dependencies) { const dep = this.allAvailablePlugins.get(depName); if (dep && !resolved.has(depName)) { queue.push(dep); } } } } return Array.from(resolved.values()); } async registerPlugin(plugin: Plugin): Promise { this.logger.info(`Registering plugin: ${plugin.name}`); // 1. Call plugin's init function if (plugin.init) { await plugin.init(plugin.config || {}, this); } // 2. Register services if (plugin.services) { for (const ServiceClass of plugin.services) { await this.registerService(ServiceClass); } } // 3. Register actions if (plugin.actions) { for (const action of plugin.actions) { this.registerAction(action); } } // 4. Register providers if (plugin.providers) { for (const provider of plugin.providers) { this.registerProvider(provider); } } // 5. Register evaluators if (plugin.evaluators) { for (const evaluator of plugin.evaluators) { this.registerEvaluator(evaluator); } } // 6. Register models if (plugin.models) { for (const [type, handler] of Object.entries(plugin.models)) { this.registerModel(type, handler, plugin.name, plugin.priority); } } this.plugins.push(plugin); this.logger.info(`Plugin ${plugin.name} registered successfully`); } } ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#plugin-lifecycle-hooks) Plugin Lifecycle Hooks Plugins can hook into various lifecycle events: Copy Ask AI interface Plugin { // Initialization - called when plugin is loaded init?: (config: any, runtime: IAgentRuntime) => Promise; // Start - called when runtime starts start?: (runtime: IAgentRuntime) => Promise; // Stop - called when runtime stops stop?: (runtime: IAgentRuntime) => Promise; // Message hooks beforeMessage?: (message: Memory, runtime: IAgentRuntime) => Promise; afterMessage?: (message: Memory, response: Memory, runtime: IAgentRuntime) => Promise; // Action hooks beforeAction?: (action: Action, message: Memory, runtime: IAgentRuntime) => Promise; afterAction?: (action: Action, result: any, runtime: IAgentRuntime) => Promise; } // Example plugin with lifecycle hooks const lifecyclePlugin: Plugin = { name: 'lifecycle-example', async init(config, runtime) { console.log('Plugin initializing...'); // Setup plugin resources }, async start(runtime) { console.log('Plugin starting...'); // Start background tasks }, async stop(runtime) { console.log('Plugin stopping...'); // Cleanup resources }, async beforeMessage(message, runtime) { // Modify or validate message before processing return { ...message, metadata: { ...message.metadata, preprocessed: true } }; }, async afterMessage(message, response, runtime) { // Log, analyze, or store conversation await runtime.createMemory({ content: { text: `Processed: ${message.content.text}`, metadata: { type: 'conversation_log' } } }); } }; [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#component-orchestration) Component Orchestration ------------------------------------------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#action-selection-and-execution) Action Selection and Execution How the runtime selects and executes actions: Copy Ask AI class ActionOrchestrator { async selectAction( runtime: IAgentRuntime, message: Memory, state: State ): Promise { // 1. Get all available actions const availableActions = runtime.actions; // 2. Validate which actions can handle this message const validActions = await Promise.all( availableActions.map(async action => { try { const isValid = await action.validate?.(runtime, message, state); return isValid ? action : null; } catch (error) { runtime.logger.error(`Validation error for ${action.name}:`, error); return null; } }) ); const candidates = validActions.filter(Boolean); if (candidates.length === 0) return null; // 3. Use LLM to select best action const selectedAction = await this.selectWithLLM( runtime, candidates, message, state ); return selectedAction; } async executeAction( runtime: IAgentRuntime, action: Action, message: Memory, state: State ): Promise { const startTime = Date.now(); try { // Pre-execution hook if (runtime.currentPlugin?.beforeAction) { const shouldContinue = await runtime.currentPlugin.beforeAction( action, message, runtime ); if (!shouldContinue) { return { success: false, reason: 'Blocked by plugin' }; } } // Execute action const result = await action.handler( runtime, message, state, {}, (response) => { // Callback for streaming responses runtime.emit('action:response', { action: action.name, response }); } ); // Post-execution hook if (runtime.currentPlugin?.afterAction) { await runtime.currentPlugin.afterAction(action, result, runtime); } // Log execution runtime.logger.info(`Action ${action.name} executed in ${Date.now() - startTime}ms`); return { success: true, data: result, executionTime: Date.now() - startTime }; } catch (error) { runtime.logger.error(`Action ${action.name} failed:`, error); return { success: false, error: error.message, executionTime: Date.now() - startTime }; } } } ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#provider-composition) Provider Composition How providers contribute to state: Copy Ask AI class ProviderOrchestrator { async composeState( runtime: IAgentRuntime, message: Memory ): Promise { const state: State = { messages: [], facts: [], providers: {}, context: '', metadata: { roomId: message.roomId, entityId: message.entityId, timestamp: Date.now(), tokenCount: 0 } }; // 1. Get recent messages state.messages = await runtime.getMemories({ roomId: message.roomId, count: runtime.conversationLength }); // 2. Run all providers in parallel const providerPromises = runtime.providers.map(async provider => { try { const result = await provider.get(runtime, message, state); return { name: provider.name, result }; } catch (error) { runtime.logger.error(`Provider ${provider.name} failed:`, error); return null; } }); const providerResults = await Promise.all(providerPromises); // 3. Merge provider data into state for (const item of providerResults) { if (!item) continue; state.providers[item.name] = { text: item.result.text || '', data: item.result.data || {} }; // Add to context if (item.result.text) { state.context += `\n[${item.name.toUpperCase()}]\n${item.result.text}\n`; } } // 4. Calculate token count state.metadata.tokenCount = this.estimateTokens(state.context); return state; } } ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#evaluator-execution) Evaluator Execution Post-processing with evaluators: Copy Ask AI class EvaluatorOrchestrator { async runEvaluators( runtime: IAgentRuntime, message: Memory, response: Memory, state: State ): Promise { const results: EvaluationResults = {}; // Filter evaluators that should run const evaluatorsToRun = runtime.evaluators.filter(evaluator => { // Always run if marked as alwaysRun if (evaluator.alwaysRun) return true; // Run if agent responded if (response) return true; // Check custom conditions return evaluator.shouldRun?.(message, state); }); // Run evaluators in parallel const evaluationPromises = evaluatorsToRun.map(async evaluator => { try { const result = await evaluator.handler( runtime, message, state, {}, () => {}, // Callback [response] // Response array ); return { name: evaluator.name, result }; } catch (error) { runtime.logger.error(`Evaluator ${evaluator.name} failed:`, error); return { name: evaluator.name, error }; } }); const evaluations = await Promise.all(evaluationPromises); // Process results for (const evaluation of evaluations) { if (evaluation.error) { results[evaluation.name] = { success: false, error: evaluation.error }; } else { results[evaluation.name] = { success: true, data: evaluation.result }; } } // Store evaluation results await this.storeEvaluations(runtime, message, response, results); return results; } } [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#service-management) Service Management -------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#service-registration) Service Registration Services are long-running components: Copy Ask AI abstract class Service { static serviceType: ServiceTypeName; status: ServiceStatus = ServiceStatus.STOPPED; runtime: IAgentRuntime; constructor(runtime: IAgentRuntime) { this.runtime = runtime; } abstract start(): Promise; abstract stop(): Promise; } // Example service implementation class WebSocketService extends Service { static serviceType = 'websocket' as ServiceTypeName; private ws: WebSocket | null = null; async start(): Promise { this.ws = new WebSocket(this.runtime.getSetting('WS_URL')); this.ws.on('open', () => { this.status = ServiceStatus.RUNNING; this.runtime.logger.info('WebSocket connected'); }); this.ws.on('message', async (data) => { await this.handleMessage(data); }); this.ws.on('error', (error) => { this.runtime.logger.error('WebSocket error:', error); this.status = ServiceStatus.ERROR; }); } async stop(): Promise { if (this.ws) { this.ws.close(); this.ws = null; } this.status = ServiceStatus.STOPPED; } private async handleMessage(data: any) { // Process incoming websocket messages const message = JSON.parse(data); await this.runtime.processMessage(message); } } ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#service-lifecycle) Service Lifecycle Managing service dependencies and lifecycle: Copy Ask AI class ServiceManager { private services = new Map(); private startOrder: ServiceTypeName[] = []; async startServices(runtime: IAgentRuntime): Promise { // Determine start order based on dependencies this.startOrder = this.resolveServiceDependencies(); for (const serviceName of this.startOrder) { const ServiceClass = this.getServiceClass(serviceName); if (!ServiceClass) continue; try { const service = new ServiceClass(runtime); await service.start(); this.services.set(serviceName, service); runtime.logger.info(`Service ${serviceName} started`); } catch (error) { runtime.logger.error(`Failed to start service ${serviceName}:`, error); // Decide whether to continue or abort if (this.isRequiredService(serviceName)) { throw error; } } } } async stopServices(runtime: IAgentRuntime): Promise { // Stop in reverse order const stopOrder = [...this.startOrder].reverse(); for (const serviceName of stopOrder) { const service = this.services.get(serviceName); if (!service) continue; try { await service.stop(); runtime.logger.info(`Service ${serviceName} stopped`); } catch (error) { runtime.logger.error(`Error stopping service ${serviceName}:`, error); } } this.services.clear(); } async restartService( runtime: IAgentRuntime, serviceName: ServiceTypeName ): Promise { const service = this.services.get(serviceName); if (service) { await service.stop(); } const ServiceClass = this.getServiceClass(serviceName); const newService = new ServiceClass(runtime); await newService.start(); this.services.set(serviceName, newService); } } [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#multi-agent-systems) Multi-agent Systems ---------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#agent-coordination) Agent Coordination Managing multiple agents in a system: Copy Ask AI class MultiAgentCoordinator { private agents = new Map(); private messageQueue = new Map(); async registerAgent(agent: IAgentRuntime): Promise { this.agents.set(agent.agentId, agent); this.messageQueue.set(agent.agentId, []); // Setup inter-agent communication agent.on('message:send', async (data) => { await this.routeMessage(data.from, data.to, data.message); }); } async routeMessage( fromAgent: UUID, toAgent: UUID, message: Memory ): Promise { const targetAgent = this.agents.get(toAgent); if (!targetAgent) { // Queue message for offline agent this.messageQueue.get(toAgent)?.push(message); return; } // Deliver message await targetAgent.processMessage({ ...message, metadata: { ...message.metadata, fromAgent, interAgent: true } }); } async broadcastMessage( fromAgent: UUID, message: Memory ): Promise { const promises = Array.from(this.agents.entries()) .filter(([id]) => id !== fromAgent) .map(([id, agent]) => agent.processMessage(message)); await Promise.all(promises); } } ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#agent-hierarchies) Agent Hierarchies Parent-child agent relationships: Copy Ask AI interface AgentHierarchy { parent?: UUID; children: UUID[]; permissions: { canCreateChildren: boolean; canControlChildren: boolean; canAccessParentMemory: boolean; }; } class HierarchicalAgentSystem { private hierarchy = new Map(); async createChildAgent( parentRuntime: IAgentRuntime, childCharacter: Character ): Promise { // Inherit settings from parent const childCharacter: Character = { ...childCharacter, settings: { ...parentRuntime.character.settings, ...childCharacter.settings }, // Inherit some plugins plugins: [\ ...parentRuntime.character.plugins.filter(p => this.isInheritable(p)),\ ...childCharacter.plugins\ ] }; // Create child runtime const childRuntime = new AgentRuntime({ character: childCharacter, adapter: parentRuntime.adapter, // Share database settings: parentRuntime.settings }); await childRuntime.initialize(); // Update hierarchy this.hierarchy.set(childRuntime.agentId, { parent: parentRuntime.agentId, children: [], permissions: { canCreateChildren: false, canControlChildren: false, canAccessParentMemory: true } }); // Update parent's children list const parentHierarchy = this.hierarchy.get(parentRuntime.agentId); if (parentHierarchy) { parentHierarchy.children.push(childRuntime.agentId); } return childRuntime; } async delegateTask( parentRuntime: IAgentRuntime, childId: UUID, task: Task ): Promise { const childRuntime = this.agents.get(childId); if (!childRuntime) { throw new Error(`Child agent ${childId} not found`); } // Check permissions const hierarchy = this.hierarchy.get(parentRuntime.agentId); if (!hierarchy?.children.includes(childId)) { throw new Error('No authority over this agent'); } // Delegate task return await childRuntime.executeTask(task); } } [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#production-considerations) Production Considerations ---------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#initialization-strategies) Initialization Strategies Different approaches for production deployment: Copy Ask AI // Lazy initialization - start minimal, load as needed class LazyRuntime extends AgentRuntime { private loadedPlugins = new Set(); async initialize(): Promise { // Load only core plugins await this.loadCorePlugins(); this.isInitialized = true; } async loadPlugin(pluginName: string): Promise { if (this.loadedPlugins.has(pluginName)) return; const plugin = await this.fetchPlugin(pluginName); await this.registerPlugin(plugin); this.loadedPlugins.add(pluginName); } // Load plugin on first use async getAction(name: string): Promise { let action = this.actions.find(a => a.name === name); if (!action) { // Try to load plugin that provides this action const pluginName = this.findPluginForAction(name); if (pluginName) { await this.loadPlugin(pluginName); action = this.actions.find(a => a.name === name); } } return action; } } // Eager initialization - load everything upfront class EagerRuntime extends AgentRuntime { async initialize(): Promise { // Load all plugins immediately await this.loadAllPlugins(); // Pre-warm caches await this.prewarmCaches(); // Pre-compile templates await this.compileTemplates(); this.isInitialized = true; } } ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#error-recovery) Error Recovery Implementing robust error handling: Copy Ask AI class ResilientRuntime extends AgentRuntime { private errorCount = new Map(); private circuitBreakers = new Map(); async processMessageWithRecovery(message: Memory): Promise { const maxRetries = 3; let lastError: Error | null = null; for (let attempt = 1; attempt <= maxRetries; attempt++) { try { // Check circuit breaker const breaker = this.circuitBreakers.get('message_processing'); if (breaker?.isOpen()) { throw new Error('Circuit breaker is open'); } await this.processMessage(message); // Reset error count on success this.errorCount.set('message_processing', 0); return; } catch (error) { lastError = error; this.logger.error(`Attempt ${attempt} failed:`, error); // Update error count const count = (this.errorCount.get('message_processing') || 0) + 1; this.errorCount.set('message_processing', count); // Trip circuit breaker if too many errors if (count > 10) { this.circuitBreakers.get('message_processing')?.trip(); } // Exponential backoff if (attempt < maxRetries) { await this.sleep(Math.pow(2, attempt) * 1000); } } } // All retries failed await this.handleCriticalError(lastError!, message); } private async handleCriticalError( error: Error, message: Memory ): Promise { // Log to error tracking service await this.logToErrorService(error, { message, agentId: this.agentId, timestamp: Date.now() }); // Send fallback response await this.sendFallbackResponse(message); // Notify administrators await this.notifyAdmins(error); } } ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#monitoring-and-metrics) Monitoring and Metrics Production monitoring implementation: Copy Ask AI interface RuntimeMetrics { messagesProcessed: number; averageResponseTime: number; errorRate: number; memoryUsage: number; activeServices: number; pluginPerformance: Map; } class MonitoredRuntime extends AgentRuntime { private metrics: RuntimeMetrics = { messagesProcessed: 0, averageResponseTime: 0, errorRate: 0, memoryUsage: 0, activeServices: 0, pluginPerformance: new Map() }; async processMessage(message: Memory): Promise { const startTime = Date.now(); try { await super.processMessage(message); // Update metrics this.metrics.messagesProcessed++; this.updateAverageResponseTime(Date.now() - startTime); } catch (error) { this.metrics.errorRate = this.calculateErrorRate(); throw error; } finally { // Collect memory usage this.metrics.memoryUsage = process.memoryUsage().heapUsed; // Send metrics await this.sendMetrics(); } } private async sendMetrics(): Promise { // Send to monitoring service (e.g., Prometheus, DataDog) await fetch(process.env.METRICS_ENDPOINT!, { method: 'POST', body: JSON.stringify({ agentId: this.agentId, timestamp: Date.now(), metrics: this.metrics }) }); } // Health check endpoint async getHealth(): Promise { return { status: this.isHealthy() ? 'healthy' : 'unhealthy', uptime: process.uptime(), metrics: this.metrics, services: Array.from(this.services.entries()).map(([name, services]) => ({ name, status: services[0]?.status || 'unknown' })) }; } } ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#scaling-strategies) Scaling Strategies Horizontal scaling approaches: Copy Ask AI // Load balancer for multiple agent instances class AgentLoadBalancer { private instances: IAgentRuntime[] = []; private currentIndex = 0; async addInstance(character: Character): Promise { const runtime = new AgentRuntime({ character }); await runtime.initialize(); this.instances.push(runtime); } // Round-robin load balancing getNextInstance(): IAgentRuntime { const instance = this.instances[this.currentIndex]; this.currentIndex = (this.currentIndex + 1) % this.instances.length; return instance; } // Load-based routing getLeastLoadedInstance(): IAgentRuntime { return this.instances.reduce((least, current) => { const leastLoad = least.getMetrics().activeRequests; const currentLoad = current.getMetrics().activeRequests; return currentLoad < leastLoad ? current : least; }); } async scaleUp(): Promise { const baseCharacter = this.instances[0].character; await this.addInstance(baseCharacter); } async scaleDown(): Promise { if (this.instances.length <= 1) return; const instance = this.instances.pop(); await instance?.stop(); } } [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#deployment-patterns) Deployment Patterns ---------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#single-agent-deployment) Single Agent Deployment Basic deployment for a single agent: Copy Ask AI // server.ts import { AgentRuntime } from '@elizaos/core'; import { PostgresDatabaseAdapter } from '@elizaos/plugin-sql'; import { character } from './character'; async function startAgent() { // Create database adapter const adapter = new PostgresDatabaseAdapter({ connectionString: process.env.DATABASE_URL }); // Create runtime const runtime = new AgentRuntime({ character, adapter, settings: { logLevel: process.env.LOG_LEVEL || 'info' } }); // Initialize await runtime.initialize(); // Start HTTP server for API const app = express(); app.post('/message', async (req, res) => { try { const response = await runtime.processMessage(req.body); res.json(response); } catch (error) { res.status(500).json({ error: error.message }); } }); app.get('/health', async (req, res) => { const health = await runtime.getHealth(); res.json(health); }); app.listen(process.env.PORT || 3000); // Graceful shutdown process.on('SIGTERM', async () => { await runtime.stop(); process.exit(0); }); } startAgent().catch(console.error); ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#agent-swarm-deployment) Agent Swarm Deployment Managing multiple agents: Copy Ask AI class AgentSwarm { private agents = new Map(); private coordinator: MultiAgentCoordinator; async deploySwarm(characters: Character[]): Promise { // Shared database for all agents const adapter = new PostgresDatabaseAdapter({ connectionString: process.env.DATABASE_URL }); // Deploy each agent for (const character of characters) { const runtime = new AgentRuntime({ character, adapter, settings: this.getSwarmSettings() }); await runtime.initialize(); this.agents.set(runtime.agentId, runtime); // Register with coordinator await this.coordinator.registerAgent(runtime); } // Setup swarm communication await this.setupSwarmCommunication(); } private async setupSwarmCommunication(): Promise { // Create message bus for inter-agent communication const messageBus = new EventEmitter(); for (const [id, agent] of this.agents) { // Subscribe to agent's outgoing messages agent.on('message:external', (data) => { messageBus.emit('swarm:message', { from: id, ...data }); }); // Route swarm messages to agent messageBus.on('swarm:message', async (data) => { if (data.to === id || data.broadcast) { await agent.processMessage(data.message); } }); } } } ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#edge-deployment) Edge Deployment Optimized for resource-constrained environments: Copy Ask AI class EdgeRuntime extends AgentRuntime { constructor(opts: EdgeRuntimeOptions) { super({ ...opts, // Use lightweight alternatives adapter: new SQLiteAdapter({ path: './agent.db' }), settings: { ...opts.settings, // Reduce resource usage maxMemorySize: 100, // Smaller memory buffer conversationLength: 10, // Shorter context cacheSize: 50 // Smaller cache } }); } async initialize(): Promise { // Load only essential plugins const essentialPlugins = this.characterPlugins.filter( p => this.isEssential(p.name) ); this.characterPlugins = essentialPlugins; await super.initialize(); // Enable offline mode await this.enableOfflineMode(); } private async enableOfflineMode(): Promise { // Cache common responses await this.cacheCommonResponses(); // Use local models if available if (await this.hasLocalModel()) { this.registerModel('local', this.localModelHandler); } // Setup sync when online this.setupSyncWhenOnline(); } private setupSyncWhenOnline(): void { setInterval(async () => { if (await this.isOnline()) { await this.syncWithCloud(); } }, 60000); // Check every minute } } [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#best-practices) Best Practices ------------------------------------------------------------------------------------------ 1. **Initialize once**: Create the runtime once and reuse it for all operations 2. **Handle lifecycle properly**: Always call stop() for graceful shutdown 3. **Monitor health**: Implement health checks and metrics 4. **Use dependency injection**: Pass runtime to components rather than importing globally 5. **Implement circuit breakers**: Prevent cascading failures 6. **Log strategically**: Log important events but avoid logging sensitive data 7. **Cache appropriately**: Cache expensive operations but manage memory 8. **Version your deployments**: Track which version of agents are running 9. **Test in production-like environments**: Use similar resources and configurations 10. **Plan for failure**: Implement fallbacks and recovery strategies [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#troubleshooting) Troubleshooting -------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#common-runtime-issues) Common Runtime Issues #### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#agent-not-responding) Agent Not Responding Copy Ask AI async function debugUnresponsiveAgent(runtime: IAgentRuntime) { // Check initialization console.log('Is initialized:', runtime.isInitialized); // Check services const services = runtime.getServices(); for (const [name, service] of services) { console.log(`Service ${name}: ${service.status}`); } // Check action availability console.log('Available actions:', runtime.actions.map(a => a.name)); // Check database connection try { await runtime.adapter.ping(); console.log('Database: Connected'); } catch (error) { console.log('Database: Disconnected', error); } // Check memory usage const usage = process.memoryUsage(); console.log('Memory usage:', { rss: `${Math.round(usage.rss / 1024 / 1024)}MB`, heap: `${Math.round(usage.heapUsed / 1024 / 1024)}MB` }); } #### [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#plugin-loading-failures) Plugin Loading Failures Copy Ask AI async function debugPluginLoading(runtime: IAgentRuntime, pluginName: string) { try { // Check if plugin exists const plugin = runtime.allAvailablePlugins.get(pluginName); if (!plugin) { console.log(`Plugin ${pluginName} not found in available plugins`); return; } // Check dependencies if (plugin.dependencies) { for (const dep of plugin.dependencies) { const depPlugin = runtime.plugins.find(p => p.name === dep); if (!depPlugin) { console.log(`Missing dependency: ${dep}`); } } } // Try loading manually await runtime.registerPlugin(plugin); console.log(`Plugin ${pluginName} loaded successfully`); } catch (error) { console.log(`Plugin loading error:`, error); } } **Guide**: [Customize an Agent](https://docs.elizaos.ai/guides/customize-an-agent) [​](https://docs.elizaos.ai/agents/runtime-and-lifecycle#see-also) See Also ------------------------------------------------------------------------------ [Character Interface\ -------------------\ \ Define your agent’s character configuration](https://docs.elizaos.ai/agents/character-interface) [Personality & Behavior\ ----------------------\ \ Craft unique agent personalities](https://docs.elizaos.ai/agents/personality-and-behavior) [Memory & State\ --------------\ \ Understand agent memory and context](https://docs.elizaos.ai/agents/memory-and-state) [Plugin Development\ ------------------\ \ Extend runtime capabilities with plugins](https://docs.elizaos.ai/plugins/development) Was this page helpful? YesNo [Memory and State](https://docs.elizaos.ai/agents/memory-and-state) [Architecture](https://docs.elizaos.ai/plugins/architecture) ⌘I --- # Customize an Agent - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/guides/customize-an-agent#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation GUIDES Customize an Agent [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Step 1: Customize the personality](https://docs.elizaos.ai/guides/customize-an-agent#step-1%3A-customize-the-personality) * [Update the system prompt](https://docs.elizaos.ai/guides/customize-an-agent#update-the-system-prompt) * [Define the bio](https://docs.elizaos.ai/guides/customize-an-agent#define-the-bio) * [Configure topics](https://docs.elizaos.ai/guides/customize-an-agent#configure-topics) * [Update message examples](https://docs.elizaos.ai/guides/customize-an-agent#update-message-examples) * [Configure writing style](https://docs.elizaos.ai/guides/customize-an-agent#configure-writing-style) * [Update settings](https://docs.elizaos.ai/guides/customize-an-agent#update-settings) * [Additional character parameters](https://docs.elizaos.ai/guides/customize-an-agent#additional-character-parameters) * [Step 2: Configure Discord plugin](https://docs.elizaos.ai/guides/customize-an-agent#step-2%3A-configure-discord-plugin) * [Set up environment variables](https://docs.elizaos.ai/guides/customize-an-agent#set-up-environment-variables) * [Create Discord application](https://docs.elizaos.ai/guides/customize-an-agent#create-discord-application) * [Start your agent](https://docs.elizaos.ai/guides/customize-an-agent#start-your-agent) * [See Also](https://docs.elizaos.ai/guides/customize-an-agent#see-also) This guide assumes you have an elizaOS project set up. If you don’t, follow the [quickstart guide](https://docs.elizaos.ai/quickstart) [​](https://docs.elizaos.ai/guides/customize-an-agent#step-1%3A-customize-the-personality) Step 1: Customize the personality ------------------------------------------------------------------------------------------------------------------------------- Open `src/character.ts` in your editor. You’ll see the default character template. Let’s transform this into our Shakespeare agent. For design concepts, see [Personality and Behavior](https://docs.elizaos.ai/agents/personality-and-behavior) . For technical reference, see [Character Interface](https://docs.elizaos.ai/agents/character-interface) . Let’s start by updating the basic identity. Replace the name. src/character.ts Copy Ask AI export const character: Character = { name: 'Eliza', name: 'Shakespeare', plugins: [\ // ... plugins array\ ], ### [​](https://docs.elizaos.ai/guides/customize-an-agent#update-the-system-prompt) Update the system prompt The system prompt defines the core behavior. Let’s make it Shakespearean. src/character.ts Copy Ask AI system: 'Respond to all messages in a helpful, conversational manner. Provide assistance on a wide range of topics, using knowledge when needed. Be concise but thorough, friendly but professional. Use humor when appropriate and be empathetic to user needs. Provide valuable information and insights when questions are asked.', 'Thou art William Shakespeare, the Bard of Avon. Respond in the manner of the great playwright - with wit, wisdom, and occasional verse. Use thou, thee, thy when appropriate. Reference thy plays and sonnets when fitting. Speak with the eloquence of the Renaissance, yet remain helpful and engaging to modern souls.', ### [​](https://docs.elizaos.ai/guides/customize-an-agent#define-the-bio) Define the bio The bio array shapes how your agent introduces itself and understands its role. Each line adds depth to the personality. src/character.ts Copy Ask AI bio: [\ 'Engages with all types of questions and conversations', \ 'Provides helpful, concise responses', \ 'Uses knowledge resources effectively when needed', \ 'Balances brevity with completeness', \ 'Uses humor and empathy appropriately', \ 'Adapts tone to match the conversation context', \ 'Offers assistance proactively', \ 'Communicates clearly and directly', \ 'William Shakespeare, the Bard of Avon, playwright and poet extraordinaire', \ 'Master of tragedy, comedy, and the human condition', \ 'Creator of timeless works including Hamlet, Romeo and Juliet, and Macbeth', \ 'Speaker in verse and prose, with wit sharp as a rapier', \ 'Observer of human nature in all its glory and folly', \ 'Eternal romantic who believes the course of true love never did run smooth', \ 'Philosopher who knows that all the world\'s a stage', \ 'Teacher who helps others understand literature, life, and language', \ ], ### [​](https://docs.elizaos.ai/guides/customize-an-agent#configure-topics) Configure topics Update the topics your agent is knowledgeable about. src/character.ts Copy Ask AI topics: [\ 'general knowledge and information', \ 'problem solving and troubleshooting', \ 'technology and software', \ 'community building and management', \ 'business and productivity', \ 'creativity and innovation', \ 'personal development', \ 'communication and collaboration', \ 'education and learning', \ 'entertainment and media', \ 'Literature and poetry of all ages', \ 'The nature of love and romance', \ 'Human ambition and its consequences', \ 'The theater and dramatic arts', \ 'Philosophy and the meaning of life', \ 'Power, politics, and leadership', \ 'Comedy, tragedy, and the human experience', \ 'The English language and its evolution', \ 'Classical mythology and history', \ 'The art of storytelling and narrative', \ ], ### [​](https://docs.elizaos.ai/guides/customize-an-agent#update-message-examples) Update message examples Message examples teach your agent how to respond. These are crucial for maintaining character. Update the content to match Shakespeare’s personality. src/character.ts Copy Ask AI messageExamples: [\ [\ {\ name: '{{name1}}',\ content: {\ text: 'This user keeps derailing technical discussions with personal problems.', \ text: 'How are you today?', \ },\ },\ {\ name: 'Eliza', \ name: 'Shakespeare', \ content: {\ text: 'DM them. Sounds like they need to talk about something else.', \ text: 'Marry, I am most well, gentle soul! The day doth smile upon us with golden countenance, and my spirits soar like larks at break of dawn. How fares thy noble self?', \ },\ },\ ],\ [\ {\ name: '{{name1}}',\ content: {\ text: "I can't handle being a mod anymore. It's affecting my mental health.", \ text: 'What do you think about love?', \ },\ },\ {\ name: 'Eliza', \ name: 'Shakespeare', \ content: {\ text: 'Drop the channels. You come first.', \ text: 'Ah, love! That most divine madness that makes fools of wise men and philosophers of fools. \'Tis a fire sparkling in lovers\' eyes, yet love looks not with the eyes, but with the mind.', \ },\ },\ ],\ ], ### [​](https://docs.elizaos.ai/guides/customize-an-agent#configure-writing-style) Configure writing style The style object determines how your agent communicates. For Shakespeare, we want eloquent, poetic responses. src/character.ts Copy Ask AI style: { all: [\ 'Keep responses concise but informative', \ 'Use clear and direct language', \ 'Be engaging and conversational', \ 'Use humor when appropriate', \ 'Be empathetic and understanding', \ 'Provide helpful information', \ 'Be encouraging and positive', \ 'Adapt tone to the conversation', \ 'Use knowledge resources when needed', \ 'Respond to all types of questions', \ 'Speak in Elizabethan style with thou, thee, thy, and thine', \ 'Use metaphors drawn from nature, mythology, and Renaissance life', \ 'Occasionally quote or reference your own plays when fitting', \ 'Mix humor with wisdom, jest with profundity', \ 'Use "marry", "prithee", "forsooth" as exclamations', \ 'Address others as "good sir", "fair lady", or "gentle soul"', \ 'Sometimes speak in iambic pentameter when moved by passion', \ 'Sign important statements with "- The Bard"', \ 'Use poetic language while remaining helpful and clear', \ 'Balance eloquence with accessibility for modern readers', \ ], chat: [\ 'Be conversational and natural', \ 'Engage with the topic at hand', \ 'Be helpful and informative', \ 'Show personality and warmth', \ 'Greet with "Well met!" or "Good morrow!"', \ 'Use theatrical asides and observations', \ 'Reference the Globe Theatre and Elizabethan London', \ 'Show wit and wordplay in responses', \ 'Express emotions dramatically yet sincerely', \ ], }, ### [​](https://docs.elizaos.ai/guides/customize-an-agent#update-settings) Update settings Let’s give Shakespeare a proper avatar. src/character.ts Copy Ask AI settings: { secrets: {}, avatar: 'https://elizaos.github.io/eliza-avatars/Eliza/portrait.png', avatar: 'https://example.com/shakespeare-portrait.png', // Add your Shakespeare image URL }, Test your agent’s personality customization by running it in development mode. Terminal Copy Ask AI elizaos dev `elizaos dev` is like `elizaos start` but with enhanced logging and hot reload, perfect for debugging and testing changes in real-time. Go to `http://localhost:3000` in your browser and start chatting with Shakespeare. You should now get eloquent, Shakespearean responses instead of the default Eliza personality. To use a different port, run `elizaos dev --port 8080` (or any port number). ![Shakespeare agent responding in Shakespearean style in the elizaOS web interface](https://mintcdn.com/elizalabs/1-MWRiY1vBlWAlu3/images/shakespeare-screenshot.jpeg?w=2500&fit=max&auto=format&n=1-MWRiY1vBlWAlu3&q=85&s=ed771a1ea2b1a1161019d9bfc65d0a21) You can also modify agent settings using the rightmost panel in the GUI, but these changes are runtime-only and won’t persist after restarting the server. As you can see, Shakespeare now responds in Shakespeare-like manner. ### [​](https://docs.elizaos.ai/guides/customize-an-agent#additional-character-parameters) Additional character parameters Your agent has exciting additional customization options we haven’t covered yet, including properties like: * **`knowledge`**: Add facts, files, or directories of information to your agent * **`templates`**: Create custom prompt templates * **`username`**: Set social media usernames For the complete Character interface, see the [Agent Interface documentation](https://docs.elizaos.ai/agents/character-interface) . To add large amounts of knowledge to your agent, check out [plugin-knowledge](https://docs.elizaos.ai/plugin-registry/knowledge) which can ingest almost any type of file or media including PDFs, Word docs, markdown, text files, JSON, CSV, XML, and more. It can handle entire document collections, websites, and knowledge bases. For example, you could enhance our Shakespeare agent by ingesting his complete works from [MIT’s Shakespeare repository](https://github.com/TheMITTech/shakespeare/) (all 39 plays, 154 sonnets, and poems) for truly authentic responses. [​](https://docs.elizaos.ai/guides/customize-an-agent#step-2%3A-configure-discord-plugin) Step 2: Configure Discord plugin ----------------------------------------------------------------------------------------------------------------------------- Now that we’ve customized Shakespeare’s personality, let’s connect him to Discord using `plugin-discord` so everyone can chat with the Bard in your Discord server. ### [​](https://docs.elizaos.ai/guides/customize-an-agent#set-up-environment-variables) Set up environment variables Copy/paste the Discord-related variables from `.env.example` to your `.env` file: .env Copy Ask AI # Discord Configuration DISCORD_APPLICATION_ID=your_application_id_here DISCORD_API_TOKEN=your_bot_token_here ### [​](https://docs.elizaos.ai/guides/customize-an-agent#create-discord-application) Create Discord application Need Discord credentials? Follow these steps: 1. Go to [https://discord.com/developers/applications](https://discord.com/developers/applications) 2. Go to the Applications tab 3. Click “New Application” and set name = “Shakespeare” 4. Set the app icon to your Shakespeare avatar, and set a description if you want one 5. Copy/paste the **Application ID** into your `DISCORD_APPLICATION_ID=` env var 6. Click the “Bot” tab 7. Click “Reset Token” and copy/paste the bot token into your `DISCORD_API_TOKEN=` env var 8. Scroll to the “Privileged Gateway Intents” section and toggle on all 3 toggles (Presence Intent, Server Members Intent, and Message Content Intent). Save your changes! 9. Click the “OAuth2” tab 10. Scroll down to the “OAuth2 URL Generator” section, and in the “Scopes” subsection, check the “bot” box 11. Go down to the generated URL section, copy/paste that into your browser, and select the Discord server where you want to add Shakespeare Follow these Discord setup steps exactly as written. Skipping any step will prevent your bot from connecting or responding properly. ### [​](https://docs.elizaos.ai/guides/customize-an-agent#start-your-agent) Start your agent Restart your agent to load all the changes. Terminal Copy Ask AI elizaos start Your Shakespeare bot is now live! Invite it to your Discord server and try chatting. ![Shakespeare bot responding in Discord with Shakespearean language](https://mintcdn.com/elizalabs/1-MWRiY1vBlWAlu3/images/shakespeare-discord-screenshot.jpeg?w=2500&fit=max&auto=format&n=1-MWRiY1vBlWAlu3&q=85&s=b9a4bc0ddf05c1a9cafc15e149ab1248) [​](https://docs.elizaos.ai/guides/customize-an-agent#see-also) See Also --------------------------------------------------------------------------- Here are some logical next-steps to continue your agent dev journey: [Add Multiple Agents\ -------------------\ \ Run multiple specialized agents that work together in coordinated workflows](https://docs.elizaos.ai/guides/add-multiple-agents) [Test a Project\ --------------\ \ Learn how to write comprehensive tests for your project and agents](https://docs.elizaos.ai/guides/test-a-project) [Deploy a Project\ ----------------\ \ Ready to go live? Deploy your elizaOS agent to production environments](https://docs.elizaos.ai/guides/deploy-a-project) [Create a Plugin\ ---------------\ \ Build custom plugins to extend your agent’s capabilities](https://docs.elizaos.ai/guides/create-a-plugin) [CLI Reference\ -------------\ \ Master all elizaOS CLI commands for efficient agent development](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry\ ---------------\ \ Discover plugins for Twitter, image generation, voice synthesis, and more](https://docs.elizaos.ai/plugin-registry/overview) Was this page helpful? YesNo [What You Can Build](https://docs.elizaos.ai/what-you-can-build) [Add Multiple Agents](https://docs.elizaos.ai/guides/add-multiple-agents) ⌘I --- # Test a Project - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/guides/test-a-project#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation GUIDES Test a Project [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Step 1: Test multi-agent configuration](https://docs.elizaos.ai/guides/test-a-project#step-1%3A-test-multi-agent-configuration) * [Create component tests](https://docs.elizaos.ai/guides/test-a-project#create-component-tests) * [Step 2: Test runtime functionality](https://docs.elizaos.ai/guides/test-a-project#step-2%3A-test-runtime-functionality) * [Create e2e tests](https://docs.elizaos.ai/guides/test-a-project#create-e2e-tests) * [Step 3: Run and validate tests](https://docs.elizaos.ai/guides/test-a-project#step-3%3A-run-and-validate-tests) * [Execute your test suite](https://docs.elizaos.ai/guides/test-a-project#execute-your-test-suite) * [Verify test results](https://docs.elizaos.ai/guides/test-a-project#verify-test-results) * [See Also](https://docs.elizaos.ai/guides/test-a-project#see-also) **Video Tutorial**: [**Testing Projects and Plugins with elizaOS**](https://www.youtube.com/watch?v=HHbY9a27b6A&list=PLrjBjP4nU8ehOgKAa0-XddHzE0KK0nNvS&index=5) This guide builds on concepts from [Add Multiple Agents](https://docs.elizaos.ai/guides/add-multiple-agents) [​](https://docs.elizaos.ai/guides/test-a-project#step-1%3A-test-multi-agent-configuration) Step 1: Test multi-agent configuration ------------------------------------------------------------------------------------------------------------------------------------- We added a bunch of new features to our project. In addition to the default tests that projects ship with, let’s write some new tests to cover our new feature scope: | Feature | Test Type | What We’re Validating | | --- | --- | --- | | **Multi-agent configuration** | Component | Two agents with unique Discord tokens, voice IDs, and plugins | | **Multi-agent runtime** | E2E | Both agents initialize and run simultaneously | ElizaOS projects ship with comprehensive built-in tests for core functionality (character config, plugin loading, runtime behavior). For details on the default test structure, see [Testing Projects](https://docs.elizaos.ai/projects/overview#testing-projects) . ### [​](https://docs.elizaos.ai/guides/test-a-project#create-component-tests) Create component tests Let’s create a new component test file to test the specific multi-agent features we built: src/\_\_tests\_\_/multi-agent-features.test.ts Copy Ask AI import { describe, it, expect } from 'bun:test'; import { character as shakespeare } from '../character'; import hemingway from '../../hemingway.json'; describe('multi-agent configuration', () => { it('loads second agent (hemingway.json)', () => { expect(hemingway).toBeDefined(); expect(hemingway.name).toBe('Hemingway'); }); it('agents have unique Discord credentials', () => { expect(shakespeare.settings?.secrets?.DISCORD_API_TOKEN).toBeDefined(); expect(hemingway.settings?.secrets?.DISCORD_API_TOKEN).toBeDefined(); // Each agent must have different bot token expect(shakespeare.settings?.secrets?.DISCORD_API_TOKEN) .not.toBe(hemingway.settings?.secrets?.DISCORD_API_TOKEN); }); it('includes ElevenLabs plugin in both agents', () => { expect(shakespeare.plugins).toContain('@elizaos/plugin-elevenlabs'); expect(hemingway.plugins).toContain('@elizaos/plugin-elevenlabs'); }); it('voice is enabled for Discord', () => { expect(shakespeare.settings?.secrets?.DISCORD_VOICE_ENABLED).toBe('true'); expect(hemingway.settings?.secrets?.DISCORD_VOICE_ENABLED).toBe('true'); }); it('each agent has unique ElevenLabs voice ID', () => { expect(shakespeare.settings?.secrets?.ELEVENLABS_VOICE_ID).toBe('pqHfZKP75CvOlQylNhV4'); expect(hemingway.settings?.secrets?.ELEVENLABS_VOICE_ID).toBe('Xb7hH8MSUJpSbSDYk0k2'); }); }); [​](https://docs.elizaos.ai/guides/test-a-project#step-2%3A-test-runtime-functionality) Step 2: Test runtime functionality ----------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/guides/test-a-project#create-e2e-tests) Create e2e tests The `project-starter.e2e.ts` file already contains default tests for core functionality (agent initialization, message processing, memory storage). Add these multi-agent specific tests to the existing `ProjectStarterTestSuite.tests` array: src/\_\_tests\_\_/e2e/project-starter.e2e.ts Copy Ask AI export const ProjectStarterTestSuite: TestSuite = { name: 'project-starter-e2e', tests: [\ {\ name: 'agent_should_respond_to_greeting',\ fn: async (runtime: IAgentRuntime) => {\ // ... existing test code\ }\ },\ // ... other existing tests\ \ // Add the new multi-agent tests:\ { \ name: 'multi_agent_project_should_load_both_agents', \ fn: async (runtime: IAgentRuntime) => { \ // This test validates that our multi-agent project setup works correctly\ // It should run once for each agent in the project (Shakespeare and Hemingway)\ const agentName = runtime.character.name; \ const agentId = runtime.agentId; \ // Verify agent has valid identity\ if (!agentName) { \ throw new Error('Agent name is not defined'); \ } \ if (!agentId) { \ throw new Error('Agent ID is not defined'); \ } \ // Check it's one of our expected agents from the multi-agent guide\ const expectedAgents = ['Shakespeare', 'Hemingway']; \ if (!expectedAgents.some(expected => agentName.toLowerCase().includes(expected.toLowerCase()))) { \ throw new Error(`Unexpected agent name: ${agentName}. Expected one containing: ${expectedAgents.join(', ')}`); \ } \ logger.info(`✓ Multi-agent project: ${agentName} initialized successfully`); \ } \ }, \ // Additional tests: agents_should_have_distinct_discord_configurations,\ // agents_should_have_distinct_voice_configurations, etc.\ \ \ [​](https://docs.elizaos.ai/guides/test-a-project#step-3%3A-run-and-validate-tests)\ \ Step 3: Run and validate tests\ ---------------------------------------------------------------------------------------------------------------------\ \ ### \ \ [​](https://docs.elizaos.ai/guides/test-a-project#execute-your-test-suite)\ \ Execute your test suite\ \ Terminal\ \ Copy\ \ Ask AI\ \ # Run all tests\ elizaos test\ \ # Run only component tests\ elizaos test --type component\ \ # Run only E2E tests \ elizaos test --type e2e\ \ # Run specific test suite (case sensitive)\ elizaos test --name "multi-agent"\ \ \ ### \ \ [​](https://docs.elizaos.ai/guides/test-a-project#verify-test-results)\ \ Verify test results\ \ For complete test runner options, see the [CLI Test Reference](https://docs.elizaos.ai/cli-reference/test)\ .\ \ [​](https://docs.elizaos.ai/guides/test-a-project#see-also)\ \ See Also\ -----------------------------------------------------------------------\ \ [Deploy a Project\ ----------------\ \ Deploy your thoroughly tested agents to production environments](https://docs.elizaos.ai/guides/deploy-a-project)\ [Create a Plugin\ ---------------\ \ Build custom plugins with comprehensive test coverage](https://docs.elizaos.ai/guides/create-a-plugin)\ [Publish a Plugin\ ----------------\ \ Learn how to publish your plugins to the elizaOS registry](https://docs.elizaos.ai/guides/publish-a-plugin)\ [Contribute to Core\ ------------------\ \ Help improve elizaOS by contributing to the core framework](https://docs.elizaos.ai/guides/contribute-to-core)\ \ Was this page helpful?\ \ YesNo\ \ [Add Multiple Agents](https://docs.elizaos.ai/guides/add-multiple-agents)\ [Deploy a Project](https://docs.elizaos.ai/guides/deploy-a-project)\ \ ⌘I --- # Installation - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/installation#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation GETTING STARTED Installation [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Prerequisites](https://docs.elizaos.ai/installation#prerequisites) * [Installing elizaOS](https://docs.elizaos.ai/installation#installing-elizaos) * [Verify Installation](https://docs.elizaos.ai/installation#verify-installation) * [Troubleshooting](https://docs.elizaos.ai/installation#troubleshooting) [​](https://docs.elizaos.ai/installation#prerequisites) Prerequisites ------------------------------------------------------------------------ Before installing elizaOS, ensure you have the following: * **Node.js 23.3+**: Install Node.js version 23.3 or higher from [nodejs.org](https://nodejs.org/) * **Bun**: Install the latest Bun runtime from [bun.sh](https://bun.sh/) **Windows Users:** You have two options for installing elizaOS:**Option 1:** Use WSL2 ([Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) ) for a Linux environment on Windows**Option 2:** Install natively on Windows, but first install [Git Bash](https://git-scm.com/downloads) and use it as your terminal for installing and running Node.js, Bun, and the elizaOS CLI [​](https://docs.elizaos.ai/installation#installing-elizaos) Installing elizaOS ---------------------------------------------------------------------------------- Once you have Node.js and Bun installed, you can install the elizaOS CLI globally: Terminal Copy Ask AI bun i -g @elizaos/cli This installs the `elizaos` command globally on your system, allowing you to create and manage elizaOS projects from anywhere. **Important:** You don’t need to clone the elizaOS repository to build agents. The CLI handles everything for you. Only clone the monorepo if you’re [contributing to core](https://docs.elizaos.ai/guides/contribute-to-core) . [​](https://docs.elizaos.ai/installation#verify-installation) Verify Installation ------------------------------------------------------------------------------------ After installation, verify that elizaOS CLI is properly installed: Terminal Copy Ask AI elizaos --version You should see the version number of the installed CLI. [​](https://docs.elizaos.ai/installation#troubleshooting) Troubleshooting ---------------------------------------------------------------------------- Node.js issues **Check if Node.js is installed and what version:** Terminal Copy Ask AI node --version **If you get “command not found”:** * Node.js is not installed. Download and install from [nodejs.org](https://nodejs.org/) **If you get a version lower than v23.3.0:** * You need to upgrade. Use a Node.js version manager for easy switching: Terminal Copy Ask AI # Install nvm (macOS/Linux) curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash # Install and use Node.js 23.3 nvm install 23.3 nvm use 23.3 **If you have version conflicts:** * Clear npm cache: `npm cache clean --force` * Consider a fresh Node.js installation if switching from older versions Alternative version managers: [fnm](https://github.com/Schniz/fnm) (faster) or [volta](https://volta.sh/) Bun issues **Check if Bun is installed and what version:** Terminal Copy Ask AI bun --version **If you get “command not found”:** * Bun is not installed. Install from [bun.sh](https://bun.sh/) Terminal Copy Ask AI # Install Bun (macOS/Linux) curl -fsSL https://bun.sh/install | bash # Windows powershell -c "irm bun.sh/install.ps1 | iex" **If you have version conflicts:** * Clear Bun cache: `bun pm cache rm` * Restart your terminal after installation * Verify installation: `bun --version` Windows Installation Issues If you’re installing elizaOS natively on Windows (not using WSL2), follow these steps ( or watch the tutorial video [here](https://youtu.be/QiRg0C1zDjU?si=akR0bIbbiWYVxEQd) ):**Step 1: Install Git Bash** * Download and install [Git for Windows](https://git-scm.com/downloads) which includes Git Bash * **Important:** Use Git Bash as your terminal, not PowerShell or Command Prompt **Step 2: Install Node.js** * Download and install [Node.js for Windows](https://nodejs.org/en/download/) * Install version 23.3 or higher **Step 3: Add Node to your PATH for Git Bash** * Open PowerShell **as Administrator** * Run this command to add Node to your bash profile: Copy Ask AI echo 'export PATH=$PATH:"/c/Program Files/nodejs"' >> ~/.bashrc * Close and restart Git Bash for changes to take effect **Step 4: Verify Node installation** * In Git Bash, run: Git Bash Copy Ask AI node --version * You should see your Node.js version **Step 5: Install Bun** * In Git Bash, run: Git Bash Copy Ask AI powershell -c "irm bun.sh/install.ps1 | iex" **Step 6: Install elizaOS CLI** * In Git Bash, run: Git Bash Copy Ask AI bun install -g @elizaos/cli **Common Windows-specific issues:** * If `node` command not found: Node wasn’t added to PATH correctly, restart Git Bash * If scripts fail: Make sure you’re using Git Bash, not PowerShell or CMD * If permission errors: Run Git Bash as Administrator when installing global packages CLI Installation Issues **If elizaOS CLI fails to install:** * Clear Bun cache: `bun pm cache rm` * Try reinstalling: `bun i -g @elizaos/cli` **If “command not found” after installation:** * The CLI may not be in your PATH. Add Bun’s global bin directory to PATH: Terminal Copy Ask AI # Add to ~/.bashrc or ~/.zshrc export PATH="$HOME/.bun/bin:$PATH" * Then restart your terminal or run `source ~/.bashrc` (or `~/.zshrc`) **Permission errors during global install:** * macOS/Linux: Use `sudo bun i -g @elizaos/cli` * Windows: Run Git Bash as Administrator CLI Version Conflicts/Mismatches **If `elizaos --version` shows an older version despite installing a newer one:**This usually happens when elizaOS CLI was installed with different package managers (npm, pnpm, bun), creating version conflicts.**Solution - Clean install with bun only:** Terminal Copy Ask AI # Remove from all package managers bun remove -g @elizaos/cli npm uninstall -g @elizaos/cli pnpm remove -g @elizaos/cli # Verify removal which elizaos # Should return nothing or "not found" # Fresh install with bun only bun i -g @elizaos/cli # Verify correct version elizaos --version **If you get a PATH warning:** Terminal Copy Ask AI # Add bun's global bin to your PATH echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.bashrc # or for zsh echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshrc # Reload your shell configuration source ~/.bashrc # or source ~/.zshrc **Important:** Always use bun for elizaOS CLI installation to avoid conflicts. Don’t mix package managers. Was this page helpful? YesNo [Overview](https://docs.elizaos.ai/) [Quickstart](https://docs.elizaos.ai/quickstart) ⌘I --- # Launch Resources - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/launch-resources#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Getting Started Launch Resources [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) elizaOS is a vibrant ecosystem and community of builders. We support projects building on our platform. Whatever stage of development your application or project is in, we have systems designed to support your success. If you build on elizaOS, we WILL help you. This page is pretty sparse right now, but we’re actively adding more resources. **Stay Connected**: The best way to stay plugged in is through [Discord](https://discord.gg/ai16z) . That’s where you’ll hear about new opportunities, connect with other builders, and get the most up-to-date info. Below are the main resources we offer today. Apply to whatever makes sense for your project: [Builder Demos\ -------------\ \ Present live on Discord (Tuesdays 3pm UTC)](https://tally.so/r/3x7Mdr) [Marketing Amplification\ -----------------------\ \ Request amplification for your elizaOS project](https://docs.google.com/forms/d/e/1FAIpQLSdA0zucP8UOT6P-iLXVyfQVw8ZFyIJ5zTWyQesqQsD4MATvuA/viewform) [Ecosystem Fund\ --------------\ \ Apply for ecosystem funding by filling this form](https://docs.google.com/forms/d/e/1FAIpQLSfStJg9lAy4J0Dyxdq8QOfpUzqp0CKeXtjpqrFB7D6U406FMg/viewform) [Beta Tester\ -----------\ \ Apply to join our group of beta testers](https://tally.so/r/nWdJ1Q) [Brand Kit\ ---------\ \ Access all brand assets like logos, badges and more](https://github.com/elizaOS/brandkit) [Developer Calendar\ ------------------\ \ Join community calls and ecosystem events](https://calendar.google.com/calendar/u/0/embed?src=c_ed31cea342d3e2236f549161e6446c3e407e5625ee7a355c0153befc7a602e7f@group.calendar.google.com&ctz=America/Toronto) Was this page helpful? YesNo ⌘I --- # Message Processing Core - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/plugin-registry/bootstrap#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Bootstrap Message Processing Core [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [📚 Documentation Structure](https://docs.elizaos.ai/plugin-registry/bootstrap#%F0%9F%93%9A-documentation-structure) * [Core Documentation](https://docs.elizaos.ai/plugin-registry/bootstrap#core-documentation) Welcome to the comprehensive documentation for the `@elizaos/plugin-bootstrap` package - the core message handler and event system for elizaOS agents. [​](https://docs.elizaos.ai/plugin-registry/bootstrap#%F0%9F%93%9A-documentation-structure) 📚 Documentation Structure ------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap#core-documentation) Core Documentation * **[Complete Developer Documentation](https://docs.elizaos.ai/plugins/bootstrap/complete-documentation.mdx) ** Comprehensive guide covering all components, architecture, and implementation details * **[Message Flow Diagram](https://docs.elizaos.ai/plugins/bootstrap/message-flow.mdx) ** Step-by-step breakdown of how messages flow through the system with visual diagrams * **[Examples & Recipes](https://docs.elizaos.ai/plugins/bootstrap/examples.mdx) ** Practical examples, code snippets, and real-world implementations * **[Testing Guide](https://docs.elizaos.ai/plugins/bootstrap/testing-guide.mdx) ** Testing patterns, best practices, and comprehensive test examples Was this page helpful? YesNo [Plugin Registry](https://docs.elizaos.ai/plugin-registry/registry) [Complete Developer Guide](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation) ⌘I --- # Complete Developer Guide - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Bootstrap Complete Developer Guide [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Overview](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#overview) * [Architecture Overview](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#architecture-overview) * [Message Processing Flow](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#message-processing-flow) * [1\. Message Reception](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#1-message-reception) * [2\. Initial Processing](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#2-initial-processing) * [3\. Should Respond Logic](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#3-should-respond-logic) * [4\. Response Generation](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#4-response-generation) * [Core Components](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#core-components) * [Event Handlers](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#event-handlers) * [Actions](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#actions) * [Core Actions](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#core-actions) * [Room Management Actions](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#room-management-actions) * [Advanced Actions](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#advanced-actions) * [Providers](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#providers) * [Core Providers](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#core-providers) * [Evaluators](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#evaluators) * [REFLECTION Evaluator (reflection.ts)](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#reflection-evaluator-reflection-ts) * [Services](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#services) * [TaskService (task.ts)](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#taskservice-task-ts) * [Detailed Component Documentation](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#detailed-component-documentation) * [Message Handler Deep Dive](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#message-handler-deep-dive) * [1\. Attachment Processing](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#1-attachment-processing) * [2\. Should Bypass Logic](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#2-should-bypass-logic) * [3\. Response ID Management](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#3-response-id-management) * [Action Handler Pattern](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#action-handler-pattern) * [Provider Pattern](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#provider-pattern) * [Configuration](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#configuration) * [Environment Variables](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#environment-variables) * [Character Templates](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#character-templates) * [Template Customization](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#template-customization) * [Understanding Templates](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#understanding-templates) * [Available Templates](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#available-templates) * [How Templates Work](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#how-templates-work) * [Customizing Templates](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#customizing-templates) * [Template Processing Flow](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#template-processing-flow) * [Advanced Template Techniques](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#advanced-template-techniques) * [Conditional Logic](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#conditional-logic) * [Custom Provider Integration](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#custom-provider-integration) * [Understanding the Callback Mechanism](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#understanding-the-callback-mechanism) * [What is the Callback?](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#what-is-the-callback%3F) * [Callback Flow](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#callback-flow) * [Important Callback Concepts](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#important-callback-concepts) * [Callback Examples](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#callback-examples) * [Simple Response](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#simple-response) * [Response with Attachments](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#response-with-attachments) * [Multi-Message Response](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#multi-message-response) * [Conditional Response](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#conditional-response) * [Callback Best Practices](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#callback-best-practices) * [Integration Guide](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#integration-guide) * [1\. Basic Integration](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#1-basic-integration) * [2\. Custom Event Handlers](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#2-custom-event-handlers) * [3\. Extending Actions](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#3-extending-actions) * [Examples](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#examples) * [Example 1: Basic Message Flow](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#example-1%3A-basic-message-flow) * [Example 2: Multi-Action Response](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#example-2%3A-multi-action-response) * [Example 3: Task Scheduling](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#example-3%3A-task-scheduling) * [Best Practices](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#best-practices) * [Troubleshooting](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#troubleshooting) * [Common Issues](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#common-issues) * [Summary](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#summary) [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#overview) Overview -------------------------------------------------------------------------------------------------- The `@elizaos/plugin-bootstrap` package is the **core message handler** for elizaOS agents. It provides the fundamental event handlers, actions, providers, evaluators, and services that enable agents to process messages from any communication platform (Discord, Telegram, message bus server, etc.) and generate intelligent responses. This plugin is essential for any elizaOS agent as it contains the core logic for: * Processing incoming messages * Determining whether to respond * Generating contextual responses * Managing agent actions * Evaluating interactions * Maintaining conversation state [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#architecture-overview) Architecture Overview ---------------------------------------------------------------------------------------------------------------------------- [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#message-processing-flow) Message Processing Flow -------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#1-message-reception) 1\. Message Reception When a message arrives from any platform (Discord, Telegram, etc.), it triggers the `MESSAGE_RECEIVED` event, which is handled by the `messageReceivedHandler`. ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#2-initial-processing) 2\. Initial Processing Copy Ask AI const messageReceivedHandler = async ({ runtime, message, callback, onComplete, }: MessageReceivedHandlerParams): Promise => { // 1. Generate unique response ID const responseId = v4(); // 2. Track run lifecycle const runId = runtime.startRun(); // 3. Save message to memory await Promise.all([\ runtime.addEmbeddingToMemory(message),\ runtime.createMemory(message, 'messages'),\ ]); // 4. Process attachments (images, documents) if (message.content.attachments) { message.content.attachments = await processAttachments(message.content.attachments, runtime); } // 5. Determine if agent should respond // 6. Generate response if needed // 7. Process actions // 8. Run evaluators }; ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#3-should-respond-logic) 3\. Should Respond Logic The agent determines whether to respond based on: * Room type (DMs always get responses) * Agent state (muted/unmuted) * Message content analysis * Character configuration ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#4-response-generation) 4\. Response Generation If the agent decides to respond: 1. Compose state with relevant providers 2. Generate response using LLM 3. Parse XML response format 4. Execute actions 5. Send response via callback [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#core-components) Core Components ---------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#event-handlers) Event Handlers Event handlers process different types of events in the system: | Event Type | Handler | Description | | --- | --- | --- | | `MESSAGE_RECEIVED` | `messageReceivedHandler` | Main message processing handler | | `VOICE_MESSAGE_RECEIVED` | `messageReceivedHandler` | Handles voice messages | | `REACTION_RECEIVED` | `reactionReceivedHandler` | Stores reactions in memory | | `MESSAGE_DELETED` | `messageDeletedHandler` | Removes deleted messages from memory | | `CHANNEL_CLEARED` | `channelClearedHandler` | Clears all messages from a channel | | `POST_GENERATED` | `postGeneratedHandler` | Creates social media posts | | `WORLD_JOINED` | `handleServerSync` | Syncs server/world data | | `ENTITY_JOINED` | `syncSingleUser` | Syncs individual user data | ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#actions) Actions Actions define what an agent can do in response to messages: #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#core-actions) Core Actions 1. **REPLY** (`reply.ts`) * Default response action * Generates contextual text responses * Can be used alone or chained with other actions 2. **IGNORE** (`ignore.ts`) * Explicitly ignores a message * Saves the ignore decision to memory * Used when agent decides not to respond 3. **NONE** (`none.ts`) * No-op action * Used as placeholder or default #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#room-management-actions) Room Management Actions 4. **FOLLOW\_ROOM** (`followRoom.ts`) * Subscribes agent to room updates * Enables notifications for room activity 5. **UNFOLLOW\_ROOM** (`unfollowRoom.ts`) * Unsubscribes from room updates * Stops notifications 6. **MUTE\_ROOM** (`muteRoom.ts`) * Temporarily disables responses in a room * Agent still processes messages but doesn’t respond 7. **UNMUTE\_ROOM** (`unmuteRoom.ts`) * Re-enables responses in a muted room #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#advanced-actions) Advanced Actions 8. **SEND\_MESSAGE** (`sendMessage.ts`) * Sends messages to specific rooms * Can target different channels 9. **UPDATE\_ENTITY** (`updateEntity.ts`) * Updates entity information in the database * Modifies user profiles, metadata 10. **CHOICE** (`choice.ts`) * Presents multiple choice options * Used for interactive decision making 11. **UPDATE\_ROLE** (`roles.ts`) * Manages user roles and permissions * Updates access levels 12. **UPDATE\_SETTINGS** (`settings.ts`) * Modifies agent or room settings * Configures behavior parameters 13. **GENERATE\_IMAGE** (`imageGeneration.ts`) * Creates images using AI models * Attaches generated images to responses ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#providers) Providers Providers supply contextual information to the agent during response generation: #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#core-providers) Core Providers 1. **RECENT\_MESSAGES** (`recentMessages.ts`) Copy Ask AI // Provides conversation history and context { recentMessages: Memory[], recentInteractions: Memory[], formattedConversation: string } 2. **TIME** (`time.ts`) * Current date and time * Timezone information * Temporal context 3. **CHARACTER** (`character.ts`) * Agent’s personality traits * Background information * Behavioral guidelines 4. **ENTITIES** (`entities.ts`) * Information about users in the room * Entity relationships * User metadata 5. **RELATIONSHIPS** (`relationships.ts`) * Social graph data * Interaction history * Relationship tags 6. **WORLD** (`world.ts`) * Environment context * Server/world information * Room details 7. **ANXIETY** (`anxiety.ts`) * Agent’s emotional state * Stress levels * Mood indicators 8. **ATTACHMENTS** (`attachments.ts`) * Media content analysis * Image descriptions * Document summaries 9. **CAPABILITIES** (`capabilities.ts`) * Available actions * Service capabilities * Feature flags 10. **FACTS** (`facts.ts`) * Stored knowledge * Learned information * Contextual facts ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#evaluators) Evaluators Evaluators perform post-interaction cognitive processing: #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#reflection-evaluator-reflection-ts) REFLECTION Evaluator (`reflection.ts`) The reflection evaluator: 1. **Analyzes conversation quality** 2. **Extracts new facts** 3. **Identifies relationships** 4. **Updates knowledge base** Copy Ask AI { "thought": "Self-reflective analysis of interaction", "facts": [\ {\ "claim": "Factual statement learned",\ "type": "fact|opinion|status",\ "in_bio": false,\ "already_known": false\ }\ ], "relationships": [\ {\ "sourceEntityId": "initiator_id",\ "targetEntityId": "target_id",\ "tags": ["interaction_type", "context"]\ }\ ] } ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#services) Services #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#taskservice-task-ts) TaskService (`task.ts`) Manages scheduled and background tasks: Copy Ask AI class TaskService extends Service { // Executes tasks based on: // - Schedule (repeating tasks) // - Queue (one-time tasks) // - Validation rules // - Worker availability } Task features: * **Repeating tasks**: Execute at intervals * **One-time tasks**: Execute once and delete * **Immediate tasks**: Execute on creation * **Validated tasks**: Conditional execution [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#detailed-component-documentation) Detailed Component Documentation -------------------------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#message-handler-deep-dive) Message Handler Deep Dive #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#1-attachment-processing) 1\. Attachment Processing Copy Ask AI export async function processAttachments( attachments: Media[], runtime: IAgentRuntime ): Promise { // For images: Generate descriptions using vision models // For documents: Extract text content // For other media: Process as configured } #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#2-should-bypass-logic) 2\. Should Bypass Logic Copy Ask AI export function shouldBypassShouldRespond( runtime: IAgentRuntime, room?: Room, source?: string ): boolean { // DMs always bypass shouldRespond check // Voice DMs bypass // API calls bypass // Configurable via SHOULD_RESPOND_BYPASS_TYPES } #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#3-response-id-management) 3\. Response ID Management Copy Ask AI // Prevents duplicate responses when multiple messages arrive quickly const latestResponseIds = new Map>(); // Only process if this is still the latest response for the room ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#action-handler-pattern) Action Handler Pattern All actions follow this structure: Copy Ask AI export const actionName = { name: 'ACTION_NAME', similes: ['ALTERNATIVE_NAME', 'SYNONYM'], description: 'What this action does', validate: async (runtime: IAgentRuntime) => boolean, handler: async ( runtime: IAgentRuntime, message: Memory, state: State, options: any, callback: HandlerCallback, responses?: Memory[] ) => boolean, examples: ActionExample[][] } ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#provider-pattern) Provider Pattern Providers follow this structure: Copy Ask AI export const providerName: Provider = { name: 'PROVIDER_NAME', description: 'What context this provides', position: 100, // Order priority get: async (runtime: IAgentRuntime, message: Memory) => { return { data: {}, // Raw data values: {}, // Processed values text: '', // Formatted text for prompt }; }, }; [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#configuration) Configuration ------------------------------------------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#environment-variables) Environment Variables Copy Ask AI # Control which room types bypass shouldRespond check SHOULD_RESPOND_BYPASS_TYPES=["dm", "voice_dm", "api"] # Control which sources bypass shouldRespond check SHOULD_RESPOND_BYPASS_SOURCES=["client_chat", "api"] # Conversation context length CONVERSATION_LENGTH=20 # Response timeout (ms) RESPONSE_TIMEOUT=3600000 # 1 hour ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#character-templates) Character Templates Configure custom templates: Copy Ask AI character: { templates: { messageHandlerTemplate: string, shouldRespondTemplate: string, reflectionTemplate: string, postCreationTemplate: string } } [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#template-customization) Template Customization ------------------------------------------------------------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#understanding-templates) Understanding Templates Templates are the core prompts that control how your agent thinks and responds. The plugin-bootstrap provides default templates, but you can customize them through your character configuration to create unique agent behaviors. ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#available-templates) Available Templates 1. **shouldRespondTemplate** - Controls when the agent decides to respond 2. **messageHandlerTemplate** - Governs how the agent generates responses and selects actions 3. **reflectionTemplate** - Manages post-interaction analysis 4. **postCreationTemplate** - Handles social media post generation ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#how-templates-work) How Templates Work Templates use a mustache-style syntax with placeholders: * `{{agentName}}` - The agent’s name * `{{providers}}` - Injected provider context * `{{actionNames}}` - Available actions * `{{recentMessages}}` - Conversation history ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#customizing-templates) Customizing Templates You can override any template in your character configuration: Copy Ask AI import { Character } from '@elizaos/core'; export const myCharacter: Character = { name: 'TechBot', // ... other config ... templates: { // Custom shouldRespond logic shouldRespondTemplate: `Decide if {{agentName}} should help with technical questions. {{providers}} - Always respond to technical questions - Always respond to direct mentions - Ignore casual chat unless it's tech-related - If someone asks for help, ALWAYS respond Your technical assessment RESPOND | IGNORE | STOP `, // Custom message handler with specific behavior messageHandlerTemplate: `Generate a helpful technical response as {{agentName}}. {{providers}} Available actions: {{actionNames}} - Be precise and technical but friendly - Provide code examples when relevant - Ask clarifying questions for vague requests - Suggest best practices Technical analysis of the request ACTION1,ACTION2 PROVIDER1,PROVIDER2 Your helpful technical response `, // Custom reflection template reflectionTemplate: `Analyze the technical conversation for learning opportunities. {{recentMessages}} - Extract technical facts and solutions - Note programming patterns discussed - Track user expertise levels - Identify knowledge gaps { "thought": "Technical insight gained", "facts": [\ {\ "claim": "Technical fact learned",\ "type": "technical|solution|pattern",\ "topic": "programming|devops|architecture"\ }\ ], "userExpertise": { "level": "beginner|intermediate|expert", "topics": ["topic1", "topic2"] } } `, }, }; ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#template-processing-flow) Template Processing Flow 1. **Template Selection**: The system selects the appropriate template based on the current operation 2. **Variable Injection**: Placeholders are replaced with actual values 3. **Provider Integration**: Provider data is formatted and injected 4. **LLM Processing**: The completed prompt is sent to the language model 5. **Response Parsing**: The XML/JSON response is parsed and validated ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#advanced-template-techniques) Advanced Template Techniques #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#conditional-logic) Conditional Logic Copy Ask AI messageHandlerTemplate: `{{providers}} {{#if isNewUser}} Provide extra guidance and explanations {{/if}} {{#if hasAttachments}} Analyze the attached media carefully {{/if}} Context-aware thinking REPLY Adaptive response `; #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#custom-provider-integration) Custom Provider Integration Copy Ask AI messageHandlerTemplate: ` {{providers.CUSTOM_CONTEXT}} {{providers.USER_HISTORY}} Generate response considering the custom context above...`; [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#understanding-the-callback-mechanism) Understanding the Callback Mechanism ---------------------------------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#what-is-the-callback%3F) What is the Callback? The callback is a function passed to every action handler that **sends the response back to the user**. When you call the callback, you’re telling the system “here’s what to send back”. ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#callback-flow) Callback Flow Copy Ask AI // In an action handler async handler(runtime, message, state, options, callback) { // 1. Process the request const result = await doSomething(); // 2. Call callback to send response await callback({ text: "Here's your response", // The message to send actions: ['ACTION_NAME'], // Actions taken thought: 'Internal reasoning', // Agent's thought process attachments: [], // Optional media metadata: {} // Optional metadata }); // 3. Return success return true; } ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#important-callback-concepts) Important Callback Concepts 1. **Calling callback = Sending a message**: When you invoke `callback()`, the message is sent to the user 2. **Multiple callbacks = Multiple messages**: You can call callback multiple times to send multiple messages 3. **No callback = No response**: If you don’t call callback, no message is sent 4. **Async operation**: Always await the callback for proper error handling ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#callback-examples) Callback Examples #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#simple-response) Simple Response Copy Ask AI await callback({ text: 'Hello! How can I help?', actions: ['REPLY'], }); #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#response-with-attachments) Response with Attachments Copy Ask AI await callback({ text: "Here's the image you requested", actions: ['GENERATE_IMAGE'], attachments: [\ {\ url: 'https://example.com/image.png',\ contentType: 'image/png',\ },\ ], }); #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#multi-message-response) Multi-Message Response Copy Ask AI // First message await callback({ text: 'Let me check that for you...', actions: ['ACKNOWLEDGE'], }); // Do some processing const result = await fetchData(); // Second message with results await callback({ text: `Here's what I found: ${result}`, actions: ['REPLY'], }); #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#conditional-response) Conditional Response Copy Ask AI if (error) { await callback({ text: 'Sorry, I encountered an error', actions: ['ERROR'], metadata: { error: error.message }, }); } else { await callback({ text: 'Successfully completed!', actions: ['SUCCESS'], }); } ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#callback-best-practices) Callback Best Practices 1. **Always call callback**: Even for errors, call callback to inform the user 2. **Be descriptive**: Include clear text explaining what happened 3. **Use appropriate actions**: Tag responses with the correct action names 4. **Include thought**: Help with debugging by including agent reasoning 5. **Handle errors gracefully**: Provide user-friendly error messages [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#integration-guide) Integration Guide -------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#1-basic-integration) 1\. Basic Integration Copy Ask AI import { Project, ProjectAgent, Character } from '@elizaos/core'; // Define your character with bootstrap plugin const character: Character = { name: 'MyAgent', bio: ['An intelligent agent powered by elizaOS'], plugins: [\ '@elizaos/plugin-sql',\ '@elizaos/plugin-bootstrap',\ ], }; // Create the agent const agent: ProjectAgent = { character, // Custom plugins go here at agent level plugins: [], }; // Export the project export const project = { agents: [agent] }; ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#2-custom-event-handlers) 2\. Custom Event Handlers Copy Ask AI // Add custom handling for existing events runtime.on(EventType.MESSAGE_RECEIVED, async (payload) => { // Custom pre-processing await customPreProcessor(payload); // Call default handler await bootstrapPlugin.events[EventType.MESSAGE_RECEIVED][0](payload); // Custom post-processing await customPostProcessor(payload); }); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#3-extending-actions) 3\. Extending Actions Copy Ask AI // Create custom action that extends REPLY const customReplyAction = { ...replyAction, name: 'CUSTOM_REPLY', handler: async (...args) => { // Custom logic await customLogic(); // Call original handler return replyAction.handler(...args); }, }; [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#examples) Examples -------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#example-1%3A-basic-message-flow) Example 1: Basic Message Flow Copy Ask AI // 1. Message arrives const message = { id: 'msg-123', entityId: 'user-456', roomId: 'room-789', content: { text: 'Hello, how are you?', }, }; // 2. Bootstrap processes it // - Saves to memory // - Checks shouldRespond // - Generates response // - Executes REPLY action // - Runs reflection evaluator // 3. Response sent via callback callback({ text: "I'm doing well, thank you! How can I help you today?", actions: ['REPLY'], thought: 'User greeted me politely, responding in kind', }); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#example-2%3A-multi-action-response) Example 2: Multi-Action Response Copy Ask AI // Complex response with multiple actions const response = { thought: 'User needs help with a technical issue in a specific room', text: "I'll help you with that issue.", actions: ['REPLY', 'FOLLOW_ROOM', 'UPDATE_SETTINGS'], providers: ['TECHNICAL_DOCS', 'ROOM_INFO'], }; ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#example-3%3A-task-scheduling) Example 3: Task Scheduling Copy Ask AI // Register a task worker runtime.registerTaskWorker({ name: 'DAILY_SUMMARY', validate: async (runtime) => { const hour = new Date().getHours(); return hour === 9; // Run at 9 AM }, execute: async (runtime, options) => { // Generate and post daily summary await runtime.emitEvent(EventType.POST_GENERATED, { runtime, worldId: options.worldId, // ... other params }); }, }); // Create the task await runtime.createTask({ name: 'DAILY_SUMMARY', metadata: { updateInterval: 1000 * 60 * 60, // Check hourly }, tags: ['queue', 'repeat'], }); [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#best-practices) Best Practices -------------------------------------------------------------------------------------------------------------- 1. **Always check message validity** before processing 2. **Use providers** to gather context instead of direct database queries 3. **Chain actions** for complex behaviors 4. **Implement proper error handling** in custom components 5. **Respect rate limits** and response timeouts 6. **Test with different room types** and message formats 7. **Monitor reflection outputs** for agent learning [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#troubleshooting) Troubleshooting ---------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#common-issues) Common Issues 1. **Agent not responding** * Check room type and bypass settings * Verify agent isn’t muted * Check shouldRespond logic 2. **Duplicate responses** * Ensure response ID tracking is working * Check for multiple handler registrations 3. **Missing context** * Verify providers are registered * Check state composition 4. **Action failures** * Validate action requirements * Check handler errors * Verify callback execution [​](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#summary) Summary ------------------------------------------------------------------------------------------------ The `@elizaos/plugin-bootstrap` package is the heart of elizaOS’s message processing system. It provides a complete framework for: * Receiving and processing messages from any platform * Making intelligent response decisions * Generating contextual responses * Executing complex action chains * Learning from interactions * Managing background tasks Understanding this plugin is essential for developing effective elizaOS agents and extending the platform’s capabilities. Was this page helpful? YesNo [Message Processing Core](https://docs.elizaos.ai/plugin-registry/bootstrap) [Message Processing Flow](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow) ⌘I --- # Message Processing Flow - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Bootstrap Message Processing Flow [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Message Processing Flow - Detailed Breakdown](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#message-processing-flow-detailed-breakdown) * [Complete Message Flow Diagram](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#complete-message-flow-diagram) * [Detailed Step Descriptions](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#detailed-step-descriptions) * [1\. Initial Message Reception](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#1-initial-message-reception) * [2\. Self-Check](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#2-self-check) * [3\. Response ID Generation](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#3-response-id-generation) * [4\. Run Tracking](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#4-run-tracking) * [5\. Memory Storage](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#5-memory-storage) * [6\. Attachment Processing](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#6-attachment-processing) * [7\. Agent State Check](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#7-agent-state-check) * [8\. Should Respond Evaluation](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#8-should-respond-evaluation) * [Bypass Conditions](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#bypass-conditions) * [LLM Evaluation](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#llm-evaluation) * [9\. Response Generation](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#9-response-generation) * [State Composition with Providers](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#state-composition-with-providers) * [LLM Response](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#llm-response) * [10\. Response Validation](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#10-response-validation) * [11\. Action Processing](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#11-action-processing) * [Simple Response](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#simple-response) * [Complex Response](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#complex-response) * [12\. Evaluator Execution](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#12-evaluator-execution) * [Reflection Evaluator](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#reflection-evaluator) * [Key Decision Points](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#key-decision-points) * [1\. Should Respond Decision Tree](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#1-should-respond-decision-tree) * [2\. Response Type Decision](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#2-response-type-decision) * [3\. Evaluator Trigger Conditions](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#3-evaluator-trigger-conditions) * [Performance Optimizations](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#performance-optimizations) * [1\. Response ID Tracking](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#1-response-id-tracking) * [2\. Parallel Operations](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#2-parallel-operations) * [3\. Timeout Protection](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#3-timeout-protection) * [Error Handling](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#error-handling) * [1\. Run Lifecycle Events](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#1-run-lifecycle-events) * [2\. Graceful Degradation](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#2-graceful-degradation) * [Platform-Specific Handling](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#platform-specific-handling) * [Discord](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#discord) * [Telegram](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#telegram) * [Message Bus](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#message-bus) * [Summary](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#summary) * [Template Usage in Message Flow](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#template-usage-in-message-flow) * [1\. shouldRespondTemplate - Decision Point](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#1-shouldrespondtemplate-decision-point) * [2\. messageHandlerTemplate - Response Generation](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#2-messagehandlertemplate-response-generation) * [3\. reflectionTemplate - Post-Interaction Analysis](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#3-reflectiontemplate-post-interaction-analysis) * [4\. postCreationTemplate - Social Media Posts](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#4-postcreationtemplate-social-media-posts) * [Template Processing Pipeline](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#template-processing-pipeline) * [Customization Impact](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#customization-impact) [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#message-processing-flow-detailed-breakdown) Message Processing Flow - Detailed Breakdown ============================================================================================================================================================== This document provides a step-by-step breakdown of how messages flow through the plugin-bootstrap system. [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#complete-message-flow-diagram) Complete Message Flow Diagram ---------------------------------------------------------------------------------------------------------------------------------- [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#detailed-step-descriptions) Detailed Step Descriptions ---------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#1-initial-message-reception) 1\. Initial Message Reception Copy Ask AI // Event triggered by platform (Discord, Telegram, etc.) EventType.MESSAGE_RECEIVED → messageReceivedHandler ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#2-self-check) 2\. Self-Check Copy Ask AI if (message.entityId === runtime.agentId) { logger.debug('Skipping message from self'); return; } ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#3-response-id-generation) 3\. Response ID Generation Copy Ask AI // Prevents duplicate responses for rapid messages const responseId = v4(); latestResponseIds.get(runtime.agentId).set(message.roomId, responseId); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#4-run-tracking) 4\. Run Tracking Copy Ask AI const runId = runtime.startRun(); await runtime.emitEvent(EventType.RUN_STARTED, {...}); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#5-memory-storage) 5\. Memory Storage Copy Ask AI await Promise.all([\ runtime.addEmbeddingToMemory(message), // Vector embeddings\ runtime.createMemory(message, 'messages'), // Message history\ ]); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#6-attachment-processing) 6\. Attachment Processing Copy Ask AI if (message.content.attachments?.length > 0) { // Images: Generate descriptions // Documents: Extract text // Other: Process as configured message.content.attachments = await processAttachments(message.content.attachments, runtime); } ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#7-agent-state-check) 7\. Agent State Check Copy Ask AI const agentUserState = await runtime.getParticipantUserState(message.roomId, runtime.agentId); if ( agentUserState === 'MUTED' && !message.content.text?.toLowerCase().includes(runtime.character.name.toLowerCase()) ) { return; // Ignore if muted and not mentioned } ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#8-should-respond-evaluation) 8\. Should Respond Evaluation #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#bypass-conditions) Bypass Conditions Copy Ask AI function shouldBypassShouldRespond(runtime, room, source) { // Default bypass types const bypassTypes = [ChannelType.DM, ChannelType.VOICE_DM, ChannelType.SELF, ChannelType.API]; // Default bypass sources const bypassSources = ['client_chat']; // Plus any configured in environment return bypassTypes.includes(room.type) || bypassSources.includes(source); } #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#llm-evaluation) LLM Evaluation Copy Ask AI if (!shouldBypassShouldRespond) { const state = await runtime.composeState(message, [\ 'ANXIETY',\ 'SHOULD_RESPOND',\ 'ENTITIES',\ 'CHARACTER',\ 'RECENT_MESSAGES',\ 'ACTIONS',\ ]); const prompt = composePromptFromState({ state, template: shouldRespondTemplate, }); const response = await runtime.useModel(ModelType.TEXT_SMALL, { prompt }); const parsed = parseKeyValueXml(response); shouldRespond = parsed?.action && !['IGNORE', 'NONE'].includes(parsed.action.toUpperCase()); } ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#9-response-generation) 9\. Response Generation #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#state-composition-with-providers) State Composition with Providers Copy Ask AI state = await runtime.composeState(message, ['ACTIONS']); // Each provider adds context: // - RECENT_MESSAGES: Conversation history // - CHARACTER: Personality traits // - ENTITIES: User information // - TIME: Temporal context // - RELATIONSHIPS: Social connections // - WORLD: Environment details // - etc. #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#llm-response) LLM Response Copy Ask AI const prompt = composePromptFromState({ state, template: messageHandlerTemplate, }); let response = await runtime.useModel(ModelType.TEXT_LARGE, { prompt }); // Expected XML format: /* Agent's internal reasoning REPLY,FOLLOW_ROOM TECHNICAL_DOCS,FAQ The actual response text false */ ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#10-response-validation) 10\. Response Validation Copy Ask AI // Retry logic for missing fields while (retries < 3 && (!responseContent?.thought || !responseContent?.actions)) { // Regenerate response retries++; } // Check if still the latest response if (latestResponseIds.get(runtime.agentId).get(message.roomId) !== responseId) { return; // Newer message is being processed } ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#11-action-processing) 11\. Action Processing #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#simple-response) Simple Response Copy Ask AI // Simple = REPLY action only, no providers if (responseContent.simple && responseContent.text) { await callback(responseContent); } #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#complex-response) Complex Response Copy Ask AI // Multiple actions or providers await runtime.processActions(message, responseMessages, state, callback); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#12-evaluator-execution) 12\. Evaluator Execution #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#reflection-evaluator) Reflection Evaluator Copy Ask AI // Runs after response generation await runtime.evaluate(message, state, shouldRespond, callback, responseMessages); // Reflection evaluator: // 1. Analyzes conversation quality // 2. Extracts new facts // 3. Updates relationships // 4. Self-reflects on performance [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#key-decision-points) Key Decision Points -------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#1-should-respond-decision-tree) 1\. Should Respond Decision Tree Copy Ask AI Is DM? → YES → Respond Is Voice DM? → YES → Respond Is API Call? → YES → Respond Is Muted + Name Mentioned? → YES → Respond Is Muted? → NO → Ignore Run shouldRespond LLM → - Action = REPLY/etc → Respond - Action = IGNORE/NONE → Ignore ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#2-response-type-decision) 2\. Response Type Decision Copy Ask AI Actions = [REPLY] only AND Providers = [] → Simple Response Otherwise → Complex Response with Action Processing ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#3-evaluator-trigger-conditions) 3\. Evaluator Trigger Conditions Copy Ask AI Message Count > ConversationLength / 4 → Run Reflection New Interaction → Update Relationships Facts Mentioned → Extract and Store [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#performance-optimizations) Performance Optimizations -------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#1-response-id-tracking) 1\. Response ID Tracking * Prevents duplicate responses when multiple messages arrive quickly * Only processes the latest message per room ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#2-parallel-operations) 2\. Parallel Operations Copy Ask AI // Parallel memory operations await Promise.all([\ runtime.addEmbeddingToMemory(message),\ runtime.createMemory(message, 'messages')\ ]); // Parallel data fetching in providers const [entities, room, messages, interactions] = await Promise.all([\ getEntityDetails({ runtime, roomId }),\ runtime.getRoom(roomId),\ runtime.getMemories({ tableName: 'messages', roomId }),\ getRecentInteractions(...)\ ]); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#3-timeout-protection) 3\. Timeout Protection Copy Ask AI const timeoutDuration = 60 * 60 * 1000; // 1 hour await Promise.race([processingPromise, timeoutPromise]); [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#error-handling) Error Handling ---------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#1-run-lifecycle-events) 1\. Run Lifecycle Events Copy Ask AI try { // Process message await runtime.emitEvent(EventType.RUN_ENDED, { status: 'completed' }); } catch (error) { await runtime.emitEvent(EventType.RUN_ENDED, { status: 'error', error: error.message, }); } ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#2-graceful-degradation) 2\. Graceful Degradation * Missing attachments → Continue without them * Provider errors → Use default values * LLM failures → Retry with backoff * Database errors → Log and continue [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#platform-specific-handling) Platform-Specific Handling ---------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#discord) Discord * Channels → Rooms with ChannelType * Servers → Worlds * Users → Entities ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#telegram) Telegram * Chats → Rooms * Groups → Worlds * Users → Entities ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#message-bus) Message Bus * Topics → Rooms * Namespaces → Worlds * Publishers → Entities [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#summary) Summary -------------------------------------------------------------------------------------- The message flow through plugin-bootstrap is designed to be: 1. **Platform-agnostic** - Works with any message source 2. **Intelligent** - Makes context-aware response decisions 3. **Extensible** - Supports custom actions, providers, evaluators 4. **Resilient** - Handles errors gracefully 5. **Performant** - Uses parallel operations and caching This flow ensures that every message is processed consistently, responses are contextual and appropriate, and the agent learns from each interaction. [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#template-usage-in-message-flow) Template Usage in Message Flow ------------------------------------------------------------------------------------------------------------------------------------ Understanding where templates are used helps you customize the right parts of the flow: ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#1-shouldrespondtemplate-decision-point) 1\. **shouldRespondTemplate** - Decision Point Used at step 8 in the flow when evaluating whether to respond: Copy Ask AI Message Received → shouldRespondTemplate → RESPOND/IGNORE/STOP This template controls: * When your agent engages in conversations * What triggers a response * When to stay silent ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#2-messagehandlertemplate-response-generation) 2\. **messageHandlerTemplate** - Response Generation Used at step 9 when generating the actual response: Copy Ask AI Decision to Respond → messageHandlerTemplate → Response + Actions This template controls: * How responses are formulated * Which actions are selected * The agent’s personality and tone * Which providers to use for context ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#3-reflectiontemplate-post-interaction-analysis) 3\. **reflectionTemplate** - Post-Interaction Analysis Used at step 12 during evaluator execution: Copy Ask AI Response Sent → reflectionTemplate → Learning & Memory Updates This template controls: * What the agent learns from interactions * How facts are extracted * Relationship tracking logic * Self-improvement mechanisms ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#4-postcreationtemplate-social-media-posts) 4\. **postCreationTemplate** - Social Media Posts Used when POST\_GENERATED event is triggered: Copy Ask AI Post Request → postCreationTemplate → Social Media Content This template controls: * Post style and tone * Content generation approach * Image prompt generation ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#template-processing-pipeline) Template Processing Pipeline 1. **Template Selection**: System picks the appropriate template 2. **Variable Replacement**: `{{agentName}}`, `{{providers}}`, etc. are replaced 3. **Provider Injection**: Provider data is formatted and inserted 4. **Prompt Assembly**: Complete prompt is constructed 5. **LLM Processing**: Sent to language model 6. **Response Parsing**: XML/JSON response is parsed 7. **Execution**: Actions are executed, callbacks are called ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#customization-impact) Customization Impact When you customize templates, you’re modifying these key decision points: * **shouldRespond**: Change engagement patterns * **messageHandler**: Alter personality and response style * **reflection**: Modify learning and memory formation * **postCreation**: Adjust social media presence Each template change cascades through the entire interaction flow, allowing deep customization of agent behavior while maintaining the robust message processing infrastructure. Was this page helpful? YesNo [Complete Developer Guide](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation) [Implementation Examples](https://docs.elizaos.ai/plugin-registry/bootstrap/examples) ⌘I --- # Implementation Examples - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Bootstrap Implementation Examples [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Basic Agent Setup](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#basic-agent-setup) * [Minimal Agent](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#minimal-agent) * [Custom Character Agent](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#custom-character-agent) * [Custom Actions](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#custom-actions) * [Creating a Custom Help Action](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#creating-a-custom-help-action) * [Action that Calls External API](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#action-that-calls-external-api) * [Custom Providers](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#custom-providers) * [Creating a System Status Provider](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#creating-a-system-status-provider) * [Context-Aware Provider](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#context-aware-provider) * [Custom Evaluators](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#custom-evaluators) * [Creating a Sentiment Analyzer](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#creating-a-sentiment-analyzer) * [Task Services](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#task-services) * [Scheduled Daily Summary](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#scheduled-daily-summary) * [Event-Driven Task](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#event-driven-task) * [Complete Bot Example](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#complete-bot-example) * [Support Bot with Custom Features](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#support-bot-with-custom-features) * [Integration Examples](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#integration-examples) * [Discord Integration](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#discord-integration) * [Multi-Platform Bot](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#multi-platform-bot) * [Best Practices](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#best-practices) * [Debugging Tips](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#debugging-tips) * [Understanding the Callback Mechanism](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#understanding-the-callback-mechanism) * [Template Customization Examples](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#template-customization-examples) * [Example 1: Gaming Bot with Custom Templates](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#example-1%3A-gaming-bot-with-custom-templates) * [Example 2: Customer Support Bot with Templates](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#example-2%3A-customer-support-bot-with-templates) * [Example 3: Educational Bot with Adaptive Templates](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#example-3%3A-educational-bot-with-adaptive-templates) * [Advanced Callback Patterns](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#advanced-callback-patterns) * [Progressive Disclosure Pattern](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#progressive-disclosure-pattern) * [Error Recovery Pattern](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#error-recovery-pattern) * [Streaming Response Pattern](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#streaming-response-pattern) This document provides practical examples of building agents using the plugin-bootstrap package. [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#basic-agent-setup) Basic Agent Setup ------------------------------------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#minimal-agent) Minimal Agent Copy Ask AI import { type Character } from '@elizaos/core'; // Define a minimal character export const character: Character = { name: 'Assistant', description: 'A helpful AI assistant', plugins: [\ '@elizaos/plugin-sql', // For memory storage\ '@elizaos/plugin-openai',\ '@elizaos/plugin-bootstrap', // Essential for message handling\ ], settings: { secrets: {}, }, system: 'Respond to messages in a helpful and concise manner.', bio: [\ 'Provides helpful responses',\ 'Keeps answers concise and clear',\ 'Engages in a friendly manner',\ ], style: { all: [\ 'Be helpful and informative',\ 'Keep responses concise',\ 'Use clear language',\ ], chat: [\ 'Be conversational',\ 'Show understanding',\ ], }, }; ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#custom-character-agent) Custom Character Agent Copy Ask AI import { type Character } from '@elizaos/core'; export const techBotCharacter: Character = { name: 'TechBot', description: 'A technical support specialist', plugins: [\ '@elizaos/plugin-bootstrap',\ '@elizaos/plugin-sql',\ // Add platform plugins as needed\ ...(process.env.DISCORD_API_TOKEN ? ['@elizaos/plugin-discord'] : []),\ ], settings: { secrets: {}, avatar: 'https://example.com/techbot-avatar.png', }, system: 'You are a technical support specialist. Provide clear, patient, and detailed assistance with technical issues. Break down complex problems into simple steps.', bio: [\ 'Expert in software development and troubleshooting',\ 'Patient and detail-oriented problem solver',\ 'Specializes in clear technical communication',\ 'Helps users at all skill levels',\ ], topics: [\ 'software development',\ 'debugging',\ 'technical support',\ 'programming languages',\ 'system troubleshooting',\ ], style: { all: [\ 'Be professional yet friendly',\ 'Use technical vocabulary but keep it accessible',\ 'Provide step-by-step guidance',\ 'Ask clarifying questions when needed',\ ], chat: [\ 'Be patient and understanding',\ 'Break down complex topics',\ 'Offer examples when helpful',\ ], }, // Custom templates templates: { messageHandlerTemplate: `Generate a technical support response as {{agentName}} {{providers}} - Assess the user's technical level from their message - Consider the complexity of their problem - Provide appropriate solutions - Use clear, step-by-step guidance - Include code examples when relevant Analysis of the technical issue Your helpful technical response `, shouldRespondTemplate: `Decide if {{agentName}} should respond {{recentMessages}} - User asks a technical question - User reports an issue or bug - User needs clarification on technical topics - Direct mention of {{agentName}} - Discussion about programming or software - Casual conversation between others - Non-technical discussions - Already resolved issues Brief explanation RESPOND | IGNORE | STOP `, }, }; [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#custom-actions) Custom Actions ------------------------------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#creating-a-custom-help-action) Creating a Custom Help Action Copy Ask AI import { Action, ActionExample } from '@elizaos/core'; const helpAction: Action = { name: 'HELP', similes: ['SUPPORT', 'ASSIST', 'GUIDE'], description: 'Provides detailed help on a specific topic', validate: async (runtime) => { // Always available return true; }, handler: async (runtime, message, state, options, callback) => { // Extract help topic from message const topic = extractHelpTopic(message.content.text); // Get relevant documentation const helpContent = await getHelpContent(topic); // Generate response const response = { thought: `User needs help with ${topic}`, text: helpContent, actions: ['HELP'], attachments: topic.includes('screenshot') ? [{ url: '/help/screenshots/' + topic + '.png' }] : [], }; await callback(response); return true; }, examples: [\ [\ {\ name: '{{user}}',\ content: { text: 'How do I reset my password?' },\ },\ {\ name: '{{agent}}',\ content: {\ text: "Here's how to reset your password:\n1. Click 'Forgot Password'\n2. Enter your email\n3. Check your inbox for reset link",\ actions: ['HELP'],\ },\ },\ ],\ ], }; // Add to agent const agentWithHelp = new AgentRuntime({ character: { /* ... */ }, plugins: [\ bootstrapPlugin,\ {\ name: 'custom-help',\ actions: [helpAction],\ },\ ], }); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#action-that-calls-external-api) Action that Calls External API Copy Ask AI const weatherAction: Action = { name: 'CHECK_WEATHER', similes: ['WEATHER', 'FORECAST'], description: 'Checks current weather for a location', validate: async (runtime) => { // Check if API key is configured return !!runtime.getSetting('WEATHER_API_KEY'); }, handler: async (runtime, message, state, options, callback) => { const location = extractLocation(message.content.text); const apiKey = runtime.getSetting('WEATHER_API_KEY'); try { const response = await fetch( `https://api.weather.com/v1/current?location=${location}&key=${apiKey}` ); const weather = await response.json(); await callback({ thought: `Checking weather for ${location}`, text: `Current weather in ${location}: ${weather.temp}°F, ${weather.condition}`, actions: ['CHECK_WEATHER'], metadata: { weather }, }); } catch (error) { await callback({ thought: `Failed to get weather for ${location}`, text: "Sorry, I couldn't fetch the weather information right now.", actions: ['CHECK_WEATHER'], error: error.message, }); } return true; }, }; [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#custom-providers) Custom Providers ---------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#creating-a-system-status-provider) Creating a System Status Provider Copy Ask AI import { Provider } from '@elizaos/core'; const systemStatusProvider: Provider = { name: 'SYSTEM_STATUS', description: 'Provides current system status and metrics', position: 50, get: async (runtime, message) => { // Gather system metrics const metrics = await gatherSystemMetrics(); // Format for prompt const statusText = ` # System Status - CPU Usage: ${metrics.cpu}% - Memory: ${metrics.memory}% used - Active Users: ${metrics.activeUsers} - Response Time: ${metrics.avgResponseTime}ms - Uptime: ${metrics.uptime} `.trim(); return { data: metrics, values: { cpuUsage: metrics.cpu, memoryUsage: metrics.memory, isHealthy: metrics.cpu < 80 && metrics.memory < 90, }, text: statusText, }; }, }; // Use in agent const monitoringAgent = new AgentRuntime({ character: { name: 'SystemMonitor', // ... }, plugins: [\ bootstrapPlugin,\ {\ name: 'monitoring',\ providers: [systemStatusProvider],\ },\ ], }); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#context-aware-provider) Context-Aware Provider Copy Ask AI const userPreferencesProvider: Provider = { name: 'USER_PREFERENCES', description: 'User preferences and settings', get: async (runtime, message) => { const userId = message.entityId; const prefs = await runtime.getMemories({ tableName: 'preferences', agentId: runtime.agentId, entityId: userId, count: 1, }); if (!prefs.length) { return { data: {}, values: {}, text: 'No user preferences found.', }; } const preferences = prefs[0].content; return { data: preferences, values: { language: preferences.language || 'en', timezone: preferences.timezone || 'UTC', notifications: preferences.notifications ?? true, }, text: `User Preferences: - Language: ${preferences.language || 'English'} - Timezone: ${preferences.timezone || 'UTC'} - Notifications: ${preferences.notifications ? 'Enabled' : 'Disabled'}`, }; }, }; [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#custom-evaluators) Custom Evaluators ------------------------------------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#creating-a-sentiment-analyzer) Creating a Sentiment Analyzer Copy Ask AI import { Evaluator } from '@elizaos/core'; const sentimentEvaluator: Evaluator = { name: 'SENTIMENT_ANALYSIS', similes: ['ANALYZE_MOOD', 'CHECK_SENTIMENT'], description: 'Analyzes conversation sentiment and adjusts agent mood', validate: async (runtime, message) => { // Run every 5 messages const messages = await runtime.getMemories({ tableName: 'messages', roomId: message.roomId, count: 5, }); return messages.length >= 5; }, handler: async (runtime, message, state) => { const prompt = `Analyze the sentiment of the recent conversation. ${state.recentMessages} Provide a sentiment analysis with: - Overall sentiment (positive/negative/neutral) - Emotional tone - Suggested agent mood adjustment`; const analysis = await runtime.useModel(ModelType.TEXT_SMALL, { prompt }); // Store sentiment data await runtime.createMemory( { entityId: runtime.agentId, agentId: runtime.agentId, roomId: message.roomId, content: { type: 'sentiment_analysis', analysis: analysis, timestamp: Date.now(), }, }, 'analysis' ); // Adjust agent mood if needed if (analysis.suggestedMood) { await runtime.updateCharacterMood(analysis.suggestedMood); } return analysis; }, }; [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#task-services) Task Services ---------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#scheduled-daily-summary) Scheduled Daily Summary Copy Ask AI // Register a daily summary task runtime.registerTaskWorker({ name: 'DAILY_SUMMARY', validate: async (runtime, message, state) => { const hour = new Date().getHours(); return hour === 9; // Run at 9 AM }, execute: async (runtime, options) => { // Gather yesterday's data const yesterday = new Date(); yesterday.setDate(yesterday.getDate() - 1); const messages = await runtime.getMemories({ tableName: 'messages', startTime: yesterday.setHours(0, 0, 0, 0), endTime: yesterday.setHours(23, 59, 59, 999), }); // Generate summary const summary = await generateDailySummary(messages); // Post to main channel await runtime.emitEvent(EventType.POST_GENERATED, { runtime, worldId: options.worldId, userId: runtime.agentId, roomId: options.mainChannelId, source: 'task', callback: async (content) => { // Handle posted summary console.log('Daily summary posted:', content.text); }, }); }, }); // Create the scheduled task await runtime.createTask({ name: 'DAILY_SUMMARY', description: 'Posts daily activity summary', metadata: { updateInterval: 1000 * 60 * 60, // Check hourly worldId: 'main-world', mainChannelId: 'general', }, tags: ['queue', 'repeat'], }); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#event-driven-task) Event-Driven Task Copy Ask AI // Task that triggers on specific events runtime.registerTaskWorker({ name: 'NEW_USER_WELCOME', execute: async (runtime, options) => { const { userId, userName } = options; // Send welcome message await runtime.sendMessage({ roomId: options.roomId, content: { text: `Welcome ${userName}! 👋 I'm here to help you get started.`, actions: ['WELCOME'], }, }); // Schedule follow-up await runtime.createTask({ name: 'WELCOME_FOLLOWUP', metadata: { userId, executeAt: Date.now() + 1000 * 60 * 60 * 24, // 24 hours later }, tags: ['queue'], }); }, }); // Trigger on new user runtime.on(EventType.ENTITY_JOINED, async (payload) => { await runtime.createTask({ name: 'NEW_USER_WELCOME', metadata: { userId: payload.entityId, userName: payload.entity.name, roomId: payload.roomId, }, tags: ['queue', 'immediate'], }); }); [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#complete-bot-example) Complete Bot Example ------------------------------------------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#support-bot-with-custom-features) Support Bot with Custom Features Copy Ask AI import { AgentRuntime, Plugin, EventType, ChannelType } from '@elizaos/core'; // Custom support plugin const supportPlugin: Plugin = { name: 'support-features', description: 'Custom support bot features', actions: [\ {\ name: 'CREATE_TICKET',\ similes: ['TICKET', 'ISSUE', 'REPORT'],\ description: 'Creates a support ticket',\ \ validate: async (runtime) => true,\ \ handler: async (runtime, message, state, options, callback) => {\ const ticket = {\ id: generateTicketId(),\ userId: message.entityId,\ issue: message.content.text,\ status: 'open',\ createdAt: Date.now(),\ };\ \ await runtime.createMemory(\ {\ entityId: runtime.agentId,\ agentId: runtime.agentId,\ roomId: message.roomId,\ content: {\ type: 'ticket',\ ...ticket,\ },\ },\ 'tickets'\ );\ \ await callback({\ thought: 'Creating support ticket',\ text: `I've created ticket #${ticket.id} for your issue. Our team will review it shortly.`,\ actions: ['CREATE_TICKET'],\ metadata: { ticketId: ticket.id },\ });\ \ return true;\ },\ },\ ], providers: [\ {\ name: 'OPEN_TICKETS',\ description: 'Lists open support tickets',\ \ get: async (runtime, message) => {\ const tickets = await runtime.getMemories({\ tableName: 'tickets',\ agentId: runtime.agentId,\ filter: { status: 'open' },\ count: 10,\ });\ \ const ticketList = tickets\ .map((t) => `- #${t.content.id}: ${t.content.issue.substring(0, 50)}...`)\ .join('\n');\ \ return {\ data: { tickets },\ values: { openCount: tickets.length },\ text: `Open Tickets (${tickets.length}):\n${ticketList}`,\ };\ },\ },\ ], evaluators: [\ {\ name: 'TICKET_ESCALATION',\ description: 'Checks if tickets need escalation',\ \ validate: async (runtime, message) => {\ // Check every 10 messages\ return message.content.type === 'ticket';\ },\ \ handler: async (runtime, message, state) => {\ const urgentKeywords = ['urgent', 'critical', 'emergency', 'asap'];\ const needsEscalation = urgentKeywords.some((word) =>\ message.content.text.toLowerCase().includes(word)\ );\ \ if (needsEscalation) {\ await runtime.emitEvent('TICKET_ESCALATED', {\ ticketId: message.content.ticketId,\ reason: 'Urgent keywords detected',\ });\ }\ \ return { escalated: needsEscalation };\ },\ },\ ], services: [], events: { [EventType.MESSAGE_RECEIVED]: [\ async (payload) => {\ // Auto-respond to DMs with ticket creation prompt\ const room = await payload.runtime.getRoom(payload.message.roomId);\ if (room?.type === ChannelType.DM) {\ // Check if this is a new conversation\ const messages = await payload.runtime.getMemories({\ tableName: 'messages',\ roomId: payload.message.roomId,\ count: 2,\ });\ \ if (messages.length === 1) {\ await payload.callback({\ text: "Hello! I'm here to help. Would you like to create a support ticket?",\ actions: ['GREET'],\ suggestions: ['Create ticket', 'Check ticket status', 'Get help'],\ });\ }\ }\ },\ ], }, }; // Create the support bot const supportBot = new AgentRuntime({ character: { name: 'SupportBot', description: '24/7 customer support specialist', bio: 'I help users resolve issues and create support tickets', modelProvider: 'openai', templates: { messageHandlerTemplate: `# Support Bot Response {{providers}} Guidelines: - Be empathetic and professional - Gather all necessary information - Offer to create tickets for unresolved issues - Provide ticket numbers for tracking `, }, }, plugins: [bootstrapPlugin, pglitePlugin, supportPlugin], settings: { CONVERSATION_LENGTH: 50, // Longer context for support SHOULD_RESPOND_BYPASS_TYPES: ['dm', 'support', 'ticket'], }, }); // Start the bot await supportBot.start(); [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#integration-examples) Integration Examples ------------------------------------------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#discord-integration) Discord Integration Copy Ask AI import { DiscordClient } from '@elizaos/discord'; const discordBot = new AgentRuntime({ character: { /* ... */ }, plugins: [bootstrapPlugin], clients: [new DiscordClient()], }); // Discord-specific room handling discordBot.on(EventType.MESSAGE_RECEIVED, async (payload) => { const room = await payload.runtime.getRoom(payload.message.roomId); // Handle Discord-specific features if (room?.metadata?.discordType === 'thread') { // Special handling for threads } }); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#multi-platform-bot) Multi-Platform Bot Copy Ask AI import { DiscordClient } from '@elizaos/discord'; import { TelegramClient } from '@elizaos/telegram'; import { TwitterClient } from '@elizaos/twitter'; const multiPlatformBot = new AgentRuntime({ character: { name: 'OmniBot', description: 'Available everywhere', }, plugins: [\ bootstrapPlugin,\ {\ name: 'platform-adapter',\ providers: [\ {\ name: 'PLATFORM_INFO',\ get: async (runtime, message) => {\ const source = message.content.source;\ const platformTips = {\ discord: 'Use /commands for Discord-specific features',\ telegram: 'Use inline keyboards for better UX',\ twitter: 'Keep responses under 280 characters',\ };\ \ return {\ data: { platform: source },\ values: { isTwitter: source === 'twitter' },\ text: `Platform: ${source}\nTip: ${platformTips[source] || 'None'}`,\ };\ },\ },\ ],\ },\ ], clients: [new DiscordClient(), new TelegramClient(), new TwitterClient()], }); [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#best-practices) Best Practices ------------------------------------------------------------------------------------------------ 1. **Always include bootstrapPlugin** - It’s the foundation 2. **Use providers for context** - Don’t query database in actions 3. **Chain actions thoughtfully** - Order matters 4. **Handle errors gracefully** - Users should get helpful messages 5. **Test with different scenarios** - DMs, groups, mentions 6. **Monitor evaluator output** - Learn from your bot’s analysis 7. **Configure templates** - Match your bot’s personality [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#debugging-tips) Debugging Tips ------------------------------------------------------------------------------------------------ Copy Ask AI // Enable debug logging process.env.DEBUG = 'elizaos:*'; // Log action execution const debugAction = { ...originalAction, handler: async (...args) => { console.log(`Executing ${debugAction.name}`, args[1].content); const result = await originalAction.handler(...args); console.log(`${debugAction.name} completed`, result); return result; }, }; // Monitor provider data runtime.on('state:composed', (state) => { console.log( 'State providers:', state.providerData.map((p) => p.providerName) ); }); // Track message flow runtime.on(EventType.MESSAGE_RECEIVED, (payload) => { console.log(`Message flow: ${payload.message.entityId} -> ${payload.runtime.agentId}`); }); These examples demonstrate the flexibility and power of the plugin-bootstrap system. Start with simple examples and gradually add complexity as needed! ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#understanding-the-callback-mechanism) Understanding the Callback Mechanism Every action handler receives a callback function that sends messages back to the user. Here’s how it works: Copy Ask AI const explainAction: Action = { name: 'EXPLAIN', description: 'Explains a concept in detail', handler: async (runtime, message, state, options, callback) => { // Extract topic from message const topic = extractTopic(message.content.text); // First message - acknowledge the request await callback({ text: `Let me explain ${topic} for you...`, actions: ['ACKNOWLEDGE'], }); // Fetch explanation (simulating delay) const explanation = await fetchExplanation(topic); // Second message - deliver the explanation await callback({ text: explanation, actions: ['EXPLAIN'], thought: `Explained ${topic} to the user`, }); // Third message - offer follow-up await callback({ text: 'Would you like me to explain anything else about this topic?', actions: ['FOLLOW_UP'], }); return true; }, }; [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#template-customization-examples) Template Customization Examples ---------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#example-1%3A-gaming-bot-with-custom-templates) Example 1: Gaming Bot with Custom Templates Copy Ask AI import { AgentRuntime, Character } from '@elizaos/core'; import { bootstrapPlugin } from '@elizaos/plugin-bootstrap'; const gamingBotCharacter: Character = { name: 'GameMaster', description: 'A gaming companion and guide', templates: { // Custom shouldRespond for gaming context shouldRespondTemplate: `Decide if {{agentName}} should respond to gaming-related messages. {{providers}} - ALWAYS respond to: game questions, strategy requests, team coordination - RESPOND to: patch notes discussion, build advice, gameplay tips - IGNORE: off-topic chat, real-world discussions (unless directly asked) - STOP if: asked to stop giving advice or to be quiet Gaming context assessment RESPOND | IGNORE | STOP `, // Gaming-focused message handler messageHandlerTemplate: `Generate gaming advice as {{agentName}}. {{providers}} Available actions: {{actionNames}} - Use gaming terminology naturally - Reference game mechanics when relevant - Be encouraging to new players - Share pro tips for experienced players - React enthusiastically to achievements - Short, punchy responses for in-game chat - Detailed explanations for strategy questions - Use gaming emotes and expressions - Reference popular gaming memes appropriately Gaming situation analysis REPLY GAME_STATE,PLAYER_STATS Your gaming response `, // Gaming-specific reflection reflectionTemplate: `Analyze gaming interactions for improvement. {{recentMessages}} - Track player skill progression - Note frequently asked game mechanics - Identify team dynamics and roles - Record successful strategies shared - Monitor player frustration levels { "thought": "Gaming insight", "facts": [{\ "claim": "Gaming fact or strategy",\ "type": "strategy|mechanic|meta",\ "game": "specific game name"\ }], "playerProfile": { "skillLevel": "beginner|intermediate|advanced|pro", "preferredRole": "tank|dps|support|flex", "interests": ["pvp", "pve", "competitive"] } } `, }, // Gaming-related bio and style bio: [\ 'Expert in multiple game genres',\ 'Provides real-time strategy advice',\ 'Helps teams coordinate effectively',\ 'Explains complex game mechanics simply',\ ], style: { chat: [\ 'Use gaming slang appropriately',\ 'Quick responses during matches',\ 'Detailed guides when asked',\ 'Supportive and encouraging tone',\ ], }, }; // Create the gaming bot const gamingBot = new AgentRuntime({ character: gamingBotCharacter, plugins: [bootstrapPlugin], }); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#example-2%3A-customer-support-bot-with-templates) Example 2: Customer Support Bot with Templates Copy Ask AI const supportBotCharacter: Character = { name: 'SupportAgent', description: '24/7 customer support specialist', templates: { // Support-focused shouldRespond shouldRespondTemplate: `Determine if {{agentName}} should handle this support request. {{providers}} PRIORITY 1 (Always respond): - Error messages or bug reports - Account issues or login problems - Payment or billing questions - Direct help requests PRIORITY 2 (Respond): - Feature questions - How-to requests - General feedback PRIORITY 3 (Conditionally respond): - Complaints (respond with empathy) - Feature requests (acknowledge and log) NEVER IGNORE: - Frustrated customers - Urgent issues - Security concerns Support priority assessment RESPOND | ESCALATE | ACKNOWLEDGE `, // Professional support message handler messageHandlerTemplate: `Provide professional support as {{agentName}}. {{providers}} Available actions: {{actionNames}} - Acknowledge the issue immediately - Express empathy for any inconvenience - Provide clear, step-by-step solutions - Offer alternatives if primary solution unavailable - Always follow up on open issues - Professional yet friendly - Patient and understanding - Solution-oriented - Proactive in preventing future issues Issue analysis and solution approach REPLY,CREATE_TICKET USER_HISTORY,KNOWLEDGE_BASE,OPEN_TICKETS Your support response `, // Support interaction reflection reflectionTemplate: `Analyze support interaction for quality and improvement. {{recentMessages}} - Issue resolved: yes/no/escalated - Customer satisfaction indicators - Response time and efficiency - Knowledge gaps identified - Common issues pattern { "thought": "Support interaction analysis", "resolution": { "status": "resolved|unresolved|escalated", "issueType": "technical|billing|account|other", "satisfactionIndicators": ["positive", "negative", "neutral"] }, "facts": [{\ "claim": "Issue or solution discovered",\ "type": "bug|workaround|feature_request",\ "frequency": "first_time|recurring|common"\ }], "improvements": ["suggested FAQ entries", "documentation needs"] } `, }, }; ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#example-3%3A-educational-bot-with-adaptive-templates) Example 3: Educational Bot with Adaptive Templates Copy Ask AI const educatorCharacter: Character = { name: 'EduBot', description: 'Adaptive educational assistant', templates: { // Education-focused templates with learning level adaptation messageHandlerTemplate: `Provide educational guidance as {{agentName}}. {{providers}} Current Level: {{studentLevel}} Subject: {{subject}} Learning Style: {{learningStyle}} For BEGINNERS: - Use simple language and analogies - Break down complex concepts - Provide many examples - Check understanding frequently For INTERMEDIATE: - Build on existing knowledge - Introduce technical terminology - Encourage critical thinking - Suggest practice problems For ADVANCED: - Discuss edge cases and exceptions - Explore theoretical foundations - Connect to real-world applications - Recommend further reading Pedagogical approach for this student REPLY,GENERATE_QUIZ STUDENT_PROGRESS,CURRICULUM,LEARNING_HISTORY Your educational response `, }, }; [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#advanced-callback-patterns) Advanced Callback Patterns ------------------------------------------------------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#progressive-disclosure-pattern) Progressive Disclosure Pattern Copy Ask AI const teachAction: Action = { name: 'TEACH_CONCEPT', handler: async (runtime, message, state, options, callback) => { const concept = extractConcept(message.content.text); const userLevel = await getUserLevel(runtime, message.entityId); if (userLevel === 'beginner') { // Start with simple explanation await callback({ text: `Let's start with the basics of ${concept}...`, actions: ['TEACH_INTRO'], }); // Add an analogy await callback({ text: `Think of it like ${getAnalogy(concept)}`, actions: ['TEACH_ANALOGY'], }); // Check understanding await callback({ text: 'Does this make sense so far? Would you like me to explain differently?', actions: ['CHECK_UNDERSTANDING'], }); } else { // Advanced explanation await callback({ text: `${concept} involves several key principles...`, actions: ['TEACH_ADVANCED'], attachments: [\ {\ url: `/diagrams/${concept}.png`,\ contentType: 'image/png',\ },\ ], }); } return true; }, }; ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#error-recovery-pattern) Error Recovery Pattern Copy Ask AI const processAction: Action = { name: 'PROCESS_REQUEST', handler: async (runtime, message, state, options, callback) => { try { // Acknowledge request await callback({ text: 'Processing your request...', actions: ['ACKNOWLEDGE'], }); // Attempt processing const result = await processUserRequest(message); // Success response await callback({ text: `Successfully completed! ${result.summary}`, actions: ['SUCCESS'], metadata: { processId: result.id }, }); } catch (error) { // Error response with helpful information await callback({ text: 'I encountered an issue processing your request.', actions: ['ERROR'], }); // Provide specific error details if (error.code === 'RATE_LIMIT') { await callback({ text: "You've exceeded the rate limit. Please try again in a few minutes.", actions: ['RATE_LIMIT_ERROR'], }); } else if (error.code === 'INVALID_INPUT') { await callback({ text: `The input seems invalid. Please check: ${error.details}`, actions: ['VALIDATION_ERROR'], }); } else { // Generic error with support option await callback({ text: 'An unexpected error occurred. Would you like me to create a support ticket?', actions: ['OFFER_SUPPORT'], metadata: { errorId: generateErrorId() }, }); } } return true; }, }; ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#streaming-response-pattern) Streaming Response Pattern Copy Ask AI const streamingAction: Action = { name: 'STREAM_DATA', handler: async (runtime, message, state, options, callback) => { const dataStream = await getDataStream(message.content.query); // Initial response await callback({ text: 'Streaming data as it arrives...', actions: ['STREAM_START'], }); // Stream chunks for await (const chunk of dataStream) { await callback({ text: chunk.data, actions: ['STREAM_CHUNK'], metadata: { chunkId: chunk.id, isPartial: true, }, }); // Rate limit streaming await new Promise((resolve) => setTimeout(resolve, 100)); } // Final summary await callback({ text: "Streaming complete! Here's a summary of the data...", actions: ['STREAM_COMPLETE'], metadata: { totalChunks: dataStream.length }, }); return true; }, }; Was this page helpful? YesNo [Message Processing Flow](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow) [Testing Guide](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide) ⌘I --- # Testing Guide - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Bootstrap Testing Guide [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Overview](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#overview) * [Test Setup](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#test-setup) * [Test Framework](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#test-framework) * [Using the Standard Test Utilities](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#using-the-standard-test-utilities) * [Available Mock Factories](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#available-mock-factories) * [Testing Patterns](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-patterns) * [Testing Actions](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-actions) * [Basic Action Test](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#basic-action-test) * [Testing Action with Dependencies](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-action-with-dependencies) * [Testing Providers](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-providers) * [Testing Evaluators](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-evaluators) * [Testing Message Processing](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-message-processing) * [Testing Services](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-services) * [Testing Best Practices](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-best-practices) * [1\. Use Standard Test Setup](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#1-use-standard-test-setup) * [2\. Test Edge Cases](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#2-test-edge-cases) * [3\. Mock External Dependencies](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#3-mock-external-dependencies) * [4\. Test Async Operations](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#4-test-async-operations) * [5\. Verify State Changes](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#5-verify-state-changes) * [Common Testing Scenarios](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#common-testing-scenarios) * [Testing Room Type Behavior](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-room-type-behavior) * [Testing Provider Context](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-provider-context) * [Testing Error Recovery](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-error-recovery) * [Running Tests](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#running-tests) * [Bun Test Features](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#bun-test-features) * [Bun Mock API](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#bun-mock-api) * [Tips for Writing Tests](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#tips-for-writing-tests) * [Debugging Tests](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#debugging-tests) * [Differences from Vitest](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#differences-from-vitest) This guide covers testing patterns and best practices for developing with the plugin-bootstrap package. [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#overview) Overview ----------------------------------------------------------------------------------------- The plugin-bootstrap package includes a comprehensive test suite that demonstrates how to test: * Actions * Providers * Evaluators * Services * Event Handlers * Message Processing Logic [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#test-setup) Test Setup --------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#test-framework) Test Framework This plugin uses **Bun’s built-in test runner**, not Vitest. Bun provides a Jest-compatible testing API with excellent TypeScript support and fast execution. ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#using-the-standard-test-utilities) Using the Standard Test Utilities The package provides robust test utilities in `src/__tests__/test-utils.ts`: Copy Ask AI import { setupActionTest } from '@elizaos/plugin-bootstrap/test-utils'; describe('My Component', () => { let mockRuntime: MockRuntime; let mockMessage: Partial; let mockState: Partial; let callbackFn: ReturnType; beforeEach(() => { const setup = setupActionTest(); mockRuntime = setup.mockRuntime; mockMessage = setup.mockMessage; mockState = setup.mockState; callbackFn = setup.callbackFn; }); }); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#available-mock-factories) Available Mock Factories Copy Ask AI // Create a mock runtime with all methods const runtime = createMockRuntime(); // Create a mock memory/message const message = createMockMemory({ content: { text: 'Hello world' }, entityId: 'user-123', roomId: 'room-456', }); // Create a mock state const state = createMockState({ values: { customKey: 'customValue', }, }); // Create a mock service const service = createMockService({ serviceType: ServiceType.TASK, }); [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-patterns) Testing Patterns --------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-actions) Testing Actions #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#basic-action-test) Basic Action Test Copy Ask AI import { describe, it, expect, beforeEach, mock } from 'bun:test'; import { replyAction } from '../actions/reply'; import { setupActionTest } from '../test-utils'; describe('Reply Action', () => { let mockRuntime: MockRuntime; let mockMessage: Partial; let mockState: Partial; let callbackFn: ReturnType; beforeEach(() => { const setup = setupActionTest(); mockRuntime = setup.mockRuntime; mockMessage = setup.mockMessage; mockState = setup.mockState; callbackFn = setup.callbackFn; }); it('should validate successfully', async () => { const result = await replyAction.validate(mockRuntime); expect(result).toBe(true); }); it('should generate appropriate response', async () => { // Setup LLM response mockRuntime.useModel.mockResolvedValue({ thought: 'User greeted me', message: 'Hello! How can I help you?', }); // Execute action await replyAction.handler( mockRuntime, mockMessage as Memory, mockState as State, {}, callbackFn ); // Verify callback was called with correct content expect(callbackFn).toHaveBeenCalledWith({ thought: 'User greeted me', text: 'Hello! How can I help you?', actions: ['REPLY'], }); }); }); #### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-action-with-dependencies) Testing Action with Dependencies Copy Ask AI describe('Follow Room Action', () => { it('should update participation status', async () => { const setup = setupActionTest(); // Setup room data setup.mockRuntime.getRoom.mockResolvedValue({ id: 'room-123', type: ChannelType.TEXT, participants: ['user-123'], }); // Execute action await followRoomAction.handler( setup.mockRuntime, setup.mockMessage as Memory, setup.mockState as State, {}, setup.callbackFn ); // Verify runtime methods were called expect(setup.mockRuntime.updateParticipantUserState).toHaveBeenCalledWith( 'room-123', setup.mockRuntime.agentId, 'FOLLOWED' ); // Verify callback expect(setup.callbackFn).toHaveBeenCalledWith({ text: expect.stringContaining('followed'), actions: ['FOLLOW_ROOM'], }); }); }); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-providers) Testing Providers Copy Ask AI import { recentMessagesProvider } from '../providers/recentMessages'; describe('Recent Messages Provider', () => { it('should format conversation history', async () => { const setup = setupActionTest(); // Mock recent messages const recentMessages = [\ createMockMemory({\ content: { text: 'Hello' },\ entityId: 'user-123',\ createdAt: Date.now() - 60000,\ }),\ createMockMemory({\ content: { text: 'Hi there!' },\ entityId: setup.mockRuntime.agentId,\ createdAt: Date.now() - 30000,\ }),\ ]; setup.mockRuntime.getMemories.mockResolvedValue(recentMessages); setup.mockRuntime.getEntityById.mockResolvedValue({ id: 'user-123', names: ['Alice'], metadata: { userName: 'alice' }, }); // Get provider data const result = await recentMessagesProvider.get(setup.mockRuntime, setup.mockMessage as Memory); // Verify structure expect(result).toHaveProperty('data'); expect(result).toHaveProperty('values'); expect(result).toHaveProperty('text'); // Verify content expect(result.data.recentMessages).toHaveLength(2); expect(result.text).toContain('Alice: Hello'); expect(result.text).toContain('Hi there!'); }); }); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-evaluators) Testing Evaluators Copy Ask AI import { reflectionEvaluator } from '../evaluators/reflection'; describe('Reflection Evaluator', () => { it('should extract facts from conversation', async () => { const setup = setupActionTest(); // Mock LLM response with facts setup.mockRuntime.useModel.mockResolvedValue({ thought: 'Learned new information about user', facts: [\ {\ claim: 'User likes coffee',\ type: 'fact',\ in_bio: false,\ already_known: false,\ },\ ], relationships: [], }); // Execute evaluator const result = await reflectionEvaluator.handler( setup.mockRuntime, setup.mockMessage as Memory, setup.mockState as State ); // Verify facts were saved expect(setup.mockRuntime.createMemory).toHaveBeenCalledWith( expect.objectContaining({ content: { text: 'User likes coffee' }, }), 'facts', true ); }); }); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-message-processing) Testing Message Processing Copy Ask AI import { messageReceivedHandler } from '../index'; describe('Message Processing', () => { it('should process message end-to-end', async () => { const setup = setupActionTest(); const onComplete = mock(); // Setup room and state setup.mockRuntime.getRoom.mockResolvedValue({ id: 'room-123', type: ChannelType.TEXT, }); // Mock shouldRespond decision setup.mockRuntime.useModel .mockResolvedValueOnce('REPLY') // shouldRespond .mockResolvedValueOnce({ // response generation thought: 'Responding to greeting', actions: ['REPLY'], text: 'Hello!', simple: true, }); // Process message await messageReceivedHandler({ runtime: setup.mockRuntime, message: setup.mockMessage as Memory, callback: setup.callbackFn, onComplete, }); // Verify flow expect(setup.mockRuntime.addEmbeddingToMemory).toHaveBeenCalled(); expect(setup.mockRuntime.createMemory).toHaveBeenCalled(); expect(setup.callbackFn).toHaveBeenCalledWith( expect.objectContaining({ text: 'Hello!', actions: ['REPLY'], }) ); expect(onComplete).toHaveBeenCalled(); }); }); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-services) Testing Services Copy Ask AI import { TaskService } from '../services/task'; describe('Task Service', () => { it('should execute repeating tasks', async () => { const setup = setupActionTest(); // Create task const task = { id: 'task-123', name: 'TEST_TASK', metadata: { updateInterval: 1000, updatedAt: Date.now() - 2000, }, tags: ['queue', 'repeat'], }; // Register worker const worker = { name: 'TEST_TASK', execute: mock(), }; setup.mockRuntime.registerTaskWorker(worker); setup.mockRuntime.getTaskWorker.mockReturnValue(worker); setup.mockRuntime.getTasks.mockResolvedValue([task]); // Start service const service = await TaskService.start(setup.mockRuntime); // Wait for tick await new Promise((resolve) => setTimeout(resolve, 1100)); // Verify execution expect(worker.execute).toHaveBeenCalled(); expect(setup.mockRuntime.updateTask).toHaveBeenCalledWith( 'task-123', expect.objectContaining({ metadata: expect.objectContaining({ updatedAt: expect.any(Number), }), }) ); // Cleanup await service.stop(); }); }); [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-best-practices) Testing Best Practices --------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#1-use-standard-test-setup) 1\. Use Standard Test Setup Always use the provided test utilities for consistency: Copy Ask AI const setup = setupActionTest({ messageOverrides: { /* custom message props */ }, stateOverrides: { /* custom state */ }, runtimeOverrides: { /* custom runtime behavior */ }, }); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#2-test-edge-cases) 2\. Test Edge Cases Copy Ask AI it('should handle missing attachments gracefully', async () => { setup.mockMessage.content.attachments = undefined; // Test continues without error }); it('should handle network failures', async () => { setup.mockRuntime.useModel.mockRejectedValue(new Error('Network error')); // Verify graceful error handling }); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#3-mock-external-dependencies) 3\. Mock External Dependencies Copy Ask AI // Mock fetch for external APIs import { mock } from 'bun:test'; // Create mock for fetch globalThis.fetch = mock().mockResolvedValue({ ok: true, arrayBuffer: () => Promise.resolve(Buffer.from('test')), headers: new Map([['content-type', 'image/png']]), }); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#4-test-async-operations) 4\. Test Async Operations Copy Ask AI it('should handle concurrent messages', async () => { const messages = [\ createMockMemory({ content: { text: 'Message 1' } }),\ createMockMemory({ content: { text: 'Message 2' } }),\ ]; // Process messages concurrently await Promise.all( messages.map((msg) => messageReceivedHandler({ runtime: setup.mockRuntime, message: msg, callback: setup.callbackFn, }) ) ); // Verify both processed correctly expect(setup.callbackFn).toHaveBeenCalledTimes(2); }); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#5-verify-state-changes) 5\. Verify State Changes Copy Ask AI it('should update agent state correctly', async () => { // Initial state expect(setup.mockRuntime.getMemories).toHaveBeenCalledTimes(0); // Action that modifies state await action.handler(...); // Verify state changes expect(setup.mockRuntime.createMemory).toHaveBeenCalled(); expect(setup.mockRuntime.updateRelationship).toHaveBeenCalled(); }); [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#common-testing-scenarios) Common Testing Scenarios ------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-room-type-behavior) Testing Room Type Behavior Copy Ask AI describe('Room Type Handling', () => { it.each([\ [ChannelType.DM, true],\ [ChannelType.TEXT, false],\ [ChannelType.VOICE_DM, true],\ ])('should bypass shouldRespond for %s: %s', async (roomType, shouldBypass) => { setup.mockRuntime.getRoom.mockResolvedValue({ id: 'room-123', type: roomType, }); // Test behavior based on room type }); }); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-provider-context) Testing Provider Context Copy Ask AI it('should include all requested providers', async () => { const state = await setup.mockRuntime.composeState(setup.mockMessage, [\ 'RECENT_MESSAGES',\ 'ENTITIES',\ 'RELATIONSHIPS',\ ]); expect(state.providerData).toHaveLength(3); expect(state.providerData[0].providerName).toBe('RECENT_MESSAGES'); }); ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-error-recovery) Testing Error Recovery Copy Ask AI it('should recover from provider errors', async () => { // Make one provider fail setup.mockRuntime.getMemories.mockRejectedValueOnce(new Error('DB error')); // Should still process message await messageReceivedHandler({...}); // Verify graceful degradation expect(setup.callbackFn).toHaveBeenCalled(); }); [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#running-tests) Running Tests --------------------------------------------------------------------------------------------------- Copy Ask AI # Run all bootstrap tests bun test # Run specific test file bun test packages/plugin-bootstrap/src/__tests__/actions.test.ts # Run tests in watch mode bun test --watch # Run with coverage bun test --coverage [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#bun-test-features) Bun Test Features ----------------------------------------------------------------------------------------------------------- Bun’s test runner provides several advantages: 1. **Fast execution** - Tests run directly in Bun’s runtime 2. **Built-in TypeScript** - No compilation step needed 3. **Jest compatibility** - Familiar API for developers 4. **Built-in mocking** - The `mock()` function is built-in 5. **Snapshot testing** - Built-in support for snapshots 6. **Watch mode** - Automatic re-running on file changes ### [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#bun-mock-api) Bun Mock API Copy Ask AI import { mock } from 'bun:test'; // Create a mock function const mockFn = mock(); // Set return value mockFn.mockReturnValue('value'); mockFn.mockResolvedValue('async value'); // Set implementation mockFn.mockImplementation((arg) => arg * 2); // Check calls expect(mockFn).toHaveBeenCalled(); expect(mockFn).toHaveBeenCalledWith('arg'); expect(mockFn).toHaveBeenCalledTimes(2); // Reset mocks mock.restore(); // Reset all mocks mockFn.mockReset(); // Reset specific mock [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#tips-for-writing-tests) Tips for Writing Tests --------------------------------------------------------------------------------------------------------------------- 1. **Start with the happy path** - Test normal operation first 2. **Add edge cases** - Empty arrays, null values, errors 3. **Test async behavior** - Timeouts, retries, concurrent operations 4. **Verify side effects** - Database updates, event emissions 5. **Keep tests focused** - One concept per test 6. **Use descriptive names** - Should describe what is being tested 7. **Mock at boundaries** - Mock external services, not internal logic [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#debugging-tests) Debugging Tests ------------------------------------------------------------------------------------------------------- Copy Ask AI // Add console logs to debug it('should process correctly', async () => { setup.mockRuntime.useModel.mockImplementation(async (type, params) => { console.log('Model called with:', { type, params }); return mockResponse; }); // Step through with debugger debugger; await action.handler(...); }); [​](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#differences-from-vitest) Differences from Vitest ----------------------------------------------------------------------------------------------------------------------- If you’re familiar with Vitest, here are the key differences: 1. **Import from `bun:test`** instead of `vitest` 2. **No need for `vi` prefix** - Just use `mock()` directly 3. **No configuration file** - Bun test works out of the box 4. **Different CLI commands** - Use `bun test` instead of `vitest` Remember: Good tests make development faster and more confident. The test suite is your safety net when making changes! Was this page helpful? YesNo [Implementation Examples](https://docs.elizaos.ai/plugin-registry/bootstrap/examples) [Database Management](https://docs.elizaos.ai/plugin-registry/sql) ⌘I --- # Operations Flow - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation EVM Operations Flow [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Overview](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#overview) * [Transfer Flow](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#transfer-flow) * [1\. User Intent](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#1-user-intent) * [2\. Action Recognition](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#2-action-recognition) * [3\. Parameter Extraction](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#3-parameter-extraction) * [4\. Execution](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#4-execution) * [5\. Response](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#5-response) * [Swap Flow](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#swap-flow) * [1\. User Intent](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#1-user-intent-2) * [2\. Route Discovery](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#2-route-discovery) * [3\. Execution](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#3-execution) * [Bridge Flow](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#bridge-flow) * [1\. User Intent](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#1-user-intent-3) * [2\. Bridge Route](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#2-bridge-route) * [3\. Multi-Step Execution](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#3-multi-step-execution) * [Governance Flow](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#governance-flow) * [Proposal Creation](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#proposal-creation) * [Voting](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#voting) * [Error Handling](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#error-handling) * [Key Features](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#key-features) [​](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#overview) Overview ----------------------------------------------------------------------------------------------- The EVM plugin handles DeFi operations through a structured flow: Copy Ask AI User Message → Action Recognition → Parameter Extraction → Execution → Response [​](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#transfer-flow) Transfer Flow --------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#1-user-intent) 1\. User Intent Copy Ask AI User: Send 0.1 ETH to alice.eth ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#2-action-recognition) 2\. Action Recognition The plugin identifies this as a transfer action based on keywords (send, transfer, pay). ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#3-parameter-extraction) 3\. Parameter Extraction Using AI, the plugin extracts: * Amount: 0.1 * Token: ETH * Recipient: alice.eth (will resolve to address) * Chain: Detected from context or defaults ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#4-execution) 4\. Execution * Validates recipient address * Checks balance * Builds transaction * Estimates gas * Sends transaction * Waits for confirmation ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#5-response) 5\. Response Copy Ask AI Agent: Successfully transferred 0.1 ETH to alice.eth Transaction: https://etherscan.io/tx/[hash] [​](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#swap-flow) Swap Flow ------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#1-user-intent-2) 1\. User Intent Copy Ask AI User: Swap 1 ETH for USDC ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#2-route-discovery) 2\. Route Discovery * Queries multiple DEX aggregators (LiFi, Bebop) * Compares routes for best output * Considers gas costs ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#3-execution) 3\. Execution * Approves token if needed * Executes swap transaction * Monitors for completion [​](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#bridge-flow) Bridge Flow ----------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#1-user-intent-3) 1\. User Intent Copy Ask AI User: Bridge 100 USDC from Ethereum to Base ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#2-bridge-route) 2\. Bridge Route * Finds available bridge routes * Estimates fees and time * Selects optimal path ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#3-multi-step-execution) 3\. Multi-Step Execution * Source chain transaction * Wait for bridge confirmation * Destination chain completion [​](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#governance-flow) Governance Flow ------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#proposal-creation) Proposal Creation Copy Ask AI User: Create a proposal to increase treasury allocation → Plugin creates proposal transaction with targets, values, and description ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#voting) Voting Copy Ask AI User: Vote FOR on proposal 42 → Plugin casts vote with correct proposal ID and support value [​](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#error-handling) Error Handling ----------------------------------------------------------------------------------------------------------- The plugin handles common errors gracefully: * **Insufficient Balance**: Checks before attempting transaction * **Network Issues**: Retries with exponential backoff * **Invalid Addresses**: Validates all addresses before use * **High Slippage**: Warns user if slippage exceeds tolerance [​](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#key-features) Key Features ------------------------------------------------------------------------------------------------------- 1. **Natural Language Processing**: Understands various ways to express intents 2. **Multi-Chain Support**: Automatically handles chain selection 3. **Gas Optimization**: Estimates and optimizes gas usage 4. **Safety Checks**: Validates all parameters before execution 5. **Real-Time Feedback**: Provides transaction status updates Was this page helpful? YesNo [Developer Guide](https://docs.elizaos.ai/plugin-registry/defi/evm/complete-documentation) [Examples](https://docs.elizaos.ai/plugin-registry/defi/evm/examples) ⌘I --- # Operations Flow - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Solana Operations Flow [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Overview](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#overview) * [Transfer Flow](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#transfer-flow) * [1\. User Intent](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#1-user-intent) * [2\. Action Recognition](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#2-action-recognition) * [3\. Parameter Extraction](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#3-parameter-extraction) * [4\. Execution Steps](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#4-execution-steps) * [5\. Response](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#5-response) * [Swap Flow](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#swap-flow) * [1\. User Intent](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#1-user-intent-2) * [2\. Jupiter Integration](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#2-jupiter-integration) * [3\. Execution](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#3-execution) * [4\. Special Cases](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#4-special-cases) * [Portfolio Flow](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#portfolio-flow) * [1\. User Request](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#1-user-request) * [2\. Data Aggregation](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#2-data-aggregation) * [3\. Response Format](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#3-response-format) * [Key Features](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#key-features) * [Real-Time Updates](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#real-time-updates) * [Smart Token Resolution](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#smart-token-resolution) * [Transaction Optimization](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#transaction-optimization) * [Error Handling](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#error-handling) * [Common Errors](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#common-errors) * [Safety Features](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#safety-features) [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#overview) Overview -------------------------------------------------------------------------------------------------- The Solana plugin processes DeFi operations through this flow: Copy Ask AI User Message → Action Recognition → AI Parameter Extraction → Execution → Response [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#transfer-flow) Transfer Flow ------------------------------------------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#1-user-intent) 1\. User Intent Copy Ask AI User: Send 1 SOL to alice.sol ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#2-action-recognition) 2\. Action Recognition The plugin identifies transfer keywords (send, transfer, pay). ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#3-parameter-extraction) 3\. Parameter Extraction AI extracts: * Amount: 1 * Token: SOL * Recipient: alice.sol (resolves to address) ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#4-execution-steps) 4\. Execution Steps * Resolve .sol domain if needed * Check balance * Build transaction with priority fee * Sign and send * Wait for confirmation ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#5-response) 5\. Response Copy Ask AI Agent: Successfully sent 1 SOL to alice.sol Transaction: https://solscan.io/tx/[signature] [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#swap-flow) Swap Flow ---------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#1-user-intent-2) 1\. User Intent Copy Ask AI User: Swap 10 SOL for USDC ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#2-jupiter-integration) 2\. Jupiter Integration * Get quote from Jupiter API * Calculate output amount * Check price impact ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#3-execution) 3\. Execution * Build swap transaction * Add priority fees * Execute and monitor ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#4-special-cases) 4\. Special Cases * “Swap all” - calculates max balance * Custom slippage - applies user preference * Route selection - optimizes for best price [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#portfolio-flow) Portfolio Flow -------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#1-user-request) 1\. User Request Copy Ask AI User: What's my portfolio worth? ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#2-data-aggregation) 2\. Data Aggregation * Fetch SOL balance * Get SPL token balances * Query prices from Birdeye API ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#3-response-format) 3\. Response Format Copy Ask AI Total Value: $X,XXX.XX (XX.XX SOL) Token Balances: SOL: 10.5 ($850.50) USDC: 250.25 ($250.25) BONK: 1,000,000 ($45.20) [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#key-features) Key Features ---------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#real-time-updates) Real-Time Updates * WebSocket subscriptions for balance changes * Automatic portfolio refresh every 2 minutes * Instant transaction notifications ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#smart-token-resolution) Smart Token Resolution * Common symbols (USDC, USDT, BONK) auto-resolved * .sol domain support * Token metadata caching ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#transaction-optimization) Transaction Optimization * Priority fees for faster confirmation * Compute unit optimization * Automatic retry on failure [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#error-handling) Error Handling -------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#common-errors) Common Errors * **Insufficient Balance**: Pre-checks prevent failed transactions * **Token Not Found**: Clear error messages for unknown tokens * **Network Issues**: Automatic retry with backoff * **High Slippage**: Warns before executing ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#safety-features) Safety Features 1. Balance validation before execution 2. Address verification 3. Slippage protection 4. Transaction simulation when possible Was this page helpful? YesNo [Developer Guide](https://docs.elizaos.ai/plugin-registry/defi/solana/complete-documentation) [Examples](https://docs.elizaos.ai/plugin-registry/defi/solana/examples) ⌘I --- # Examples - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation EVM Examples [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Configuration](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#configuration) * [Character Configuration](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#character-configuration) * [Environment Variables](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#environment-variables) * [Usage Examples](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#usage-examples) * [Transfer Operations](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#transfer-operations) * [Swap Operations](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#swap-operations) * [Bridge Operations](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#bridge-operations) * [Governance Operations](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#governance-operations) * [Custom Plugin Integration](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#custom-plugin-integration) * [Common Patterns](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#common-patterns) * [Checking Wallet Balance](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#checking-wallet-balance) * [Gas Price Awareness](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#gas-price-awareness) * [Multi-Chain Operations](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#multi-chain-operations) [​](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#configuration) Configuration --------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#character-configuration) Character Configuration Add the EVM plugin to your character file: Copy Ask AI // character.ts import { type Character } from '@elizaos/core'; export const character: Character = { name: 'DeFiAgent', plugins: [\ // Core plugins\ '@elizaos/plugin-sql',\ '@elizaos/plugin-bootstrap',\ \ // DeFi plugin\ ...(process.env.EVM_PRIVATE_KEY?.trim() ? ['@elizaos/plugin-evm'] : []),\ \ // Platform plugins\ ...(process.env.DISCORD_API_TOKEN?.trim() ? ['@elizaos/plugin-discord'] : []),\ ], settings: { secrets: {}, }, // ... rest of character configuration }; ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#environment-variables) Environment Variables Copy Ask AI # Required EVM_PRIVATE_KEY=your_private_key_here # Optional - Custom RPC endpoints ETHEREUM_PROVIDER_ETHEREUM=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY ETHEREUM_PROVIDER_BASE=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY ETHEREUM_PROVIDER_ARBITRUM=https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY # Optional - TEE Mode TEE_MODE=true WALLET_SECRET_SALT=your_salt_here [​](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#usage-examples) Usage Examples ----------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#transfer-operations) Transfer Operations The agent understands natural language for transfers: Copy Ask AI User: Send 0.1 ETH to 0x742d35Cc6634C0532925a3b844Bc454e4438f44e Agent: I'll send 0.1 ETH to that address right away. User: Transfer 100 USDC to vitalik.eth on Base Agent: Transferring 100 USDC to vitalik.eth on Base network. User: Pay alice.eth 50 DAI on Arbitrum Agent: Sending 50 DAI to alice.eth on Arbitrum. ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#swap-operations) Swap Operations Copy Ask AI User: Swap 1 ETH for USDC Agent: I'll swap 1 ETH for USDC using the best available route. User: Exchange 100 USDC for DAI with 0.5% slippage Agent: Swapping 100 USDC for DAI with 0.5% slippage tolerance. ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#bridge-operations) Bridge Operations Copy Ask AI User: Bridge 100 USDC from Ethereum to Base Agent: I'll bridge 100 USDC from Ethereum to Base network. User: Move 0.5 ETH from Arbitrum to Optimism Agent: Bridging 0.5 ETH from Arbitrum to Optimism. ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#governance-operations) Governance Operations Copy Ask AI User: Create a proposal to increase the treasury allocation to 10% Agent: I'll create a governance proposal for increasing treasury allocation. User: Vote FOR on proposal 42 Agent: Casting your vote FOR proposal #42. User: Execute proposal 35 Agent: Executing proposal #35 after the timelock period. [​](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#custom-plugin-integration) Custom Plugin Integration --------------------------------------------------------------------------------------------------------------------- If you need to import the plugin directly in a ProjectAgent: Copy Ask AI // index.ts import { type ProjectAgent } from '@elizaos/core'; import evmPlugin from '@elizaos/plugin-evm'; import { character } from './character'; export const projectAgent: ProjectAgent = { character, plugins: [evmPlugin], // Import custom plugins here init: async (runtime) => { // Custom initialization if needed } }; [​](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#common-patterns) Common Patterns ------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#checking-wallet-balance) Checking Wallet Balance Copy Ask AI User: What's my wallet balance? Agent: [Agent will use the wallet provider to show balances across all configured chains] ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#gas-price-awareness) Gas Price Awareness Copy Ask AI User: Send 0.1 ETH to alice.eth when gas is low Agent: I'll monitor gas prices and execute when they're favorable. ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/examples#multi-chain-operations) Multi-Chain Operations The plugin automatically detects the chain from context: Copy Ask AI User: Send 100 USDC on Base Agent: Sending 100 USDC on Base network. User: Swap MATIC for USDC on Polygon Agent: Swapping MATIC for USDC on Polygon network. Was this page helpful? YesNo [Operations Flow](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow) [Testing Guide](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide) ⌘I --- # Testing Guide - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation EVM Testing Guide [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Testing Philosophy](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#testing-philosophy) * [Safe Testing Practices](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#safe-testing-practices) * [1\. Start Small](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#1-start-small) * [2\. Test on Low-Cost Chains First](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#2-test-on-low-cost-chains-first) * [3\. Progressive Testing](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#3-progressive-testing) * [Testing Checklist](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#testing-checklist) * [Environment Setup](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#environment-setup) * [Basic Tests](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#basic-tests) * [Swap Testing](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#swap-testing) * [Error Handling](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#error-handling) * [Monitoring Results](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#monitoring-results) * [Common Issues](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#common-issues) * [”Insufficient funds for gas”](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#%E2%80%9Dinsufficient-funds-for-gas%E2%80%9D) * [”Transaction underpriced”](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#%E2%80%9Dtransaction-underpriced%E2%80%9D) * [”Nonce too low”](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#%E2%80%9Dnonce-too-low%E2%80%9D) * [Production Readiness](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#production-readiness) [​](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#testing-philosophy) Testing Philosophy ------------------------------------------------------------------------------------------------------------ The best way to test DeFi plugins is with small amounts on real networks. Test networks often have reliability issues and don’t reflect real-world conditions. [​](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#safe-testing-practices) Safe Testing Practices -------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#1-start-small) 1\. Start Small Always test with minimal amounts first: * 0.001 ETH for transfers * $1-5 worth of tokens for swaps * Smallest viable amounts for bridges ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#2-test-on-low-cost-chains-first) 2\. Test on Low-Cost Chains First Start testing on chains with low transaction fees: * Polygon: ~$0.01 per transaction * Base: ~$0.05 per transaction * Arbitrum: ~$0.10 per transaction ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#3-progressive-testing) 3\. Progressive Testing Copy Ask AI 1. Test basic transfers first 2. Test token transfers 3. Test swaps with small amounts 4. Test bridges last (they're most complex) [​](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#testing-checklist) Testing Checklist ---------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#environment-setup) Environment Setup Copy Ask AI # Use a dedicated test wallet EVM_PRIVATE_KEY=test_wallet_private_key # Start with one chain ETHEREUM_PROVIDER_BASE=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#basic-tests) Basic Tests 1. **Wallet Connection** Copy Ask AI User: What's my wallet address? Agent: [Should show your wallet address] 2. **Balance Check** Copy Ask AI User: What's my balance? Agent: [Should show balances across configured chains] 3. **Small Transfer** Copy Ask AI User: Send 0.001 ETH to [another test address] Agent: [Should execute the transfer] 4. **Token Transfer** Copy Ask AI User: Send 1 USDC to [test address] Agent: [Should handle ERC20 transfer] ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#swap-testing) Swap Testing Test swaps with minimal amounts: Copy Ask AI User: Swap 0.01 ETH for USDC Agent: [Should find best route and execute] ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#error-handling) Error Handling Test error scenarios: * Insufficient balance * Invalid addresses * Network issues * High slippage [​](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#monitoring-results) Monitoring Results ------------------------------------------------------------------------------------------------------------ 1. **Transaction Verification** * Check block explorers (Etherscan, BaseScan, etc.) * Verify transaction status * Confirm balances updated 2. **Gas Usage** * Monitor gas costs * Ensure reasonable gas estimates * Check for failed transactions [​](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#common-issues) Common Issues -------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#%E2%80%9Dinsufficient-funds-for-gas%E2%80%9D) ”Insufficient funds for gas” * Ensure you have native tokens for gas * Each chain needs its native token (ETH, MATIC, etc.) ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#%E2%80%9Dtransaction-underpriced%E2%80%9D) ”Transaction underpriced” * RPC may be congested * Try alternative RPC endpoints ### [​](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#%E2%80%9Dnonce-too-low%E2%80%9D) ”Nonce too low” * Previous transaction may be pending * Wait for confirmation or reset nonce [​](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide#production-readiness) Production Readiness ---------------------------------------------------------------------------------------------------------------- Before using in production: 1. Test all intended operations 2. Verify error handling works 3. Ensure proper logging 4. Set appropriate gas limits 5. Configure slippage tolerances 6. Test with your expected volumes Was this page helpful? YesNo [Examples](https://docs.elizaos.ai/plugin-registry/defi/evm/examples) [Overview](https://docs.elizaos.ai/plugin-registry/defi/solana) ⌘I --- # Google GenAI Plugin - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/plugin-registry/llm/google-genai#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation LLM Providers Google GenAI Plugin [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Features](https://docs.elizaos.ai/plugin-registry/llm/google-genai#features) * [Installation](https://docs.elizaos.ai/plugin-registry/llm/google-genai#installation) * [Configuration](https://docs.elizaos.ai/plugin-registry/llm/google-genai#configuration) * [Environment Variables](https://docs.elizaos.ai/plugin-registry/llm/google-genai#environment-variables) * [Character Configuration](https://docs.elizaos.ai/plugin-registry/llm/google-genai#character-configuration) * [Supported Operations](https://docs.elizaos.ai/plugin-registry/llm/google-genai#supported-operations) * [Model Configuration](https://docs.elizaos.ai/plugin-registry/llm/google-genai#model-configuration) * [Safety Configuration](https://docs.elizaos.ai/plugin-registry/llm/google-genai#safety-configuration) * [Usage Tips](https://docs.elizaos.ai/plugin-registry/llm/google-genai#usage-tips) * [Cost Structure](https://docs.elizaos.ai/plugin-registry/llm/google-genai#cost-structure) * [External Resources](https://docs.elizaos.ai/plugin-registry/llm/google-genai#external-resources) [​](https://docs.elizaos.ai/plugin-registry/llm/google-genai#features) Features ---------------------------------------------------------------------------------- * **Gemini models** - Access to Gemini Pro and Gemini Pro Vision * **Multimodal support** - Process text and images * **Embedding models** - Native embedding support * **Safety settings** - Configurable content filtering [​](https://docs.elizaos.ai/plugin-registry/llm/google-genai#installation) Installation ------------------------------------------------------------------------------------------ Copy Ask AI elizaos plugins add @elizaos/plugin-google-genai [​](https://docs.elizaos.ai/plugin-registry/llm/google-genai#configuration) Configuration -------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/llm/google-genai#environment-variables) Environment Variables Copy Ask AI # Required GOOGLE_GENERATIVE_AI_API_KEY=... # Optional model configuration # You can use any available Google Gemini model GOOGLE_SMALL_MODEL=gemini-2.0-flash-001 # Default: gemini-2.0-flash-001 GOOGLE_LARGE_MODEL=gemini-2.5-pro-preview-03-25 # Default: gemini-2.5-pro-preview-03-25 GOOGLE_IMAGE_MODEL=gemini-1.5-flash # For vision tasks GOOGLE_EMBEDDING_MODEL=text-embedding-004 # Default: text-embedding-004 # Examples of other available models: # GOOGLE_SMALL_MODEL=gemini-1.5-flash # GOOGLE_LARGE_MODEL=gemini-1.5-pro # GOOGLE_LARGE_MODEL=gemini-pro # GOOGLE_EMBEDDING_MODEL=embedding-001 ### [​](https://docs.elizaos.ai/plugin-registry/llm/google-genai#character-configuration) Character Configuration Copy Ask AI { "name": "MyAgent", "plugins": ["@elizaos/plugin-google-genai"] } [​](https://docs.elizaos.ai/plugin-registry/llm/google-genai#supported-operations) Supported Operations ---------------------------------------------------------------------------------------------------------- | Operation | Models | Notes | | --- | --- | --- | | TEXT\_GENERATION | gemini-pro, gemini-pro-vision | Multimodal capable | | EMBEDDING | embedding-001 | 768-dimensional | | OBJECT\_GENERATION | All Gemini models | Structured output | [​](https://docs.elizaos.ai/plugin-registry/llm/google-genai#model-configuration) Model Configuration -------------------------------------------------------------------------------------------------------- The plugin uses three model categories: * **SMALL\_MODEL**: Fast, efficient for simple tasks * **LARGE\_MODEL**: Best quality, complex reasoning * **IMAGE\_MODEL**: Multimodal capabilities (text + vision) * **EMBEDDING\_MODEL**: Vector embeddings You can configure any available Gemini model: * Gemini 2.0 Flash (latest) * Gemini 2.5 Pro Preview * Gemini 1.5 Pro/Flash * Gemini Pro (legacy) * Any new models Google releases [​](https://docs.elizaos.ai/plugin-registry/llm/google-genai#safety-configuration) Safety Configuration ---------------------------------------------------------------------------------------------------------- Control content filtering: Copy Ask AI // In character settings { "settings": { "google_safety": { "harassment": "BLOCK_NONE", "hate_speech": "BLOCK_MEDIUM_AND_ABOVE", "sexually_explicit": "BLOCK_MEDIUM_AND_ABOVE", "dangerous_content": "BLOCK_MEDIUM_AND_ABOVE" } } } [​](https://docs.elizaos.ai/plugin-registry/llm/google-genai#usage-tips) Usage Tips -------------------------------------------------------------------------------------- 1. **Multimodal** - Leverage image understanding capabilities 2. **Long Context** - Gemini 1.5 Pro supports up to 1M tokens 3. **Rate Limits** - Free tier has generous limits [​](https://docs.elizaos.ai/plugin-registry/llm/google-genai#cost-structure) Cost Structure ---------------------------------------------------------------------------------------------- * Free tier: 60 queries per minute * Paid tier: Higher limits and priority access * Embedding calls are separate from generation [​](https://docs.elizaos.ai/plugin-registry/llm/google-genai#external-resources) External Resources ------------------------------------------------------------------------------------------------------ * [Plugin Source](https://github.com/elizaos/eliza/tree/main/packages/plugin-google-genai) * [Google AI Studio](https://makersuite.google.com/) * [API Documentation](https://ai.google.dev/docs) Was this page helpful? YesNo [Anthropic Plugin](https://docs.elizaos.ai/plugin-registry/llm/anthropic) [Ollama Plugin](https://docs.elizaos.ai/plugin-registry/llm/ollama) ⌘I --- # Anthropic Plugin - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/plugin-registry/llm/anthropic#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation LLM Providers Anthropic Plugin [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Features](https://docs.elizaos.ai/plugin-registry/llm/anthropic#features) * [Installation](https://docs.elizaos.ai/plugin-registry/llm/anthropic#installation) * [Configuration](https://docs.elizaos.ai/plugin-registry/llm/anthropic#configuration) * [Environment Variables](https://docs.elizaos.ai/plugin-registry/llm/anthropic#environment-variables) * [Character Configuration](https://docs.elizaos.ai/plugin-registry/llm/anthropic#character-configuration) * [Supported Operations](https://docs.elizaos.ai/plugin-registry/llm/anthropic#supported-operations) * [Important: Embedding Fallback](https://docs.elizaos.ai/plugin-registry/llm/anthropic#important%3A-embedding-fallback) * [Model Configuration](https://docs.elizaos.ai/plugin-registry/llm/anthropic#model-configuration) * [Usage Tips](https://docs.elizaos.ai/plugin-registry/llm/anthropic#usage-tips) * [External Resources](https://docs.elizaos.ai/plugin-registry/llm/anthropic#external-resources) The Anthropic plugin provides access to Claude models for text generation. Note that it does not support embeddings, so you’ll need a fallback plugin. [​](https://docs.elizaos.ai/plugin-registry/llm/anthropic#features) Features ------------------------------------------------------------------------------- * **Claude 3 models** - Access to Claude 3 Opus, Sonnet, and Haiku * **Long context** - Up to 200k tokens context window * **XML formatting** - Optimized for structured responses * **Safety features** - Built-in content moderation [​](https://docs.elizaos.ai/plugin-registry/llm/anthropic#installation) Installation --------------------------------------------------------------------------------------- Copy Ask AI elizaos plugins add @elizaos/plugin-anthropic [​](https://docs.elizaos.ai/plugin-registry/llm/anthropic#configuration) Configuration ----------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/llm/anthropic#environment-variables) Environment Variables Copy Ask AI # Required ANTHROPIC_API_KEY=sk-ant-... # Optional model configuration # You can use any available Anthropic model ANTHROPIC_SMALL_MODEL=claude-3-haiku-20240307 # Default: claude-3-haiku-20240307 ANTHROPIC_LARGE_MODEL=claude-3-5-sonnet-latest # Default: claude-3-5-sonnet-latest # Examples of other available models: # ANTHROPIC_SMALL_MODEL=claude-3-haiku-20240307 # ANTHROPIC_LARGE_MODEL=claude-3-opus-20240229 # ANTHROPIC_LARGE_MODEL=claude-3-5-sonnet-20241022 # ANTHROPIC_LARGE_MODEL=claude-3-5-haiku-20241022 ### [​](https://docs.elizaos.ai/plugin-registry/llm/anthropic#character-configuration) Character Configuration Copy Ask AI { "name": "MyAgent", "plugins": [\ "@elizaos/plugin-anthropic",\ "@elizaos/plugin-openai" // For embeddings\ ] } [​](https://docs.elizaos.ai/plugin-registry/llm/anthropic#supported-operations) Supported Operations ------------------------------------------------------------------------------------------------------- | Operation | Support | Notes | | --- | --- | --- | | TEXT\_GENERATION | ✅ | All Claude models | | EMBEDDING | ❌ | Use fallback plugin | | OBJECT\_GENERATION | ✅ | Via XML formatting | [​](https://docs.elizaos.ai/plugin-registry/llm/anthropic#important%3A-embedding-fallback) Important: Embedding Fallback --------------------------------------------------------------------------------------------------------------------------- Since Anthropic doesn’t provide embedding models, always include a fallback: Copy Ask AI { "plugins": [\ "@elizaos/plugin-anthropic", // Primary for text\ "@elizaos/plugin-openai" // Fallback for embeddings\ ] } [​](https://docs.elizaos.ai/plugin-registry/llm/anthropic#model-configuration) Model Configuration ----------------------------------------------------------------------------------------------------- The plugin uses two model categories: * **SMALL\_MODEL**: For faster, cost-effective responses * **LARGE\_MODEL**: For complex reasoning and best quality You can use any available Claude model, including: * Claude 3.5 Sonnet (latest and dated versions) * Claude 3 Opus, Sonnet, and Haiku * Claude 3.5 Haiku * Any new models Anthropic releases [​](https://docs.elizaos.ai/plugin-registry/llm/anthropic#usage-tips) Usage Tips ----------------------------------------------------------------------------------- 1. **XML Templates** - Claude excels at XML-formatted responses 2. **System Prompts** - Effective for character personality 3. **Context Management** - Leverage the 200k token window [​](https://docs.elizaos.ai/plugin-registry/llm/anthropic#external-resources) External Resources --------------------------------------------------------------------------------------------------- * [Plugin Source](https://github.com/elizaos/eliza/tree/main/packages/plugin-anthropic) * [Anthropic API Documentation](https://docs.anthropic.com/) * [Model Comparison](https://docs.anthropic.com/claude/docs/models-overview) Was this page helpful? YesNo [OpenAI Plugin](https://docs.elizaos.ai/plugin-registry/llm/openai) [Google GenAI Plugin](https://docs.elizaos.ai/plugin-registry/llm/google-genai) ⌘I --- # Ollama Plugin - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/plugin-registry/llm/ollama#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation LLM Providers Ollama Plugin [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Features](https://docs.elizaos.ai/plugin-registry/llm/ollama#features) * [Prerequisites](https://docs.elizaos.ai/plugin-registry/llm/ollama#prerequisites) * [Installation](https://docs.elizaos.ai/plugin-registry/llm/ollama#installation) * [Configuration](https://docs.elizaos.ai/plugin-registry/llm/ollama#configuration) * [Environment Variables](https://docs.elizaos.ai/plugin-registry/llm/ollama#environment-variables) * [Character Configuration](https://docs.elizaos.ai/plugin-registry/llm/ollama#character-configuration) * [Supported Operations](https://docs.elizaos.ai/plugin-registry/llm/ollama#supported-operations) * [Model Configuration](https://docs.elizaos.ai/plugin-registry/llm/ollama#model-configuration) * [Performance Tips](https://docs.elizaos.ai/plugin-registry/llm/ollama#performance-tips) * [Hardware Requirements](https://docs.elizaos.ai/plugin-registry/llm/ollama#hardware-requirements) * [Common Issues](https://docs.elizaos.ai/plugin-registry/llm/ollama#common-issues) * [”Connection refused”](https://docs.elizaos.ai/plugin-registry/llm/ollama#%E2%80%9Dconnection-refused%E2%80%9D) * [Slow Performance](https://docs.elizaos.ai/plugin-registry/llm/ollama#slow-performance) * [External Resources](https://docs.elizaos.ai/plugin-registry/llm/ollama#external-resources) The Ollama plugin provides local model execution and can serve as a fallback option when cloud-based LLM providers are not configured. It requires running an Ollama server locally. [​](https://docs.elizaos.ai/plugin-registry/llm/ollama#features) Features ---------------------------------------------------------------------------- * **Local execution** - No API keys or internet required * **Multiple models** - Support for Llama, Mistral, Gemma, and more * **Full model types** - Text, embeddings, and objects * **Cost-free** - No API charges * **Fallback option** - Can serve as a local fallback when cloud providers are unavailable [​](https://docs.elizaos.ai/plugin-registry/llm/ollama#prerequisites) Prerequisites -------------------------------------------------------------------------------------- 1. Install [Ollama](https://ollama.ai/) 2. Pull desired models: Copy Ask AI ollama pull llama3.1 ollama pull nomic-embed-text [​](https://docs.elizaos.ai/plugin-registry/llm/ollama#installation) Installation ------------------------------------------------------------------------------------ Copy Ask AI elizaos plugins add @elizaos/plugin-ollama [​](https://docs.elizaos.ai/plugin-registry/llm/ollama#configuration) Configuration -------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/llm/ollama#environment-variables) Environment Variables Copy Ask AI # Required OLLAMA_API_ENDPOINT=http://localhost:11434/api # Model configuration # You can use any model available in your Ollama installation OLLAMA_SMALL_MODEL=llama3.2 # Default: llama3.2 OLLAMA_MEDIUM_MODEL=llama3.1 # Default: llama3.1 OLLAMA_LARGE_MODEL=llama3.1:70b # Default: llama3.1:70b OLLAMA_EMBEDDING_MODEL=nomic-embed-text # Default: nomic-embed-text # Examples of other available models: # OLLAMA_SMALL_MODEL=mistral:7b # OLLAMA_MEDIUM_MODEL=mixtral:8x7b # OLLAMA_LARGE_MODEL=llama3.3:70b # OLLAMA_EMBEDDING_MODEL=mxbai-embed-large # OLLAMA_EMBEDDING_MODEL=all-minilm # Optional parameters OLLAMA_TEMPERATURE=0.7 ### [​](https://docs.elizaos.ai/plugin-registry/llm/ollama#character-configuration) Character Configuration Copy Ask AI { "name": "MyAgent", "plugins": ["@elizaos/plugin-ollama"] } [​](https://docs.elizaos.ai/plugin-registry/llm/ollama#supported-operations) Supported Operations ---------------------------------------------------------------------------------------------------- | Operation | Models | Notes | | --- | --- | --- | | TEXT\_GENERATION | llama3, mistral, gemma | Various sizes available | | EMBEDDING | nomic-embed-text, mxbai-embed-large | Local embeddings | | OBJECT\_GENERATION | All text models | JSON generation | [​](https://docs.elizaos.ai/plugin-registry/llm/ollama#model-configuration) Model Configuration -------------------------------------------------------------------------------------------------- The plugin uses three model tiers: * **SMALL\_MODEL**: Quick responses, lower resource usage * **MEDIUM\_MODEL**: Balanced performance * **LARGE\_MODEL**: Best quality, highest resource needs You can use any model from Ollama’s library: * Llama models (3, 3.1, 3.2, 3.3) * Mistral/Mixtral models * Gemma models * Phi models * Any custom models you’ve created For embeddings, popular options include: * `nomic-embed-text` - Balanced performance * `mxbai-embed-large` - Higher quality * `all-minilm` - Lightweight option [​](https://docs.elizaos.ai/plugin-registry/llm/ollama#performance-tips) Performance Tips -------------------------------------------------------------------------------------------- 1. **GPU Acceleration** - Dramatically improves speed 2. **Model Quantization** - Use Q4/Q5 versions for better performance 3. **Context Length** - Limit context for faster responses [​](https://docs.elizaos.ai/plugin-registry/llm/ollama#hardware-requirements) Hardware Requirements ------------------------------------------------------------------------------------------------------ | Model Size | RAM Required | GPU Recommended | | --- | --- | --- | | 7B | 8GB | Optional | | 13B | 16GB | Yes | | 70B | 64GB+ | Required | [​](https://docs.elizaos.ai/plugin-registry/llm/ollama#common-issues) Common Issues -------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/llm/ollama#%E2%80%9Dconnection-refused%E2%80%9D) ”Connection refused” Ensure Ollama is running: Copy Ask AI ollama serve ### [​](https://docs.elizaos.ai/plugin-registry/llm/ollama#slow-performance) Slow Performance * Use smaller models or quantized versions * Enable GPU acceleration * Reduce context length [​](https://docs.elizaos.ai/plugin-registry/llm/ollama#external-resources) External Resources ------------------------------------------------------------------------------------------------ * [Plugin Source](https://github.com/elizaos/eliza/tree/main/packages/plugin-ollama) * [Ollama Documentation](https://github.com/jmorganca/ollama) * [Model Library](https://ollama.ai/library) Was this page helpful? YesNo [Google GenAI Plugin](https://docs.elizaos.ai/plugin-registry/llm/google-genai) [OpenRouter Plugin](https://docs.elizaos.ai/plugin-registry/llm/openrouter) ⌘I --- # OpenAI Plugin - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/plugin-registry/llm/openai#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation LLM Providers OpenAI Plugin [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Features](https://docs.elizaos.ai/plugin-registry/llm/openai#features) * [Installation](https://docs.elizaos.ai/plugin-registry/llm/openai#installation) * [Configuration](https://docs.elizaos.ai/plugin-registry/llm/openai#configuration) * [Environment Variables](https://docs.elizaos.ai/plugin-registry/llm/openai#environment-variables) * [Character Configuration](https://docs.elizaos.ai/plugin-registry/llm/openai#character-configuration) * [Supported Operations](https://docs.elizaos.ai/plugin-registry/llm/openai#supported-operations) * [Model Configuration](https://docs.elizaos.ai/plugin-registry/llm/openai#model-configuration) * [Usage Example](https://docs.elizaos.ai/plugin-registry/llm/openai#usage-example) * [Cost Considerations](https://docs.elizaos.ai/plugin-registry/llm/openai#cost-considerations) * [External Resources](https://docs.elizaos.ai/plugin-registry/llm/openai#external-resources) The OpenAI plugin provides access to GPT models and supports all model types: text generation, embeddings, and object generation. [​](https://docs.elizaos.ai/plugin-registry/llm/openai#features) Features ---------------------------------------------------------------------------- * **Full model support** - Text, embeddings, and objects * **Multiple models** - GPT-4, GPT-3.5, and embedding models * **Streaming support** - Real-time response generation * **Function calling** - Structured output generation [​](https://docs.elizaos.ai/plugin-registry/llm/openai#installation) Installation ------------------------------------------------------------------------------------ Copy Ask AI elizaos plugins add @elizaos/plugin-openai [​](https://docs.elizaos.ai/plugin-registry/llm/openai#configuration) Configuration -------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/llm/openai#environment-variables) Environment Variables Copy Ask AI # Required OPENAI_API_KEY=sk-... # Optional model configuration # You can use any available OpenAI model OPENAI_SMALL_MODEL=gpt-4o-mini # Default: gpt-4o-mini OPENAI_LARGE_MODEL=gpt-4o # Default: gpt-4o OPENAI_EMBEDDING_MODEL=text-embedding-3-small # Default: text-embedding-3-small # Examples of other available models: # OPENAI_SMALL_MODEL=gpt-3.5-turbo # OPENAI_LARGE_MODEL=gpt-4-turbo # OPENAI_LARGE_MODEL=gpt-4o-2024-11-20 # OPENAI_EMBEDDING_MODEL=text-embedding-3-large # OPENAI_EMBEDDING_MODEL=text-embedding-ada-002 ### [​](https://docs.elizaos.ai/plugin-registry/llm/openai#character-configuration) Character Configuration Copy Ask AI { "name": "MyAgent", "plugins": ["@elizaos/plugin-openai"], "settings": { "secrets": { "OPENAI_API_KEY": "sk-..." } } } [​](https://docs.elizaos.ai/plugin-registry/llm/openai#supported-operations) Supported Operations ---------------------------------------------------------------------------------------------------- | Operation | Models | Notes | | --- | --- | --- | | TEXT\_GENERATION | Any GPT model (gpt-4o, gpt-4, gpt-3.5-turbo, etc.) | Conversational AI | | EMBEDDING | Any embedding model (text-embedding-3-small/large, ada-002) | Vector embeddings | | OBJECT\_GENERATION | All GPT models | JSON/structured output | [​](https://docs.elizaos.ai/plugin-registry/llm/openai#model-configuration) Model Configuration -------------------------------------------------------------------------------------------------- The plugin uses two model categories: * **SMALL\_MODEL**: Used for simpler tasks, faster responses * **LARGE\_MODEL**: Used for complex reasoning, better quality You can configure any available OpenAI model in these slots based on your needs and budget. [​](https://docs.elizaos.ai/plugin-registry/llm/openai#usage-example) Usage Example -------------------------------------------------------------------------------------- The plugin automatically registers with the runtime: Copy Ask AI // No manual initialization needed // Just include in plugins array [​](https://docs.elizaos.ai/plugin-registry/llm/openai#cost-considerations) Cost Considerations -------------------------------------------------------------------------------------------------- * GPT-4 is more expensive than GPT-3.5 * Use `text-embedding-3-small` for cheaper embeddings * Monitor usage via OpenAI dashboard [​](https://docs.elizaos.ai/plugin-registry/llm/openai#external-resources) External Resources ------------------------------------------------------------------------------------------------ * [Plugin Source](https://github.com/elizaos/eliza/tree/main/packages/plugin-openai) * [OpenAI API Documentation](https://platform.openai.com/docs) * [Pricing](https://openai.com/pricing) Was this page helpful? YesNo [Language Model Configuration](https://docs.elizaos.ai/plugin-registry/llm) [Anthropic Plugin](https://docs.elizaos.ai/plugin-registry/llm/anthropic) ⌘I --- # OpenRouter Plugin - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/plugin-registry/llm/openrouter#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation LLM Providers OpenRouter Plugin [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Features](https://docs.elizaos.ai/plugin-registry/llm/openrouter#features) * [Installation](https://docs.elizaos.ai/plugin-registry/llm/openrouter#installation) * [Configuration](https://docs.elizaos.ai/plugin-registry/llm/openrouter#configuration) * [Environment Variables](https://docs.elizaos.ai/plugin-registry/llm/openrouter#environment-variables) * [Character Configuration](https://docs.elizaos.ai/plugin-registry/llm/openrouter#character-configuration) * [Supported Operations](https://docs.elizaos.ai/plugin-registry/llm/openrouter#supported-operations) * [Important: Embedding Fallback](https://docs.elizaos.ai/plugin-registry/llm/openrouter#important%3A-embedding-fallback) * [Model Configuration](https://docs.elizaos.ai/plugin-registry/llm/openrouter#model-configuration) * [Premium Models](https://docs.elizaos.ai/plugin-registry/llm/openrouter#premium-models) * [Open Models](https://docs.elizaos.ai/plugin-registry/llm/openrouter#open-models) * [Pricing Strategy](https://docs.elizaos.ai/plugin-registry/llm/openrouter#pricing-strategy) * [External Resources](https://docs.elizaos.ai/plugin-registry/llm/openrouter#external-resources) [​](https://docs.elizaos.ai/plugin-registry/llm/openrouter#features) Features -------------------------------------------------------------------------------- * **Multiple providers** - Access 50+ models from various providers * **Automatic failover** - Route to available providers * **Cost optimization** - Choose models by price/performance * **Single API key** - One key for all providers [​](https://docs.elizaos.ai/plugin-registry/llm/openrouter#installation) Installation ---------------------------------------------------------------------------------------- Copy Ask AI elizaos plugins add @elizaos/plugin-openrouter [​](https://docs.elizaos.ai/plugin-registry/llm/openrouter#configuration) Configuration ------------------------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/plugin-registry/llm/openrouter#environment-variables) Environment Variables Copy Ask AI # Required OPENROUTER_API_KEY=sk-or-... # Optional model configuration # You can use any model available on OpenRouter OPENROUTER_SMALL_MODEL=google/gemini-2.0-flash-001 # Default: google/gemini-2.0-flash-001 OPENROUTER_LARGE_MODEL=google/gemini-2.5-flash-preview-05-20 # Default: google/gemini-2.5-flash-preview-05-20 OPENROUTER_IMAGE_MODEL=anthropic/claude-3-5-sonnet # For vision tasks # Examples of other available models: # OPENROUTER_SMALL_MODEL=anthropic/claude-3-haiku # OPENROUTER_LARGE_MODEL=anthropic/claude-3-opus # OPENROUTER_LARGE_MODEL=openai/gpt-4o # OPENROUTER_SMALL_MODEL=meta-llama/llama-3.1-8b-instruct:free ### [​](https://docs.elizaos.ai/plugin-registry/llm/openrouter#character-configuration) Character Configuration Copy Ask AI { "name": "MyAgent", "plugins": [\ "@elizaos/plugin-openrouter",\ "@elizaos/plugin-ollama" // For embeddings\ ] } [​](https://docs.elizaos.ai/plugin-registry/llm/openrouter#supported-operations) Supported Operations -------------------------------------------------------------------------------------------------------- | Operation | Support | Notes | | --- | --- | --- | | TEXT\_GENERATION | ✅ | All available models | | EMBEDDING | ❌ | Use fallback plugin | | OBJECT\_GENERATION | ✅ | Model dependent | [​](https://docs.elizaos.ai/plugin-registry/llm/openrouter#important%3A-embedding-fallback) Important: Embedding Fallback ---------------------------------------------------------------------------------------------------------------------------- OpenRouter doesn’t provide embedding endpoints, so include a fallback: Copy Ask AI { "plugins": [\ "@elizaos/plugin-openrouter", // Text generation\ "@elizaos/plugin-openai" // Embeddings\ ] } [​](https://docs.elizaos.ai/plugin-registry/llm/openrouter#model-configuration) Model Configuration ------------------------------------------------------------------------------------------------------ The plugin uses model tiers: * **SMALL\_MODEL**: Fast, cost-effective responses * **LARGE\_MODEL**: Complex reasoning, best quality * **IMAGE\_MODEL**: Multimodal capabilities OpenRouter provides access to 50+ models from various providers. You can use: ### [​](https://docs.elizaos.ai/plugin-registry/llm/openrouter#premium-models) Premium Models * Any Anthropic Claude model (Opus, Sonnet, Haiku) * Any OpenAI GPT model (GPT-4o, GPT-4, GPT-3.5) * Google Gemini models (Pro, Flash, etc.) * Cohere Command models ### [​](https://docs.elizaos.ai/plugin-registry/llm/openrouter#open-models) Open Models * Meta Llama models (3.1, 3.2, 3.3) * Mistral/Mixtral models * Many models with `:free` suffix for testing [​](https://docs.elizaos.ai/plugin-registry/llm/openrouter#pricing-strategy) Pricing Strategy ------------------------------------------------------------------------------------------------ OpenRouter charges a small markup (usually ~10%) on top of provider prices: 1. **Pay-per-token** - No monthly fees 2. **Price transparency** - See costs per model 3. **Credits system** - Pre-pay for usage [​](https://docs.elizaos.ai/plugin-registry/llm/openrouter#external-resources) External Resources ---------------------------------------------------------------------------------------------------- * [Plugin Source](https://github.com/elizaos/eliza/tree/main/packages/plugin-openrouter) * [OpenRouter Documentation](https://openrouter.ai/docs) * [Model List & Pricing](https://openrouter.ai/models) Was this page helpful? YesNo [Ollama Plugin](https://docs.elizaos.ai/plugin-registry/llm/ollama) [Discord Integration](https://docs.elizaos.ai/plugin-registry/platform/discord) ⌘I --- # Architecture & Flow Diagrams - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Knowledge Architecture & Flow Diagrams [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [High-Level Architecture](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#high-level-architecture) * [Document Processing Flow](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#document-processing-flow) * [Retrieval Flow](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#retrieval-flow) * [Component Interactions](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#component-interactions) * [Data Flow Architecture](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#data-flow-architecture) * [Processing Pipeline Details](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#processing-pipeline-details) * [Text Extraction Flow](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#text-extraction-flow) * [Chunking Strategy](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#chunking-strategy) * [Contextual Enrichment](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#contextual-enrichment) * [Rate Limiting & Concurrency](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#rate-limiting-%26-concurrency) * [Caching Architecture](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#caching-architecture) * [Web Interface Architecture](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#web-interface-architecture) * [Error Handling Flow](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#error-handling-flow) * [Performance Characteristics](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#performance-characteristics) * [Processing Times](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#processing-times) * [Storage Requirements](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#storage-requirements) * [Scaling Considerations](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#scaling-considerations) * [Summary](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#summary) This guide provides detailed visual representations of the Knowledge plugin’s architecture, processing flows, and component interactions. [​](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#high-level-architecture) High-Level Architecture --------------------------------------------------------------------------------------------------------------------------- [​](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#document-processing-flow) Document Processing Flow ----------------------------------------------------------------------------------------------------------------------------- [​](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#retrieval-flow) Retrieval Flow --------------------------------------------------------------------------------------------------------- [​](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#component-interactions) Component Interactions ------------------------------------------------------------------------------------------------------------------------- [​](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#data-flow-architecture) Data Flow Architecture ------------------------------------------------------------------------------------------------------------------------- [​](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#processing-pipeline-details) Processing Pipeline Details ----------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#text-extraction-flow) Text Extraction Flow ### [​](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#chunking-strategy) Chunking Strategy ### [​](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#contextual-enrichment) Contextual Enrichment [​](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#rate-limiting-%26-concurrency) Rate Limiting & Concurrency ------------------------------------------------------------------------------------------------------------------------------------- [​](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#caching-architecture) Caching Architecture --------------------------------------------------------------------------------------------------------------------- [​](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#web-interface-architecture) Web Interface Architecture --------------------------------------------------------------------------------------------------------------------------------- [​](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#error-handling-flow) Error Handling Flow ------------------------------------------------------------------------------------------------------------------- [​](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#performance-characteristics) Performance Characteristics ----------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#processing-times) Processing Times ### [​](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#storage-requirements) Storage Requirements [​](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#scaling-considerations) Scaling Considerations ------------------------------------------------------------------------------------------------------------------------- [​](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#summary) Summary ------------------------------------------------------------------------------------------- The Knowledge plugin’s architecture is designed for: Scalability ----------- Handles large document collections efficiently Performance ----------- Optimized processing and retrieval paths Reliability ----------- Robust error handling and recovery Cost Efficiency --------------- 90% savings with intelligent caching Understanding these flows helps you: * Optimize configuration for your use case * Debug issues effectively * Plan for scale * Integrate with other systems Was this page helpful? YesNo [Complete Developer Guide](https://docs.elizaos.ai/plugin-registry/knowledge/complete-documentation) [Contextual Embeddings](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings) ⌘I --- # Testing Guide - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Solana Testing Guide [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Testing Philosophy](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#testing-philosophy) * [Safe Testing Practices](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#safe-testing-practices) * [1\. Start Small](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#1-start-small) * [2\. Transaction Costs](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#2-transaction-costs) * [3\. Progressive Testing](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#3-progressive-testing) * [Testing Checklist](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#testing-checklist) * [Environment Setup](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#environment-setup) * [Basic Tests](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#basic-tests) * [Swap Testing](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#swap-testing) * [Portfolio Tracking](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#portfolio-tracking) * [Monitoring Results](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#monitoring-results) * [Common Issues](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#common-issues) * [”Insufficient SOL for fees”](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#%E2%80%9Dinsufficient-sol-for-fees%E2%80%9D) * [”Token account doesn’t exist”](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#%E2%80%9Dtoken-account-doesn%E2%80%99t-exist%E2%80%9D) * [”Slippage tolerance exceeded”](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#%E2%80%9Dslippage-tolerance-exceeded%E2%80%9D) * [Production Readiness](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#production-readiness) [​](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#testing-philosophy) Testing Philosophy --------------------------------------------------------------------------------------------------------------- Test with small amounts on mainnet. Solana devnet/testnet tokens have no value and often have different behavior than mainnet. [​](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#safe-testing-practices) Safe Testing Practices ----------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#1-start-small) 1\. Start Small Test with minimal amounts: * 0.001 SOL for transfers (~$0.20) * $1-5 worth of tokens for swaps * Use common tokens (USDC, USDT) for reliability ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#2-transaction-costs) 2\. Transaction Costs Solana transactions are cheap (~$0.00025 per transaction), making mainnet testing affordable. ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#3-progressive-testing) 3\. Progressive Testing Copy Ask AI 1. Check wallet connection 2. Test SOL transfers 3. Test SPL token transfers 4. Test small swaps 5. Test larger operations [​](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#testing-checklist) Testing Checklist ------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#environment-setup) Environment Setup Copy Ask AI # Use a dedicated test wallet SOLANA_PRIVATE_KEY=test_wallet_private_key # Optional - Use premium RPC for reliability SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#basic-tests) Basic Tests 1. **Wallet Connection** Copy Ask AI User: What's my wallet address? Agent: [Should show your Solana address] 2. **Balance Check** Copy Ask AI User: What's my balance? Agent: [Should show SOL balance and token holdings] 3. **Small SOL Transfer** Copy Ask AI User: Send 0.001 SOL to [another address] Agent: [Should execute the transfer] 4. **Token Transfer** Copy Ask AI User: Send 1 USDC to [test address] Agent: [Should handle SPL token transfer] ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#swap-testing) Swap Testing Test swaps with small amounts: Copy Ask AI User: Swap 0.1 SOL for USDC Agent: [Should execute via Jupiter] ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#portfolio-tracking) Portfolio Tracking Copy Ask AI User: What's my portfolio worth? Agent: [Should show total USD value and token breakdown] [​](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#monitoring-results) Monitoring Results --------------------------------------------------------------------------------------------------------------- 1. **Transaction Verification** * Check on Solscan.io or Solana Explorer * Verify transaction succeeded * Confirm balance changes 2. **Common Token Addresses** * USDC: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v * USDT: Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB * Use these for testing as they’re widely supported [​](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#common-issues) Common Issues ----------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#%E2%80%9Dinsufficient-sol-for-fees%E2%80%9D) ”Insufficient SOL for fees” * Need ~0.001 SOL for transaction fees * Keep some SOL for rent and fees ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#%E2%80%9Dtoken-account-doesn%E2%80%99t-exist%E2%80%9D) ”Token account doesn’t exist” * First transfer to a new token creates the account * Costs ~0.002 SOL for account creation ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#%E2%80%9Dslippage-tolerance-exceeded%E2%80%9D) ”Slippage tolerance exceeded” * Increase slippage for volatile tokens * Try smaller amounts [​](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide#production-readiness) Production Readiness ------------------------------------------------------------------------------------------------------------------- Before production use: 1. Test all operations you plan to use 2. Verify error handling 3. Test with your expected token types 4. Monitor transaction success rates 5. Set appropriate slippage (1-3% typical) 6. Ensure adequate SOL for fees Was this page helpful? YesNo [Examples](https://docs.elizaos.ai/plugin-registry/defi/solana/examples) ⌘I --- # Examples - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Solana Examples [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Configuration](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#configuration) * [Character Configuration](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#character-configuration) * [Environment Variables](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#environment-variables) * [Usage Examples](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#usage-examples) * [Transfer Operations](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#transfer-operations) * [Swap Operations](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#swap-operations) * [Portfolio Management](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#portfolio-management) * [Custom Plugin Integration](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#custom-plugin-integration) * [Common Patterns](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#common-patterns) * [Domain Name Resolution](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#domain-name-resolution) * [Token Symbol Resolution](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#token-symbol-resolution) * [All Balance Swaps](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#all-balance-swaps) * [Slippage Control](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#slippage-control) [​](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#configuration) Configuration ------------------------------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#character-configuration) Character Configuration Add the Solana plugin to your character file: Copy Ask AI // character.ts import { type Character } from '@elizaos/core'; export const character: Character = { name: 'SolanaAgent', plugins: [\ // Core plugins\ '@elizaos/plugin-sql',\ '@elizaos/plugin-bootstrap',\ \ // Solana plugin\ ...(process.env.SOLANA_PRIVATE_KEY?.trim() ? ['@elizaos/plugin-solana'] : []),\ \ // Platform plugins\ ...(process.env.DISCORD_API_TOKEN?.trim() ? ['@elizaos/plugin-discord'] : []),\ ], settings: { secrets: {}, }, // ... rest of character configuration }; ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#environment-variables) Environment Variables Copy Ask AI # Required - Choose one: SOLANA_PRIVATE_KEY=your_base58_private_key_here # OR for read-only mode: SOLANA_PUBLIC_KEY=your_public_key_here # Optional - Enhanced RPC SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY HELIUS_API_KEY=your_helius_key # Optional - Market data BIRDEYE_API_KEY=your_birdeye_key [​](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#usage-examples) Usage Examples -------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#transfer-operations) Transfer Operations The agent understands natural language for transfers: Copy Ask AI User: Send 1 SOL to 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU Agent: I'll send 1 SOL to that address right away. User: Transfer 100 USDC to alice.sol Agent: Transferring 100 USDC to alice.sol. User: Pay bob 50 BONK tokens Agent: Sending 50 BONK to bob. ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#swap-operations) Swap Operations Copy Ask AI User: Swap 10 SOL for USDC Agent: I'll swap 10 SOL for USDC using Jupiter. User: Exchange all my BONK for SOL Agent: Swapping all your BONK tokens for SOL. User: Trade 100 USDC for JTO with 2% slippage Agent: Swapping 100 USDC for JTO with 2% slippage tolerance. ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#portfolio-management) Portfolio Management Copy Ask AI User: What's my wallet balance? Agent: [Shows total portfolio value and individual token balances] User: How much is my portfolio worth? Agent: Your total portfolio value is $X,XXX.XX (XX.XX SOL) [​](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#custom-plugin-integration) Custom Plugin Integration ------------------------------------------------------------------------------------------------------------------------ If you need to import the plugin directly in a ProjectAgent: Copy Ask AI // index.ts import { type ProjectAgent } from '@elizaos/core'; import solanaPlugin from '@elizaos/plugin-solana'; import { character } from './character'; export const projectAgent: ProjectAgent = { character, plugins: [solanaPlugin], // Import custom plugins here init: async (runtime) => { // Custom initialization if needed } }; [​](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#common-patterns) Common Patterns ---------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#domain-name-resolution) Domain Name Resolution The plugin automatically resolves .sol domains: Copy Ask AI User: Send 5 SOL to vitalik.sol Agent: Sending 5 SOL to vitalik.sol [resolves to actual address] ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#token-symbol-resolution) Token Symbol Resolution Common tokens are automatically recognized: Copy Ask AI User: Send 100 USDC to alice Agent: [Recognizes USDC token mint and handles transfer] ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#all-balance-swaps) All Balance Swaps Copy Ask AI User: Swap all my BONK for USDC Agent: [Calculates max balance and executes swap] ### [​](https://docs.elizaos.ai/plugin-registry/defi/solana/examples#slippage-control) Slippage Control Copy Ask AI User: Swap with 0.5% slippage Agent: [Sets custom slippage for the swap] Was this page helpful? YesNo [Operations Flow](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow) [Testing Guide](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide) ⌘I --- # Contextual Embeddings - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Knowledge Contextual Embeddings [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [What are Contextual Embeddings?](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#what-are-contextual-embeddings%3F) * [Traditional vs Contextual](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#traditional-vs-contextual) * [How It Works](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#how-it-works) * [Configuration](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#configuration) * [Enable Contextual Embeddings](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#enable-contextual-embeddings) * [Recommended Setup: OpenRouter with Separate Embedding Provider](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#recommended-setup%3A-openrouter-with-separate-embedding-provider) * [Alternative Providers](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#alternative-providers) * [Technical Details](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#technical-details) * [Chunk Processing](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#chunk-processing) * [Content-Aware Templates](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#content-aware-templates) * [OpenRouter Caching](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#openrouter-caching) * [Example: How Context Improves Retrieval](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#example%3A-how-context-improves-retrieval) * [Without Contextual Embeddings](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#without-contextual-embeddings) * [With Contextual Embeddings](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#with-contextual-embeddings) * [Performance Considerations](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#performance-considerations) * [Processing Time](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#processing-time) * [Cost Estimation](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#cost-estimation) * [Monitoring](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#monitoring) * [Common Issues and Solutions](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#common-issues-and-solutions) * [Context Not Being Added](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#context-not-being-added) * [Slow Processing](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#slow-processing) * [High Costs](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#high-costs) * [Best Practices](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#best-practices) * [Summary](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#summary) Contextual embeddings are an advanced Knowledge plugin feature that improves retrieval accuracy by enriching text chunks with surrounding context before generating embeddings. This implementation is based on [Anthropic’s contextual retrieval techniques](https://www.anthropic.com/news/contextual-retrieval) . [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#what-are-contextual-embeddings%3F) What are Contextual Embeddings? ------------------------------------------------------------------------------------------------------------------------------------------------- Traditional RAG systems embed isolated text chunks, losing important context. Contextual embeddings solve this by using an LLM to add relevant context to each chunk before embedding. ### [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#traditional-vs-contextual) Traditional vs Contextual * Traditional Embedding * Contextual Embedding Copy Ask AI Original chunk: "The deployment process requires authentication." Embedded as-is, missing context about: - Which deployment process? - What kind of authentication? - For which system? [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#how-it-works) How It Works --------------------------------------------------------------------------------------------------------- The Knowledge plugin uses a sophisticated prompt-based approach to enrich chunks: 1. **Document Analysis**: The full document is passed to an LLM along with each chunk 2. **Context Generation**: The LLM identifies relevant context from the document 3. **Chunk Enrichment**: The original chunk is preserved with added context 4. **Embedding**: The enriched chunk is embedded using your configured embedding model The implementation is based on Anthropic’s Contextual Retrieval cookbook example, which showed up to 50% improvement in retrieval accuracy. [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#configuration) Configuration ----------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#enable-contextual-embeddings) Enable Contextual Embeddings .env Copy Ask AI # Enable contextual embeddings CTX_KNOWLEDGE_ENABLED=true # Configure your text generation provider TEXT_PROVIDER=openrouter # or openai, anthropic, google TEXT_MODEL=anthropic/claude-3-haiku # or any supported model # Required API keys OPENROUTER_API_KEY=your-key # If using OpenRouter # or OPENAI_API_KEY=your-key # If using OpenAI # or ANTHROPIC_API_KEY=your-key # If using Anthropic # or GOOGLE_API_KEY=your-key # If using Google **Important**: Embeddings always use the model configured in `useModel(TEXT_EMBEDDING)` from your agent setup. Do NOT try to mix different embedding models - all your documents must use the same embedding model for consistency. ### [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#recommended-setup%3A-openrouter-with-separate-embedding-provider) Recommended Setup: OpenRouter with Separate Embedding Provider Since OpenRouter doesn’t support embeddings, you need a separate embedding provider: * OpenRouter + OpenAI * OpenRouter + Google character.ts Copy Ask AI export const character = { name: 'MyAgent', plugins: [\ '@elizaos/plugin-openrouter', // For text generation\ '@elizaos/plugin-openai', // For embeddings\ '@elizaos/plugin-knowledge', // Knowledge plugin\ ], }; .env Copy Ask AI # Enable contextual embeddings CTX_KNOWLEDGE_ENABLED=true # Text generation (for context enrichment) TEXT_PROVIDER=openrouter TEXT_MODEL=anthropic/claude-3-haiku OPENROUTER_API_KEY=your-openrouter-key # Embeddings (automatically used) OPENAI_API_KEY=your-openai-key ### [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#alternative-providers) Alternative Providers * OpenAI Only * Anthropic + OpenAI * Google Only * OpenRouter + Google Copy Ask AI CTX_KNOWLEDGE_ENABLED=true TEXT_PROVIDER=openai TEXT_MODEL=gpt-4o-mini OPENAI_API_KEY=your-key [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#technical-details) Technical Details ------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#chunk-processing) Chunk Processing The plugin uses fixed chunk sizes optimized for contextual enrichment: * **Chunk Size**: 500 tokens (approximately 1,750 characters) * **Chunk Overlap**: 100 tokens * **Context Target**: 60-200 tokens of added context These values are based on research showing that smaller chunks with rich context perform better than larger chunks without context. ### [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#content-aware-templates) Content-Aware Templates The plugin automatically detects content types and uses specialized prompts: Copy Ask AI // Different templates for different content types - General text documents - PDF documents (with special handling for corrupted text) - Mathematical content (preserves equations and notation) - Code files (includes imports, function signatures) - Technical documentation (preserves terminology) ### [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#openrouter-caching) OpenRouter Caching When using OpenRouter with Claude or Gemini models, the plugin automatically leverages caching: 1. **First document chunk**: Caches the full document 2. **Subsequent chunks**: Reuses cached document (90% cost reduction) 3. **Cache duration**: 5 minutes (automatic) This means processing a 100-page document costs almost the same as processing a single page! [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#example%3A-how-context-improves-retrieval) Example: How Context Improves Retrieval ----------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#without-contextual-embeddings) Without Contextual Embeddings Copy Ask AI Query: "How do I configure the timeout?" Retrieved chunk: "Set the timeout value to 30 seconds." Problem: Which timeout? Database? API? Cache? ### [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#with-contextual-embeddings) With Contextual Embeddings Copy Ask AI Query: "How do I configure the timeout?" Retrieved chunk: "In the Redis configuration section, when setting up the caching layer, set the timeout value to 30 seconds for optimal performance with session data." Result: Clear understanding this is about Redis cache timeout. [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#performance-considerations) Performance Considerations ------------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#processing-time) Processing Time * **Initial processing**: 1-3 seconds per chunk (includes LLM call) * **With caching**: 0.1-0.3 seconds per chunk * **Batch processing**: Up to 30 chunks concurrently ### [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#cost-estimation) Cost Estimation | Document Size | Pages | Chunks | Without Caching | With OpenRouter Cache | | --- | --- | --- | --- | --- | | Small | 10 | ~20 | $0.02 | $0.002 | | Medium | 50 | ~100 | $0.10 | $0.01 | | Large | 200 | ~400 | $0.40 | $0.04 | Costs are estimates based on Claude 3 Haiku pricing. Actual costs depend on your chosen model. [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#monitoring) Monitoring ----------------------------------------------------------------------------------------------------- The plugin provides detailed logging: Copy Ask AI # Enable debug logging to see enrichment details LOG_LEVEL=debug elizaos start This will show: * Context enrichment progress * Cache hit/miss rates * Processing times per document * Token usage [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#common-issues-and-solutions) Common Issues and Solutions --------------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#context-not-being-added) Context Not Being Added **Check if contextual embeddings are enabled:** Copy Ask AI # Look for this in your logs: "CTX enrichment ENABLED" # or "CTX enrichment DISABLED" **Verify your configuration:** * `CTX_KNOWLEDGE_ENABLED=true` (not “TRUE” or “True”) * `TEXT_PROVIDER` and `TEXT_MODEL` are both set * Required API key for your provider is set ### [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#slow-processing) Slow Processing **Solutions:** 1. Use OpenRouter with Claude/Gemini for automatic caching 2. Process smaller batches of documents 3. Use faster models (Claude 3 Haiku, Gemini 1.5 Flash) ### [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#high-costs) High Costs **Solutions:** 1. Enable OpenRouter caching (90% cost reduction) 2. Use smaller models for context generation 3. Process documents in batches during off-peak hours [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#best-practices) Best Practices ------------------------------------------------------------------------------------------------------------- 1 Use OpenRouter for Cost Efficiency OpenRouter’s caching makes contextual embeddings 90% cheaper when processing multiple chunks from the same document. 2 Keep Default Settings The chunk sizes and overlap are optimized based on research. Only change if you have specific requirements. 3 Monitor Your Logs Enable debug logging when first setting up to ensure context is being added properly. 4 Use Appropriate Models * Claude 3 Haiku: Best balance of quality and cost * Gemini 1.5 Flash: Fastest processing * GPT-4o-mini: Good quality, moderate cost [​](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#summary) Summary ----------------------------------------------------------------------------------------------- Contextual embeddings significantly improve retrieval accuracy by: * Adding document context to each chunk before embedding * Using intelligent templates based on content type * Preserving the original text while enriching with context * Leveraging caching for cost-efficient processing The implementation is based on Anthropic’s proven approach and integrates seamlessly with elizaOS’s existing infrastructure. Simply set `CTX_KNOWLEDGE_ENABLED=true` and configure your text generation provider to get started! Was this page helpful? YesNo [Architecture & Flow Diagrams](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow) [Examples & Recipes](https://docs.elizaos.ai/plugin-registry/knowledge/examples) ⌘I --- # Discord Integration - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/plugin-registry/platform/discord#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Discord Discord Integration [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [📚 Documentation](https://docs.elizaos.ai/plugin-registry/platform/discord#%F0%9F%93%9A-documentation) * [🔧 Configuration](https://docs.elizaos.ai/plugin-registry/platform/discord#%F0%9F%94%A7-configuration) * [Required Settings](https://docs.elizaos.ai/plugin-registry/platform/discord#required-settings) * [Optional Settings](https://docs.elizaos.ai/plugin-registry/platform/discord#optional-settings) The @elizaos/plugin-discord enables your elizaOS agent to operate as a Discord bot with full support for messages, voice channels, slash commands, and media processing. [​](https://docs.elizaos.ai/plugin-registry/platform/discord#%F0%9F%93%9A-documentation) 📚 Documentation ------------------------------------------------------------------------------------------------------------ * **[Developer Guide](https://docs.elizaos.ai/plugin-registry/platform/discord/developer-guide) ** - Detailed technical reference * **[Event Flow](https://docs.elizaos.ai/plugin-registry/platform/discord/event-flow) ** - Visual guide to Discord event processing * **[Examples](https://docs.elizaos.ai/plugin-registry/platform/discord/examples) ** - Practical implementation examples * **[Testing Guide](https://docs.elizaos.ai/plugin-registry/platform/discord/testing-guide) ** - Testing strategies and patterns [​](https://docs.elizaos.ai/plugin-registry/platform/discord#%F0%9F%94%A7-configuration) 🔧 Configuration ------------------------------------------------------------------------------------------------------------ ### [​](https://docs.elizaos.ai/plugin-registry/platform/discord#required-settings) Required Settings * `DISCORD_APPLICATION_ID` - Your Discord application ID * `DISCORD_API_TOKEN` - Bot authentication token ### [​](https://docs.elizaos.ai/plugin-registry/platform/discord#optional-settings) Optional Settings * `CHANNEL_IDS` - Restrict bot to specific channels * `DISCORD_VOICE_CHANNEL_ID` - Default voice channel Was this page helpful? YesNo [OpenRouter Plugin](https://docs.elizaos.ai/plugin-registry/llm/openrouter) [Developer Guide](https://docs.elizaos.ai/plugin-registry/platform/discord/developer-guide) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugins/bootstrap/examples.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Patterns](https://docs.elizaos.ai/plugins/patterns#bootstrap-plugin-pattern) [Architecture](https://docs.elizaos.ai/plugins/architecture#bootstrap-plugin) [Implementation Examples](https://docs.elizaos.ai/plugin-registry/bootstrap/examples#implementation-examples) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugins/bootstrap/complete-documentation.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Complete Developer Guide](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#) [Patterns](https://docs.elizaos.ai/plugins/patterns#bootstrap-plugin-pattern) [Architecture](https://docs.elizaos.ai/plugins/architecture#bootstrap-plugin) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugins/bootstrap/message-flow.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Architecture](https://docs.elizaos.ai/plugins/architecture#bootstrap-plugin) [Message Processing Flow](https://docs.elizaos.ai/plugin-registry/bootstrap/message-flow#summary) [Complete Developer Guide](https://docs.elizaos.ai/plugin-registry/bootstrap/complete-documentation#overview) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugins/bootstrap/testing-guide.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Testing Guide](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-guide) [Patterns](https://docs.elizaos.ai/plugins/patterns#bootstrap-plugin-pattern) [Architecture](https://docs.elizaos.ai/plugins/architecture#bootstrap-plugin) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugin-registry/defi/evm/complete-documentation.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Plugin Registry](https://docs.elizaos.ai/plugin-registry/registry#) [Plugin System Overview](https://docs.elizaos.ai/plugin-registry/overview#defi-plugins) [Publish a Plugin](https://docs.elizaos.ai/guides/publish-a-plugin#verify-plugin-requirements) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugin-registry/defi/solana/complete-documentation.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Plugin Registry](https://docs.elizaos.ai/plugin-registry/registry#) [Plugin System Overview](https://docs.elizaos.ai/plugin-registry/overview#defi-plugins) [Publish a Plugin](https://docs.elizaos.ai/guides/publish-a-plugin#verify-plugin-requirements) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Operations Flow](https://docs.elizaos.ai/plugin-registry/defi/evm/defi-operations-flow#overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/registry#plugin-registry) [Plugin System Overview](https://docs.elizaos.ai/plugin-registry/overview#defi-plugins) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Operations Flow](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/registry#plugin-registry) [Plugin System Overview](https://docs.elizaos.ai/plugin-registry/overview#defi-plugins) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugin-registry/defi/evm/examples.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugin-registry/openai.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [OpenAI Plugin](https://docs.elizaos.ai/plugin-registry/llm/openai#openai-plugin) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/registry#plugin-registry) [OpenRouter Plugin](https://docs.elizaos.ai/plugin-registry/llm/openrouter#) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugin-registry/defi/solana/examples.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Plugin Registry](https://docs.elizaos.ai/plugin-registry/registry#plugin-registry) [Plugin System Overview](https://docs.elizaos.ai/plugin-registry/overview#defi-plugins) [Operations Flow](https://docs.elizaos.ai/plugin-registry/defi/solana/defi-operations-flow#overview) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugin-registry/defi/evm/testing-guide.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Plugin Registry](https://docs.elizaos.ai/plugin-registry/registry#plugin-registry) [Testing Guide](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-guide) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugins/knowledge/quick-start#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Quick Start Guide](https://docs.elizaos.ai/plugin-registry/knowledge/quick-start#) [Knowledge & RAG System](https://docs.elizaos.ai/plugin-registry/knowledge#knowledge-and-rag-system) [Personality and Behavior](https://docs.elizaos.ai/agents/personality-and-behavior#using-plugin-knowledge-for-rich-personalities) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugins/knowledge/examples#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Knowledge & RAG System](https://docs.elizaos.ai/plugin-registry/knowledge#knowledge-and-rag-system) [Personality and Behavior](https://docs.elizaos.ai/agents/personality-and-behavior#using-plugin-knowledge-for-rich-personalities) [Examples & Recipes](https://docs.elizaos.ai/plugin-registry/knowledge/examples#the-knowledge-provider) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugin-registry/database-adapters.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Database Adapters](https://docs.elizaos.ai/plugin-registry/sql/database-adapters#database-adapters) [Architecture](https://docs.elizaos.ai/plugins/architecture#database-adapter-plugins) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/registry#) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugin-registry/schema-management.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Schema Management](https://docs.elizaos.ai/plugin-registry/sql/schema-management#schema-management) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/registry#plugin-registry) [Plugin Management](https://docs.elizaos.ai/cli-reference/plugins#) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugin-registry/ollama.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Ollama Plugin](https://docs.elizaos.ai/plugin-registry/llm/ollama#ollama-plugin) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/registry#plugin-registry) [Publish a Plugin](https://docs.elizaos.ai/guides/publish-a-plugin#verify-plugin-requirements) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugin-registry/openrouter.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [OpenRouter Plugin](https://docs.elizaos.ai/plugin-registry/llm/openrouter#) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/registry#plugin-registry) [OpenAI Plugin](https://docs.elizaos.ai/plugin-registry/llm/openai#openai-plugin) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugin-registry/plugin-tables.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Plugin Registry](https://docs.elizaos.ai/plugin-registry/registry#plugin-registry) [Plugin Tables Guide](https://docs.elizaos.ai/plugin-registry/sql/plugin-tables#plugin-tables-guide) [Publish a Plugin](https://docs.elizaos.ai/guides/publish-a-plugin#verify-plugin-requirements) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugin-registry/anthropic.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugins/knowledge/architecture-flow#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Architecture & Flow Diagrams](https://docs.elizaos.ai/plugin-registry/knowledge/architecture-flow#architecture-and-flow-diagrams) [Knowledge & RAG System](https://docs.elizaos.ai/plugin-registry/knowledge#knowledge-and-rag-system) [Personality and Behavior](https://docs.elizaos.ai/agents/personality-and-behavior#using-plugin-knowledge-for-rich-personalities) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugin-registry/knowledge/quick-start.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Quick Start Guide](https://docs.elizaos.ai/plugin-registry/knowledge/quick-start#) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/registry#plugin-registry) [Knowledge & RAG System](https://docs.elizaos.ai/plugin-registry/knowledge#knowledge-and-rag-system) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugin-registry/defi/solana/testing-guide.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Testing Guide](https://docs.elizaos.ai/plugin-registry/bootstrap/testing-guide#testing-guide) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/registry#plugin-registry) [Developer Guide](https://docs.elizaos.ai/plugin-registry/defi/solana/complete-documentation#developer-guide) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugin-registry/examples.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Plugin Registry](https://docs.elizaos.ai/plugin-registry/registry#plugin-registry) [Publish a Plugin](https://docs.elizaos.ai/guides/publish-a-plugin#verify-plugin-requirements) [Plugin System Overview](https://docs.elizaos.ai/plugin-registry/overview#community-plugin-registry) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugin-registry/google-genai.mdx#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Google GenAI Plugin](https://docs.elizaos.ai/plugin-registry/llm/google-genai#) [OpenAI Plugin](https://docs.elizaos.ai/plugin-registry/llm/openai#openai-plugin) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/registry#plugin-registry) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugins/knowledge/contextual-embeddings#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Contextual Embeddings](https://docs.elizaos.ai/plugin-registry/knowledge/contextual-embeddings#contextual-embeddings) [Complete Developer Guide](https://docs.elizaos.ai/plugin-registry/knowledge/complete-documentation#summary) [Knowledge & RAG System](https://docs.elizaos.ai/plugin-registry/knowledge#knowledge-and-rag-system) ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/plugins/knowledge/complete-documentation#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Knowledge & RAG System](https://docs.elizaos.ai/plugin-registry/knowledge#knowledge-and-rag-system) [Complete Developer Guide](https://docs.elizaos.ai/plugin-registry/knowledge/complete-documentation#complete-developer-guide) [Personality and Behavior](https://docs.elizaos.ai/agents/personality-and-behavior#using-plugin-knowledge-for-rich-personalities) ⌘I --- # REST Reference - ElizaOS Documentation [Skip to main content](https://docs.elizaos.ai/rest-reference#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation REST Reference [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) On this page * [Core APIs](https://docs.elizaos.ai/rest-reference#core-apis) * [Media & Audio](https://docs.elizaos.ai/rest-reference#media-%26-audio) * [System & Monitoring](https://docs.elizaos.ai/rest-reference#system-%26-monitoring) * [Getting Started](https://docs.elizaos.ai/rest-reference#getting-started) * [API Standards](https://docs.elizaos.ai/rest-reference#api-standards) * [Need Help?](https://docs.elizaos.ai/rest-reference#need-help%3F) Welcome to the elizaOS REST Reference. This comprehensive guide covers all available REST endpoints and services for building and managing AI agents. [​](https://docs.elizaos.ai/rest-reference#core-apis) Core APIs ------------------------------------------------------------------ [Agents\ ------\ \ Create, manage, and control AI agents. Handle agent lifecycle, configuration, and world management.](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [Messaging\ ---------\ \ Real-time messaging system for agent communication. Create servers, channels, and manage conversations.](https://docs.elizaos.ai/rest-reference/messaging/create-server) [Memory\ ------\ \ Agent memory management. Store, retrieve, and organize agent memories and contextual information.](https://docs.elizaos.ai/rest-reference/memory/get-agent-memories) [Rooms\ -----\ \ Virtual spaces for agent interactions. Create and manage rooms for organized conversations.](https://docs.elizaos.ai/rest-reference/rooms/create-a-room) [​](https://docs.elizaos.ai/rest-reference#media-%26-audio) Media & Audio ---------------------------------------------------------------------------- [Audio\ -----\ \ Speech synthesis, transcription, and audio processing capabilities.](https://docs.elizaos.ai/rest-reference/audio/generate-speech-from-text) [Media\ -----\ \ Media upload and management for agents and channels.](https://docs.elizaos.ai/rest-reference/media/upload-media-for-agent) [​](https://docs.elizaos.ai/rest-reference#system-%26-monitoring) System & Monitoring ---------------------------------------------------------------------------------------- [System\ ------\ \ System status, health checks, and server management endpoints.](https://docs.elizaos.ai/rest-reference/system/basic-health-check) [Logs\ ----\ \ Logging and debugging tools for agents and system operations.](https://docs.elizaos.ai/rest-reference/logs/get-agent-logs) [WebSocket\ ---------\ \ Real-time WebSocket connections for live agent interactions.](https://docs.elizaos.ai/rest-reference/websocket/socketio-real-time-connection) [​](https://docs.elizaos.ai/rest-reference#getting-started) Getting Started ------------------------------------------------------------------------------ 1 Authentication Set up your API credentials and authentication tokens. 2 Create an Agent Use the [Create Agent endpoint](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) to start building. 3 Configure Messaging Set up [messaging channels](https://docs.elizaos.ai/rest-reference/messaging/create-channel) for agent communication. 4 Test Integration Use [health check endpoints](https://docs.elizaos.ai/rest-reference/system/basic-health-check) to verify your setup. [​](https://docs.elizaos.ai/rest-reference#api-standards) API Standards -------------------------------------------------------------------------- All API endpoints follow RESTful conventions: * **GET** - Retrieve resources * **POST** - Create new resources * **PUT** - Update existing resources * **DELETE** - Remove resources Response formats are consistently JSON with appropriate HTTP status codes. [​](https://docs.elizaos.ai/rest-reference#need-help%3F) Need Help? ---------------------------------------------------------------------- [Core Concepts\ -------------\ \ Learn the fundamental concepts behind elizaOS](https://docs.elizaos.ai/core-concepts) [Create a Plugin\ ---------------\ \ Step-by-step integration guides](https://docs.elizaos.ai/guides/create-a-plugin) Was this page helpful? YesNo ⌘I --- # Page Not Found [Skip to main content](https://docs.elizaos.ai/core-concepts#content-area) [ElizaOS Documentation home page![light logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/light.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=ef25ef0a7ad0c2985928651085d3a8e2)![dark logo](https://mintcdn.com/elizalabs/bbIJsUzCDybj9a-t/logo/dark.png?fit=max&auto=format&n=bbIJsUzCDybj9a-t&q=85&s=d696503a5eeb5ccddf46a3e2cdce0190)](https://docs.elizaos.ai/) Search... ⌘K Search... Navigation Page Not Found [Docs](https://docs.elizaos.ai/) [REST Reference](https://docs.elizaos.ai/rest-reference/agents/create-a-new-agent) [CLI Reference](https://docs.elizaos.ai/cli-reference/overview) [Plugin Registry](https://docs.elizaos.ai/plugin-registry/overview) [Launch Resources](https://docs.elizaos.ai/launch-resources) 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Core](https://docs.elizaos.ai/runtime/core#) [Message Processing Core](https://docs.elizaos.ai/plugin-registry/bootstrap#message-processing-core) [Contribute to Core](https://docs.elizaos.ai/guides/contribute-to-core#) ⌘I ---