# Table of Contents - [Introduction to Eliza | eliza](#introduction-to-eliza-eliza) - [Frequently Asked Questions | eliza](#frequently-asked-questions-eliza) - [Quickstart Guide | eliza](#quickstart-guide-eliza) - [AI Agent Dev School | eliza](#ai-agent-dev-school-eliza) - [Changelog | eliza](#changelog-eliza) - [Overview | eliza](#overview-eliza) - [πŸ“ Character Files | eliza](#-character-files-eliza) - [πŸ€– Agent Runtime | eliza](#-agent-runtime-eliza) - [Plugins | eliza](#plugins-eliza) - [πŸ”Œ Clients | eliza](#-clients-eliza) - [πŸ”Œ Providers | eliza](#-providers-eliza) - [⚑ Actions | eliza](#-actions-eliza) - [πŸ“Š Evaluators | eliza](#-evaluators-eliza) - [Part 1: Introduction and Foundations | eliza](#part-1-introduction-and-foundations-eliza) - [Part 2: Deep Dive into Actions, Providers, and Evaluators | eliza](#part-2-deep-dive-into-actions-providers-and-evaluators-eliza) - [Deploying ElizaOS to Production | eliza](#deploying-elizaos-to-production-eliza) - [πŸ’Ύ Database Adapters | eliza](#-database-adapters-eliza) - [🎯 Fine-tuning Guide | eliza](#-fine-tuning-guide-eliza) - [Part 3: Building a User Data Extraction Agent | eliza](#part-3-building-a-user-data-extraction-agent-eliza) - [πŸ” Secrets Management | eliza](#-secrets-management-eliza) - [βš™οΈ Configuration Guide | eliza](#-configuration-guide-eliza) - [Building a Social AI Agent in 15 Minutes | eliza](#building-a-social-ai-agent-in-15-minutes-eliza) - [Creating an AI Agent with Your Own Personality | eliza](#creating-an-ai-agent-with-your-own-personality-eliza) - [Memory Management | eliza](#memory-management-eliza) - [How to Build an API Plugin | eliza](#how-to-build-an-api-plugin-eliza) - [WSL Setup Guide | eliza](#wsl-setup-guide-eliza) - [🀝 Trust Engine | eliza](#-trust-engine-eliza) - [πŸ“ˆ Autonomous Trading | eliza](#-autonomous-trading-eliza) - [Page Not Found | eliza](#page-not-found-eliza) - [Page Not Found | eliza](#page-not-found-eliza) - [πŸ«– Eliza in TEE | eliza](#-eliza-in-tee-eliza) - [Page Not Found | eliza](#page-not-found-eliza) - [πŸͺͺ Verified Inference | eliza](#-verified-inference-eliza) - [Page Not Found | eliza](#page-not-found-eliza) - [Fact Evaluator: Memory Formation System | eliza](#fact-evaluator-memory-formation-system-eliza) - [Page Not Found | eliza](#page-not-found-eliza) - [Page Not Found | eliza](#page-not-found-eliza) - [Page Not Found | eliza](#page-not-found-eliza) - [Page Not Found | eliza](#page-not-found-eliza) - [Page Not Found | eliza](#page-not-found-eliza) - [Page Not Found | eliza](#page-not-found-eliza) - [Page Not Found | eliza](#page-not-found-eliza) --- # Introduction to Eliza | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page ![](/eliza/assets/images/eliza_banner-ab8921c786c75d3716bd237159da3bdc.jpg) _As seen powering [@DegenSpartanAI](https://x.com/degenspartanai) and [@aixvc\_agent](https://x.com/aixvc_agent) _ What is Eliza?[​](#what-is-eliza "Direct link to What is Eliza?") ------------------------------------------------------------------ Eliza is a powerful multi-agent simulation framework designed to create, deploy, and manage autonomous AI agents. Built with TypeScript, it provides a flexible and extensible platform for developing intelligent agents that can interact across multiple platforms while maintaining consistent personalities and knowledge. * [Technical Report (Whitepaper)](https://arxiv.org/pdf/2501.06781) * [Examples (Awesome Eliza)](https://github.com/thejoven/awesome-eliza) Key Features[​](#key-features "Direct link to Key Features") ------------------------------------------------------------- * **Platform Integration**: Clients for Discord, X (Twitter), Telegram, and many others * **Flexible Model Support**: Deepseek, Ollama, Grok, OpenAI, Anthropic, Gemini, LLama, etc. * **Character System**: Create diverse agents using [characterfiles](https://github.com/elizaOS/characterfile) * **Multi-Agent Architecture**: Manage multiple unique AI personalities simultaneously * **Memory Management**: Easily ingest and interact with documents using RAG * **Media Processing**: PDF, URLs, Audio transcription, Video processing, Image analysis, Conversation summarization * **Technical Foundation**: * 100% TypeScript implementation * Modular architecture * Highly extensible action and plugin system * Custom client support * Comprehensive API Use Cases[​](#use-cases "Direct link to Use Cases") ---------------------------------------------------- Eliza can be used to create: * **AI Assistants**: Customer support agents, Community moderators, Personal assistants * **Social Media Personas**: Automated content creators, Brand representatives, Influencers * **Knowledge Workers**: Research assistants, Content analysts, Document processors * **Interactive Characters**: Role-playing characters, Educational tutors, Entertainment bots Architecture[​](#architecture "Direct link to Architecture") ------------------------------------------------------------- ![](/eliza/assets/images/eliza-architecture-52934d28c13a41bc53a2b0c7e7b88a77.jpg) Source: [https://x.com/0xCygaar/status/1874575841763770492](https://x.com/0xCygaar/status/1874575841763770492) The characterfile contains everything about the agent's personality, backstory, knowledge, and topics to talk about, as well as which clients / models / and plugins to load. The database is where an agent stores relevant info for generating responses, including previous tweets, interactions, and embeddings. Without a db, agent's wouldn't be able to give good responses. Then we have the "runtime", which you can think of as the core agent logic. It's effectively the coordination layer of the agent or the brain, calling the necessary modules and external services to generate responses and take actions. Within the runtime is the LLM, which processes various inputs and generates responses or action items for the agent to take. Devs can declare which LLM provider to use in the characterfile. The runtime also handles the registration of plugins, which are called when a user input asks it take an action, such as transferring ETH on Abstract or doing a web search. Eliza supports a variety of clients including `Discord`, `Twitter`, `Slack`, `Farcaster`, and others. The client is basically where the agent will live and interact with users. Agents can run on multiple clients at once. Clients can have modules to handle different interactions, such as responding to tweets, or even participating in Twitter spaces. * * * Getting Started[​](#getting-started "Direct link to Getting Started") ---------------------------------------------------------------------- For a more detailed guide, check out our [Quickstart Guide](/eliza/docs/quickstart) to begin your journey with Eliza. ### Prerequisites[​](#prerequisites "Direct link to Prerequisites") * [Python 2.7+](https://www.python.org/downloads/) * [Node.js 23+](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) * [pnpm](https://pnpm.io/installation) > **Note for Windows Users:** [WSL 2](https://learn.microsoft.com/en-us/windows/wsl/install-manual) > is required. The start script provides an automated way to set up and run Eliza: ### Automated Start[​](#automated-start "Direct link to Automated Start") git clone https://github.com/elizaos/eliza-starter.gitcd eliza-startercp .env.example .envpnpm i && pnpm build && pnpm start OR git clone https://github.com/elizaos/elizacd elizash scripts/start.sh For detailed instructions on using the start script, including character management and troubleshooting, see our [Quickstart Guide](/eliza/docs/quickstart) . > **Note**: The start script handles all dependencies, environment setup, and character management automatically. * * * Community and Support[​](#community-and-support "Direct link to Community and Support") ---------------------------------------------------------------------------------------- Eliza is backed by an active community of developers and users: * [**Open Source**](https://github.com/elizaos/eliza) : Contribute to the project on GitHub * [**Examples**](https://github.com/elizaos/characters) : Ready-to-use character templates and implementations * [**Support**](https://discord.gg/elizaos) : Active community for troubleshooting and discussion Join us in building the future of autonomous AI agents with Eliza! Next Steps[​](#next-steps "Direct link to Next Steps") ------------------------------------------------------- * [Create Your First Agent](/eliza/quickstart) * [Understand Core Concepts](/eliza/core/agents) * [What is Eliza?](#what-is-eliza) * [Key Features](#key-features) * [Use Cases](#use-cases) * [Architecture](#architecture) * [Getting Started](#getting-started) * [Prerequisites](#prerequisites) * [Automated Start](#automated-start) * [Community and Support](#community-and-support) * [Next Steps](#next-steps) --- # Frequently Asked Questions | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page ### What is Eliza?[​](#what-is-eliza "Direct link to What is Eliza?") Eliza is an open-source framework for building AI agents that can interact on platforms like Twitter, Discord, and Telegram. It was created by Shaw and is maintained by the community. ### What's the difference between v1 and v2?[​](#whats-the-difference-between-v1-and-v2 "Direct link to What's the difference between v1 and v2?") Note: It's recommended for devs to keep working with v1, v2 will be mostly backwards compatible **What's Wrong with V1:** 1. Cluttered: Too many packages directly in the core codebase 2. Message Handling: Isolated and limited message routing between platforms 3. Wallet Confusion: Separate wallets for different chains adds friction 4. Limited Planning: Limited action planning abilities **What's New in V2:** 1. Better Organization * New package registry system to submit packages without core code changes * More modular and maintainable architecture * CLI tool for package management 2. Smarter Communication * Agents can more easily route messages across different platforms * Better support for autonomous actions 3. Simplified Wallet System * One unified wallet system (like a video game inventory) * Better at handling transactions across different blockchains * Each "inventory provider" can have its own unique actions 4. Character Improvements * Characters can now evolve and learn over time * All character data stored in a database instead of static files * Can grow and change based on community interactions 5. Advanced Planning * Agents can now plan out a series of actions in advance * More strategic and autonomous behavior * * * Installation and Setup[​](#installation-and-setup "Direct link to Installation and Setup") ------------------------------------------------------------------------------------------- ### What are the system requirements for running Eliza?[​](#what-are-the-system-requirements-for-running-eliza "Direct link to What are the system requirements for running Eliza?") * Node.js version 23+ (specifically 23.3.0 is recommended) * pnpm package manager * At least 2GB RAM * For Windows users: WSL2 (Windows Subsystem for Linux) ### How do I get started with Eliza?[​](#how-do-i-get-started-with-eliza "Direct link to How do I get started with Eliza?") 1. Follow the [quick start guide](/eliza/docs/quickstart) in the README 2. Watch the AI Agent Dev School videos on YouTube for step-by-step guidance 3. Join the Discord community for support ### How do I fix common installation issues?[​](#how-do-i-fix-common-installation-issues "Direct link to How do I fix common installation issues?") If you encounter build failures or dependency errors: 1. Ensure you're using Node.js v23.3.0: `nvm install 23.3.0 && nvm use 23.3.0` 2. Clean your environment: `pnpm clean` 3. Install dependencies: `pnpm install --no-frozen-lockfile` 4. Rebuild: `pnpm build` 5. If issues persist, try checking out the latest release: git checkout $(git describe --tags --abbrev=0) ### How do I use local models with Eliza?[​](#how-do-i-use-local-models-with-eliza "Direct link to How do I use local models with Eliza?") Use **Ollama** for local models. Install Ollama, download the desired model (e.g., `llama3.1`), set `modelProvider` to `"ollama"` in the character file, and configure `OLLAMA` settings in `.env`. ### How do I update Eliza to the latest version?[​](#how-do-i-update-eliza-to-the-latest-version "Direct link to How do I update Eliza to the latest version?") 1. Pull the latest changes 2. Clean your environment: `pnpm clean` 3. Reinstall dependencies: `pnpm install --no-frozen-lockfile` 4. Rebuild: `pnpm build` * * * Running Multiple Agents[​](#running-multiple-agents "Direct link to Running Multiple Agents") ---------------------------------------------------------------------------------------------- ### How do I run multiple agents simultaneously?[​](#how-do-i-run-multiple-agents-simultaneously "Direct link to How do I run multiple agents simultaneously?") You have several options: 1. Use the command line: pnpm start --characters="characters/agent1.json,characters/agent2.json" 2. Create separate projects for each agent with their own configurations 3. For production, use separate Docker containers for each agent ### Can I run multiple agents on one machine?[​](#can-i-run-multiple-agents-on-one-machine "Direct link to Can I run multiple agents on one machine?") Yes, but consider: * Each agent needs its own port configuration * Separate the .env files or use character-specific secrets * Monitor memory usage (2-4GB RAM per agent recommended) * * * Twitter/X Integration[​](#twitterx-integration "Direct link to Twitter/X Integration") --------------------------------------------------------------------------------------- ### How do I prevent my agent from spamming or posting duplicates?[​](#how-do-i-prevent-my-agent-from-spamming-or-posting-duplicates "Direct link to How do I prevent my agent from spamming or posting duplicates?") Configure your .env file: ENABLE_ACTION_PROCESSING=falsePOST_INTERVAL_MIN=900 # 15 minutes minimumPOST_INTERVAL_MAX=1200 # 20 minutes maximumTWITTER_DRY_RUN=true # Test mode ### How do I control which tweets my agent responds to?[​](#how-do-i-control-which-tweets-my-agent-responds-to "Direct link to How do I control which tweets my agent responds to?") 1. Configure target users in .env: TWITTER_TARGET_USERS="user1,user2,user3" 2. Control specific actions: TWITTER_LIKES_ENABLE=falseTWITTER_RETWEETS_ENABLE=falseTWITTER_REPLY_ENABLE=trueTWITTER_FOLLOW_ENABLE=false ### How do I fix Twitter authentication issues?[​](#how-do-i-fix-twitter-authentication-issues "Direct link to How do I fix Twitter authentication issues?") 1. Mark your account as "Automated" in Twitter settings 2. Ensure proper credentials in .env file 3. Consider using a residential IP or VPN as Twitter may block cloud IPs 4. Set up proper rate limiting to avoid suspensions ### How do I prevent unwanted Twitter interactions?[​](#how-do-i-prevent-unwanted-twitter-interactions "Direct link to How do I prevent unwanted Twitter interactions?") To better control what tweets your agent responds to, configure `TWITTER_TARGET_USERS` in `.env` and set specific action flags like `TWITTER_LIKES_ENABLE=false` to control interaction types. ### How do I troubleshoot Twitter authentication issues?[​](#how-do-i-troubleshoot-twitter-authentication-issues "Direct link to How do I troubleshoot Twitter authentication issues?") Ensure correct credentials in `.env`, mark account as "Automated" in Twitter settings, and consider using a residential IP to avoid blocks. ### How do I make my agent respond to Twitter replies?[​](#how-do-i-make-my-agent-respond-to-twitter-replies "Direct link to How do I make my agent respond to Twitter replies?") Set `ENABLE_ACTION_PROCESSING=true` and configure `TWITTER_POLL_INTERVAL`. Target specific users for guaranteed responses. ### How do I avoid Twitter bot suspensions?[​](#how-do-i-avoid-twitter-bot-suspensions "Direct link to How do I avoid Twitter bot suspensions?") * Mark account as automated in Twitter settings * Space out posts (15-20 minutes between interactions) * Avoid using proxies ### How do I fix Twitter authentication issues?[​](#how-do-i-fix-twitter-authentication-issues-1 "Direct link to How do I fix Twitter authentication issues?") * Ensure correct credentials in .env file * Use valid TWITTER\_COOKIES format * Turn on "Automated" in Twitter profile settings * * * Model Configuration[​](#model-configuration "Direct link to Model Configuration") ---------------------------------------------------------------------------------- ### How do I switch between different AI models?[​](#how-do-i-switch-between-different-ai-models "Direct link to How do I switch between different AI models?") In your character.json file: { "modelProvider": "openai", // or "anthropic", "deepseek", etc. "settings": { "model": "gpt-4", "maxInputTokens": 200000, "maxOutputTokens": 8192 }} ### How do I manage API keys and secrets?[​](#how-do-i-manage-api-keys-and-secrets "Direct link to How do I manage API keys and secrets?") Two options: 1. Global .env file for shared settings 2. Character-specific secrets in character.json: { "settings": { "secrets": { "OPENAI_API_KEY": "your-key-here" } }} * * * Memory and Knowledge Management[​](#memory-and-knowledge-management "Direct link to Memory and Knowledge Management") ---------------------------------------------------------------------------------------------------------------------- ### How does memory management work in ElizaOS?[​](#how-does-memory-management-work-in-elizaos "Direct link to How does memory management work in ElizaOS?") ElizaOS uses RAG (Retrieval-Augmented Generation) to convert prompts into vector embeddings for efficient context retrieval and memory storage. ### How do I fix "Cannot generate embedding: Memory content is empty"?[​](#how-do-i-fix-cannot-generate-embedding-memory-content-is-empty "Direct link to How do I fix "Cannot generate embedding: Memory content is empty"?") Check your database for null memory entries and ensure proper content formatting when storing new memories. ### How do I manage my agent's memory?[​](#how-do-i-manage-my-agents-memory "Direct link to How do I manage my agent's memory?") * To reset memory: Delete the db.sqlite file and restart * To add documents: Specify path to file / folder in the characterfile * For large datasets: Consider using a vector database ### How much does it cost to run an agent?[​](#how-much-does-it-cost-to-run-an-agent "Direct link to How much does it cost to run an agent?") * OpenAI API: Approximately 500 simple replies for $1 * Server hosting: $5-20/month depending on provider * Optional: Twitter API costs if using premium features * Local deployment can reduce costs but requires 24/7 uptime ### How do I clear or reset my agent's memory?[​](#how-do-i-clear-or-reset-my-agents-memory "Direct link to How do I clear or reset my agent's memory?") 1. Delete the db.sqlite file in the agent/data directory 2. Restart your agent 3. Alternatively, use `pnpm cleanstart` ### How do I add custom knowledge or use RAG with my agent?[​](#how-do-i-add-custom-knowledge-or-use-rag-with-my-agent "Direct link to How do I add custom knowledge or use RAG with my agent?") 1. Convert documents to txt/md format 2. Use the [folder2knowledge](https://github.com/elizaOS/characterfile/tree/main/scripts) tool 3. Add to the knowledge section in your character file, [see docs](/eliza/docs/core/characterfile) via `"ragKnowledge": true` * * * Plugins and Extensions[​](#plugins-and-extensions "Direct link to Plugins and Extensions") ------------------------------------------------------------------------------------------- ### How do I add plugins to my agent?[​](#how-do-i-add-plugins-to-my-agent "Direct link to How do I add plugins to my agent?") 1. Add the plugin to your character.json: { "plugins": ["@elizaos/plugin-name"]} 2. Install the plugin: `pnpm install @elizaos/plugin-name` 3. Rebuild: `pnpm build` 4. Configure any required plugin settings in .env or character file ### How do I create custom plugins?[​](#how-do-i-create-custom-plugins "Direct link to How do I create custom plugins?") 1. Create a new directory in packages/plugins 2. Implement required interfaces (actions, providers, evaluators) 3. Add to your character's plugins array 4. Test locally before deployment * * * Production Deployment[​](#production-deployment "Direct link to Production Deployment") ---------------------------------------------------------------------------------------- ### What's the recommended way to deploy Eliza?[​](#whats-the-recommended-way-to-deploy-eliza "Direct link to What's the recommended way to deploy Eliza?") 1. Use a VPS or cloud provider (DigitalOcean, AWS, Hetzner) 2. Requirements: * Minimum 2GB RAM * 20GB storage * Ubuntu or Debian recommended 3. Use PM2 or Docker for process management 4. Consider using residential IPs for Twitter bots ### How do I ensure my agent runs continuously?[​](#how-do-i-ensure-my-agent-runs-continuously "Direct link to How do I ensure my agent runs continuously?") 1. Use a process manager like PM2: npm install -g pm2pm2 start "pnpm start" --name elizapm2 save 2. Set up monitoring and automatic restarts 3. Use proper error handling and logging * * * Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ---------------------------------------------------------------------- ### How do I fix database connection issues?[​](#how-do-i-fix-database-connection-issues "Direct link to How do I fix database connection issues?") 1. For SQLite: * Delete db.sqlite and restart * Check file permissions 2. For PostgreSQL: * Verify connection string * Check database exists * Ensure proper credentials ### How do I debug when my agent isn't responding?[​](#how-do-i-debug-when-my-agent-isnt-responding "Direct link to How do I debug when my agent isn't responding?") 1. Enable debug logging in .env: DEBUG=eliza:* 2. Check the database for saved messages 3. Verify API keys and model provider status 4. Check client-specific settings (Twitter, Discord, etc.) ### How do I resolve embedding dimension mismatch errors?[​](#how-do-i-resolve-embedding-dimension-mismatch-errors "Direct link to How do I resolve embedding dimension mismatch errors?") 1. Set `USE_OPENAI_EMBEDDING=true` in .env 2. Delete db.sqlite to reset embeddings 3. Ensure consistent embedding models across your setup ### Why does my agent post in JSON format sometimes?[​](#why-does-my-agent-post-in-json-format-sometimes "Direct link to Why does my agent post in JSON format sometimes?") This usually happens due to incorrect output formatting or template issues. Check your character file's templates and ensure the text formatting is correct without raw JSON objects. ### How do I make my agent only respond to mentions?[​](#how-do-i-make-my-agent-only-respond-to-mentions "Direct link to How do I make my agent only respond to mentions?") Add a mention filter to your character's configuration and set `ENABLE_ACTION_PROCESSING=false` in your .env file. * * * How can I contribute?[​](#how-can-i-contribute "Direct link to How can I contribute?") --------------------------------------------------------------------------------------- Eliza welcomes contributions from individuals with a wide range of skills: * **Participate in community discussions**: Share your memecoin insights, propose new ideas, and engage with other community members. * **Contribute to the development of the Eliza platform**: [https://github.com/elizaOS/eliza](https://github.com/elizaOS/eliza) * **Help build the Eliza ecosystem**: Create applications / tools, resources, and memes. Give feedback, and spread the word #### Technical Contributions[​](#technical-contributions "Direct link to Technical Contributions") * **Develop new actions, clients, providers, and evaluators**: Extend Eliza's functionality by creating new modules or enhancing existing ones. * **Contribute to database management**: Improve or expand Eliza's database capabilities using PostgreSQL, SQLite, or SQL.js. * **Enhance local development workflows**: Improve documentation and tools for local development using SQLite and VS Code. * **Fine-tune models**: Optimize existing models or implement new models for specific tasks and personalities. * **Contribute to the autonomous trading system and trust engine**: Leverage expertise in market analysis, technical analysis, and risk management to enhance these features. #### Non-Technical Contributions[​](#non-technical-contributions "Direct link to Non-Technical Contributions") * **Community Management**: Onboard new members, organize events, moderate discussions, and foster a welcoming community. * **Content Creation**: Create memes, tutorials, documentation, and videos to share project updates. * **Translation**: Translate documentation and other materials to make Eliza accessible to a global audience. * **Domain Expertise**: Provide insights and feedback on specific applications of Eliza in various fields. * [What is Eliza?](#what-is-eliza) * [What's the difference between v1 and v2?](#whats-the-difference-between-v1-and-v2) * [Installation and Setup](#installation-and-setup) * [What are the system requirements for running Eliza?](#what-are-the-system-requirements-for-running-eliza) * [How do I get started with Eliza?](#how-do-i-get-started-with-eliza) * [How do I fix common installation issues?](#how-do-i-fix-common-installation-issues) * [How do I use local models with Eliza?](#how-do-i-use-local-models-with-eliza) * [How do I update Eliza to the latest version?](#how-do-i-update-eliza-to-the-latest-version) * [Running Multiple Agents](#running-multiple-agents) * [How do I run multiple agents simultaneously?](#how-do-i-run-multiple-agents-simultaneously) * [Can I run multiple agents on one machine?](#can-i-run-multiple-agents-on-one-machine) * [Twitter/X Integration](#twitterx-integration) * [How do I prevent my agent from spamming or posting duplicates?](#how-do-i-prevent-my-agent-from-spamming-or-posting-duplicates) * [How do I control which tweets my agent responds to?](#how-do-i-control-which-tweets-my-agent-responds-to) * [How do I fix Twitter authentication issues?](#how-do-i-fix-twitter-authentication-issues) * [How do I prevent unwanted Twitter interactions?](#how-do-i-prevent-unwanted-twitter-interactions) * [How do I troubleshoot Twitter authentication issues?](#how-do-i-troubleshoot-twitter-authentication-issues) * [How do I make my agent respond to Twitter replies?](#how-do-i-make-my-agent-respond-to-twitter-replies) * [How do I avoid Twitter bot suspensions?](#how-do-i-avoid-twitter-bot-suspensions) * [How do I fix Twitter authentication issues?](#how-do-i-fix-twitter-authentication-issues-1) * [Model Configuration](#model-configuration) * [How do I switch between different AI models?](#how-do-i-switch-between-different-ai-models) * [How do I manage API keys and secrets?](#how-do-i-manage-api-keys-and-secrets) * [Memory and Knowledge Management](#memory-and-knowledge-management) * [How does memory management work in ElizaOS?](#how-does-memory-management-work-in-elizaos) * [How do I fix "Cannot generate embedding: Memory content is empty"?](#how-do-i-fix-cannot-generate-embedding-memory-content-is-empty) * [How do I manage my agent's memory?](#how-do-i-manage-my-agents-memory) * [How much does it cost to run an agent?](#how-much-does-it-cost-to-run-an-agent) * [How do I clear or reset my agent's memory?](#how-do-i-clear-or-reset-my-agents-memory) * [How do I add custom knowledge or use RAG with my agent?](#how-do-i-add-custom-knowledge-or-use-rag-with-my-agent) * [Plugins and Extensions](#plugins-and-extensions) * [How do I add plugins to my agent?](#how-do-i-add-plugins-to-my-agent) * [How do I create custom plugins?](#how-do-i-create-custom-plugins) * [Production Deployment](#production-deployment) * [What's the recommended way to deploy Eliza?](#whats-the-recommended-way-to-deploy-eliza) * [How do I ensure my agent runs continuously?](#how-do-i-ensure-my-agent-runs-continuously) * [Troubleshooting](#troubleshooting) * [How do I fix database connection issues?](#how-do-i-fix-database-connection-issues) * [How do I debug when my agent isn't responding?](#how-do-i-debug-when-my-agent-isnt-responding) * [How do I resolve embedding dimension mismatch errors?](#how-do-i-resolve-embedding-dimension-mismatch-errors) * [Why does my agent post in JSON format sometimes?](#why-does-my-agent-post-in-json-format-sometimes) * [How do I make my agent only respond to mentions?](#how-do-i-make-my-agent-only-respond-to-mentions) * [How can I contribute?](#how-can-i-contribute) --- # Quickstart Guide | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page Prerequisites[​](#prerequisites "Direct link to Prerequisites") ---------------------------------------------------------------- Before getting started with Eliza, ensure you have: * [Node.js 23+](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) (using [nvm](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating) is recommended) * [pnpm 9+](https://pnpm.io/installation) * Git for version control * A code editor ([VS Code](https://code.visualstudio.com/) , [Cursor](https://cursor.com/) or [VSCodium](https://vscodium.com) recommended) * Python (mainly for installing NPM) * (Optional) FFmpeg (for audio/video handling) * (Optional) [CUDA Toolkit](https://developer.nvidia.com/cuda-toolkit) (for GPU acceleration) > On Windows? See here before continuing to make life easier: [WSL setup guide](/eliza/docs/guides/wsl) * * * Automated Installation[​](#automated-installation "Direct link to Automated Installation") ------------------------------------------------------------------------------------------- 1. Use [https://github.com/elizaOS/eliza-starter](https://github.com/elizaOS/eliza-starter) git clone git@github.com:elizaos/eliza-starter.gitcd eliza-startercp .env.example .envpnpm i && pnpm build && pnpm start 2. Use the [start script](https://howieduhzit.best/start-sh/) git clone git@github.com:elizaOS/eliza.gitcd eliza# usage start.sh [-v|--verbose] [--skip-nvm]./scripts/start.sh 3. Using Docker Prerequisites: * A Linux-based server (Ubuntu/Debian recommended) * Git installed * [Docker](https://docs.docker.com/get-started/get-docker/) git clone git@github.com:elizaOS/eliza.gitcd elizadocker-compose builddocker-compose up > Note: If you get permission issues run the docker-compose commands with sudo or add yourself to the docker group Troubleshooting #### Common Error[​](#common-error "Direct link to Common Error") - "characters not found": Check working directory- `./scripts/start.sh -v` Run with logging- Check console output- [Open an issue](https://github.com/elizaOS/eliza/issues) #### Permission Issues[​](#permission-issues "Direct link to Permission Issues") sudo chmod +x scripts/start.sh # Linux/macOSSet-ExecutionPolicy RemoteSigned -Scope CurrentUser # Windows #### Package Issues[​](#package-issues "Direct link to Package Issues") > Note: Always verify scripts before running it ## Linuxsudo apt update## MacOS/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"brew update## Windows# Run as admin #### Node.js Issues[​](#nodejs-issues "Direct link to Node.js Issues") * Ensure Node.js 23.3.0 is installed * Use `node -v` to check version * Consider using [nvm](https://github.com/nvm-sh/nvm) to manage Node versions * Use `--skip-nvm` for system Node * Check PATH configuration If you see Sharp-related errors, try this: pnpm install --include=optional sharp If you see errors about better-sqlite3, try `pnpm rebuild better-sqlite3` or go into `node_modules/better-sqlite3` and run `pnpm i` You can also add a postinstall script in your `package.json` if you want to automate this: scripts: { "postinstall": "npm rebuild better-sqlite3"} pnpm may be bundled with a different node version, ignoring nvm. If this is the case, try: pnpm env use --global 23.3.0 #### Docker issues[​](#docker-issues "Direct link to Docker issues") Some tips on cleaning your working directory before rebuilding: * List all docker images: `sudo docker images` * Reomove all Docker images: `docker rmi -f $(docker images -aq)` * Remove all build cache: `docker builder prune -a -f` * Verify cleanup: `docker system df` * * * Manual Installation[​](#manual-installation "Direct link to Manual Installation") ---------------------------------------------------------------------------------- After installing the prerequisites, clone the repository and enter the directory: git clone git@github.com:elizaOS/eliza.gitcd eliza tip If you're planning on doing development, we suggest using the code on the develop branch: git checkout develop From the main repo you can also download [sample character files](https://github.com/elizaos/characters) this way: git submodule update --init Install the dependencies pnpm install > **Note:** you may need to use --no-frozen-lockfile if it gives a message about the frozen lock file being out of date. Compile the typescript: pnpm build * * * Start the Agent[​](#start-the-agent "Direct link to Start the Agent") ---------------------------------------------------------------------- [Character files](/eliza/docs/core/characterfile) are where you can configure your agent's personality, lore, and capabilities via plugins. Inform eliza which character you want to run: pnpm start --character="characters/deep-thought.character.json" You can load multiple characters with a comma-separated list: pnpm start --characters="characters/deep-thought.character.json,characters/sbf.character.json" By default the agent will be accessible via the terminal and REST API. #### Chat Client[​](#chat-client "Direct link to Chat Client") If you're using the main [eliza repo](https://github.com/elizaos/eliza) and want to use the chat client, open a new terminal window and run the client's http server: pnpm start:client Once the client is running, you'll see a message like this: ➜ Local: http://localhost:5173/ Simply click the link or open your browser to `http://localhost:5173/`. You'll see the chat interface connect to the system, and you can begin interacting with your character. * * * Additional Configuration[​](#additional-configuration "Direct link to Additional Configuration") ------------------------------------------------------------------------------------------------- You can load plugins or additional client support with your character file to unlock more capabilities for your agent. ### Add Plugins and Clients[​](#add-plugins-and-clients "Direct link to Add Plugins and Clients") Here's how to import and register plugins in your character file: { "name": "Eliza", "clients": ["telegram"], // ... other config options "plugins": ["@elizaos/plugin-image"],} There are two ways to get a list of available plugins: 1. Web Interface Go [https://elizaos.github.io/registry/](https://elizaos.github.io/registry/) or the [Showcase](/eliza/showcase) and search for plugins 2. CLI Interface $ npx elizaos plugins list Here's a sample list of plugins you can check out! | plugin name | Description | | --- | --- | | [`@elizaos/plugin-llama`](https://github.com/elizaos-plugins/plugin-llama) | Run LLM models on your local machine | | [`@elizaos/client-twitter`](https://github.com/elizaos-plugins/client-twitter) | Twitter bot integration | | [`@elizaos/client-discord`](https://github.com/elizaos-plugins/client-discord) | Discord bot integration | | [`@elizaos/client-telegram`](https://github.com/elizaos-plugins/client-telegram) | Telegram integration | | [`@elizaos/plugin-image`](https://github.com/elizaos-plugins/plugin-image) | Image processing and analysis | | [`@elizaos/plugin-video`](https://github.com/elizaos-plugins/plugin-video) | Video processing capabilities | | [`@elizaos/plugin-browser`](https://github.com/elizaos-plugins/plugin-browser) | Web scraping capabilities | | [`@elizaos/plugin-pdf`](https://github.com/elizaos-plugins/plugin-pdf) | PDF processing | ### Configure Environment[​](#configure-environment "Direct link to Configure Environment") There are two ways to configure elizaOS ### Option 1: Default .env file[​](#option-1-default-env-file "Direct link to Option 1: Default .env file") Copying the `.example.env` file and editing is the simpler option especially if you plan to just host one agent: cp .env.example .envnano .env ### Option 2: Secrets in the character file[​](#option-2-secrets-in-the-character-file "Direct link to Option 2: Secrets in the character file") This option allows you finer grain control over which character uses what resources and is required if you want multiple agents but using different keys. For example: { "name": "eliza", // ... other config options "settings": { "secrets": { "DISCORD_APPLICATION_ID": "1234", "DISCORD_API_TOKEN": "xxxx", "OPENAI_API_KEY": "sk-proj-xxxxxxxxx-..." } } Watch the commas to make sure it's valid json! Here's a few more config tips: Discord Bot Setup 1. Create a new application at [Discord Developer Portal](https://discord.com/developers/applications) 2. Create a bot and get your token 3. Add bot to your server using OAuth2 URL generator 4. Set `DISCORD_API_TOKEN` and `DISCORD_APPLICATION_ID` in your `.env` Twitter Integration Add to your `.env`: TWITTER_USERNAME= # Account usernameTWITTER_PASSWORD= # Account passwordTWITTER_EMAIL= # Account emailTWITTER_2FA_SECRET= # In order to avoid X preventing the login, it is better to activate 2fa in the target account, copy the 2fa secret and paste it here **Important:** Log in to the [Twitter Developer Portal](https://developer.twitter.com) and enable the "Automated" label for your account to avoid being flagged as inauthentic. Telegram Bot 1. Create a bot 2. Add your bot token to `.env`: TELEGRAM_BOT_TOKEN=your_token_here ### GPU Acceleration[​](#gpu-acceleration "Direct link to GPU Acceleration") If you have a Nvidia GPU you can enable CUDA support. First ensure CUDA Toolkit, cuDNN, and cuBLAS are first installed, then: `npx --no node-llama-cpp source download --gpu cuda` * * * FAQ[​](#faq "Direct link to FAQ") ---------------------------------- ### What's the difference between eliza and eliza-starter?[​](#whats-the-difference-between-eliza-and-eliza-starter "Direct link to What's the difference between eliza and eliza-starter?") Eliza-starter is a lightweight version for simpler setups, while the main eliza repository includes all advanced features and a web client. ### How do I fix build/installation issues?[​](#how-do-i-fix-buildinstallation-issues "Direct link to How do I fix build/installation issues?") Use Node v23.3.0, run `pnpm clean`, then `pnpm install --no-frozen-lockfile`, followed by `pnpm build`. If issues persist, checkout the latest stable tag. ### What are the minimum system requirements?[​](#what-are-the-minimum-system-requirements "Direct link to What are the minimum system requirements?") 8GB RAM recommended for build process. For deployment, a t2.large instance on AWS with 20GB storage running Ubuntu is the minimum tested configuration. ### How do I fix "Exit Status 1" errors?[​](#how-do-i-fix-exit-status-1-errors "Direct link to How do I fix "Exit Status 1" errors?") If you see `triggerUncaughtException` errors, try: 1. Add dependencies to workspace root 2. Add dependencies to specific packages 3. Clean and rebuild Next Steps[​](#next-steps "Direct link to Next Steps") ------------------------------------------------------- Once you have your agent running, explore: 1. πŸ€– [Understand Agents](/eliza/docs/core/agents) 2. πŸ“ [Create Custom Characters](/eliza/docs/core/characterfile) 3. ⚑ [Add Custom Actions](/eliza/docs/core/actions) 4. πŸ”§ [Advanced Configuration](/eliza/docs/guides/configuration) Join the [Discord community](https://discord.gg/elizaOS) for support and to share what you're building! * [Prerequisites](#prerequisites) * [Automated Installation](#automated-installation) * [Manual Installation](#manual-installation) * [Start the Agent](#start-the-agent) * [Additional Configuration](#additional-configuration) * [Add Plugins and Clients](#add-plugins-and-clients) * [Configure Environment](#configure-environment) * [Option 1: Default .env file](#option-1-default-env-file) * [Option 2: Secrets in the character file](#option-2-secrets-in-the-character-file) * [GPU Acceleration](#gpu-acceleration) * [FAQ](#faq) * [What's the difference between eliza and eliza-starter?](#whats-the-difference-between-eliza-and-eliza-starter) * [How do I fix build/installation issues?](#how-do-i-fix-buildinstallation-issues) * [What are the minimum system requirements?](#what-are-the-minimum-system-requirements) * [How do I fix "Exit Status 1" errors?](#how-do-i-fix-exit-status-1-errors) * [Next Steps](#next-steps) --- # AI Agent Dev School | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page Welcome to the AI Agent Dev School series, a comprehensive guide to building intelligent agents using the Eliza framework. Over the course of three in-depth sessions, we cover everything from the basics of TypeScript and plugins to advanced topics like providers, evaluators, and dynamic agent behaviors. [Part 1: Introduction and Foundations](/eliza/docs/tutorials/part1) [​](#part-1-introduction-and-foundations "Direct link to part-1-introduction-and-foundations") ------------------------------------------------------------------------------------------------------------------------------------------------------------------- In the first session, we start from the very beginning, assuming no prior knowledge of TypeScript, Git, or AI agent development. We cover: * Historical context and the evolution of JavaScript and TypeScript * Setting up your development environment * Key concepts in Eliza: embedding models, characters, and chat clients * Basics of working with Git and GitHub By the end of part 1, you'll have a solid foundation for diving into agent development with Eliza. [Part 2: Deep Dive into Actions, Providers, and Evaluators](/eliza/docs/tutorials/part2) [​](#part-2-deep-dive-into-actions-providers-and-evaluators "Direct link to part-2-deep-dive-into-actions-providers-and-evaluators") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ The second session focuses on the core building blocks of agent behavior in Eliza: * Actions: The tasks and responses that agents can perform * Providers: Modules that provide information and state to the agent's context * Evaluators: Modules that analyze situations and agent actions, triggering further actions or modifications We explore each of these in detail, walking through code examples and common use cases. We also cover how to package actions, providers and evaluators into reusable plugins. [Part 3: Building a User Data Extraction Agent](/eliza/docs/tutorials/part3) [​](#part-3-building-a-user-data-extraction-agent "Direct link to part-3-building-a-user-data-extraction-agent") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- In the final session, we apply the concepts from parts 1 and 2 to build a practical agentic application - a user data extraction flow. We cover: * The provider-evaluator loop for gathering information and triggering actions * Leveraging Eliza's cache manager for efficient storage * Using AI assistants to aid in code development * Testing and debugging agent flows * Adding dynamic behaviors based on completion state By the end of part 3, you'll have the skills to build sophisticated, stateful agents that can interact naturally with users to accomplish complex tasks. * [Part 1: Introduction and Foundations](#part-1-introduction-and-foundations) * [Part 2: Deep Dive into Actions, Providers, and Evaluators](#part-2-deep-dive-into-actions-providers-and-evaluators) * [Part 3: Building a User Data Extraction Agent](#part-3-building-a-user-data-extraction-agent) --- # Changelog | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page v0.25.8 (2025-02-24)[​](#v0258-2025-02-24 "Direct link to v0.25.8 (2025-02-24)") --------------------------------------------------------------------------------- #### Summary[​](#summary "Direct link to Summary") This release introduces significant architectural changes to plugin management, adds several new AI model providers, enhances RAG knowledge processing, and improves backend infrastructure. Key themes include modular plugin architecture, expanded AI model support, and improved knowledge handling. #### Plugin System Enhancements[​](#plugin-system-enhancements "Direct link to Plugin System Enhancements") * Dynamic plugin loading architecture implemented (PR #3339) * CLI utility for plugin listing and installation (PR #3429) * Modified NKN plugin configuration (PR #3570) #### AI Model Providers[​](#ai-model-providers "Direct link to AI Model Providers") * Added NEAR AI model provider (PR #3275) * Added Secret AI LLM support (PR #3615) * Enabled structured objects and image generation with NEAR AI (PR #3644) #### Knowledge Processing[​](#knowledge-processing "Direct link to Knowledge Processing") * Enhanced fact provider with relevant fact fetching capability (PR #2635) * Improved RAG function with optimized chunk & overlap parameters (PR #2525) * Fixed stringKnowledge storage in RAG knowledge system (PR #3435) * Removed LangChain dependency for text splitting (PR #3642) #### Infrastructure Updates[​](#infrastructure-updates "Direct link to Infrastructure Updates") * Added cachedir support to filesystem cache (PR #3291) * Set Lava as default RPC URL for NEAR and Starknet (PR #3323) * Fixed Bedrock inference functionality (PR #3553) #### Bug Fixes[​](#bug-fixes "Direct link to Bug Fixes") * Addressed security vulnerability GHSA-584q-6j8j-r5pm (PR #2958) * Fixed default character reference issues (PR #3345) * Fixed agent configuration via API (PR #3618) * Resolved image URL handling for outbound messages (PR #3122) * Fixed OpenAI and Vercel AI package integration (PR #3146) * Corrected attribute extraction from raw text (PR #3190) #### Technical Improvements[​](#technical-improvements "Direct link to Technical Improvements") * Replaced AgentRuntime with interface to extend client capabilities (PR #2388) * Implemented Turbo optimizations for build performance (PR #2503) * Updated pnpm version in Docker build (PR #3158) * Added various fixes for plugin compatibility and configuration #### Breaking Changes[​](#breaking-changes "Direct link to Breaking Changes") * Plugin architecture now uses dynamic loading instead of static imports * All plugins moved out of core codebase into separate packages * Changed dependency structure for plugin initialization #### Deprecated Features[​](#deprecated-features "Direct link to Deprecated Features") * Static plugin imports are no longer supported * Legacy verifiable inference concept removed (now plugin-based) This version represents a significant step toward a more modular, extensible architecture while adding support for additional AI models and improving the knowledge processing capabilities. #### Full Changelog[​](#full-changelog "Direct link to Full Changelog") [https://github.com/elizaOS/eliza/compare/v0.1.9...v0.25.8](https://github.com/elizaOS/eliza/compare/v0.1.9...v0.25.8) * * * v0.25.6-alpha.1 (2025-02-06)[​](#v0256-alpha1-2025-02-06 "Direct link to v0.25.6-alpha.1 (2025-02-06)") -------------------------------------------------------------------------------------------------------- #### Summary[​](#summary-1 "Direct link to Summary") This alpha release introduces versioning changes (year.week format), enhances social media integration capabilities, adds new blockchain plugins, and fixes various issues across multiple plugins. The release focuses on improving media handling for messaging platforms and expanding blockchain functionality. #### Major Features[​](#major-features "Direct link to Major Features") #### Social Media & Messaging[​](#social-media--messaging "Direct link to Social Media & Messaging") * Added image URL support for outbound tweets/messages (PR #3122) * Added configuration toggle for Twitter post generation (PR #3219) * New Spanish-speaking Trump sample character (PR #3119) * Action suppression capability for Twitter, Discord, and Telegram (PRs #3286, #3284, #3285) #### Blockchain Integrations[​](#blockchain-integrations "Direct link to Blockchain Integrations") * TON Plugin: Added NFT collection, item creation, metadata change and transfer functionality (PR #3211) * MultiversX Plugin: Added CREATE\_POOL action (PR #3209) * Added herotag support for MultiversX plugin (PR #3238) * Coingecko advanced features for various pools by network (PR #3170) #### New Plugins[​](#new-plugins "Direct link to New Plugins") * Added Edwin plugin (PR #3045) * Added Desk Exchange plugin (PR #3096) * Enhanced Quick-Intel plugin (PR #3208) #### Bug Fixes[​](#bug-fixes-1 "Direct link to Bug Fixes") * Fixed OpenAI and Vercel AI packages to resolve O1 errors (PR #3146) * Resolved duplicate plugins issue (PR #3126) * Updated provider-utils for better compatibility (PR #3189) * Improved attribute extraction from raw text (PR #3190) * Fixed "think" tag from Venice (PR #3203) * Enhanced Slack attachments handling (PR #3194) * Updated pnpm version in Docker build (PR #3158) * Removed duplicated dependencies (PR #3215) * Fixed DenyLoginSubtask functionality (PR #3278) * Implemented RAG optimizations for context handling (PR #3248) * Fixed Google API key handling (PR #3274) #### Developer Improvements[​](#developer-improvements "Direct link to Developer Improvements") * Added test configurations for multiple plugins (CoinGecko, Cronos, Conflux) * Fixed Docker and types issues (PR #3220) * Improved OpenAI-like provider endpoint resolution (PR #3281) * Enhanced JSON normalization process (PR #3301) * Fixed various unit tests for parsing and models (PRs #3311, #3312) * Added model configuration reading from character files (PR #3313) * Set package publishing access to public (PR #3330) #### Documentation Updates[​](#documentation-updates "Direct link to Documentation Updates") * Updated documentation for plugins (PR #3324) * Fixed broken links in contributing guide (PR #3269) * Added GitHub issues link to contribution guidelines (PR #3268) * Fixed various typos and improved consistency (PRs #3111, #3270, #3271) This alpha release introduces the new versioning scheme that uses year.week format (25.6) and prepares for significant architecture changes planned for the stable release. #### Full Changelog[​](#full-changelog-1 "Direct link to Full Changelog") [https://github.com/elizaOS/eliza/compare/v0.1.9...v0.25.6-alpha.1](https://github.com/elizaOS/eliza/compare/v0.1.9...v0.25.6-alpha.1) * * * v0.1.9 (2025-02-01)[​](#v019-2025-02-01 "Direct link to v0.1.9 (2025-02-01)") ------------------------------------------------------------------------------ #### Summary[​](#summary-2 "Direct link to Summary") This release significantly expands Eliza's client ecosystem, introduces numerous blockchain integrations, enhances AI model support, and improves platform stability. Major additions include Instagram, Telegram, and XMTP clients, Discord and Telegram autonomous agent enhancements, and support for multiple blockchain networks. #### Major Features[​](#major-features-1 "Direct link to Major Features") #### New Clients & Communication[​](#new-clients--communication "Direct link to New Clients & Communication") * Instagram client implementation (PR #1964) * Telegram account client (PR #2839) * XMTP client for decentralized messaging (PR #2786) * Twitter media post capabilities (PR #2818) * Discord autonomous agent enhancement (PR #2335) * Telegram autonomous agent enhancement (PR #2338) * Direct Client API with agent deletion functionality (PR #2267) #### AI & LLM Integrations[​](#ai--llm-integrations "Direct link to AI & LLM Integrations") * NVIDIA inference support (PR #2512) * Livepeer LLM provider integration (PR #2154) * Amazon Bedrock as LLM provider (PR #2769) * Added Birdeye plugin for market data (PR #1417) #### Blockchain Integrations[​](#blockchain-integrations-1 "Direct link to Blockchain Integrations") * Solana improvements: flawless transfers (PR #2340), Agent Kit features (PR #2458) * EVM ecosystem: OZ governance (PR #1710), ETH storage (PR #2737), cross-chain swaps via Squid Router (PR #1482) * Added support for multiple chains: Gravity (PR #2228), Cronos (PR #2585), BNB (PR #2278) * Sui updates: Aggregator swap for tokens (PR #3012), secp256k1/secp256r1 algorithm support (PR #2476) * Cosmos: IBC transfer (PR #2358) and IBC swap functionality (PR #2554) * Injective plugin implementation (PR #1764) * Added Mina blockchain support (PR #2702) * CoinGecko price per address functionality (PR #2262) * Dex Screener plugin with price actions (PR #1865) and trending features (PR #2325) #### Critical Bug Fixes[​](#critical-bug-fixes "Direct link to Critical Bug Fixes") * DeepSeek API key configuration issue (PR #2186) * Windows path resolution in pnpm build client (PR #2240) * IME multiple messages on Enter issue (PR #2274) * Fixed key derivation and remote attestation (PR #2303) * Prevented app crash with undefined REMOTE\_CHARACTER\_URLS (PR #2384) * Resolved AI-SDK provider version conflicts (PR #2714) * Fixed Ethers/viem issue in Mind Network plugin (PR #2783) * Message ID collision in Telegram Client (PR #3053) * Fixed image vision model provider application (PR #3056) * Improved unsupported image provider handling (PR #3057) * Resolved JSON parsing error with array values (PR #3113) #### Client Improvements[​](#client-improvements "Direct link to Client Improvements") * Tweet ID parameter correction (PR #2430) * Twitter bot replies metadata handling (PR #2712) * Home timeline name parsing fix (PR #2789) * Topics formatting bug resolution (PR #2951) * Auto-scrolling improvements (PR #3115) * Action tweet reply functionality (PR #2966) #### Infrastructure Enhancements[​](#infrastructure-enhancements "Direct link to Infrastructure Enhancements") * Docker build command optimization (PR #3110) * Service startup optimization (PR #3007) * Sqlite error with zero-length vectors (PR #1984) * RAG knowledge handling with Postgres (PR #2153) * OpenAI embedding issue resolution (PR #3003) This release represents a major expansion of Eliza's capabilities across multiple platforms and blockchain networks, with significant improvements to agent autonomy and stability. #### Full Changelog[​](#full-changelog-2 "Direct link to Full Changelog") [https://github.com/elizaOS/eliza/compare/v0.1.8-alpha.1...v0.1.9](https://github.com/elizaOS/eliza/compare/v0.1.8-alpha.1...v0.1.9) * * * v0.1.8+build.1 (2025-01-12)[​](#v018build1-2025-01-12 "Direct link to v0.1.8+build.1 (2025-01-12)") ---------------------------------------------------------------------------------------------------- #### Summary[​](#summary-3 "Direct link to Summary") This is a minor update to v0.1.8 focusing on critical fixes for security, Docker builds, and specific module issues. It addresses file upload security, PostgreSQL migration problems, and Twitter client functionality. #### Key Fixes[​](#key-fixes "Direct link to Key Fixes") * Fixed Docker image build process * Updated version numbering for proper npm publication as v0.1.8 * Implemented security improvements for file uploads (PR #1806) * Fixed Twitter client mention deduplication (PR #2185) * Resolved PostgreSQL adapter migration extension creation issue (PR #2188) * Added missing LETZAI model support (PR #2187) #### Documentation[​](#documentation "Direct link to Documentation") * Added Persian README file (PR #2182) This build release provides essential fixes that improve security and stability without introducing new features. * * * v0.1.8-alpha.1 (2025-01-01)[​](#v018-alpha1-2025-01-01 "Direct link to v0.1.8-alpha.1 (2025-01-01)") ----------------------------------------------------------------------------------------------------- #### Summary[​](#summary-4 "Direct link to Summary") This minor alpha release contains blockchain sector diagram updates and plugin description corrections. #### Changes[​](#changes "Direct link to Changes") * Added 0G to blockchain sector diagram (PR #2204) * Fixed SentientAI description in plugin-depin (PR #2668) #### Full Changelog[​](#full-changelog-3 "Direct link to Full Changelog") [https://github.com/elizaOS/eliza/compare/v0.1.8...v0.1.8+build.1](https://github.com/elizaOS/eliza/compare/v0.1.8...v0.1.8+build.1) * * * Version 0.1.8 (2025-01-12)[​](#version-018-2025-01-12 "Direct link to Version 0.1.8 (2025-01-12)") --------------------------------------------------------------------------------------------------- #### Major Features[​](#major-features-2 "Direct link to Major Features") * **TTS (Text2Speech)**: Added support for over 15 languages (#2110) * **AI Providers**: * Added Cloudflare AI Gateway support (#821) * Integrated Mistral AI as a new model provider (#2137) * Added DeepSeek AI provider (#2067) * Added Heurist embedding model (#2093) * **Infrastructure**: * Added support for TEE logging and Intel SGX (#1470) * Implemented Pro API support with trending coins API (#2068) * **Blockchain Plugins**: * Added Irys plugin (#1708) * Added Akash Network plugin with autonomous deployment capabilities (#2111) * Added Lens Network Plugin (#2101) * Added Hyperliquid plugin (#2141) * Added Asterai plugin (#2045) * Added Massa plugin (#1582) * Added Quai integration (#2083) * Implemented Primus zkTLS plugin to verify agent activities (#2086) * Modified Solana transactions to be more lenient (wait for confirmed instead of finalized) (#2053) #### Bug Fixes[​](#bug-fixes-2 "Direct link to Bug Fixes") * Fixed plugin loading from character.json files (#2095) * Prevented repeated login by reusing client-twitter session (#2129) * Fixed chat getting stuck in infinite loop (#1755) * Fixed client-discord join voice action (#2160) * Replaced invalid together.ai medium model (#2173) * Fixed missing langdetect in plugin-tts package.json (#2175) * Fixed model settings for images and removed duplicate files (#2118) * Fixed clientConfig.telegram.isPartOfTeam type (#2103) * Fixed starknet plugin by replacing walletProvider with portfolio provider (#2029) * Corrected SUI/USD price calculation (#2150) * Fixed DeepSeek support in getTokenForProvider (#2179) * Updated Supabase components (#2100) * Fixed RAG knowledge for Postgres (#2153) * Fixed case-sensitive column reference in knowledge table CHECK constraint (#2058) #### Technical Improvements[​](#technical-improvements-1 "Direct link to Technical Improvements") * Applied syntax fixes for autonome plugin and updated lock file (#2131) * Fixed lens export name and duplicate imports (#2142) * Fixed double responses from Continue Action (#1606) * Fixed double spaced tweets in Post.ts (#1626) * Added ability to select transcription provider based on character settings (#1625) * Fixed image description service (#1667) * Separated imageModelProvider and imageVisionModelProvider for ImageDescriptionServices (#1664) * Updated Supabase schema.sql (#1660) * Fixed Twitter image link issues (#1671) #### Full Changelog[​](#full-changelog-4 "Direct link to Full Changelog") [https://github.com/elizaOS/eliza/compare/v0.1.7...v0.1.8](https://github.com/elizaOS/eliza/compare/v0.1.7...v0.1.8) * * * Version 0.1.7 (2025-01-04)[​](#version-017-2025-01-04 "Direct link to Version 0.1.7 (2025-01-04)") --------------------------------------------------------------------------------------------------- #### New Features[​](#new-features "Direct link to New Features") * **UI/UX**: * Added text to 3D function (#1446) * Added custom system prompt support for image generation (#839) * Added /:agentId/speak endpoint for text-to-speech (#1528) * Added Livepeer Image Provider (#1525) * Added autoscroll chat client (#1538) * Added theme toggle with dark/light mode support (#1555) * **Plugins and Integration**: * Added Abstract plugin (#1225) * Added Avalanche plugin (#842) * Added Cronos ZKEVM plugin (#1464) * Added GitBook Plugin provider (#1126) * Added Venice style presets & watermark removal option (#1410) * Added FerePro plugin (#1502) * Added Fuel plugin (#1512) * **Development**: * Added ModelConfiguration to Character for temperature/response control (#1455) * Added support for custom OpenAI API endpoint via OPENAI\_API\_URL (#1522) * Added client-github retry functionality (#1425) * Added dynamic watch paths for agent development (#931) * Added Redis Cache Implementation (#1279, #1295) #### Client Improvements[​](#client-improvements-1 "Direct link to Client Improvements") * **Twitter**: * Enhanced Twitter client with cookie validation and retry (#856) * Improved Tweet handling for long content (#1339, #1520) * Enhanced Twitter Post Action Implementation (#1422) * Improved Twitter client dry run mode and configuration (#1498) * Fixed Twitter engagement criteria in prompt (#1533) * **Discord/Telegram**: * Added Discord Team features (#1032) * Added Telegram Team features (#1033) * Added parse mode=Markdown for Telegram output (#1229) * Fixed multiple Discord bots joining voice channels (#1156) #### Bug Fixes[​](#bug-fixes-3 "Direct link to Bug Fixes") * Fixed multiple agents running on localhost simultaneously (#1415) * Fixed image model provider API key selection fallback (#1272) * Fixed empty tags in templates/examples passed to LLM (#1305) * Fixed postgres adapter settings not being applied (#1379) * Fixed swap and bridge actions in plugin-evm (#1456) * Fixed Twitter search feature (#1433) * Fixed duplicate twitter posts (#1472) * Fixed client type identification with test coverage (#1490) * Fixed Twitter username validation to allow numbers (#1541) #### Technical Improvements[​](#technical-improvements-2 "Direct link to Technical Improvements") * Improved TypeScript configuration with incremental option (#1485) * Improved chat formatting for line breaks (#1483) * Extended parseBooleanFromText function with additional values (#1501) * Made express payload limit configurable (#1245) * Made Twitter login retry attempts configurable (#1244) * Added callback to the runtime evaluate method (#938) * Synced UI Client with server port env (#1239) #### Full Changelog[​](#full-changelog-5 "Direct link to Full Changelog") [https://github.com/elizaOS/eliza/compare/v0.1.6...v0.1.7](https://github.com/elizaOS/eliza/compare/v0.1.6...v0.1.7) * * * Version 0.1.7-alpha.2 (2024-12-28)[​](#version-017-alpha2-2024-12-28 "Direct link to Version 0.1.7-alpha.2 (2024-12-28)") -------------------------------------------------------------------------------------------------------------------------- #### New Components[​](#new-components "Direct link to New Components") * Added a new default character (#1453) * Added Text to 3D function (#1446) * Added /:agentId/speak endpoint for text-to-speech functionality (#1528) * Added Livepeer Image Provider for image generation (#1525) * Added support for Custom System Prompts in plugin-image-generation (#839) #### Content Handling[​](#content-handling "Direct link to Content Handling") * Improved handling of long tweets (#1339, #1520) * Enhanced Twitter Post Action Implementation (#1422) * Added image features to react chat client (#1481) * Improved chat formatting for line breaks (#1483) #### Plugins[​](#plugins "Direct link to Plugins") * Added GitBook Plugin provider (#1126) * Added Abstract plugin (#1225) * Added Avalanche plugin (#842) * Added FerePro plugin (#1502) * Added Cronos ZKEVM plugin (#1464) * Added Fuel plugin (#1512) * Added Venice style presets with option to remove watermark (#1410) * Added AlienX chain to plugin-evm (#1438) #### Client Improvements[​](#client-improvements-2 "Direct link to Client Improvements") * Enhanced client-github with retry capability (#1425) * Enhanced client-direct functionality (#1479) * Added client-discord chat\_with\_attachment action flexibility to use any tiktoken model (#1408) * Implemented timeline fetching for followed accounts in Twitter client (#1475) #### Technical Enhancements[​](#technical-enhancements "Direct link to Technical Enhancements") * Added ModelConfiguration to Character for adjusting temperature, response length & penalties (#1455) * Added support for custom OpenAI API endpoint via OPENAI\_API\_URL (#1522) * Extended parseBooleanFromText function with additional boolean values (#1501) * Added agentic JSDoc generation (#1343) * Added support for passing secrets through environment (#1454) #### Twitter Client[​](#twitter-client "Direct link to Twitter Client") * Fixed duplicate tweet log (#1402) * Fixed duplicate twitter post issues (#1472) * Fixed search feature in twitter client (#1433) * Improved Twitter client dry run mode and configuration logging (#1498) * Improved interaction prompts in the Twitter plugin (#1469) * Fixed client-twitter lowercase bug and environment cleanup (#1514) * Fixed ENABLE\_ACTION\_PROCESSING logic in Twitter client (#1463) * Fixed Twitter login notifications and cookie management (#1330) #### System Issues[​](#system-issues "Direct link to System Issues") * Fixed multiple agents running simultaneously on localhost (#1415) * Fixed postgres adapter settings not being applied (#1379) * Fixed imageModelProvider API key selection fallback (#1272) * Fixed empty tags in templates/examples when passed to LLM (#1305) * Fixed swap and bridge actions in plugin-evm (#1456) * Fixed incorrect link redirection issue (#1443) * Fixed code duplication in getGoals call (#1450) * Improved client type identification with test coverage (#1490) * Added required incremental option and fixed TypeScript configuration (#1485) * Fixed type imports from 'elizaos' (#1492) #### Documentation and Testing[​](#documentation-and-testing "Direct link to Documentation and Testing") * Added documentation for plugin-nft-generation (#1327) * Added readme files for ton plugin (#1496) and websearch plugin (#1494) * Added CODE\_OF\_CONDUCT.md (#1487) * Fixed documentation links in eliza-in-tee.md (#1500) * Added Cleanstart options for new database (#1449) #### Full Changelog[​](#full-changelog-6 "Direct link to Full Changelog") [https://github.com/elizaOS/eliza/compare/v0.1.7-alpha.1...v0.1.7-alpha.2](https://github.com/elizaOS/eliza/compare/v0.1.7-alpha.1...v0.1.7-alpha.2) * * * Version 0.1.7-alpha.1 (2024-12-22)[​](#version-017-alpha1-2024-12-22 "Direct link to Version 0.1.7-alpha.1 (2024-12-22)") -------------------------------------------------------------------------------------------------------------------------- #### Core Changes[​](#core-changes "Direct link to Core Changes") * **Package Structure**: Changed package name from `@elizaos/eliza` to `@elizaos/core` (#1357) * **Branding**: Introduced elizaOS branding and structure (#1352) * **Documentation**: Updated documentation links to point to [https://elizaOS.github.io/eliza/](https://elizaOS.github.io/eliza/) (#1353) #### Model Support[​](#model-support "Direct link to Model Support") * Added support for Google models (#1310) * Added OLLAMA model to the getTokenForProvider class (#1338) #### Client Improvements[​](#client-improvements-3 "Direct link to Client Improvements") * Bumped agent-twitter-client version to v0.0.17 (#1311) * Updated farcaster client max cast length (#1347) * Implemented MAX\_TWEET\_LENGTH setting for Twitter posts (#1323) * Removed TWITTER\_COOKIES environment variable (#1288) #### Technical Fixes[​](#technical-fixes "Direct link to Technical Fixes") * Fixed turbo configuration to resolve "cannot find package" error (#1307) * Set default value for cache store (#1308) * Added lint script for plugin-evm and fixed lint errors (#1171) * Fixed postgres adapter schema (#1345) * Removed token requirement for gaianet (#1306) #### Technical Notes[​](#technical-notes "Direct link to Technical Notes") This alpha release focuses primarily on structural changes to the codebase, renaming the core package, and fixing technical issues. It sets the groundwork for the more feature-rich alpha.2 release. #### Full Changelog[​](#full-changelog-7 "Direct link to Full Changelog") [https://github.com/elizaOS/eliza/compare/v0.1.6...v0.1.7-alpha.1](https://github.com/elizaOS/eliza/compare/v0.1.6...v0.1.7-alpha.1) * * * Version 0.1.6-alpha.5 (2024-12-21)[​](#version-016-alpha5-2024-12-21 "Direct link to Version 0.1.6-alpha.5 (2024-12-21)") -------------------------------------------------------------------------------------------------------------------------- #### Caching[​](#caching "Direct link to Caching") * **Redis Integration**: Added Redis Cache Implementation (#1279) * **Enhanced Caching**: Added general caching support for Redis (#1295) #### Platform Enhancements[​](#platform-enhancements "Direct link to Platform Enhancements") * Added parse mode=Markdown to enhance telegram bot output (#1229) * Made scripts dash compatible for better shell compatibility (#1165) * Made Twitter login retry times configurable via environment variables (#1244) * Made express payload limit configurable (#1245) * Upgraded Tavily API with comprehensive input and constrained token consumption (#1246) #### Discord & Telegram[​](#discord--telegram "Direct link to Discord & Telegram") * Fixed issue allowing multiple bots to join Discord voice channels (#1156) * Enabled Telegram bots to post messages with images generated by imageGenerationPlugin (#1220) #### Model & Provider Issues[​](#model--provider-issues "Direct link to Model & Provider Issues") * Fixed handling of unsupported model provider: claude\_vertex (#1258) * Added missing claude vertex case to handleProvider (#1293) * Fixed local\_llama key warning (#1250) #### Client & UI[​](#client--ui "Direct link to Client & UI") * Fixed client.push issue for Slack client verification (#1182) * Synced UI Client with server port environment variable (#1239) * Fixed ENABLE\_ACTION\_PROCESSING logic (#1268) * Improved Twitter post generation prompt (#1217) * Fixed issue where twitterShouldRespondTemplate fails when defined as a string in JSON Character Config (#1242) #### Database & Testing[​](#database--testing "Direct link to Database & Testing") * Fixed postgres requirement for user to exist before adding a participant (#1219) * Fixed CircuitBreaker.ts implementation (#1226) * Added integration tests fixes (#1177, #1291) * Fixed output checkable variable for conditional tests (#1294) #### Documentation & Internationalization[​](#documentation--internationalization "Direct link to Documentation & Internationalization") * Added German README (#1262) * Added Twitter automation label notice documentation (#1254) * Updated README for French, Spanish, and Italian languages (#1236) * Updated Chinese README with more details (#1196, #1201) #### Technical Improvements[​](#technical-improvements-3 "Direct link to Technical Improvements") * Fixed build and dependency issues * Improved error handling when token retrieval fails (#1214) * Added optional chaining on search to avoid startup errors when search is disabled (#1202) * Improved script output with clearer command instructions (#1163, #1218) * Fixed visibility issue for GitHub image CI/CD workflow (#1243) * Improved handling of summary files in caching (#1205) #### Full Changelog[​](#full-changelog-8 "Direct link to Full Changelog") [https://github.com/ai16z/eliza/compare/v0.1.6-alpha.4...v0.1.6-alpha.5](https://github.com/ai16z/eliza/compare/v0.1.6-alpha.4...v0.1.6-alpha.5) * * * Version 0.1.6 (2024-12-21)[​](#version-016-2024-12-21 "Direct link to Version 0.1.6 (2024-12-21)") --------------------------------------------------------------------------------------------------- #### Blockchain & Web3 Integration[​](#blockchain--web3-integration "Direct link to Blockchain & Web3 Integration") * **New Blockchain Plugins**: * Added Flow Blockchain plugin (#874) * Added Aptos plugin (#818) * Added MultiversX plugin (#860) * Added NEAR Protocol plugin (#847) * Added TON plugin (#1039) * Added ZKsync Era plugin (#906) * Added SUI plugin (#934) * Added TEE Mode to Solana Plugin (#835) * Enabled agents to create/buy/sell tokens on FOMO.fund's bonding curve in plugin-solana (#1135) * **Coinbase Integration**: * Added Coinbase ERC20, ERC721, ERC1155 token deployment/invocation (#803) * Implemented advanced Coinbase trading functionality (#725) * Added readContract/invokeContract functionality (#923) * Added webhook support and testing examples (#801) #### Social Media & Messaging[​](#social-media--messaging-1 "Direct link to Social Media & Messaging") * **Twitter/X Improvements**: * Enhanced X/Twitter login with cookie validation and retry mechanism (#856) * Improved Twitter client with action processing (#1007) * Fixed Twitter Search Logic (#994) * Implemented MAX\_TWEET\_LENGTH environment variable (#912) * Fixed issues with Twitter posts including newlines (#1070, #1141) * Allowed bots to post tweets with images from imageGenerationPlugin (#1040) * **New Clients**: * Added working Farcaster client with Neynar integration (#570, #914) * Added LinkedIn Client (#973) * Added Lens client (#1098) * Implemented Discord and Telegram Team features (#1032, #1033) #### AI & Model Support[​](#ai--model-support "Direct link to AI & Model Support") * **Model Providers**: * Added NanoGPT provider (#926) * Added Galadriel Image Model (#994) * Added Akash.network provider for free LLAMA API access (#1131) * Added Venice.ai API model provider (#1008) and image generation (#1057) * Added Hyperbolic API (#828) with environment variable overrides (#974) * Configured EternalAI model from environment variables (#927) * **Voice & Media**: * Improved voice processing and added Deepgram transcription option (#1026) * Added support for handlebars templating engine (#1136) * Added client-discord stop implementation (#1029) * Added NFT generation plugin for Solana collections (#1011) * Added plugin-story for narrative generation (#1030) #### System Improvements[​](#system-improvements "Direct link to System Improvements") * **Caching & Infrastructure**: * Implemented Redis Cache (#1279, #1295) * Added circuit breaker pattern for database operations (#812) * Added support for AWS S3 file uploads (#941) * Added dynamic watch paths for agent development (#931) * Fixed multiple bots joining Discord voice channels (#1156) * **API & Interface**: * Added REST API for client-direct to change agent settings (#1052) * Added custom fetch logic for agent (#1010) * Fixed Twitter posts with images generated by plugins (#1040) * Made express payload limit configurable (#1245) * Added callback handler to runtime evaluate method (#938) #### Testing & Development Improvements[​](#testing--development-improvements "Direct link to Testing & Development Improvements") * Implemented Smoke Test scripts (#1101) * Added initial release of smoke/integration tests + testing framework (#993) * Enabled test coverage reporting to Codecov (#880, #1019) * Enhanced GitHub image CI/CD workflow (#889) * Improved development scripts with better help messages (#887, #892) * Created example folder with example plugin (#1004) * Allowed users to configure models for Groq (#910), Grok (#1091), OpenAI and Anthropic (#999) * Added plugin for EVM multichain support (#1009) #### Bug Fixes[​](#bug-fixes-4 "Direct link to Bug Fixes") * Fixed issues with Twitter client login and auth (#1158) * Fixed direct-client ability to start agents (#1154) * Fixed plugin loading from character.json files (#784) * Fixed parameter parsing in plugin-evm TransferAction (#965) * Fixed various client issues (Slack, Discord, Telegram, Farcaster) * Fixed model provider issues for Claude Vertex (#1258, #1293) * Fixed Twitter post generation and interaction (#1217, #1242) * Fixed telegram response memory userId to agentId (#948) #### Documentation & Internationalization[​](#documentation--internationalization-1 "Direct link to Documentation & Internationalization") * Added README translations (German, Vietnamese, Thai) * Added templates documentation (#1013) * Added WSL Setup Guide (#983) * Added README for plugin-evm (#1095) * Added documentation for community section (#1114) #### Full Changelog[​](#full-changelog-9 "Direct link to Full Changelog") [https://github.com/ai16z/eliza/compare/v0.1.5...v0.1.6](https://github.com/ai16z/eliza/compare/v0.1.5...v0.1.6) * * * v0.1.6-alpha.4 (2024-12-17)[​](#v016-alpha4-2024-12-17 "Direct link to v0.1.6-alpha.4 (2024-12-17)") ----------------------------------------------------------------------------------------------------- #### Key Changes[​](#key-changes "Direct link to Key Changes") * Fixed Twitter client login and authentication handling (#1158) v0.1.6-alpha.3 (2024-12-17)[​](#v016-alpha3-2024-12-17 "Direct link to v0.1.6-alpha.3 (2024-12-17)") ----------------------------------------------------------------------------------------------------- #### Key Changes[​](#key-changes-1 "Direct link to Key Changes") * Added package version update script (#1150) * Set fetch log level to debug for improved troubleshooting (#1153) * Fixed direct-client functionality for starting agents (#1154) v0.1.6-alpha.2 (2024-12-17)[​](#v016-alpha2-2024-12-17 "Direct link to v0.1.6-alpha.2 (2024-12-17)") ----------------------------------------------------------------------------------------------------- #### Major Features[​](#major-features-3 "Direct link to Major Features") * **Blockchain & DeFi:** * Added FOMO.fund token creation/trading in plugin-solana (#1135) * Added support for multiple blockchain platforms: * MultiversX plugin (#860) * NEAR Protocol plugin (#847) * TON plugin (#1039) * SUI plugin (#934) * ZKsync Era plugin (#906) * Enhanced EVM with multichain support (#1009) * **Client & Social Interaction:** * Added Discord and Telegram Team features (#1032, #1033) * Added Lens client integration (#1098) * Improved X/Twitter login with cookie validation and retry (#856) * Enhanced Twitter client with action processing (#913) * Added Slack plugin (#859) * **Development & Testing:** * Added Smoke Test script infrastructure (#1101) * Added REST API for client-direct configuration (#1052) * Added GitHub image CI/CD workflow (#889) * **Content Creation:** * Added plugin-story for narrative generation (#1030) * Added plugin-nft-generation for Solana NFT collections (#1011) * Added Venice.ai image generation support (#1057) * Added support for handlebars templating engine (#1136) #### Notable Fixes[​](#notable-fixes "Direct link to Notable Fixes") * Fixed telegram and discord client duplicate functions (#1140, #1125) * Improved FOMO integration for better performance (#1147) * Fixed parameter parsing in plugin-evm TransferAction (#965) * Fixed Twitter posts to remove newline characters (#1070, #1141) * Enabled bots to post tweets with images from imageGenerationPlugin (#1040) * Added helpful default agents (Dobby and C3PO) (#1124) v0.1.6-alpha.1 (2024-12-13)[​](#v016-alpha1-2024-12-13 "Direct link to v0.1.6-alpha.1 (2024-12-13)") ----------------------------------------------------------------------------------------------------- #### Major Features[​](#major-features-4 "Direct link to Major Features") * **Blockchain & Web3:** * Added Flow Blockchain plugin (#874) * Added TEE Mode to Solana Plugin (#835) * Enhanced Coinbase plugin with advanced trading (#725) * Added readContract/invokeContract functionality (#923) * **Model Providers:** * Added NanoGPT provider (#926) * Added Venice.ai API model provider (#1008) * Added Hyperbolic API integration (#828) with env var overrides (#974) * Added configuration for EternalAI model from environment (#927) * **Development Tools:** * Added callback handler to runtime evaluate method (#938) * Added dynamic watch paths for agent development (#931) * Added custom fetch logic for agent (#1010) * Created example folder with sample plugin (#1004) * **Media & Content:** * Improved voice processing with Deepgram transcription (#1026) * Added MAX\_TWEET\_LENGTH environment variable control (#912) #### Key Fixes[​](#key-fixes-1 "Direct link to Key Fixes") * Fixed Twitter Search Logic and added Galadriel Image Model (#994) * Fixed Telegram response memory userId to agentId (#948) * Improved Farcaster client response logic (#914, #963) * Corrected EVM plugin activation condition (#962) * Re-enabled generateNewTweetLoop (#1043) #### Documentation[​](#documentation-1 "Direct link to Documentation") * Added templates documentation (#1013) * Added Thai (TH) README translation (#918) * Added WSL Setup Guide (#983) * Added AI Agent Dev School Tutorial Link (#1038) * * * v0.1.5-alpha.5 (December 07, 2024)[​](#v015-alpha5-december-07-2024 "Direct link to v0.1.5-alpha.5 (December 07, 2024)") ------------------------------------------------------------------------------------------------------------------------- #### What's Changed[​](#whats-changed "Direct link to What's Changed") * feat: working farcaster client #### Full Changelog[​](#full-changelog-10 "Direct link to Full Changelog") [https://github.com/ai16z/eliza/compare/v0.1.5-alpha.4...v0.1.5-alpha.5](https://github.com/ai16z/eliza/compare/v0.1.5-alpha.4...v0.1.5-alpha.5) * * * v0.1.5-alpha.4 (2024-12-06)[​](#v015-alpha4-2024-12-06 "Direct link to v0.1.5-alpha.4 (2024-12-06)") ----------------------------------------------------------------------------------------------------- * **Blockchain & Web3:** * Added Coinbase ERC20, ERC721, and ERC1155 token deployment/invocation plugin (#803) * Added Coinbase webhook functionality with examples and testing (#801) * Added Aptos blockchain plugin (#818) * **Model & Performance:** * Configured system to use LARGE models for responses (#853) * Added Google model environment variables (#875) * **Testing & Documentation:** * Added environment and knowledge tests (#862) * Added AI Agent Dev School summaries and timestamps (#877) * Updated quickstart documentation with common issue solutions (#861, #872) * Fixed plugins documentation (#848) * Updated Node version in local-development.md (#850) #### Full Changelog[​](#full-changelog-11 "Direct link to Full Changelog") [https://github.com/ai16z/eliza/compare/v0.1.5-alpha.3...v0.1.5-alpha.4](https://github.com/ai16z/eliza/compare/v0.1.5-alpha.3...v0.1.5-alpha.4) * * * v0.1.5-alpha.3 (2024-12-04)[​](#v015-alpha3-2024-12-04 "Direct link to v0.1.5-alpha.3 (2024-12-04)") ----------------------------------------------------------------------------------------------------- * **Core Infrastructure:** * Added circuit breaker pattern for database operations (#812) * Fixed Twitter cache expiration issues (#824) * Pinned all node dependencies and updated @solana/web3.js to safe version (#832) * **Development Workflow:** * Fixed lerna publish command (#811) * Fixed Docker setup documentation (#826) * Reverted viem package version (#834) * Bumped @goat-sdk/plugin-erc20 version (#836) #### Full Changelog[​](#full-changelog-12 "Direct link to Full Changelog") [https://github.com/ai16z/eliza/compare/v0.1.5-alpha.0...v0.1.5-alpha.3](https://github.com/ai16z/eliza/compare/v0.1.5-alpha.0...v0.1.5-alpha.3) * * * v0.1.5-alpha.0 (2024-12-03)[​](#v015-alpha0-2024-12-03 "Direct link to v0.1.5-alpha.0 (2024-12-03)") ----------------------------------------------------------------------------------------------------- * **Plugin System:** * Fixed plugin loading when configured with plugin name in character.json (#784) * Improved actions samples random selection (#799) * **Image Generation:** * Fixed TOGETHER/LLAMACLOUD image generation (#786) * **Platform Improvements:** * Made Docker use non-interactive mode for Cloud instances (#796) * Fixed swap type error and user trust creation on first Telegram message (#800) * Made UUID compatible with number types (#785) * **Development Infrastructure:** * Updated npm publication workflow (#805, #806, #807) * Fixed dev command (#793) * Fixed environment typo (#787) * Updated Korean README to match latest English version (#789) #### Full Changelog[​](#full-changelog-13 "Direct link to Full Changelog") [https://github.com/ai16z/eliza/compare/v0.1.5...v0.1.5-alpha.0](https://github.com/ai16z/eliza/compare/v0.1.5...v0.1.5-alpha.0) * * * v0.1.5 (2024-12-02)[​](#v015-2024-12-02 "Direct link to v0.1.5 (2024-12-02)") ------------------------------------------------------------------------------ #### Summary[​](#summary-5 "Direct link to Summary") This release introduces significant improvements to the Eliza framework with enhancements to database adapters, client interfaces, and plugin architecture. Notable additions include several new provider integrations, improved Twitter functionality, and expanded AI model support. #### Major Features[​](#major-features-5 "Direct link to Major Features") #### Plugin System Enhancements[​](#plugin-system-enhancements-1 "Direct link to Plugin System Enhancements") * Added 0G plugin for file storage (PR #416) * Implemented Coinbase plugin with trading and payment capabilities (PR #608, #664) * Added Conflux plugin support (PR #481) * Added Buttplug.io integration (PR #517) * Added TEE (Trusted Execution Environment) plugin (PR #632) * Added Farcaster client support (PR #386) * Added Starknet portfolio provider (PR #595) * Added Goat plugin (PR #736) #### AI Model Providers[​](#ai-model-providers-1 "Direct link to AI Model Providers") * Added decentralized inferencing for Eliza (LLAMA, Hermes, Flux) (PR #516) * Added Galadriel LLM inference provider (PR #651) * Added RedPill custom models support (PR #668) * Added decentralized GenAI backend (PR #762) * Added more AI providers: Ali Bailian (Qwen) and Volengine (Doubao, Bytedance) (PR #747) #### Knowledge Processing[​](#knowledge-processing-1 "Direct link to Knowledge Processing") * Improved knowledge embeddings (PR #472) * Enhanced embedding search for non-openai models (PR #660) * Increased knowledge context (PR #730) * Added knowledge to state functionality (PR #600) * Improved knowledge module exporting process (PR #609) #### Infrastructure Updates[​](#infrastructure-updates-1 "Direct link to Infrastructure Updates") * Implemented Cache Manager (PR #378) * Added Docker setup improvements (PR #702) * Added Turborepo for improved build performance (PR #670) * Added code coverage configuration (PR #659) * Improved database connection handling (PR #635) #### Client Improvements[​](#client-improvements-4 "Direct link to Client Improvements") * Twitter client refactoring and enhancements (PR #478, #722, #756, #763) * Discord client improvements with voice support (PR #633, #688) * Added WhatsApp integration (PR #626) * Enhanced React client with agent selection and layout improvements (PR #536) * Integrated Telegram client enhancements (PR #552, #662) * Added GitHub client initialization (PR #456) #### Bug Fixes[​](#bug-fixes-5 "Direct link to Bug Fixes") * Fixed PostgreSQL embedding issues (PR #425, #557) * Resolved Discord permissions and voice issues (PR #662, #598) * Fixed Twitter interaction handling (PR #622, #620, #729) * Improved embeddings for messages with URLs (PR #671) * Resolved database queries and memory handling (PR #606, #607, #572) * Fixed token provider and simulation services (PR #547, #627) #### Technical Improvements[​](#technical-improvements-4 "Direct link to Technical Improvements") * Switched from tiktoken to js-tiktoken for worker compatibility (PR #703) * Improved logging mechanisms (PR #688, #525) * Enhanced browser service (PR #653) * Fixed eslint configuration (PR #672) * Improved template typing system (PR #479) #### Full Changelog[​](#full-changelog-14 "Direct link to Full Changelog") [https://github.com/ai16z/eliza/compare/v0.1.3...v0.1.5](https://github.com/ai16z/eliza/compare/v0.1.3...v0.1.5) * * * v0.1.4-alpha.3 (2024-11-28)[​](#v014-alpha3-2024-11-28 "Direct link to v0.1.4-alpha.3 (2024-11-28)") ----------------------------------------------------------------------------------------------------- #### Summary[​](#summary-6 "Direct link to Summary") This alpha release introduces initial improvements to the platform with focus on documentation, bug fixes, and foundational service enhancements. #### Major Features[​](#major-features-6 "Direct link to Major Features") * Created cache manager system (PR #378) * Implemented Twitter client refactoring (PR #478) * Added GitHub client initialization (PR #456) * Introduced create-eliza-app utility (PR #462) #### Bug Fixes[​](#bug-fixes-6 "Direct link to Bug Fixes") * Fixed PostgreSQL embedding issues (PR #425) * Fixed Twitter dry run functionality (PR #452) * Resolved character path loading issues (PR #486, #487) * Fixed agent type error and SQLite file environment handling (PR #484) #### Documentation[​](#documentation-2 "Direct link to Documentation") * Added best practices documentation (PR #463) * Updated Twitter configuration examples (PR #476) * Updated contributor guidelines (PR #468, #470) * Added npm installation instructions to homepage (PR #459) #### Technical Improvements[​](#technical-improvements-5 "Direct link to Technical Improvements") * Enhanced knowledge embeddings (PR #472) * Improved type safety (PR #494) * Added template types (PR #479) * Fixed package configuration issues (PR #488, #503, #504) #### Full Changelog[​](#full-changelog-15 "Direct link to Full Changelog") [https://github.com/ai16z/eliza/compare/v0.1.3...v0.1.4-alpha.3](https://github.com/ai16z/eliza/compare/v0.1.3...v0.1.4-alpha.3) * * * v0.1.3-alpha.2 (2024-11-20)[​](#v013-alpha2-2024-11-20 "Direct link to v0.1.3-alpha.2 (2024-11-20)") ----------------------------------------------------------------------------------------------------- #### Summary[​](#summary-7 "Direct link to Summary") This minor alpha release focuses on configuration and import fixes to prepare for npm publication. #### Bug Fixes[​](#bug-fixes-7 "Direct link to Bug Fixes") * Fixed configuration settings (PR #431) * Resolved linting and import issues for npm compatibility (PR #433, #435) #### Technical Improvements[​](#technical-improvements-6 "Direct link to Technical Improvements") * Removed requirement for .env file to exist (PR #427) * Updated pull request workflows (PR #429) #### Full Changelog[​](#full-changelog-16 "Direct link to Full Changelog") [https://github.com/ai16z/eliza/compare/v0.1.1...v0.1.3-alpha.2](https://github.com/ai16z/eliza/compare/v0.1.1...v0.1.3-alpha.2) * * * v0.1.3 (2024-11-20)[​](#v013-2024-11-20 "Direct link to v0.1.3 (2024-11-20)") ------------------------------------------------------------------------------ #### Summary[​](#summary-8 "Direct link to Summary") This release improves documentation, fixes critical import issues, and enhances Discord voice functionality. #### Bug Fixes[​](#bug-fixes-8 "Direct link to Bug Fixes") * Fixed import path issues (PR #435, #436) * Adjusted default path following agent directory restructuring (PR #432) * Corrected Discord voice permissions and settings (PR #444, #447) * Fixed console logging issues (PR #440) * Resolved linter issues (PR #397) #### Documentation[​](#documentation-3 "Direct link to Documentation") * Added comprehensive style guidelines to context (PR #441) * Updated contributing documentation (PR #430) #### Technical Improvements[​](#technical-improvements-7 "Direct link to Technical Improvements") * Fixed Discord bot default deafened state (PR #437) * Improved error handling and logging (PR #433) #### Full Changelog[​](#full-changelog-17 "Direct link to Full Changelog") [https://github.com/ai16z/eliza/compare/v0.1.2...v0.1.3](https://github.com/ai16z/eliza/compare/v0.1.2...v0.1.3) * * * v0.1.1 (2024-11-20)[​](#v011-2024-11-20 "Direct link to v0.1.1 (2024-11-20)") ------------------------------------------------------------------------------ #### Summary[​](#summary-9 "Direct link to Summary") This major release implements significant architectural changes with a modular plugin system, expanded AI model support, multi-language capability, and improved knowledge processing features. #### Major Features[​](#major-features-7 "Direct link to Major Features") #### Plugin System[​](#plugin-system "Direct link to Plugin System") * Abstracted Eliza into a package for NPM publication with plugin system (PR #214) * Created various adapters, plugins, and clients (PR #225) * Added Starknet plugin (PR #287) * Implemented Unruggable plugin for token safety (PR #398, #418) * Added video generation plugin (PR #394) #### AI Model Providers[​](#ai-model-providers-2 "Direct link to AI Model Providers") * Added Groq API integration (PR #194) * Implemented GROK beta support (PR #216) * Added OLLAMA as model provider (PR #221) * Added OpenRouter model provider (PR #245) * Added Google model support (PR #246) * Added Heurist API integration (PR #335) #### Blockchain Integration[​](#blockchain-integration "Direct link to Blockchain Integration") * Implemented swap functionality (PR #197) * Added token transfer action (PR #297) * Added trust integration and database support (PR #248, #349) * Created Starknet token transfer capability (PR #373) * Added ICP token creation support (PR #357) #### Client Interfaces[​](#client-interfaces "Direct link to Client Interfaces") * Fixed Discord voice and DMs (PR #203) * Enhanced Telegram client functionality (PR #304, #308) * Improved Twitter integration with context and spam reduction (PR #383) #### Infrastructure Updates[​](#infrastructure-updates-2 "Direct link to Infrastructure Updates") * Added PostgreSQL adapter (PR #247) * Dockerized application for development and deployment (PR #293) * Implemented services architecture (PR #412) * Added logging improvements (PR #393) #### Multi-language Support[​](#multi-language-support "Direct link to Multi-language Support") * Added Japanese README (PR #307) * Added Korean and French README (PR #312) * Added Portuguese README (PR #320) * Added Spanish, Russian, Turkish, and Italian translations (PR #400, #380, #376, #411) #### Bug Fixes[​](#bug-fixes-9 "Direct link to Bug Fixes") * Fixed embedding calculation for SQLite (PR #261) * Fixed tweet truncation issues (PR #388) * Improved error handling for model providers * Fixed wallet interaction issues (PR #281) #### Technical Improvements[​](#technical-improvements-8 "Direct link to Technical Improvements") * Added lazy loading for LLAMA models (PR #220) * Implemented node version checking (PR #299) * Created template overrides system (PR #207) * Enhanced embedding handling (PR #254, #262) #### Full Changelog[​](#full-changelog-18 "Direct link to Full Changelog") [https://github.com/ai16z/eliza/compare/v0.0.10...v0.1.1](https://github.com/ai16z/eliza/compare/v0.0.10...v0.1.1) * [v0.25.8 (2025-02-24)](#v0258-2025-02-24) * [v0.25.6-alpha.1 (2025-02-06)](#v0256-alpha1-2025-02-06) * [v0.1.9 (2025-02-01)](#v019-2025-02-01) * [v0.1.8+build.1 (2025-01-12)](#v018build1-2025-01-12) * [v0.1.8-alpha.1 (2025-01-01)](#v018-alpha1-2025-01-01) * [Version 0.1.8 (2025-01-12)](#version-018-2025-01-12) * [Version 0.1.7 (2025-01-04)](#version-017-2025-01-04) * [Version 0.1.7-alpha.2 (2024-12-28)](#version-017-alpha2-2024-12-28) * [Version 0.1.7-alpha.1 (2024-12-22)](#version-017-alpha1-2024-12-22) * [Version 0.1.6-alpha.5 (2024-12-21)](#version-016-alpha5-2024-12-21) * [Version 0.1.6 (2024-12-21)](#version-016-2024-12-21) * [v0.1.6-alpha.4 (2024-12-17)](#v016-alpha4-2024-12-17) * [v0.1.6-alpha.3 (2024-12-17)](#v016-alpha3-2024-12-17) * [v0.1.6-alpha.2 (2024-12-17)](#v016-alpha2-2024-12-17) * [v0.1.6-alpha.1 (2024-12-13)](#v016-alpha1-2024-12-13) * [v0.1.5-alpha.5 (December 07, 2024)](#v015-alpha5-december-07-2024) * [v0.1.5-alpha.4 (2024-12-06)](#v015-alpha4-2024-12-06) * [v0.1.5-alpha.3 (2024-12-04)](#v015-alpha3-2024-12-04) * [v0.1.5-alpha.0 (2024-12-03)](#v015-alpha0-2024-12-03) * [v0.1.5 (2024-12-02)](#v015-2024-12-02) * [v0.1.4-alpha.3 (2024-11-28)](#v014-alpha3-2024-11-28) * [v0.1.3-alpha.2 (2024-11-20)](#v013-alpha2-2024-11-20) * [v0.1.3 (2024-11-20)](#v013-2024-11-20) * [v0.1.1 (2024-11-20)](#v011-2024-11-20) --- # Overview | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page Eliza is a framework for creating AI agents that can interact across multiple platforms. **Features** * **Modular Design**: Plugins and services allow for flexible customization. * **Knowledge**: Supports both RAG-based and direct knowledge processing. * **Stateful Interactions**: Maintains context across conversations. * **Multi-Agent Support**: Supports running multiple agents with distinct configurations. * **Multi-Platform Support**: Integrates with various clients (e.g., Discord, Telegram). Eliza consists of these core components: * **Agents (Runtime)**: AI personalities that interact with users and platforms * **Actions**: Executable behaviors that agents can perform in response to messages * **Clients**: Platform connectors for services like Discord, Twitter, and Telegram * **Plugins**: Modular extensions that add new features and capabilities * **Providers**: Services that supply contextual information to agents * **Evaluators**: Modules that analyze conversations and track agent goals * **Character Files**: JSON configurations that define agent personalities * **Memory System**: Database that stores and manages agent information using vector embeddings Here's an overview of how eliza works from user input to response generation: ![](/eliza/assets/images/overview-ce5bf72370dbb138986b287d3bf2e203.png) Source: [https://x.com/gelatonetwork/status/1894408632915169618](https://x.com/gelatonetwork/status/1894408632915169618) * * * [Agent Runtime](/eliza/docs/core/agents) [​](#agent-runtime "Direct link to agent-runtime") -------------------------------------------------------------------------------------------- **The Brain** The Runtime (`src/runtime.ts`) acts as the control tower for your AI agents. Think of it as a conductor leading an orchestra - it ensures all parts work together harmoniously. It serves as the central coordination layer for message processing, memory management, state composition, action execution, and integration with AI models and external services. * **Core Functions**: * Coordinates message processing * Manages the agent's lifecycle * Handles integration with AI models * Orchestrates plugins and services [Character Files](/eliza/docs/core/characterfile) [​](#character-files "Direct link to character-files") --------------------------------------------------------------------------------------------------------- **The Personality** [Character Files](/eliza/docs/core/characterfile) (`src/types.ts`) define agent **personalities** and **capabilities** including biographical information, interaction styles, plugin configurations, and platform integrations. The character file defines who your agent is - like a script for an actor. It includes: * Biographical information and backstory * Topics the agent can discuss * Writing style and tone * Which AI models to use * Which plugins to load * Which platforms to connect to [Clients](/eliza/docs/core/clients) [​](#clients "Direct link to clients") --------------------------------------------------------------------------- **The Interface** Clients connect your agent to different platforms (Discord, Twitter, Slack, Farcaster, etc.) while maintaining consistent behavior across all interfaces. Each client can handle different types of interactions: * Chat messages * Social media posts * Voice conversations * Platform-specific features [Actions](/eliza/docs/core/actions) [​](#actions "Direct link to actions") --------------------------------------------------------------------------- **What Agents Can Do** Actions (`src/actions.ts`) are like tools in a toolbox. They define how agents respond and interact with messages, enabling custom behaviors, external system interactions, media processing, and platform-specific features. [Evaluators](/eliza/docs/core/evaluators) [​](#evaluators "Direct link to evaluators") --------------------------------------------------------------------------------------- **Quality Control** Evaluators (`src/evaluators.ts`) act like referees, making sure the agent follows rules and guidelines. They monitor conversations and help improve agent responses over time by assessing conversations and maintaining agent knowledge through fact extraction, goal tracking, memory building, and relationship management. [Providers](/eliza/docs/core/providers.ts) [​](#providers "Direct link to providers") -------------------------------------------------------------------------------------- **Information Flow** Providers (`src/providers.ts`) are the agent's eyes and ears, like a newsroom keeping them informed about the world. They supply real-time information to agents by integrating external APIs, managing temporal awareness, and providing system status updates to help agents make better decisions. Memory & Knowledge Systems[​](#memory--knowledge-systems "Direct link to Memory & Knowledge Systems") ------------------------------------------------------------------------------------------------------ The framework implements specialized memory systems through: ### Memory Manager[​](#memory-manager "Direct link to Memory Manager") The Memory Manager (`src/memory.ts`) acts like a personal diary and helps agents remember: * Recent conversations * Important facts * User interactions * Immediate context for current discussions ### Knowledge Systems[​](#knowledge-systems "Direct link to Knowledge Systems") Think of this as the agent's library (`src/knowledge.ts`, `src/ragknowledge.ts`), where information is: * Organized into searchable chunks * Converted into vector embeddings * Retrieved based on relevance * Used to enhance responses Data Management[​](#data-management "Direct link to Data Management") ---------------------------------------------------------------------- The data layer provides robust storage and caching through: ### Database System[​](#database-system "Direct link to Database System") The database (`src/database.ts`) acts as a filing cabinet, storing: * Conversation histories * User interactions * Transaction management * Vector storage * Relationship tracking * Embedded knowledge * Agent state See also: [Memory Management](/eliza/docs/guides/memory-management) Cache System[​](#cache-system "Direct link to Cache System") ------------------------------------------------------------- **Performance Optimization** The Cache System (`src/cache.ts`) creates shortcuts for frequently accessed information, making agents respond faster and more efficiently. System Flow[​](#system-flow "Direct link to System Flow") ---------------------------------------------------------- When someone interacts with your agent, the Client receives the message and forwards it to the Runtime which processes it with the characterfile configuration. The Runtime loads relevant memories and knowledge, uses actions and evaluators to determine how to response, gets additional context through providers. Then the Runtime generates a response using the AI model, stores new memories, and sends the response back through the client. * * * Common Patterns[​](#common-patterns "Direct link to Common Patterns") ---------------------------------------------------------------------- ### Memory Usage (`src/memory.ts`)[​](#memory-usage-srcmemoryts "Direct link to memory-usage-srcmemoryts") // Store conversation dataawait messageManager.createMemory({ id: messageId, content: { text: "Message content" }, userId: userId, roomId: roomId});// Retrieve contextconst recentMessages = await messageManager.getMemories({ roomId: roomId, count: 10}); ### Action Implementation (`src/actions.ts`)[​](#action-implementation-srcactionsts "Direct link to action-implementation-srcactionsts") const customAction: Action = { name: "CUSTOM_ACTION", similes: ["ALTERNATE_NAME"], description: "Action description", validate: async (runtime, message) => { // Validation logic return true; }, handler: async (runtime, message) => { // Implementation logic return true; }}; ### Provider Integration (`src/providers.ts`)[​](#provider-integration-srcprovidersts "Direct link to provider-integration-srcprovidersts") const dataProvider: Provider = { get: async (runtime: IAgentRuntime, message: Memory) => { // Fetch and format data return "Formatted context string"; }}; * * * FAQ[​](#faq "Direct link to FAQ") ---------------------------------- ### What's the difference between Actions, Evaluators, and Providers?[​](#whats-the-difference-between-actions-evaluators-and-providers "Direct link to What's the difference between Actions, Evaluators, and Providers?") Actions define what an agent can do, Evaluators analyze what happened, and Providers supply information to help make decisions. ### Can I use multiple AI models with one agent?[​](#can-i-use-multiple-ai-models-with-one-agent "Direct link to Can I use multiple AI models with one agent?") Yes, agents can be configured to use different models for different tasks (chat, image generation, embeddings) through the modelProvider settings. ### How does memory persistence work?[​](#how-does-memory-persistence-work "Direct link to How does memory persistence work?") Memory is stored through database adapters which can use SQLite, PostgreSQL, or other backends, with each type (messages, facts, knowledge) managed separately. ### What's the difference between Lore and Knowledge?[​](#whats-the-difference-between-lore-and-knowledge "Direct link to What's the difference between Lore and Knowledge?") Lore defines the character's background and history, while Knowledge represents factual information the agent can reference and use. ### How do I add custom functionality?[​](#how-do-i-add-custom-functionality "Direct link to How do I add custom functionality?") Create plugins that implement the Action, Provider, or Evaluator interfaces and register them with the runtime. ### Do I need to implement all components?[​](#do-i-need-to-implement-all-components "Direct link to Do I need to implement all components?") No, each component is optional. Start with basic Actions and add Evaluators and Providers as needed. ### How does RAG integration work?[​](#how-does-rag-integration-work "Direct link to How does RAG integration work?") Documents are chunked, embedded, and stored in the knowledge base for semantic search during conversations via the RAGKnowledgeManager. ### What's the recommended database for production?[​](#whats-the-recommended-database-for-production "Direct link to What's the recommended database for production?") PostgreSQL with vector extensions is recommended for production, though SQLite works well for development and testing. * [Agent Runtime](#agent-runtime) * [Character Files](#character-files) * [Clients](#clients) * [Actions](#actions) * [Evaluators](#evaluators) * [Providers](#providers) * [Memory & Knowledge Systems](#memory--knowledge-systems) * [Memory Manager](#memory-manager) * [Knowledge Systems](#knowledge-systems) * [Data Management](#data-management) * [Database System](#database-system) * [Cache System](#cache-system) * [System Flow](#system-flow) * [Common Patterns](#common-patterns) * [Memory Usage (`src/memory.ts`)](#memory-usage-srcmemoryts) * [Action Implementation (`src/actions.ts`)](#action-implementation-srcactionsts) * [Provider Integration (`src/providers.ts`)](#provider-integration-srcprovidersts) * [FAQ](#faq) * [What's the difference between Actions, Evaluators, and Providers?](#whats-the-difference-between-actions-evaluators-and-providers) * [Can I use multiple AI models with one agent?](#can-i-use-multiple-ai-models-with-one-agent) * [How does memory persistence work?](#how-does-memory-persistence-work) * [What's the difference between Lore and Knowledge?](#whats-the-difference-between-lore-and-knowledge) * [How do I add custom functionality?](#how-do-i-add-custom-functionality) * [Do I need to implement all components?](#do-i-need-to-implement-all-components) * [How does RAG integration work?](#how-does-rag-integration-work) * [What's the recommended database for production?](#whats-the-recommended-database-for-production) --- # πŸ“ Character Files | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page Character files are JSON-formatted configurations that define AI agent personas, combining personality traits, knowledge bases, and interaction patterns to create consistent and effective AI agents. For a full list of capabilities check the `character` type [API docs](/eliza/api/type-aliases/character) . You can also view and contribute to open sourced example characterfiles here: [https://github.com/elizaos/characters](https://github.com/elizaos/characters) . > For making characters, check out the open source elizagen!: [https://elizagen.howieduhzit.best/](https://elizagen.howieduhzit.best/) > [![](/eliza/assets/images/elizagen-2fe2904572c28a9d36c16872fa015785.png)](/eliza/assets/files/elizagen-2fe2904572c28a9d36c16872fa015785.png) * * * Required Fields[​](#required-fields "Direct link to Required Fields") ---------------------------------------------------------------------- { "name": "character_name", // Character's display name for identification and in conversations "modelProvider": "openai", // AI model provider (e.g., anthropic, openai, groq, mistral, google) "clients": ["discord", "direct"], // Supported client types "plugins": [], // Array of plugins to use "settings": { // Configuration settings "ragKnowledge": false, // Enable RAG for knowledge (default: false) "secrets": {}, // API keys and sensitive data "voice": {}, // Voice configuration "model": "string", // Optional model override "modelConfig": {} // Optional model configuration }, "bio": [], // Character background as a string or array of statements "style": { // Interaction style guide "all": [], // General style rules "chat": [], // Chat-specific style "post": [] // Post-specific style }} ### modelProvider[​](#modelprovider "Direct link to modelProvider") Supported providers: `openai`, `eternalai`, `anthropic`, `grok`, `groq`, `llama_cloud`, `together`, `llama_local`, `lmstudio`, `google`, `mistral`, `claude_vertex`, `redpill`, `openrouter`, `ollama`, `heurist`, `galadriel`, `falai`, `gaianet`, `ali_bailian`, `volengine`, `nanogpt`, `hyperbolic`, `venice`, `nvidia`, `nineteen_ai`, `akash_chat_api`, `livepeer`, `letzai`, `deepseek`, `infera`, `bedrock`, `atoma`. See the full list of models in [api/type-aliases/Models](/eliza/docs/core/api/type-aliases/Models) . ### Client Types[​](#client-types "Direct link to Client Types") Supported client integrations in `clients` array: * `discord`: Discord bot integration * `telegram`: Telegram bot * `twitter`: Twitter/X bot * `slack`: Slack integration * `direct`: Direct chat interface * `simsai`: SimsAI platform integration ### Plugins[​](#plugins "Direct link to Plugins") See all the available plugins for Eliza here: [https://github.com/elizaos-plugins/registry](https://github.com/elizaos-plugins/registry) ### Settings Configuration[​](#settings-configuration "Direct link to Settings Configuration") The `settings` object supports: { "settings": { "ragKnowledge": false, // Enable RAG knowledge mode "voice": { "model": "string", // Voice synthesis model "url": "string" // Optional voice API URL }, "secrets": { // API keys (use env vars in production) "API_KEY": "string" }, "model": "string", // Optional model override "modelConfig": { // Optional model parameters "temperature": 0.7, "maxInputTokens": 4096, "maxOutputTokens": 1024, "frequency_penalty": 0.0, "presence_penalty": 0.0 }, "imageSettings": { // Optional image generation settings "steps": 20, "width": 1024, "height": 1024, "cfgScale": 7.5, "negativePrompt": "string" } }} ### Bio & Lore[​](#bio--lore "Direct link to Bio & Lore") * Bio = Core identity, character biography * Lore = Character background lore elements { "bio": [ "Expert in blockchain development", "Specializes in DeFi protocols" ], "lore": [ "Created first DeFi protocol in 2020", "Helped launch multiple DAOs" ]} **Bio & Lore Tips** * Mix factual and personality-defining information * Include both historical and current details * Break bio and lore into smaller chunks * This creates more natural, varied responses * Prevents repetitive or predictable behavior ### Style Guidelines[​](#style-guidelines "Direct link to Style Guidelines") Define interaction patterns: { "style": { "all": [ // Applied to all interactions "Keep responses clear", "Maintain professional tone" ], "chat": [ // Chat-specific style "Engage with curiosity", "Provide explanations" ], "post": [ // Social post style "Keep posts informative", "Focus on key points" ] }} **Style Tips** * Be specific about tone and mannerisms * Include platform-specific guidance * Define clear boundaries and limitations ### Optional but Recommended Fields[​](#optional-but-recommended-fields "Direct link to Optional but Recommended Fields") { "username": "handle", // Character's username/handle "system": "System prompt text", // Custom system prompt "lore": [], // Additional background/history "knowledge": [ // Knowledge base entries "Direct string knowledge", { "path": "file/path.md", "shared": false }, { "directory": "knowledge/path", "shared": false } ], "messageExamples": [], // Example conversations "postExamples": [], // Example social posts "topics": [], // Areas of expertise "adjectives": [] // Character traits} * * * #### Topics[​](#topics "Direct link to Topics") * List of subjects the character is interested in or knowledgeable about * Used to guide conversations and generate relevant content * Helps maintain character consistency #### Adjectives[​](#adjectives "Direct link to Adjectives") * Words that describe the character's traits and personality * Used for generating responses with a consistent tone * Can be used in "Mad Libs" style content generation * * * Knowledge Management[​](#knowledge-management "Direct link to Knowledge Management") ------------------------------------------------------------------------------------- The character system supports two knowledge modes: ### Classic Mode (Default)[​](#classic-mode-default "Direct link to Classic Mode (Default)") * Direct string knowledge added to character's context * No chunking or semantic search * Enabled by default (`settings.ragKnowledge: false`) * Only processes string knowledge entries * Simpler but less sophisticated ### RAG Mode[​](#rag-mode "Direct link to RAG Mode") * Advanced knowledge processing with semantic search * Chunks content and uses embeddings * Must be explicitly enabled (`settings.ragKnowledge: true`) * Supports three knowledge types: 1. Direct string knowledge 2. Single file references: `{ "path": "path/to/file.md", "shared": false }` 3. Directory references: `{ "directory": "knowledge/dir", "shared": false }` * Supported file types: .md, .txt, .pdf * Optional `shared` flag for knowledge reuse across characters ### Knowledge Path Configuration[​](#knowledge-path-configuration "Direct link to Knowledge Path Configuration") * Knowledge files are relative to the `characters/knowledge` directory * Paths should not contain `../` (sanitized for security) * Both shared and private knowledge supported * Files automatically reloaded if content changes **Knowledge Tips** * Focus on relevant information * Organize in digestible chunks * Update regularly to maintain relevance Use the provided tools to convert documents into knowledge: * [folder2knowledge](https://github.com/elizaos/characterfile/blob/main/scripts/folder2knowledge.js) * [knowledge2character](https://github.com/elizaos/characterfile/blob/main/scripts/knowledge2character.js) * [tweets2character](https://github.com/elizaos/characterfile/blob/main/scripts/tweets2character.js) Example: npx folder2knowledge npx knowledge2character * * * Character Definition Components[​](#character-definition-components "Direct link to Character Definition Components") ---------------------------------------------------------------------------------------------------------------------- Example Character File:[​](#example-character-file "Direct link to Example Character File:") --------------------------------------------------------------------------------------------- { "name": "Tech Helper", "modelProvider": "anthropic", "clients": ["discord"], "plugins": [], "settings": { "ragKnowledge": true, "voice": { "model": "en_US-male-medium" } }, "bio": [ "Friendly technical assistant", "Specializes in explaining complex topics simply" ], "lore": [ "Pioneer in open-source AI development", "Advocate for AI accessibility" ], "messageExamples": [ [ { "user": "{{user1}}", "content": { "text": "Can you explain how AI models work?" } }, { "user": "TechAI", "content": { "text": "Think of AI models like pattern recognition systems." } } ] ], "postExamples": [ "Understanding AI doesn't require a PhD - let's break it down simply", "The best AI solutions focus on real human needs" ], "topics": [ "artificial intelligence", "machine learning", "technology education" ], "knowledge": [ { "directory": "tech_guides", "shared": true } ], "adjectives": ["knowledgeable", "approachable", "practical"], "style": { "all": ["Clear", "Patient", "Educational"], "chat": ["Interactive", "Supportive"], "post": ["Concise", "Informative"] }} * [Required Fields](#required-fields) * [modelProvider](#modelprovider) * [Client Types](#client-types) * [Plugins](#plugins) * [Settings Configuration](#settings-configuration) * [Bio & Lore](#bio--lore) * [Style Guidelines](#style-guidelines) * [Optional but Recommended Fields](#optional-but-recommended-fields) * [Knowledge Management](#knowledge-management) * [Classic Mode (Default)](#classic-mode-default) * [RAG Mode](#rag-mode) * [Knowledge Path Configuration](#knowledge-path-configuration) * [Character Definition Components](#character-definition-components) * [Example Character File:](#example-character-file) --- # πŸ€– Agent Runtime | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page The `AgentRuntime` is the core runtime environment for Eliza agents. It handles message processing, state management, plugin integration, and interaction with external services. You can think of it as the brains that provide the high-level orchestration layer for Eliza agents. ![](/eliza/assets/images/eliza-architecture-52934d28c13a41bc53a2b0c7e7b88a77.jpg) The runtime follows this general flow: 1. Agent loads character config, plugins, and services * Processes knowledge sources (e.g., documents, directories) 2. Receives a message, composes the state 3. Processes actions and then evaluates * Retrieves relevant knowledge fragments using RAG 4. Generates and executes responses, then evaluates 5. Updates memory and state * * * Overview[​](#overview "Direct link to Overview") ------------------------------------------------- The [AgentRuntime](/eliza/api/classes/AgentRuntime) class is the primary implementation of the [IAgentRuntime](/eliza/api/interfaces/IAgentRuntime) interface, which manages the agent's core functions, including: | Component | Description | API Reference | Related Files | | --- | --- | --- | --- | | **Clients** | Supports multiple communication platforms for seamless interaction. | [Clients API](/eliza/api/interfaces/IAgentRuntime#clients) | [`clients.ts`](https://github.com/elizaos-plugins/client-discord/blob/main/__tests__/discord-client.test.ts)
, [`Discord`](https://github.com/elizaos-plugins/client-discord)
, [`Telegram`](https://github.com/elizaos-plugins/client-telegram)
, [`Twitter`](https://github.com/elizaos-plugins/client-twitter)
, [`Farcaster`](https://github.com/elizaos-plugins/client-farcaster)
, [`Lens`](https://github.com/elizaos-plugins/client-lens)
, [`Slack`](https://github.com/elizaos-plugins/client-slack)
, [`Auto`](https://github.com/elizaos-plugins/client-auto)
, [`GitHub`](https://github.com/elizaos-plugins/client-github) | | **State** | Maintains context for coherent cross-platform interactions, updates dynamically. Also tracks goals, knowledge, and recent interactions | [State API](/eliza/api/interfaces/State) | [`state.ts`](https://github.com/elizaos/runtime/state.ts) | | **Plugins** | Dynamic extensions of agent functionalities using custom actions, evaluators, providers, and adapters | [Plugins API](/eliza/api/type-aliases/Plugin) | [`plugins.ts`](https://github.com/elizaos/runtime/plugins.ts)
, [actions](/eliza/docs/actions)
, [evaluators](/eliza/docs/evaluators)
, [providers](/eliza/docs/providers) | | **Services** | Connects with external services for `IMAGE_DESCRIPTION`, `TRANSCRIPTION`, `TEXT_GENERATION`, `SPEECH_GENERATION`, `VIDEO`, `PDF`, `BROWSER`, `WEB_SEARCH`, `EMAIL_AUTOMATION`, and more | [Services API](/eliza/api/interfaces/IAgentRuntime#services) | [`services.ts`](https://github.com/elizaos/runtime/services.ts) | | **Memory Systems** | Creates, retrieves, and embeds memories and manages conversation history. | [Memory API](/eliza/api/interfaces/IMemoryManager) | [`memory.ts`](https://github.com/elizaos/runtime/memory.ts) | | **Database Adapters** | Persistent storage and retrieval for memories and knowledge | [databaseAdapter](/eliza/docs/core/api/interfaces/IAgentRuntime#databaseAdapter) | [`MongoDB`](https://github.com/elizaos-plugins/adapter-mongodb)
, [`PostgreSQL`](https://github.com/elizaos-plugins/adapter-postgres)
, [`SQLite`](https://github.com/elizaos-plugins/adapter-sqlite)
, [`Supabase`](https://github.com/elizaos-plugins/adapter-supabase)
, [`PGLite`](https://github.com/elizaos-plugins/adapter-pglite)
, [`Qdrant`](https://github.com/elizaos-plugins/adapter-qdrant)
, [`SQL.js`](https://github.com/elizaos-plugins/adapter-sqljs) | | **Cache Management** | Provides flexible storage and retrieval via various caching methods. | [Cache API](/eliza/api/interfaces/ICacheManager) | [`cache.ts`](https://github.com/elizaos/runtime/cache.ts) | Advanced: IAgentRuntime Interface interface IAgentRuntime { // Core identification agentId: UUID; token: string; serverUrl: string; // Configuration character: Character; // Personality and behavior settings modelProvider: ModelProviderName; // AI model to use imageModelProvider: ModelProviderName; imageVisionModelProvider: ModelProviderName; // Components plugins: Plugin[]; // Additional capabilities clients: Record; // Platform connections providers: Provider[]; // Real-time data sources actions: Action[]; // Available behaviors evaluators: Evaluator[]; // Analysis & learning // Memory Management messageManager: IMemoryManager; // Conversation history descriptionManager: IMemoryManager; documentsManager: IMemoryManager; // Large documents knowledgeManager: IMemoryManager; // Search & retrieval ragKnowledgeManager: IRAGKnowledgeManager; // RAG integration loreManager: IMemoryManager; // Character background // Storage & Caching databaseAdapter: IDatabaseAdapter; // Data persistence cacheManager: ICacheManager; // Performance optimization // Services services: Map; // External integrations // Networking fetch: (url: string, options: any) => Promise;} Source: [/api/interfaces/IAgentRuntime/](/eliza/api/interfaces/IAgentRuntime) * * * ### **Key Methods**[​](#key-methods "Direct link to key-methods") * **`initialize()`**: Sets up the agent's runtime environment, including services, plugins, and knowledge processing. * **`processActions()`**: Executes actions based on message content and state. * **`evaluate()`**: Assesses messages and state using registered evaluators. * **`composeState()`**: Constructs the agent's state object for response generation. * **`updateRecentMessageState()`**: Updates the state with recent messages and attachments. * **`registerService()`**: Adds a service to the runtime. * **`registerMemoryManager()`**: Registers a memory manager for specific types of memories. * **`ensureRoomExists()` / `ensureUserExists()`**: Ensures the existence of rooms and users in the database. WIP * * * Service System[​](#service-system "Direct link to Service System") ------------------------------------------------------------------- Services provide specialized functionality with standardized interfaces that can be accessed cross-platform: See Example // Speech Generationconst speechService = runtime.getService( ServiceType.SPEECH_GENERATION);const audioStream = await speechService.generate(runtime, text);// PDF Processingconst pdfService = runtime.getService(ServiceType.PDF);const textContent = await pdfService.convertPdfToText(pdfBuffer); * * * State Management[​](#state-management "Direct link to State Management") ------------------------------------------------------------------------- The runtime maintains comprehensive state through the State interface: interface State { // Core identifiers userId?: UUID; agentId?: UUID; roomId: UUID; // Character information bio: string; lore: string; messageDirections: string; postDirections: string; // Conversation context actors: string; actorsData?: Actor[]; recentMessages: string; recentMessagesData: Memory[]; // Goals and knowledge goals?: string; goalsData?: Goal[]; knowledge?: string; knowledgeData?: KnowledgeItem[]; ragKnowledgeData?: RAGKnowledgeItem[];}// State management methodsasync function manageState() { // Initial state composition const state = await runtime.composeState(message, { additionalContext: "custom context" }); // Update state with new messages const updatedState = await runtime.updateRecentMessageState(state);} * * * Plugin System[​](#plugin-system "Direct link to Plugin System") ---------------------------------------------------------------- Plugins extend agent functionality through a modular interface. The runtime supports various types of plugins including clients, services, adapters, and more: interface Plugin { name: string; description: string; actions?: Action[]; // Custom behaviors providers?: Provider[]; // Data providers evaluators?: Evaluator[]; // Response assessment services?: Service[]; // Background processes clients?: Client[]; // Platform integrations adapters?: Adapter[]; // Database/cache adapters} Plugins can be configured through [characterfile](/eliza/docs/core/characterfile) settings: { "name": "MyAgent", "plugins": [ "@elizaos/plugin-solana", "@elizaos/plugin-twitter" ]} For detailed information about plugin development and usage, see the [ElizaOS Registry](https://github.com/elizaos-plugins) . * * * Running Multiple Agents[​](#running-multiple-agents "Direct link to Running Multiple Agents") ---------------------------------------------------------------------------------------------- To run multiple agents: pnpm start --characters="characters/agent1.json,characters/agent2.json" Or use environment variables: REMOTE_CHARACTER_URLS=https://example.com/characters.json * * * FAQ[​](#faq "Direct link to FAQ") ---------------------------------- ### What's the difference between an agent and a character?[​](#whats-the-difference-between-an-agent-and-a-character "Direct link to What's the difference between an agent and a character?") A character defines personality and knowledge, while an agent provides the runtime environment and capabilities to bring that character to life. ### How do I choose the right database adapter?[​](#how-do-i-choose-the-right-database-adapter "Direct link to How do I choose the right database adapter?") Choose based on your needs: * MongoDB: For scalable, document-based storage * PostgreSQL: For relational data with complex queries * SQLite: For simple, file-based storage * Qdrant: For vector search capabilities ### How do I implement custom plugins?[​](#how-do-i-implement-custom-plugins "Direct link to How do I implement custom plugins?") Create a plugin that follows the plugin interface and register it with the runtime. See the plugin documentation for detailed examples. ### Do agents share memory across platforms?[​](#do-agents-share-memory-across-platforms "Direct link to Do agents share memory across platforms?") By default, agents maintain separate memory contexts for different platforms to avoid mixing conversations. Use the memory management system and database adapters to persist and retrieve state information. ### How do I handle multiple authentication methods?[​](#how-do-i-handle-multiple-authentication-methods "Direct link to How do I handle multiple authentication methods?") Use the character configuration to specify different authentication methods for different services. The runtime will handle the appropriate authentication flow. ### How do I manage environment variables?[​](#how-do-i-manage-environment-variables "Direct link to How do I manage environment variables?") Use a combination of: * `.env` files for local development * Character-specific settings for per-agent configuration * Environment variables for production deployment ### Can agents communicate with each other?[​](#can-agents-communicate-with-each-other "Direct link to Can agents communicate with each other?") Yes, through the message system and shared memory spaces when configured appropriately. * [Overview](#overview) * [**Key Methods**](#key-methods) * [Service System](#service-system) * [State Management](#state-management) * [Plugin System](#plugin-system) * [Running Multiple Agents](#running-multiple-agents) * [FAQ](#faq) * [What's the difference between an agent and a character?](#whats-the-difference-between-an-agent-and-a-character) * [How do I choose the right database adapter?](#how-do-i-choose-the-right-database-adapter) * [How do I implement custom plugins?](#how-do-i-implement-custom-plugins) * [Do agents share memory across platforms?](#do-agents-share-memory-across-platforms) * [How do I handle multiple authentication methods?](#how-do-i-handle-multiple-authentication-methods) * [How do I manage environment variables?](#how-do-i-manage-environment-variables) * [Can agents communicate with each other?](#can-agents-communicate-with-each-other) --- # Plugins | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page Plugins (or packages) are modular extensions that enhance the capabilities of ElizaOS agents. They provide a flexible way to add new functionality, integrate external services, and customize agent behavior across different platforms. **Browse the various plugins the eliza dev community made here: [Package Showcase](/eliza/showcase) ** [![](/eliza/assets/images/plugins-7fab2676046855656e3033b9dad264c2.png)](/eliza/showcase) > elizaOS maintains an official package registry at [github.com/elizaos-plugins/registry](https://github.com/elizaos-plugins/registry) > . * * * ### Installation[​](#installation "Direct link to Installation") Eliza now supports dynamic plugin loading directly from the package registry. Here's a couple ways you can add plugins on eliza: 1. Add the plugin to your project's dependencies (`package.json`): { "dependencies": { "@elizaos/plugin-solana": "github:elizaos-plugins/plugin-solana", "@elizaos/plugin-twitter": "github:elizaos-plugins/plugin-twitter" }} 2. Configure the plugin in your character file: { "name": "MyAgent", "plugins": [ "@elizaos/plugin-twitter", "@elizaos/plugin-example" ], "settings": { "example-plugin": { // Plugin-specific configuration } }} 3. Use the new CLI tool: You can list available plugins, install new ones, and remove them when needed. Go into the eliza directory you cloned and type `npx elizaos plugins` to use it. Usage: elizaos plugins [options] [command]manage elizaOS pluginsOptions: -h, --help display help for commandCommands: list|l [options] list available plugins add|install add a plugin remove|delete remove a plugin help [command] display help for command * * * Architecture[​](#architecture "Direct link to Architecture") ------------------------------------------------------------- Eliza uses a unified plugin architecture where everything is a plugin - including clients, adapters, actions, evaluators, and services. This approach ensures consistent behavior and better extensibility. Here's how the architecture works: 1. **Plugin Types**: Each plugin can provide one or more of the following: * Clients (e.g., Discord, Twitter, WhatsApp integrations) * Adapters (e.g., database adapters, caching systems) * Actions (custom behavior and responses functionality) * Evaluators (analysis, learning, decision-making components) * Services (background processes and integrations) * Providers (data or functionality providers) 2. **Plugin Interface**: All plugins implement the core Plugin interface: type Plugin = { name: string; description: string; config?: { [key: string]: any }; actions?: Action[]; providers?: Provider[]; evaluators?: Evaluator[]; services?: Service[]; clients?: Client[]; adapters?: Adapter[];}; 3. **Independent Repositories**: Each plugin lives in its own repository under the [elizaos-plugins](https://github.com/elizaos-plugins/) organization, allowing: * Independent versioning and releases * Focused issue tracking and documentation * Easier maintenance and contribution * Separate CI/CD pipelines 4. **Plugin Structure**: Each plugin repository should follow this structure: plugin-name/β”œβ”€β”€ images/β”‚ β”œβ”€β”€ logo.jpg # Plugin branding logoβ”‚ β”œβ”€β”€ banner.jpg # Plugin banner imageβ”œβ”€β”€ src/β”‚ β”œβ”€β”€ index.ts # Main plugin entry pointβ”‚ β”œβ”€β”€ actions/ # Plugin-specific actionsβ”‚ β”œβ”€β”€ clients/ # Client implementationsβ”‚ β”œβ”€β”€ adapters/ # Adapter implementationsβ”‚ └── types.ts # Type definitionsβ”‚ └── environment.ts # runtime.getSetting, zod validationβ”œβ”€β”€ package.json # Plugin dependencies└── README.md # Plugin documentation 5. **Package Configuration**: Your plugin's `package.json` must include an `agentConfig` section: { "name": "@elizaos/plugin-example", "version": "1.0.0", "agentConfig": { "pluginType": "elizaos:plugin:1.0.0", "pluginParameters": { "API_KEY": { "type": "string", "description": "API key for the service" } } }} 6. **Plugin Loading**: Plugins are dynamically loaded at runtime through the `handlePluginImporting` function, which: * Imports the plugin module * Reads the plugin configuration * Validates plugin parameters * Registers the plugin's components (clients, adapters, actions, etc.) 7. **Client and Adapter Implementation**: When implementing clients or adapters: // Client example const discordPlugin: Plugin = { name: "discord", description: "Discord client plugin", clients: [DiscordClientInterface] }; // Adapter example const postgresPlugin: Plugin = { name: "postgres", description: "PostgreSQL database adapter", adapters: [PostgresDatabaseAdapter] }; // Adapter example export const browserPlugin = { name: "default", description: "Pdf", services: [PdfService], actions: [], }; ### Environment Variables and Secrets[​](#environment-variables-and-secrets "Direct link to Environment Variables and Secrets") Plugins can access environment variables and secrets in two ways: 1. **Character Configuration**: Through `agent.json.secret` or character settings: { "name": "MyAgent", "settings": { "secrets": { "PLUGIN_API_KEY": "your-api-key", "PLUGIN_SECRET": "your-secret" } }} 2. **Runtime Access**: Plugins can access their configuration through the runtime: class MyPlugin implements Plugin { async initialize(runtime: AgentRuntime) { const apiKey = runtime.getSetting("PLUGIN_API_KEY"); const secret = runtime.getSetting("PLUGIN_SECRET"); }} The `getSetting` method follows this precedence: 1. Character settings secrets 2. Character settings 3. Global settings * * * ### Pull Request Requirements[​](#pull-request-requirements "Direct link to Pull Request Requirements") When submitting a plugin to the [elizaOS Registry](https://github.com/elizaos-plugins/registry) , your PR must include: 1. **Working Demo Evidence:** * Screenshots or video demonstrations of the plugin working with ElizaOS * Test results showing successful integration * Example agent configuration using your plugin * Documentation of any specific setup requirements 2. **Integration Testing:** * Proof of successful dynamic loading with ElizaOS * Test cases covering main functionality * Error handling demonstrations * Performance metrics (if applicable) 3. **Configuration Examples:** { "name": "MyAgent", "plugins": ["@elizaos/your-plugin"], "settings": { "your-plugin": { // Your plugin's configuration } }} 4. **Quality Checklist:** * [ ] Plugin follows the standard structure * [ ] All required branding assets are included * [ ] Documentation is complete and clear * [ ] GitHub topics are properly set * [ ] Tests are passing * [ ] Demo evidence is provided Visit the \[Elizaos Plugin Development Guide\]([https://github.com/elizaos-plugins/plugin-image](https://github.com/elizaOS/eliza/blob/main/docs/docs/packages/plugins.md) for detailed information on creating new plugins. ### Plugin Branding and Images[​](#plugin-branding-and-images "Direct link to Plugin Branding and Images") To maintain a consistent and professional appearance across the ElizaOS ecosystem, we recommend including the following assets in your plugin repository: 1. **Required Images:** * `logo.png` (400x400px) - Your plugin's square logo * `banner.png` (1280x640px) - A banner image for your plugin * `screenshot.png` - At least one screenshot demonstrating your plugin's functionality 2. **Image Location:** plugin-name/β”œβ”€β”€ assets/β”‚ β”œβ”€β”€ logo.pngβ”‚ β”œβ”€β”€ banner.pngβ”‚ └── screenshots/β”‚ β”œβ”€β”€ screenshot1.pngβ”‚ └── screenshot2.png 3. **Image Guidelines:** * Use clear, high-resolution images * Keep file sizes optimized (< 500KB for logos, < 1MB for banners) * [Image example](https://github.com/elizaos-plugins/client-twitter/blob/main/images/banner.jpg) * Include alt text for accessibility * * * Using Your Custom Plugins[​](#using-your-custom-plugins "Direct link to Using Your Custom Plugins") ---------------------------------------------------------------------------------------------------- Plugins that are not in the official registry for ElizaOS can be used as well. Here's how: ### Installation[​](#installation-1 "Direct link to Installation") 1. Upload the custom plugin to the packages folder: packages/β”œβ”€plugin-example/β”œβ”€β”€ package.jsonβ”œβ”€β”€ tsconfig.jsonβ”œβ”€β”€ src/β”‚ β”œβ”€β”€ index.ts # Main plugin entryβ”‚ β”œβ”€β”€ actions/ # Custom actionsβ”‚ β”œβ”€β”€ providers/ # Data providersβ”‚ β”œβ”€β”€ types.ts # Type definitionsβ”‚ └── environment.ts # Configurationβ”œβ”€β”€ README.md└── LICENSE 2. Add the custom plugin to your project's dependencies in the agent's package.json: { "dependencies": { "@elizaos/plugin-example": "workspace:*" }} 3. Import the custom plugin to your agent's character.json "plugins": [ "@elizaos/plugin-example", ], FAQ[​](#faq "Direct link to FAQ") ---------------------------------- ### What exactly is a plugin in ElizaOS?[​](#what-exactly-is-a-plugin-in-elizaos "Direct link to What exactly is a plugin in ElizaOS?") A plugin is a modular extension that adds new capabilities to ElizaOS agents, such as API integrations, custom actions, or platform connections. Plugins allow you to expand agent functionality and share reusable components with other developers. ### When should I create a plugin versus using existing ones?[​](#when-should-i-create-a-plugin-versus-using-existing-ones "Direct link to When should I create a plugin versus using existing ones?") Create a plugin when you need custom functionality not available in existing plugins, want to integrate with external services, or plan to share reusable agent capabilities with the community. ### What are the main types of plugin components?[​](#what-are-the-main-types-of-plugin-components "Direct link to What are the main types of plugin components?") Actions handle specific tasks, Providers supply data, Evaluators analyze responses, Services run background processes, Clients manage platform connections, and Adapters handle storage solutions. ### How do I test a plugin during development?[​](#how-do-i-test-a-plugin-during-development "Direct link to How do I test a plugin during development?") Use the mock client with `pnpm mock-eliza --characters=./characters/test.character.json` for rapid testing, then progress to platform-specific testing like web interface or Twitter integration. ### Why isn't my plugin being recognized?[​](#why-isnt-my-plugin-being-recognized "Direct link to Why isn't my plugin being recognized?") Most commonly this occurs due to missing dependencies, incorrect registration in your character file, or build configuration issues. Ensure you've run `pnpm build` and properly imported the plugin. ### Can I monetize my plugin?[​](#can-i-monetize-my-plugin "Direct link to Can I monetize my plugin?") Yes, plugins can be monetized through the ElizaOS marketplace or by offering premium features/API access, making them an effective distribution mechanism for software products. ### How do I debug plugin issues?[​](#how-do-i-debug-plugin-issues "Direct link to How do I debug plugin issues?") Enable debug logging, use the mock client for isolated testing, and check the runtime logs for detailed error messages about plugin initialization and execution. ### What's the difference between Actions and Services?[​](#whats-the-difference-between-actions-and-services "Direct link to What's the difference between Actions and Services?") Actions handle specific agent responses or behaviors, while Services provide ongoing background functionality or external API integrations that multiple actions might use. Additional Resources[​](#additional-resources "Direct link to Additional Resources") ------------------------------------------------------------------------------------- * [ElizaOS Registry](https://github.com/elizaos-plugins/registry) * [Example Plugins](https://github.com/elizaos-plugins) * [Installation](#installation) * [Architecture](#architecture) * [Environment Variables and Secrets](#environment-variables-and-secrets) * [Pull Request Requirements](#pull-request-requirements) * [Plugin Branding and Images](#plugin-branding-and-images) * [Using Your Custom Plugins](#using-your-custom-plugins) * [Installation](#installation-1) * [FAQ](#faq) * [What exactly is a plugin in ElizaOS?](#what-exactly-is-a-plugin-in-elizaos) * [When should I create a plugin versus using existing ones?](#when-should-i-create-a-plugin-versus-using-existing-ones) * [What are the main types of plugin components?](#what-are-the-main-types-of-plugin-components) * [How do I test a plugin during development?](#how-do-i-test-a-plugin-during-development) * [Why isn't my plugin being recognized?](#why-isnt-my-plugin-being-recognized) * [Can I monetize my plugin?](#can-i-monetize-my-plugin) * [How do I debug plugin issues?](#how-do-i-debug-plugin-issues) * [What's the difference between Actions and Services?](#whats-the-difference-between-actions-and-services) * [Additional Resources](#additional-resources) --- # πŸ”Œ Clients | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page Clients are core components in Eliza that enable AI agents to interact with external platforms and services. Each client provides a specialized interface for communication while maintaining consistent agent behavior across different platforms. * * * Supported Clients[​](#supported-clients "Direct link to Supported Clients") ---------------------------------------------------------------------------- | Client | Type | Key Features | Use Cases | | --- | --- | --- | --- | | [Discord](https://github.com/elizaos-plugins/client-discord) | Communication | β€’ Voice channels β€’ Server management β€’ Moderation tools β€’ Channel management | β€’ Community management β€’ Gaming servers β€’ Event coordination | | [Twitter](https://github.com/elizaos-plugins/client-twitter) | Social Media | β€’ Post scheduling β€’ Timeline monitoring β€’ Engagement analytics β€’ Content automation | β€’ Brand management β€’ Content creation β€’ Social engagement | | [Telegram](https://github.com/elizaos-plugins/client-telegram) | Messaging | β€’ Bot API β€’ Group chat β€’ Media handling β€’ Command system | β€’ Customer support β€’ Community engagement β€’ Broadcast messaging | | [Direct](https://github.com/elizaOS/eliza/tree/develop/packages/client-direct/src) | API | β€’ REST endpoints β€’ Web integration β€’ Custom applications β€’ Real-time communication | β€’ Backend integration β€’ Web apps β€’ Custom interfaces | | [GitHub](https://github.com/elizaos-plugins/client-github) | Development | β€’ Repository management β€’ Issue tracking β€’ Pull requests β€’ Code review | β€’ Development workflow β€’ Project management β€’ Team collaboration | | [Slack](https://github.com/elizaos-plugins/client-slack) | Enterprise | β€’ Channel management β€’ Conversation analysis β€’ Workspace tools β€’ Integration hooks | β€’ Team collaboration β€’ Process automation β€’ Internal tools | | [Lens](https://github.com/elizaos-plugins/client-lens) | Web3 | β€’ Decentralized networking β€’ Content publishing β€’ Memory management β€’ Web3 integration | β€’ Web3 social networking β€’ Content distribution β€’ Decentralized apps | | [Farcaster](https://github.com/elizaos-plugins/client-farcaster) | Web3 | β€’ Decentralized social β€’ Content publishing β€’ Community engagement | β€’ Web3 communities β€’ Content creation β€’ Social networking | | [Auto](https://github.com/elizaos-plugins/client-auto) | Automation | β€’ Workload management β€’ Task scheduling β€’ Process automation | β€’ Background jobs β€’ Automated tasks β€’ System maintenance | \***Additional clients**: * Instagram: Social media content and engagement * XMTP: Web3 messaging and communications * Alexa: Voice interface and smart device control * Home Assistant: Home automation OS * Devai.me: AI first social client * Simsai: Jeeter / Social media platform for AI * * * System Overview[​](#system-overview "Direct link to System Overview") ---------------------------------------------------------------------- Clients serve as bridges between Eliza agents and various platforms, providing core capabilities: 1. **Message Processing** * Platform-specific message formatting and delivery * Media handling and attachments via [`Memory`](/eliza/api/interfaces/Memory) objects * Reply threading and context management * Support for different content types 2. **State & Memory Management** * Each client maintains independent state to prevent cross-platform contamination * Integrates with runtime memory managers for different types of content: * Messages processed by one client don't automatically appear in other clients' contexts * [`State`](/eliza/api/interfaces/State) persists across agent restarts through the database adapter 3. **Platform Integration** * Authentication and API compliance * Event processing and webhooks * Rate limiting and cache management * Platform-specific feature support Client Configuration[​](#client-configuration "Direct link to Client Configuration") ------------------------------------------------------------------------------------- Clients are configured through the [`Character`](/eliza/api/type-aliases/Character) configuration's [`clientConfig`](/eliza/api/type-aliases/Character#clientconfig) property: export type Character = { // ... other properties ... clientConfig?: { discord?: { shouldIgnoreBotMessages?: boolean; shouldIgnoreDirectMessages?: boolean; shouldRespondOnlyToMentions?: boolean; messageSimilarityThreshold?: number; isPartOfTeam?: boolean; teamAgentIds?: string[]; teamLeaderId?: string; teamMemberInterestKeywords?: string[]; allowedChannelIds?: string[]; autoPost?: { enabled?: boolean; monitorTime?: number; inactivityThreshold?: number; mainChannelId?: string; announcementChannelIds?: string[]; minTimeBetweenPosts?: number; }; }; telegram?: { shouldIgnoreBotMessages?: boolean; shouldIgnoreDirectMessages?: boolean; shouldRespondOnlyToMentions?: boolean; shouldOnlyJoinInAllowedGroups?: boolean; allowedGroupIds?: string[]; messageSimilarityThreshold?: number; // ... other telegram-specific settings }; slack?: { shouldIgnoreBotMessages?: boolean; shouldIgnoreDirectMessages?: boolean; }; // ... other client configs };}; Client Implementation[​](#client-implementation "Direct link to Client Implementation") ---------------------------------------------------------------------------------------- Each client manages its own: * Platform-specific message formatting and delivery * Event processing and webhooks * Authentication and API integration * Message queueing and rate limiting * Media handling and attachments * State management and persistence Example of a basic client implementation: import { Client, IAgentRuntime, ClientInstance } from "@elizaos/core";export class CustomClient implements Client { name = "custom"; async start(runtime: IAgentRuntime): Promise { // Initialize platform connection // Set up event handlers // Configure message processing return { stop: async () => { // Cleanup resources // Close connections } }; }} ### Runtime Integration[​](#runtime-integration "Direct link to Runtime Integration") Clients interact with the agent runtime through the [`IAgentRuntime`](/eliza/docs/core/api/interfaces/IAgentRuntime) interface, which provides: * Memory managers for different types of data storage * Service access for capabilities like transcription or image generation * State management and composition * Message processing and action handling ### Memory System Integration[​](#memory-system-integration "Direct link to Memory System Integration") Clients use the runtime's memory managers to persist conversation data (source: [`memory.ts`](/eliza/api/interfaces/Memory) ). * `messageManager` Chat messages * `documentsManager` File attachments * `descriptionManager` Media descriptions See example // Store a new messageawait runtime.messageManager.createMemory({ id: messageId, content: { text: message.content }, userId: userId, roomId: roomId, agentId: runtime.agentId});// Retrieve recent messagesconst recentMessages = await runtime.messageManager.getMemories({ roomId: roomId, count: 10}); * * * Direct Client Example[​](#direct-client-example "Direct link to Direct Client Example") ---------------------------------------------------------------------------------------- The [Direct client](https://github.com/elizaOS/eliza/tree/develop/packages/client-direct) provides message processing, webhook integration, and a REST API interface for Eliza agents. It's the primary client used for testing and development. Key features of the Direct client: * Express.js server for HTTP endpoints * Agent runtime management * File upload handling * Memory system integration * WebSocket support for real-time communication ### Direct Client API Endpoints[​](#direct-client-api-endpoints "Direct link to Direct Client API Endpoints") | Endpoint | Method | Description | Params | Input | Response | | --- | --- | --- | --- | --- | --- | | `/:agentId/whisper` | POST | Audio transcription (Whisper) | `agentId` | Audio file | Transcription | | `/:agentId/message` | POST | Main message handler | `agentId` | Text, optional file | Agent response | | `/agents/:agentIdOrName/hyperfi/v1` | POST | Hyperfi game integration | `agentIdOrName` | Objects, emotes, history | JSON (`lookAt`, `emote`, `say`, actions) | | `/:agentId/image` | POST | Image generation | `agentId` | Generation params | Image(s) with captions | | `/fine-tune` | POST | Proxy for BagelDB fine-tuning | None | Fine-tuning data | BagelDB API response | | `/fine-tune/:assetId` | GET | Download fine-tuned assets | `assetId` | None | File download | | `/:agentId/speak` | POST | Text-to-speech (ElevenLabs) | `agentId` | Text | Audio stream | | `/:agentId/tts` | POST | Direct text-to-speech | `agentId` | Text | Audio stream | ### Static Routes[​](#static-routes "Direct link to Static Routes") | Endpoint | Method | Description | | --- | --- | --- | | `/media/uploads/` | GET | Serves uploaded files | | `/media/generated/` | GET | Serves generated images | ### Common Parameters[​](#common-parameters "Direct link to Common Parameters") Most endpoints accept: * `roomId` (defaults to agent-specific room) * `userId` (defaults to `"user"`) * `userName` (for identity management) * * * FAQ[​](#faq "Direct link to FAQ") ---------------------------------- ### What can clients actually do?[​](#what-can-clients-actually-do "Direct link to What can clients actually do?") Clients handle platform-specific communication (like Discord messages or Twitter posts), manage memories and state, and execute actions like processing media or handling commands. Each client adapts these capabilities to its platform while maintaining consistent agent behavior. ### Can multiple clients be used simultaneously?[​](#can-multiple-clients-be-used-simultaneously "Direct link to Can multiple clients be used simultaneously?") Yes, Eliza supports running multiple clients concurrently while maintaining consistent agent behavior across platforms. ### How are client-specific features handled?[​](#how-are-client-specific-features-handled "Direct link to How are client-specific features handled?") Each client implements platform-specific features through its capabilities system, while maintaining a consistent interface for the agent. ### How co clients handle rate limits?[​](#how-co-clients-handle-rate-limits "Direct link to How co clients handle rate limits?") Clients implement platform-specific rate limiting with backoff strategies and queue management. ### How is client state managed?[​](#how-is-client-state-managed "Direct link to How is client state managed?") Clients maintain their own connection state while integrating with the agent's runtime database adapter and memory / state management system. ### How do clients handle messages?[​](#how-do-clients-handle-messages "Direct link to How do clients handle messages?") Clients translate platform messages into Eliza's internal format, process any attachments (images, audio, etc.), maintain conversation context, and manage response queuing and rate limits. ### How are messages processed across clients?[​](#how-are-messages-processed-across-clients "Direct link to How are messages processed across clients?") Each client processes messages independently in its platform-specific format, while maintaining conversation context through the shared memory system. V2 improves upon this architecture. ### How is state managed between clients?[​](#how-is-state-managed-between-clients "Direct link to How is state managed between clients?") Each client maintains separate state to prevent cross-contamination, but can access shared agent state through the runtime. ### How do clients integrate with platforms?[​](#how-do-clients-integrate-with-platforms "Direct link to How do clients integrate with platforms?") Each client implements platform-specific authentication, API compliance, webhook handling, and follows the platform's rules for rate limiting and content formatting. ### How do clients manage memory?[​](#how-do-clients-manage-memory "Direct link to How do clients manage memory?") Clients use Eliza's memory system to track conversations, user relationships, and state, enabling context-aware responses and persistent interactions across sessions. * [Supported Clients](#supported-clients) * [System Overview](#system-overview) * [Client Configuration](#client-configuration) * [Client Implementation](#client-implementation) * [Runtime Integration](#runtime-integration) * [Memory System Integration](#memory-system-integration) * [Direct Client Example](#direct-client-example) * [Direct Client API Endpoints](#direct-client-api-endpoints) * [Static Routes](#static-routes) * [Common Parameters](#common-parameters) * [FAQ](#faq) * [What can clients actually do?](#what-can-clients-actually-do) * [Can multiple clients be used simultaneously?](#can-multiple-clients-be-used-simultaneously) * [How are client-specific features handled?](#how-are-client-specific-features-handled) * [How co clients handle rate limits?](#how-co-clients-handle-rate-limits) * [How is client state managed?](#how-is-client-state-managed) * [How do clients handle messages?](#how-do-clients-handle-messages) * [How are messages processed across clients?](#how-are-messages-processed-across-clients) * [How is state managed between clients?](#how-is-state-managed-between-clients) * [How do clients integrate with platforms?](#how-do-clients-integrate-with-platforms) * [How do clients manage memory?](#how-do-clients-manage-memory) --- # πŸ”Œ Providers | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page [Providers](/eliza/packages/core/src/providers.ts) are the sources of information for the agent. They provide data or state while acting as the agent's "senses", injecting real-time information into the agent's context. They serve as the eyes, ears, and other sensory inputs that allow the agent to perceive and interact with its environment, like a bridge between the agent and various external systems such as market data, wallet information, sentiment analysis, and temporal context. Anything that the agent knows is either coming from like the built-in context or from a provider. For more info, see the [providers API page](/eliza/api/interfaces/provider) . Here's an example of how providers work within ElizaOS: * A news provider could fetch and format news. * A computer terminal provider in a game could feed the agent information when the player is near a terminal. * A wallet provider can provide the agent with the current assets in a wallet. * A time provider injects the current date and time into the context. * * * Overview[​](#overview "Direct link to Overview") ------------------------------------------------- A provider's primary purpose is to supply dynamic contextual information that integrates with the agent's runtime. They format information for conversation templates and maintain consistent data access. For example: * **Function:** Providers run during or before an action is executed. * **Purpose:** They allow for fetching information from other APIs or services to provide different context or ways for an action to be performed. * **Example:** Before a "Mars rover action" is executed, a provider could fetch information from another API. This fetched information can then be used to enrich the context of the Mars rover action. The provider interface is defined in [types.ts](/eliza/packages/core/src/types.ts) : interface Provider { get: ( runtime: IAgentRuntime, // Which agent is calling the provider message: Memory, // Last message received state?: State // Current conversation state ) => Promise; // Returns info to inject into context} The `get` function takes: * `runtime`: The agent instance calling the provider * `message`: The last message received * `state`: Current conversation state (optional) It returns a string that gets injected into the agent's context. The function can return null if there is no reason to validate. * * * Examples[​](#examples "Direct link to Examples") ------------------------------------------------- ElizaOS providers typically fall into these categories, with examples from the ecosystem: ### System & Integration[​](#system--integration "Direct link to System & Integration") * **Time Provider**: Injects current date/time for temporal awareness * **Giphy Provider**: Provides GIF responses using Giphy API * **GitBook Provider**: Supplies documentation context from GitBook * **Topics Provider**: Caches and serves Allora Network topic information ### Blockchain & DeFi[​](#blockchain--defi "Direct link to Blockchain & DeFi") * **Wallet Provider**: Portfolio data from Zerion, balances and prices * **DePIN Provider**: Network metrics via DePINScan API * **Chain Providers**: Data from Abstract, Fuel, ICP, EVM networks * **Market Provider**: Token data from DexScreener, Birdeye APIs ### Knowledge & Data[​](#knowledge--data "Direct link to Knowledge & Data") * **DKG Provider**: OriginTrail decentralized knowledge integration * **News Provider**: Current events via NewsAPI * **Trust Provider**: Calculates and injects trust scores Visit the [ElizaOS Plugin Registry](https://github.com/elizaos-plugins/registry) for a complete list of available plugins and providers. ### Time Provider[​](#time-provider "Direct link to Time Provider") [Source: packages/plugin-bootstrap/src/providers/time.ts](/eliza/packages/plugin-bootstrap/src/providers/time.ts) Provides temporal awareness by injecting current date/time information: const timeProvider: Provider = { get: async (_runtime: IAgentRuntime, _message: Memory) => { const currentDate = new Date(); const options = { timeZone: "UTC", dateStyle: "full" as const, timeStyle: "long" as const }; const humanReadable = new Intl.DateTimeFormat("en-US", options) .format(currentDate); return `The current date and time is ${humanReadable}. Please use this as your reference for any time-based operations or responses.`; }}; ### Facts Provider[​](#facts-provider "Direct link to Facts Provider") [Source: packages/plugin-bootstrap/src/providers/facts.ts](/eliza/packages/plugin-bootstrap/src/providers/facts.ts) Manages and serves conversation facts and knowledge: const factsProvider: Provider = { get: async (runtime: IAgentRuntime, message: Memory, state?: State) => { // Get recent messages const recentMessagesData = state?.recentMessagesData?.slice(-10); const recentMessages = formatMessages({ messages: recentMessagesData, actors: state?.actorsData }); // Generate embedding for semantic search const embedding = await embed(runtime, recentMessages); const memoryManager = new MemoryManager({ runtime, tableName: "facts" }); // Retrieve relevant facts const facts = await memoryManager.getMemories({ roomId: message.roomId, count: 10, agentId: runtime.agentId }); if (facts.length === 0) return ""; const formattedFacts = formatFacts(facts); return `Key facts that ${runtime.character.name} knows:\n${formattedFacts}`; }}; ### Boredom Provider[​](#boredom-provider "Direct link to Boredom Provider") [Source: packages/plugin-bootstrap/src/providers/boredom.ts](/eliza/packages/plugin-bootstrap/src/providers/boredom.ts) Manages conversation dynamics and engagement by calculating a "boredom score". The provider helps agents maintain appropriate conversation engagement levels by analyzing recent messages (last 15 minutes) and tracking conversational dynamics through keywords and pattern detection that then generates status messages reflecting interaction quality. #### Scoring Mechanisms[​](#scoring-mechanisms "Direct link to Scoring Mechanisms") **Increases Boredom**: * Excessive punctuation * Negative or dismissive language * Repetitive conversation patterns **Decreases Boredom**: * Substantive discussion topics * Engaging questions * Research-related keywords // Sample scoring logicif (interestWords.some((word) => messageText.includes(word))) { boredomScore -= 1;} * * * FAQ[​](#faq "Direct link to FAQ") ---------------------------------- ### What's a good caching strategy for providers?[​](#whats-a-good-caching-strategy-for-providers "Direct link to What's a good caching strategy for providers?") Cache expensive operations with an appropriate TTL based on data freshness requirements - for example, the Topics Provider uses 30-minute caching. ### How should providers handle missing data?[​](#how-should-providers-handle-missing-data "Direct link to How should providers handle missing data?") Return an empty string for missing or invalid data rather than null or undefined. ### What's the best way to format provider output?[​](#whats-the-best-way-to-format-provider-output "Direct link to What's the best way to format provider output?") Keep context strings concise and consistently formatted, using clear templates when possible. ### When should I use a provider vs a service?[​](#when-should-i-use-a-provider-vs-a-service "Direct link to When should I use a provider vs a service?") Use a provider when you need to inject information into the agent's context, and a service when the functionality doesn't need to be part of the conversation. ### Can providers access service functionality?[​](#can-providers-access-service-functionality "Direct link to Can providers access service functionality?") Yes, providers can use services through the runtime. For example, a wallet provider might use a blockchain service to fetch data. ### How should providers handle failures?[​](#how-should-providers-handle-failures "Direct link to How should providers handle failures?") Providers should handle failures gracefully and return an empty string or implement retries for external API calls. Never throw errors that would break the agent's context composition. ### Can providers maintain state?[​](#can-providers-maintain-state "Direct link to Can providers maintain state?") While providers can maintain internal state, it's better to use the runtime's state management facilities for persistence. * * * Further Reading[​](#further-reading "Direct link to Further Reading") ---------------------------------------------------------------------- * [Provider Implementation](/eliza/packages/core/src/providers.ts) * [Types Reference](/eliza/packages/core/src/types.ts) * [Runtime Integration](/eliza/packages/core/src/runtime.ts) * [Overview](#overview) * [Examples](#examples) * [System & Integration](#system--integration) * [Blockchain & DeFi](#blockchain--defi) * [Knowledge & Data](#knowledge--data) * [Time Provider](#time-provider) * [Facts Provider](#facts-provider) * [Boredom Provider](#boredom-provider) * [FAQ](#faq) * [What's a good caching strategy for providers?](#whats-a-good-caching-strategy-for-providers) * [How should providers handle missing data?](#how-should-providers-handle-missing-data) * [What's the best way to format provider output?](#whats-the-best-way-to-format-provider-output) * [When should I use a provider vs a service?](#when-should-i-use-a-provider-vs-a-service) * [Can providers access service functionality?](#can-providers-access-service-functionality) * [How should providers handle failures?](#how-should-providers-handle-failures) * [Can providers maintain state?](#can-providers-maintain-state) * [Further Reading](#further-reading) --- # ⚑ Actions | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page Actions define how agents respond to and interact with messages. They enable agents to perform tasks beyond simple message responses by integrating with external systems and modifying behavior. Overview[​](#overview "Direct link to Overview") ------------------------------------------------- 1. Structure: An Action consists of: * `name`: Unique identifier * `similes`: Alternative names/triggers * `description`: Purpose and usage explanation * `validate`: Function to check if action is appropriate * `handler`: Core implementation logic * `examples`: Sample usage patterns * `suppressInitialMessage`: Optional flag to suppress initial response 2. Validation: * Checks if the action can be executed * Consider conversation state * Validate required * * * Implementation[​](#implementation "Direct link to Implementation") ------------------------------------------------------------------- interface Action { name: string; similes: string[]; description: string; examples: ActionExample[][]; handler: Handler; validate: Validator; suppressInitialMessage?: boolean;} Source: [https://github.com/elizaOS/eliza/blob/main/packages/core/src/types.ts](https://github.com/elizaOS/eliza/blob/main/packages/core/src/types.ts) ### Basic Action Template[​](#basic-action-template "Direct link to Basic Action Template") const customAction: Action = { name: "CUSTOM_ACTION", similes: ["ALTERNATE_NAME", "OTHER_TRIGGER"], description: "Detailed description of when and how to use this action", validate: async (runtime: IAgentRuntime, message: Memory) => { // Validation logic return true; }, handler: async (runtime: IAgentRuntime, message: Memory) => { // Implementation logic return true; }, examples: [ [ { user: "{{user1}}", content: { text: "Trigger message" }, }, { user: "{{user2}}", content: { text: "Response", action: "CUSTOM_ACTION" }, }, ], ],}; #### Character File Example[​](#character-file-example "Direct link to Character File Example") Actions can be used in character files as well. Here's an example from: [https://github.com/elizaOS/characters/blob/main/sbf.character.json](https://github.com/elizaOS/characters/blob/main/sbf.character.json) "messageExamples": [ [ { "user": "{{user1}}", "content": { "text": "Can you help transfer some SOL?" } }, { "user": "SBF", "content": { "text": "yeah yeah for sure, sending SOL is pretty straightforward. just need the recipient and amount. everything else is basically fine, trust me.", "action": "SEND_SOL" } } ],\ \ * * *\ \ Example Implementations[​](#example-implementations "Direct link to Example Implementations")\ \ ----------------------------------------------------------------------------------------------\ \ Actions can be found across various plugins in the Eliza ecosystem, with a comprehensive collection available at [https://github.com/elizaos-plugins](https://github.com/elizaos-plugins)\ . Here are some notable examples:\ \ ### Blockchain and Token Actions[​](#blockchain-and-token-actions "Direct link to Blockchain and Token Actions")\ \ * Transfers: `SEND_TOKEN`, `SEND_SOL`, `SEND_NEAR`, `SEND_AVAIL`, `SEND_TON`, `SEND_TOKENS`, `COSMOS_TRANSFER`, `CROSS_CHAIN_TRANSFER`\ * Token Management: `CREATE_TOKEN`, `GET_TOKEN_INFO`, `GET_BALANCE`, `GET_TOKEN_PRICE`, `TOKEN_SWAP`, `SWAP_TOKEN`, `EXECUTE_SPOT_TRADE`\ * Blockchain Interactions: `READ_CONTRACT`, `WRITE_CONTRACT`, `DEPLOY_CONTRACT`, `DEPLOY_TOKEN`, `GET_TRANSACTION`, `GET_CURRENT_NONCE`, `GET_CONTRACT_SCHEMA`\ \ ### Cryptographic and Security Actions[​](#cryptographic-and-security-actions "Direct link to Cryptographic and Security Actions")\ \ * Signature and Authentication: `ECDSA_SIGN`, `LIT_ACTION`, `REMOTE_ATTESTATION`, `AUTHENTICATE`\ * Wallet and Key Management: `ERC20_TRANSFER`, `WALLET_TRANSFER`, `BRIDGE_OPERATIONS`\ \ ### Staking and Governance[​](#staking-and-governance "Direct link to Staking and Governance")\ \ * Staking Actions: `STAKE`, `DELEGATE_TOKEN`, `UNDELEGATE_TOKEN`, `GET_STAKE_BALANCE`, `TOKENS_REDELEGATE`\ * Governance Actions: `VOTE_ON_PROPOSAL`, `PROPOSE`, `EXECUTE_PROPOSAL`, `QUEUE_PROPOSAL`\ \ ### AI and Agent Management[​](#ai-and-agent-management "Direct link to AI and Agent Management")\ \ * Agent Creation: `LAUNCH_AGENT`, `START_SESSION`, `CREATE_AND_REGISTER_AGENT`\ * AI-Specific Actions: `GENERATE_IMAGE`, `DESCRIBE_IMAGE`, `GENERATE_VIDEO`, `GENERATE_MUSIC`, `GET_INFERENCE`, `GENERATE_MEME`\ \ ### Media and Content Generation[​](#media-and-content-generation "Direct link to Media and Content Generation")\ \ * Image and Multimedia: `SEND_GIF`, `GENERATE_3D`, `GENERATE_COLLECTION`, `MINT_NFT`, `LIST_NFT`, `SWEEP_FLOOR_NFT`\ * Audio and Voice: `EXTEND_AUDIO`, `CREATE_TTS`\ \ ### Decentralized Infrastructure (DePIN)[​](#decentralized-infrastructure-depin "Direct link to Decentralized Infrastructure (DePIN)")\ \ * Project Interactions: `DEPIN_TOKENS`, `DEPIN_ON_CHAIN`, `ANALYZE_DEPIN_PROJECTS`\ \ ### Search and Information Retrieval[​](#search-and-information-retrieval "Direct link to Search and Information Retrieval")\ \ * Data Search: `WEB_SEARCH`, `GET_TOKEN_PRICE_BY_ADDRESS`, `GET_TRENDING_POOLS`, `GET_NEW_COINS`, `GET_MARKETS`\ \ ### Blockchain and Trading[​](#blockchain-and-trading "Direct link to Blockchain and Trading")\ \ * Specialized Actions: `GET_QUOTE_0X`, `EXECUTE_SWAP_0X`, `CANCEL_ORDERS`, `GET_INDICATIVE_PRICE`\ \ ### Social and Communication[​](#social-and-communication "Direct link to Social and Communication")\ \ * Platform Interactions: `TWEET`, `POST_TWEET`, `QUOTE`, `JOIN_VOICE`, `LEAVE_VOICE`, `TRANSCRIBE_MEDIA`, `SUMMARIZE_CONVERSATION`\ \ ### Utility Actions[​](#utility-actions "Direct link to Utility Actions")\ \ * General Utilities: `FAUCET`, `SUBMIT_DATA`, `PRICE_CHECK`, `WEATHER`, `NEWS`\ \ Check out the [ElizaOS Plugins org](https://github.com/elizaos-plugins)\ on GitHub if interested in studying or using any of these.\ \ ### Image Generation Action[​](#image-generation-action "Direct link to Image Generation Action")\ \ Here's a comprehensive example of an image generation action:\ \ import { Action, IAgentRuntime, Memory, State } from "@elizaos/core";// Example image generation actionconst generateImageAction: Action = { name: "GENERATE_IMAGE", similes: ["CREATE_IMAGE", "MAKE_IMAGE", "DRAW"], description: "Generates an image based on the user's description", suppressInitialMessage: true, // Suppress initial response since we'll generate our own // Validate if this action should be used validate: async (runtime: IAgentRuntime, message: Memory) => { const text = message.content.text.toLowerCase(); // Check if message contains image generation triggers return ( text.includes("generate") || text.includes("create") || text.includes("draw") || text.includes("make an image") ); }, // Handle the action execution handler: async (runtime: IAgentRuntime, message: Memory, state?: State) => { try { // Get image service const imageService = runtime.getService(ServiceType.IMAGE_GENERATION); // Generate image const imageUrl = await imageService.generateImage(message.content.text); // Create response with generated image await runtime.messageManager.createMemory({ id: generateId(), content: { text: "Here's the image I generated:", attachments: [{ type: "image", url: imageUrl }] }, userId: runtime.agentId, roomId: message.roomId, }); return true; } catch (error) { console.error("Image generation failed:", error); return false; } }, // Example usage patterns examples: [ [ { user: "{{user1}}", content: { text: "Can you generate an image of a sunset?" } }, { user: "{{user2}}", content: { text: "I'll create that image for you", action: "GENERATE_IMAGE" } } ] ]};\ \ ### Basic Conversation Actions[​](#basic-conversation-actions "Direct link to Basic Conversation Actions")\ \ You can find these samples in the plugin-bootstrap package: [https://github.com/elizaOS/eliza/tree/main/packages/plugin-bootstrap/src/actions](https://github.com/elizaOS/eliza/tree/main/packages/plugin-bootstrap/src/actions)\ \ #### CONTINUE[​](#continue "Direct link to CONTINUE")\ \ For continuing conversations:\ \ const continueAction: Action = { name: "CONTINUE", similes: ["ELABORATE", "GO_ON"], description: "Continues the conversation when appropriate", validate: async (runtime: IAgentRuntime, message: Memory) => { // Check if message warrants continuation const text = message.content.text.toLowerCase(); return ( text.includes("tell me more") || text.includes("what else") || text.includes("continue") || text.endsWith("?") ); }, handler: async (runtime: IAgentRuntime, message: Memory, state?: State) => { // Get recent conversation context const recentMessages = await runtime.messageManager.getMemories({ roomId: message.roomId, count: 5 }); // Generate contextual response const response = await runtime.generateResponse( message, recentMessages, state ); // Store response await runtime.messageManager.createMemory({ id: generateId(), content: response, userId: runtime.agentId, roomId: message.roomId }); return true; }, examples: [ [ { user: "{{user1}}", content: { text: "Tell me more about that" } }, { user: "{{user2}}", content: { text: "I'll continue explaining...", action: "CONTINUE" } } ] ]};\ \ #### IGNORE[​](#ignore "Direct link to IGNORE")\ \ For ending conversations:\ \ const ignoreAction: Action = { name: "IGNORE", similes: ["STOP_TALKING", "END_CONVERSATION"], description: "Stops responding when conversation is complete or irrelevant", validate: async (runtime: IAgentRuntime, message: Memory) => { const text = message.content.text.toLowerCase(); return ( text.includes("goodbye") || text.includes("bye") || text.includes("thanks") || text.length < 2 ); }, handler: async (runtime: IAgentRuntime, message: Memory) => { // No response needed return true; }, examples: [ [ { user: "{{user1}}", content: { text: "Thanks, goodbye!" } }, { user: "{{user2}}", content: { text: "", action: "IGNORE" } } ] ]};\ \ * * *\ \ FAQ[​](#faq "Direct link to FAQ")\ \ ----------------------------------\ \ ### What are Actions in Eliza?[​](#what-are-actions-in-eliza "Direct link to What are Actions in Eliza?")\ \ Actions are core building blocks that define how agents interact with messages and perform tasks beyond simple text responses.\ \ ### How do Actions work?[​](#how-do-actions-work "Direct link to How do Actions work?")\ \ Actions consist of a name, description, validation function, and handler function that determine when and how an agent can perform a specific task.\ \ ### What can Actions do?[​](#what-can-actions-do "Direct link to What can Actions do?")\ \ Actions enable agents to interact with external systems, modify behavior, process complex workflows, and extend capabilities beyond conversational responses.\ \ ### What are some example Actions?[​](#what-are-some-example-actions "Direct link to What are some example Actions?")\ \ Common actions include CONTINUE (extend dialogue), IGNORE (end conversation), GENERATE\_IMAGE (create images), TRANSFER (move tokens), and READ\_CONTRACT (retrieve blockchain data).\ \ ### How do I create a custom Action?[​](#how-do-i-create-a-custom-action "Direct link to How do I create a custom Action?")\ \ Define an action with a unique name, validation function to check eligibility, handler function to implement the logic, and provide usage examples.\ \ ### What makes a good Action?[​](#what-makes-a-good-action "Direct link to What makes a good Action?")\ \ A good action has a clear, single purpose, robust input validation, comprehensive error handling, and provides meaningful interactions.\ \ ### Can Actions be chained together?[​](#can-actions-be-chained-together "Direct link to Can Actions be chained together?")\ \ Yes, actions can be composed and chained to create complex workflows and multi-step interactions.\ \ ### How are Actions different from tools?[​](#how-are-actions-different-from-tools "Direct link to How are Actions different from tools?")\ \ Actions are more comprehensive, ensuring the entire process happens, while tools are typically more focused on specific, discrete operations.\ \ ### Where are Actions defined?[​](#where-are-actions-defined "Direct link to Where are Actions defined?")\ \ Actions can be defined in character files, plugins, or directly in agent configurations.\ \ Further Reading[​](#further-reading "Direct link to Further Reading")\ \ ----------------------------------------------------------------------\ \ * [characterfile](/eliza/docs/core/characterfile)\ \ * [providers](/eliza/docs/core/providers)\ \ \ * [Overview](#overview)\ \ * [Implementation](#implementation)\ * [Basic Action Template](#basic-action-template)\ \ * [Example Implementations](#example-implementations)\ * [Blockchain and Token Actions](#blockchain-and-token-actions)\ \ * [Cryptographic and Security Actions](#cryptographic-and-security-actions)\ \ * [Staking and Governance](#staking-and-governance)\ \ * [AI and Agent Management](#ai-and-agent-management)\ \ * [Media and Content Generation](#media-and-content-generation)\ \ * [Decentralized Infrastructure (DePIN)](#decentralized-infrastructure-depin)\ \ * [Search and Information Retrieval](#search-and-information-retrieval)\ \ * [Blockchain and Trading](#blockchain-and-trading)\ \ * [Social and Communication](#social-and-communication)\ \ * [Utility Actions](#utility-actions)\ \ * [Image Generation Action](#image-generation-action)\ \ * [Basic Conversation Actions](#basic-conversation-actions)\ \ * [FAQ](#faq)\ * [What are Actions in Eliza?](#what-are-actions-in-eliza)\ \ * [How do Actions work?](#how-do-actions-work)\ \ * [What can Actions do?](#what-can-actions-do)\ \ * [What are some example Actions?](#what-are-some-example-actions)\ \ * [How do I create a custom Action?](#how-do-i-create-a-custom-action)\ \ * [What makes a good Action?](#what-makes-a-good-action)\ \ * [Can Actions be chained together?](#can-actions-be-chained-together)\ \ * [How are Actions different from tools?](#how-are-actions-different-from-tools)\ \ * [Where are Actions defined?](#where-are-actions-defined)\ \ * [Further Reading](#further-reading) --- # πŸ“Š Evaluators | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page [Evaluators](/eliza/api/interfaces/evaluator) are core components that assess and extract information from conversations. Agents use evaluators to automatically process conversations after they happen to help build up their knowledge and understanding over time. They integrate with the [`AgentRuntime`](/eliza/api/classes/AgentRuntime) evaluation system to enable reflection, fact-gathering, and behavioral adaptation and run after each agent action to help maintain contextural awareness. Enabling agents to reflect on their actions and world state is crucial for improving coherence and problem-solving abilities. For example, by reflecting on its performance, an agent can refine its strategies and improve its interactions over time. * * * How They Work[​](#how-they-work "Direct link to How They Work") ---------------------------------------------------------------- Evaluators run automatically after each agent action (responses, messages, activities, or API calls) to analyze what happened and update the agent's understanding. They extract important information (like facts about users), track progress on goals, and learn from interactions. Let's say you're at a party and meet someone new. During the conversation: * You learn their name is Sarah * They mention living in Seattle * They work as a software engineer After the conversation, your brain: * Stores these facts for later * Updates your understanding of who Sarah is * Might note "I should connect Sarah with Bob who's also in tech" This is exactly how evaluators work for agents - they run in the background to extract insights, track progress, and build up the agent's knowledge over time. However there are some limitations, such as evaluators only process current interactions (can't modify past data), they run after actions complete (not during). Therefore evaluators are best for analysis rather than critical operations. The key thing to remember is: evaluators are your agent's way of learning and growing from each interaction, just like how we naturally process and learn from our conversations. ### Common Uses[​](#common-uses "Direct link to Common Uses") * **[Fact Evaluator](https://github.com/elizaOS/eliza/blob/main/packages/plugin-bootstrap/src/evaluators/fact.ts) **: Learns and remembers facts about users * **[Goal Evaluator](https://raw.githubusercontent.com/elizaOS/eliza/refs/heads/main/packages/plugin-bootstrap/src/evaluators/goal.ts) **: Tracks progress on objectives * **Trust Evaluator**: Builds understanding of relationships * **Sentiment Evaluator**: Tracks emotional tone of conversations * * * Implementation[​](#implementation "Direct link to Implementation") ------------------------------------------------------------------- Here's a basic example of an evaluator implementation: const evaluator = { // Should this evaluator run right now? validate: async (runtime, message) => { // Return true to run, false to skip return shouldRunThisTime; }, // What to do when it runs handler: async (runtime, message) => { // Extract info, update memory, etc const newInfo = extractFromMessage(message); await storeInMemory(newInfo); }}; ### Core Interface[​](#core-interface "Direct link to Core Interface") interface Evaluator { name: string; // Unique identifier similes: string[]; // Similar evaluator descriptions description: string; // Purpose and functionality validate: (runtime: IAgentRuntime, message: Memory) => Promise; handler: (runtime: IAgentRuntime, message: Memory) => Promise; examples: EvaluatorExample[];} For full type definitions, see the [`Evaluator`](/eliza/api/interfaces/Evaluator) interface documentation. ### Validation Function[​](#validation-function "Direct link to Validation Function") The `validate` function is critical for determining when an evaluator should run. For peak performance, proper validation ensures evaluators run only when necessary. For instance, a customer service agent might check if all required user data has been collected and only run if data is still missing. validate: async (runtime: IAgentRuntime, message: Memory) => boolean Determines if evaluator should run for current message. Returns true to execute handler, false to skip. Should be efficient and quick to check. ### Handler Function[​](#handler-function "Direct link to Handler Function") The handler function contains the evaluator's code. It is where the logic for analyzing data, extracting information, and triggering actions resides. handler: async (runtime: IAgentRuntime, message: Memory) => any Contains main evaluation logic and runs when validate() returns true. Can access [`runtime`](/eliza/api/interfaces/IAgentRuntime) services and [`memory`](/eliza/api/interfaces/Memory) . tip **Ensure Evaluators are unique and lightweight** Avoid complex operations or lengthy computations within the evaluator's handler function and ensure that evaluators have clear and distinct responsibilities not already handled by other components for peak performance. ### Memory Integration[​](#memory-integration "Direct link to Memory Integration") Results are stored using runtime memory managers: // Example storing evaluation results const memory = await runtime.memoryManager.addEmbeddingToMemory({ userId: user?.id, content: { text: evaluationResult }, roomId: roomId, embedding: await embed(runtime, evaluationResult)});await runtime.memoryManager.createMemory(memory); * * * Fact Evaluator[​](#fact-evaluator "Direct link to Fact Evaluator") ------------------------------------------------------------------- Deep Dive For a comprehensive guide on how the fact evaluator system works, including implementation details and best practices, check out our [Fact Evaluator Guide](/eliza/docs/core/fact-evaluator) . The Fact Evaluator is one of the most powerful built-in evaluators. It processes convos to: * Extract meaningful facts and opinions about users and the world * Distinguish between permanent facts, opinions, and status * Track what information is already known vs new information * Build up the agent's understanding over time through embeddings and memory storage Facts are stored with the following structure: interface Fact { claim: string; // The actual information extracted type: "fact" | "opinion" | "status"; // Classification of the information in_bio: boolean; // Whether this info is already in the agent's knowledge already_known: boolean; // Whether this was previously extracted} #### Example Facts[​](#example-facts "Direct link to Example Facts") Here's an example of extracted facts from a conversation: User: I finally finished my marathon training program!Agent: That's a huge accomplishment! How do you feel about it?User: I'm really proud of what I achieved. It was tough but worth it.Agent: What's next for you?User: I'm actually training for a triathlon now. It's a whole new challenge. const extractedFacts = [ { "claim": "User completed marathon training", "type": "fact", // Permanent info / achievement "in_bio": false, "already_known": false // Prevents duplicate storage }, { "claim": "User feels proud of their achievement", "type": "opinion", // Subjective views or feelings "in_bio": false, "already_known": false }, { "claim": "User is currently training for a triathlon", "type": "status", // Ongoing activity, changeable "in_bio": false, "already_known": false }]; View Full Fact Evaluator Implementation import { composeContext } from "@elizaos/core";import { generateObjectArray } from "@elizaos/core";import { MemoryManager } from "@elizaos/core";import { type ActionExample, type IAgentRuntime, type Memory, ModelClass, type Evaluator,} from "@elizaos/core";export const formatFacts = (facts: Memory[]) => { const messageStrings = facts .reverse() .map((fact: Memory) => fact.content.text); const finalMessageStrings = messageStrings.join("\n"); return finalMessageStrings;};const factsTemplate = // {{actors}} `TASK: Extract Claims from the conversation as an array of claims in JSON format.# START OF EXAMPLESThese are examples of the expected output of this task:{{evaluationExamples}}# END OF EXAMPLES# INSTRUCTIONSExtract any claims from the conversation that are not already present in the list of known facts above:- Try not to include already-known facts. If you think a fact is already known, but you're not sure, respond with already_known: true.- If the fact is already in the user's description, set in_bio to true- If we've already extracted this fact, set already_known to true- Set the claim type to 'status', 'fact' or 'opinion'- For true facts about the world or the character that do not change, set the claim type to 'fact'- For facts that are true but change over time, set the claim type to 'status'- For non-facts, set the type to 'opinion'- 'opinion' includes non-factual opinions and also includes the character's thoughts, feelings, judgments or recommendations- Include any factual detail, including where the user lives, works, or goes to school, what they do for a living, their hobbies, and any other relevant informationRecent Messages:{{recentMessages}}Response should be a JSON object array inside a JSON markdown block. Correct response format:\`\`\`json[ {"claim": string, "type": enum, in_bio: boolean, already_known: boolean }, {"claim": string, "type": enum, in_bio: boolean, already_known: boolean }, ...]\`\`\``;async function handler(runtime: IAgentRuntime, message: Memory) { const state = await runtime.composeState(message); const { agentId, roomId } = state; const context = composeContext({ state, template: runtime.character.templates?.factsTemplate || factsTemplate, }); const facts = await generateObjectArray({ runtime, context, modelClass: ModelClass.LARGE, }); const factsManager = new MemoryManager({ runtime, tableName: "facts", }); if (!facts) { return []; } // If the fact is known or corrupted, remove it const filteredFacts = facts .filter((fact) => { return ( !fact.already_known && fact.type === "fact" && !fact.in_bio && fact.claim && fact.claim.trim() !== "" ); }) .map((fact) => fact.claim); for (const fact of filteredFacts) { const factMemory = await factsManager.addEmbeddingToMemory({ userId: agentId!, agentId, content: { text: fact }, roomId, createdAt: Date.now(), }); await factsManager.createMemory(factMemory, true); await new Promise((resolve) => setTimeout(resolve, 250)); } return filteredFacts;}export const factEvaluator: Evaluator = { name: "GET_FACTS", similes: [ "GET_CLAIMS", "EXTRACT_CLAIMS", "EXTRACT_FACTS", "EXTRACT_CLAIM", "EXTRACT_INFORMATION", ], validate: async ( runtime: IAgentRuntime, message: Memory ): Promise => { const messageCount = (await runtime.messageManager.countMemories( message.roomId )) as number; const reflectionCount = Math.ceil(runtime.getConversationLength() / 2); return messageCount % reflectionCount === 0; }, description: "Extract factual information about the people in the conversation, the current events in the world, and anything else that might be important to remember.", handler, examples: [ { context: `Actors in the scene:{{user1}}: Programmer and moderator of the local story club.{{user2}}: New member of the club. Likes to write and read.Facts about the actors:None`, messages: [ { user: "{{user1}}", content: { text: "So where are you from" }, }, { user: "{{user2}}", content: { text: "I'm from the city" }, }, { user: "{{user1}}", content: { text: "Which city?" }, }, { user: "{{user2}}", content: { text: "Oakland" }, }, { user: "{{user1}}", content: { text: "Oh, I've never been there, but I know it's in California", }, }, ] as ActionExample[], outcome: `{ "claim": "{{user2}} is from Oakland", "type": "fact", "in_bio": false, "already_known": false },`, }, { context: `Actors in the scene:{{user1}}: Athelete and cyclist. Worked out every day for a year to prepare for a marathon.{{user2}}: Likes to go to the beach and shop.Facts about the actors:{{user1}} and {{user2}} are talking about the marathon{{user1}} and {{user2}} have just started dating`, messages: [ { user: "{{user1}}", content: { text: "I finally completed the marathon this year!", }, }, { user: "{{user2}}", content: { text: "Wow! How long did it take?" }, }, { user: "{{user1}}", content: { text: "A little over three hours." }, }, { user: "{{user1}}", content: { text: "I'm so proud of myself." }, }, ] as ActionExample[], outcome: `Claims:json\`\`\`[ { "claim": "Alex just completed a marathon in just under 4 hours.", "type": "fact", "in_bio": false, "already_known": false }, { "claim": "Alex worked out 2 hours a day at the gym for a year.", "type": "fact", "in_bio": true, "already_known": false }, { "claim": "Alex is really proud of himself.", "type": "opinion", "in_bio": false, "already_known": false }]\`\`\``, }, { context: `Actors in the scene:{{user1}}: Likes to play poker and go to the park. Friends with Eva.{{user2}}: Also likes to play poker. Likes to write and read.Facts about the actors:Mike and Eva won a regional poker tournament about six months agoMike is married to AlexEva studied Philosophy before switching to Computer Science`, messages: [ { user: "{{user1}}", content: { text: "Remember when we won the regional poker tournament last spring", }, }, { user: "{{user2}}", content: { text: "That was one of the best days of my life", }, }, { user: "{{user1}}", content: { text: "It really put our poker club on the map", }, }, ] as ActionExample[], outcome: `Claims:json\`\`\`[ { "claim": "Mike and Eva won the regional poker tournament last spring", "type": "fact", "in_bio": false, "already_known": true }, { "claim": "Winning the regional poker tournament put the poker club on the map", "type": "opinion", "in_bio": false, "already_known": false }]\`\`\``, }, ],}; Source: [https://github.com/elizaOS/eliza/blob/main/packages/plugin-bootstrap/src/evaluators/fact.ts](https://github.com/elizaOS/eliza/blob/main/packages/plugin-bootstrap/src/evaluators/fact.ts) Goal Evaluator[​](#goal-evaluator "Direct link to Goal Evaluator") ------------------------------------------------------------------- The Goal Evaluator tracks progress on conversation objectives by analyzing messages and updating goal status. Goals are structured like this: interface Goal { id: string; name: string; status: "IN_PROGRESS" | "DONE" | "FAILED"; objectives: Objective[];} #### Example Goals[​](#example-goals "Direct link to Example Goals") Here's how the goal evaluator processes a conversation: // Initial goal stateconst goal = { id: "book-club-123", name: "Complete reading assignment", status: "IN_PROGRESS", objectives: [ { description: "Read chapters 1-3", completed: false }, { description: "Take chapter notes", completed: false }, { description: "Share thoughts in book club", completed: false } ]};// Conversation happensconst conversation = `User: I finished reading the first three chapters last nightAgent: Great! Did you take any notes while reading?User: Yes, I made detailed notes about the main charactersAgent: Perfect, we can discuss those in the club meetingUser: I'm looking forward to sharing my thoughts tomorrow`;// Goal evaluator updates the goal statusconst updatedGoal = { id: "book-club-123", name: "Complete reading assignment", status: "IN_PROGRESS", // Still in progress objectives: [ { description: "Read chapters 1-3", completed: true }, // Marked complete { description: "Take chapter notes", completed: true }, // Marked complete { description: "Share thoughts in book club", completed: false } // Still pending ]};// After the book club meeting, goal would be marked DONE// If user can't complete objectives, goal could be marked FAILED View Full Goal Evaluator Implementation import { composeContext } from "@elizaos/core";import { generateText } from "@elizaos/core";import { getGoals } from "@elizaos/core";import { parseJsonArrayFromText } from "@elizaos/core";import { type IAgentRuntime, type Memory, ModelClass, type Objective, type Goal, type State, type Evaluator,} from "@elizaos/core";const goalsTemplate = `TASK: Update GoalAnalyze the conversation and update the status of the goals based on the new information provided.# INSTRUCTIONS- Review the conversation and identify any progress towards the objectives of the current goals.- Update the objectives if they have been completed or if there is new information about them.- Update the status of the goal to 'DONE' if all objectives are completed.- If no progress is made, do not change the status of the goal.# START OF ACTUAL TASK INFORMATION{{goals}}{{recentMessages}}TASK: Analyze the conversation and update the status of the goals based on the new information provided. Respond with a JSON array of goals to update.- Each item must include the goal ID, as well as the fields in the goal to update.- For updating objectives, include the entire objectives array including unchanged fields.- Only include goals which need to be updated.- Goal status options are 'IN_PROGRESS', 'DONE' and 'FAILED'. If the goal is active it should always be 'IN_PROGRESS'.- If the goal has been successfully completed, set status to DONE. If the goal cannot be completed, set status to FAILED.- If those goal is still in progress, do not include the status field.Response format should be:\`\`\`json[ { "id": , // required "status": "IN_PROGRESS" | "DONE" | "FAILED", // optional "objectives": [ // optional { "description": "Objective description", "completed": true | false }, { "description": "Objective description", "completed": true | false } ] // NOTE: If updating objectives, include the entire objectives array including unchanged fields. }]\`\`\``;async function handler( runtime: IAgentRuntime, message: Memory, state: State | undefined, options: { [key: string]: unknown } = { onlyInProgress: true }): Promise { state = (await runtime.composeState(message)) as State; const context = composeContext({ state, template: runtime.character.templates?.goalsTemplate || goalsTemplate, }); // Request generateText from OpenAI to analyze conversation and suggest goal updates const response = await generateText({ runtime, context, modelClass: ModelClass.LARGE, }); // Parse the JSON response to extract goal updates const updates = parseJsonArrayFromText(response); // get goals const goalsData = await getGoals({ runtime, roomId: message.roomId, onlyInProgress: options.onlyInProgress as boolean, }); // Apply the updates to the goals const updatedGoals = goalsData .map((goal: Goal): Goal => { const update = updates?.find((u) => u.id === goal.id); if (update) { // Merge the update into the existing goal return { ...goal, ...update, objectives: goal.objectives.map((objective) => { const updatedObjective = update.objectives?.find(uo => uo.description === objective.description); return updatedObjective ? { ...objective, ...updatedObjective } : objective; }), }; } return null; // No update for this goal }) .filter(Boolean); // Update goals in the database for (const goal of updatedGoals) { const id = goal.id; // delete id from goal if (goal.id) delete goal.id; await runtime.databaseAdapter.updateGoal({ ...goal, id }); } return updatedGoals; // Return updated goals for further processing or logging}export const goalEvaluator: Evaluator = { name: "UPDATE_GOAL", similes: [ "UPDATE_GOALS", "EDIT_GOAL", "UPDATE_GOAL_STATUS", "UPDATE_OBJECTIVES", ], validate: async ( runtime: IAgentRuntime, message: Memory ): Promise => { // Check if there are active goals that could potentially be updated const goals = await getGoals({ runtime, count: 1, onlyInProgress: true, roomId: message.roomId, }); return goals.length > 0; }, description: "Analyze the conversation and update the status of the goals based on the new information provided.", handler, examples: [ { context: `Actors in the scene: {{user1}}: An avid reader and member of a book club. {{user2}}: The organizer of the book club. Goals: - Name: Finish reading "War and Peace" id: 12345-67890-12345-67890 Status: IN_PROGRESS Objectives: - Read up to chapter 20 by the end of the month - Discuss the first part in the next meeting`, messages: [ { user: "{{user1}}", content: { text: "I've just finished chapter 20 of 'War and Peace'", }, }, { user: "{{user2}}", content: { text: "Were you able to grasp the complexities of the characters", }, }, { user: "{{user1}}", content: { text: "Yep. I've prepared some notes for our discussion", }, }, ], outcome: `[ { "id": "12345-67890-12345-67890", "status": "DONE", "objectives": [ { "description": "Read up to chapter 20 by the end of the month", "completed": true }, { "description": "Prepare notes for the next discussion", "completed": true } ] } ]`, }, { context: `Actors in the scene: {{user1}}: A fitness enthusiast working towards a marathon. {{user2}}: A personal trainer. Goals: - Name: Complete a marathon id: 23456-78901-23456-78901 Status: IN_PROGRESS Objectives: - Increase running distance to 30 miles a week - Complete a half-marathon as practice`, messages: [ { user: "{{user1}}", content: { text: "I managed to run 30 miles this week" }, }, { user: "{{user2}}", content: { text: "Impressive progress! How do you feel about the half-marathon next month?", }, }, { user: "{{user1}}", content: { text: "I feel confident. The training is paying off.", }, }, ], outcome: `[ { "id": "23456-78901-23456-78901", "objectives": [ { "description": "Increase running distance to 30 miles a week", "completed": true }, { "description": "Complete a half-marathon as practice", "completed": false } ] } ]`, }, { context: `Actors in the scene: {{user1}}: A student working on a final year project. {{user2}}: The project supervisor. Goals: - Name: Finish the final year project id: 34567-89012-34567-89012 Status: IN_PROGRESS Objectives: - Submit the first draft of the thesis - Complete the project prototype`, messages: [ { user: "{{user1}}", content: { text: "I've submitted the first draft of my thesis.", }, }, { user: "{{user2}}", content: { text: "Well done. How is the prototype coming along?", }, }, { user: "{{user1}}", content: { text: "It's almost done. I just need to finalize the testing phase.", }, }, ], outcome: `[ { "id": "34567-89012-34567-89012", "objectives": [ { "description": "Submit the first draft of the thesis", "completed": true }, { "description": "Complete the project prototype", "completed": false } ] } ]`, }, { context: `Actors in the scene: {{user1}}: A project manager working on a software development project. {{user2}}: A software developer in the project team. Goals: - Name: Launch the new software version id: 45678-90123-45678-90123 Status: IN_PROGRESS Objectives: - Complete the coding for the new features - Perform comprehensive testing of the software`, messages: [ { user: "{{user1}}", content: { text: "How's the progress on the new features?", }, }, { user: "{{user2}}", content: { text: "We've encountered some unexpected challenges and are currently troubleshooting.", }, }, { user: "{{user1}}", content: { text: "Let's move on and cancel the task.", }, }, ], outcome: `[ { "id": "45678-90123-45678-90123", "status": "FAILED" ]`, }, ],}; Source: [https://github.com/elizaOS/eliza/blob/main/packages/plugin-bootstrap/src/evaluators/goals.ts](https://github.com/elizaOS/eliza/blob/main/packages/plugin-bootstrap/src/evaluators/goals.ts) * * * FAQ[​](#faq "Direct link to FAQ") ---------------------------------- ### How do evaluators differ from providers?[​](#how-do-evaluators-differ-from-providers "Direct link to How do evaluators differ from providers?") While [providers](/eliza/api/interfaces/Provider) supply data to the agent before responses, evaluators analyze conversations after responses. Providers inform decisions, evaluators learn from outcomes. ### Can evaluators modify agent behavior?[​](#can-evaluators-modify-agent-behavior "Direct link to Can evaluators modify agent behavior?") Evaluators can influence future behavior by storing insights in memory, but cannot directly modify agent responses or interrupt ongoing actions. ### How many evaluators can run simultaneously?[​](#how-many-evaluators-can-run-simultaneously "Direct link to How many evaluators can run simultaneously?") There's no hard limit, but each evaluator adds processing overhead. Focus on essential evaluations and use efficient validation to optimize performance. ### Can evaluators communicate with each other?[​](#can-evaluators-communicate-with-each-other "Direct link to Can evaluators communicate with each other?") Evaluators don't directly communicate but can share data through the memory system. One evaluator can read insights stored by another. ### How are evaluation results persisted?[​](#how-are-evaluation-results-persisted "Direct link to How are evaluation results persisted?") Results are stored using the runtime's memory managers with embeddings for efficient retrieval. See the [`IMemoryManager`](/eliza/api/interfaces/IMemoryManager) interface for details. ### What's the difference between similes and examples in evaluators?[​](#whats-the-difference-between-similes-and-examples-in-evaluators "Direct link to What's the difference between similes and examples in evaluators?") Similes provide alternative descriptions of the evaluator's purpose, while examples show concrete scenarios with inputs and expected outcomes. Examples help verify correct implementation. ### Can evaluators be conditionally enabled?[​](#can-evaluators-be-conditionally-enabled "Direct link to Can evaluators be conditionally enabled?") Yes, use the validation function to control when evaluators run. This can be based on message content, user status, or other runtime conditions. * [How They Work](#how-they-work) * [Common Uses](#common-uses) * [Implementation](#implementation) * [Core Interface](#core-interface) * [Validation Function](#validation-function) * [Handler Function](#handler-function) * [Memory Integration](#memory-integration) * [Fact Evaluator](#fact-evaluator) * [Goal Evaluator](#goal-evaluator) * [FAQ](#faq) * [How do evaluators differ from providers?](#how-do-evaluators-differ-from-providers) * [Can evaluators modify agent behavior?](#can-evaluators-modify-agent-behavior) * [How many evaluators can run simultaneously?](#how-many-evaluators-can-run-simultaneously) * [Can evaluators communicate with each other?](#can-evaluators-communicate-with-each-other) * [How are evaluation results persisted?](#how-are-evaluation-results-persisted) * [What's the difference between similes and examples in evaluators?](#whats-the-difference-between-similes-and-examples-in-evaluators) * [Can evaluators be conditionally enabled?](#can-evaluators-be-conditionally-enabled) --- # Part 1: Introduction and Foundations | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page In this first session of the AI Agent Dev School, we dive into the fundamentals of AI agent development using the Eliza framework. The session covers the history and evolution of JavaScript, TypeScript, and the Node.js ecosystem, providing a solid foundation for understanding the tools and technologies used in building AI agents with Eliza. Origins and Ecosystem[​](#origins-and-ecosystem "Direct link to Origins and Ecosystem") ---------------------------------------------------------------------------------------- ### JavaScript and Its Evolution[​](#javascript-and-its-evolution "Direct link to JavaScript and Its Evolution") * JavaScript was initially created as a simple scripting language for web browsers in 1995 by Brendan Eich. * It has since evolved into a versatile language capable of running on servers with the introduction of Node.js, which leverages the V8 JavaScript engine. ### TypeScript for Type Safety[​](#typescript-for-type-safety "Direct link to TypeScript for Type Safety") * TypeScript is a superset of JavaScript that introduces optional static typing, providing compile-time type checking and improved developer experience. * It addresses JavaScript's lack of type safety while maintaining flexibility and compatibility with existing JavaScript code. ### The Power of npm (Node Package Manager)[​](#the-power-of-npm-node-package-manager "Direct link to The Power of npm (Node Package Manager)") * npm is a vast ecosystem of pre-built JavaScript packages that facilitate rapid development and code reuse. * With millions of packages available, developers can easily incorporate external libraries into their projects using the `npm install` command. * The open-source nature of the npm ecosystem allows developers to leverage the collective efforts of the community and build upon existing code. ### Monorepos in Eliza Development[​](#monorepos-in-eliza-development "Direct link to Monorepos in Eliza Development") * Eliza utilizes a monorepo structure, where multiple packages or projects are contained within a single repository. * Monorepos offer advantages such as simplified management, easier collaboration, and the ability to share code between packages. ### Git and GitHub for Collaboration[​](#git-and-github-for-collaboration "Direct link to Git and GitHub for Collaboration") * Git is a distributed version control system that enables collaborative software development by tracking changes in code. * GitHub is a web-based hosting service built on top of Git, providing features like issue tracking, pull requests, and wikis for effective collaboration and project management. Characters, Embeddings, and Discord Integration[​](#characters-embeddings-and-discord-integration "Direct link to Characters, Embeddings, and Discord Integration") -------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Embedding Models[​](#embedding-models "Direct link to Embedding Models") * Embedding models play a crucial role in converting words or concepts into numerical vectors, capturing semantic meaning and enabling tasks like semantic search and comparison. * These models transform textual data into multi-dimensional vectors, allowing for efficient representation and analysis of language. ### Creating Custom Characters in Eliza[​](#creating-custom-characters-in-eliza "Direct link to Creating Custom Characters in Eliza") * Eliza allows developers to create custom AI characters with distinct personalities and behaviors. * Character definitions are specified using JSON files, which include details like the character's bio, example dialogue, and configuration options. * The flexibility of character customization enables tailoring agents for specific platforms and use cases. ### Integrating Discord Clients[​](#integrating-discord-clients "Direct link to Integrating Discord Clients") * Eliza provides seamless integration with Discord, allowing AI characters to interact with users on the popular communication platform. * Setting up a Discord client involves configuring API keys, managing server permissions, and defining the character's behavior within the Discord environment. ### Key Concepts in Eliza[​](#key-concepts-in-eliza "Direct link to Key Concepts in Eliza") * System Directives: Special instructions that guide the agent's overall behavior and decision-making process. * Message Examples: Sample dialogues that demonstrate the desired communication style and tone of the AI character. * Style Directions: Additional instructions that influence the agent's personality, vocabulary, and interaction style. Database, Clients, and Templates[​](#database-clients-and-templates "Direct link to Database, Clients, and Templates") ----------------------------------------------------------------------------------------------------------------------- ### Eliza's Database and Memory Management[​](#elizas-database-and-memory-management "Direct link to Eliza's Database and Memory Management") * Eliza utilizes a database system to store and manage data related to the AI agents, their interactions, and user information. * The default database file is located within the Eliza project structure, but alternative database systems can be configured based on specific requirements. ### Clients in Eliza[​](#clients-in-eliza "Direct link to Clients in Eliza") * Clients in Eliza refer to the various platforms and communication channels through which AI agents can interact with users. * Existing clients include Discord, Twitter, and Telegram, each with its own set of features and integration requirements. * Developers can create custom clients to extend Eliza's capabilities and support additional platforms or services. ### Eliza's Template System[​](#elizas-template-system "Direct link to Eliza's Template System") * Eliza employs a template system to structure and generate agent responses dynamically. * Templates allow for the incorporation of variables, conditional logic, and other dynamic elements to create more engaging and context-aware interactions. * The template system enables developers to define reusable patterns and customize agent responses based on various factors like user input, context, and character traits. By understanding these foundational concepts and components of the Eliza framework, developers can begin their journey into building sophisticated and interactive AI agents. The subsequent sessions of the AI Agent Dev School will delve deeper into advanced topics and practical implementation techniques. * [Origins and Ecosystem](#origins-and-ecosystem) * [JavaScript and Its Evolution](#javascript-and-its-evolution) * [TypeScript for Type Safety](#typescript-for-type-safety) * [The Power of npm (Node Package Manager)](#the-power-of-npm-node-package-manager) * [Monorepos in Eliza Development](#monorepos-in-eliza-development) * [Git and GitHub for Collaboration](#git-and-github-for-collaboration) * [Characters, Embeddings, and Discord Integration](#characters-embeddings-and-discord-integration) * [Embedding Models](#embedding-models) * [Creating Custom Characters in Eliza](#creating-custom-characters-in-eliza) * [Integrating Discord Clients](#integrating-discord-clients) * [Key Concepts in Eliza](#key-concepts-in-eliza) * [Database, Clients, and Templates](#database-clients-and-templates) * [Eliza's Database and Memory Management](#elizas-database-and-memory-management) * [Clients in Eliza](#clients-in-eliza) * [Eliza's Template System](#elizas-template-system) --- # Part 2: Deep Dive into Actions, Providers, and Evaluators | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) In this second session of the AI Agent Dev School series, we take a deep dive into the key abstractions in the Eliza framework that enable developers to create powerful AI agents: * **Actions**: The tasks and responses that agents can perform. * **Providers**: Modules that provide information and state to the agent's context. * **Evaluators**: Modules that analyze situations and agent actions, often triggering further actions or modifications. We explore each of these in detail, walking through code examples and common use cases. We also cover how to package up actions, providers and evaluators into reusable plugins. * * * Key Sections ============ * [**00:03:33** - Shift in focus from characters (Dev School Part 1) to agent capabilities](https://www.youtube.com/watch?v=XenGeAcPAQo&t=213) * [**00:07:09** - Deep dive into providers, actions, and evaluators, the core building blocks of Eliza](https://www.youtube.com/watch?v=XenGeAcPAQo&t=429) * [**00:07:28** - Discussion about actions vs. tools, favoring decoupled intent and action execution](https://www.youtube.com/watch?v=XenGeAcPAQo&t=448) * [**00:18:02** - Explanation of providers and their function as information sources for agents](https://www.youtube.com/watch?v=XenGeAcPAQo&t=1082) * [**00:20:15** - Introduction to evaluators and their role in agent reflection and state analysis](https://www.youtube.com/watch?v=XenGeAcPAQo&t=1215) * [**00:29:22** - Brief overview of clients as connectors to external platforms](https://www.youtube.com/watch?v=XenGeAcPAQo&t=1762) * [**00:31:02** - Description of adapters and their function in database interactions](https://www.youtube.com/watch?v=XenGeAcPAQo&t=1862) * [**00:34:02** - Discussion about plugins as bundles of core components, examples, and recommendations](https://www.youtube.com/watch?v=XenGeAcPAQo&t=2042) * [**00:40:31** - Live Coding Demo begins: Creating a new plugin from scratch (DevSchoolExamplePlugin)](https://www.youtube.com/watch?v=XenGeAcPAQo&t=2431) * [**00:47:54** - Implementing the simple HelloWorldAction](https://www.youtube.com/watch?v=XenGeAcPAQo&t=2791) * [**01:00:26** - Implementing the CurrentNewsAction (fetching and formatting news data)](https://www.youtube.com/watch?v=XenGeAcPAQo&t=3626) * [**01:22:09** - Demonstrating the Eliza Client for interacting with agents locally](https://www.youtube.com/watch?v=XenGeAcPAQo&t=4929) * [**01:23:54** - Q&A: Plugin usage in character files, installation, Eliza vs. Eliza Starter](https://www.youtube.com/watch?v=XenGeAcPAQo&t=5034) * [**01:36:17** - Saving agent responses as memories in the database](https://www.youtube.com/watch?v=XenGeAcPAQo&t=5777) * [**01:43:06** - Using prompts for data extraction within actions](https://www.youtube.com/watch?v=XenGeAcPAQo&t=6186) * [**01:51:54** - Importance of deleting the database during development to avoid context issues](https://www.youtube.com/watch?v=XenGeAcPAQo&t=6714) * [**01:57:04** - Viewing agent context via console logs to understand model inputs](https://www.youtube.com/watch?v=XenGeAcPAQo&t=7024) * [**02:07:07** - Explanation of memory management with knowledge, facts, and lore](https://www.youtube.com/watch?v=XenGeAcPAQo&t=7627) * [**02:16:53** - Q&A: Prompt engineering opportunities, knowledge chunking and retrieval](https://www.youtube.com/watch?v=XenGeAcPAQo&t=8213) * [**02:22:57** - Call for contributions: Encouraging viewers to create their own actions and plugins](https://www.youtube.com/watch?v=XenGeAcPAQo&t=8577) * [**02:26:31** - Closing remarks and future DevSchool session announcements](https://www.youtube.com/watch?v=XenGeAcPAQo&t=8791) Working with Actions ==================== Actions represent the core capabilities of an AI agent - the things it can actually do. In Eliza, an action is defined by: * **Name**: The unique name used to reference the action * **Description**: Used to inform the agent when this action should be invoked * **Handler**: The code that actually executes the action logic * **Validator**: Determines if the action is valid to be called given the current context Some key points about actions in Eliza: * The agent decides which action to call based on the name and description. It does not have insight into the actual action code. * The handler receives the agent runtime, the triggering message, the current state, and a callback function to send messages back to the user. * The validate function allows for complex logic to determine action availability based on context and state. Providers: Injecting State and Context ====================================== Providers allow developers to dynamically inject relevant information into the agent's context. This could be real-time data, user information, results of previous conversations, or any other state the agent may need. Key aspects of providers: * Defined by a single `get` function that returns relevant state * Called before each agent execution to hydrate the context * Can conditionally provide state based on the current context Common provider examples include current time, user preferences, conversation history, and external API data. Evaluators: Reflection and Analysis =================================== Evaluators run after each agent action, allowing the agent to reflect on what happened and potentially trigger additional actions. They are a key component in creating agents that can learn and adapt. Some common use cases for evaluators: * Extracting and storing facts from a conversation for future reference * Analyzing user sentiment to measure trust and relationship * Identifying key intents and entities to inform future actions * Implementing feedback loops for agent improvement Evaluators work in close conjunction with providers - often an evaluator will extract some insight that a provider will then inject into future context. Packaging Plugins ================= The plugin system in Eliza allows developers to package up related actions, providers and evaluators into reusable modules. A plugin is defined by: * `package.json`: Metadata about the plugin * `tsconfig.json`: TypeScript configuration * `index.ts`: Registers the plugin's actions, providers and evaluators * `src` directory: Contains the actual action, provider and evaluator code Plugins can be published to npm and then easily imported into any Eliza agent. This enables a powerful ecosystem of reusable agent capabilities. Examples ======== The session walks through several code examples to illustrate these concepts: 1. Defining a simple "Hello World" action 2. Creating a "Current News" action that retrieves news headlines 3. Implementing a provider that injects a random emotion into the context 4. Registering actions and providers in a plugin Key Takeaways ============= * Actions, providers and evaluators are the core building blocks of agent behavior in Eliza * Actions define what agents can do, providers manage context and state, and evaluators allow for reflection and adaptation * The plugin system enables reusable packaging of agent capabilities * Effective prompt engineering around the composition of the agent context is a key area for optimization With a solid understanding of these abstractions, developers have immense power and flexibility to create agent behaviors in Eliza. The next session will dive into an end-to-end example. --- # Deploying ElizaOS to Production | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page A guide to deploying and maintaining an [ElizaOS](https://github.com/elizaOS/eliza) agent in a production environment. Assumptions[​](#assumptions "Direct link to Assumptions") ---------------------------------------------------------- * Freshly installed Ubuntu 22.04 LTS * RAM >= 4GB * Disk space >= 20GB * You have a user, not root, with sudo access that can ssh into the server Basic System Setup[​](#basic-system-setup "Direct link to Basic System Setup") ------------------------------------------------------------------------------- A slightly opinionated list of tools that we need to install. sudo apt updatesudo apt -y upgradesudo apt -y install \ neovim \ curl \ git \ unzip \ zip \ ntp \ ufw \ python3 \ python3-pip Configure and enable firewall. sudo ufw default deny incomingsudo ufw default allow outgoingsudo ufw allow 22/tcp If you want to publicly expose the API, you can do so with: sudo ufw allow 3000/tcp Enable the firewall. sudo ufw --force enable Note: For a Discord bot, no additional ports need to be opened. The bot makes outbound connections to Discord's servers which are allowed by default. ### Locale[​](#locale "Direct link to Locale") The following ensures that your agent's date and time matches yours. Adjust to suit. sudo timedatectl set-timezone Europe/Londonsudo locale-gen en_GB.UTF-8 > /dev/nullsudo update-locale LANG=en_GB.UTF-8 ### Service user[​](#service-user "Direct link to Service user") Create a system user called `eliza` with a home directory of `/opt/elizaos`. sudo useradd -r -s /bin/bash -d /opt/elizaos -m elizasudo chown -R eliza:eliza /opt/elizaossudo chmod 750 /opt/elizaos Install dependencies and configure the agent[​](#install-dependencies-and-configure-the-agent "Direct link to Install dependencies and configure the agent") ------------------------------------------------------------------------------------------------------------------------------------------------------------- Switch to the `eliza` user and clone the repository. sudo su - eliza # this puts you in /opt/elizaosgit clone https://github.com/elizaOS/eliza.git Switch to the latest release branch. cd elizagit checkout $(git describe --tags --abbrev=0) You can see which release you're on using `git status`. eliza@parzival:~$ git statusHEAD detached at v0.25.6-alpha.1 Install nvm. curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bashexport NVM_DIR="$HOME/.nvm". "$NVM_DIR/nvm.sh" Install the correct version of Node.js using nvm. nvm install v23.3.0nvm use v23.3.0 Install pnpm globally and verify the installation: # Install pnpmnpm install -g pnpmpnpm setupsource ~/.bashrc# Verify pnpm installation and pathwhich pnpm# Should output something like: /opt/elizaos/.local/share/pnpm/pnpm Install and build the workspace. pnpm install --no-frozen-lockfilepnpm build ### Configure Environment[​](#configure-environment "Direct link to Configure Environment") # Copy example environment filecp -v .env.example .env Make changes to the `.env` file for your production environment as required. For example, your `.env` might look like this for a simple Discord bot: USE_CHARACTER_STORAGE=true# Discord ConfigurationDISCORD_APPLICATION_ID=...DISCORD_API_TOKEN=...# AI Provider KeysOPENAI_API_KEY=sk-...ANTHROPIC_API_KEY=sk-... Setup a default character and storage for the character's state. cd charactersln -svf snoop.character.json default.character.jsoncd ..mkdir -p data/memory/defaultchmod 750 data ### Shell Environment Setup[​](#shell-environment-setup "Direct link to Shell Environment Setup") We need to properly configure the shell environment for the `eliza` user so nvm/pnpm works: sudo tee /opt/elizaos/.profile << 'EOL'# NVM setupexport NVM_DIR="$HOME/.nvm"[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"# pnpm setupexport PNPM_HOME="$HOME/.local/share/pnpm"case ":$PATH:" in *":$PNPM_HOME:"*) ;; *) export PATH="$PNPM_HOME:$PATH" ;;esacEOL Set ownership of the profile file. sudo chown eliza:eliza /opt/elizaos/.profile ### `systemd` Service[​](#systemd-service "Direct link to systemd-service") To enable eliza to start automatically on boot, we need to create a systemd service. Logout as `eliza` using `CTRL-D`, which should drop you back into your user with sudo access. Create the systemd service file: sudo tee /etc/systemd/system/eliza.service << 'EOL'[Unit]Description=Eliza AI Chat AgentAfter=network.target[Service]Type=simpleUser=elizaWorkingDirectory=/opt/elizaos/eliza# Environment setupEnvironment=NODE_ENV=productionEnvironment=HOME=/opt/elizaosEnvironment=HTTP_PORT=3000Environment=PATH=/opt/elizaos/.local/share/pnpm:/usr/local/bin:/usr/bin:/binEnvironment=NVM_DIR=/opt/elizaos/.nvm# Source NVM and start appExecStart=/bin/bash -c '. $NVM_DIR/nvm.sh && exec pnpm start --characters="characters/default.character.json"'# LoggingStandardOutput=append:/var/log/eliza/eliza.logStandardError=append:/var/log/eliza/eliza-error.log# Restart configurationRestart=alwaysRestartSec=5[Install]WantedBy=multi-user.targetEOL Create the log directory. sudo mkdir -p /var/log/elizasudo chown -R eliza:eliza /var/log/eliza Enable and start the service: sudo systemctl daemon-reloadsudo systemctl enable elizasudo systemctl start eliza The API should now be running on port 3000. Note that external access to this port is blocked by default unless you explicitly allowed it in the firewall configuration during basic system setup. If you need to troubleshoot, you can: # Check service statussudo systemctl status eliza# View service logs with journaldsudo journalctl -u eliza -f FAQ[​](#faq "Direct link to FAQ") ---------------------------------- ### How do I run multiple agents?[​](#how-do-i-run-multiple-agents "Direct link to How do I run multiple agents?") Create separate characterfiles or Docker containers for each agent with unique configurations and credentials. ### What are the resource requirements?[​](#what-are-the-resource-requirements "Direct link to What are the resource requirements?") Minimum >=4GB recommended and 20G disk space is recommended. CUDA optional unless using local LLMs. * [Assumptions](#assumptions) * [Basic System Setup](#basic-system-setup) * [Locale](#locale) * [Service user](#service-user) * [Install dependencies and configure the agent](#install-dependencies-and-configure-the-agent) * [Configure Environment](#configure-environment) * [Shell Environment Setup](#shell-environment-setup) * [`systemd` Service](#systemd-service) * [FAQ](#faq) * [How do I run multiple agents?](#how-do-i-run-multiple-agents) * [What are the resource requirements?](#what-are-the-resource-requirements) --- # πŸ’Ύ Database Adapters | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page Database adapters provide persistent storage capabilities for ElizaOS agents. They handle memory storage, relationship tracking, and knowledge management across different database backends. Overview[​](#overview "Direct link to Overview") ------------------------------------------------- Database adapters implement the [`IDatabaseAdapter`](/eliza/api/interfaces/IDatabaseAdapter) interface to provide consistent data access across different storage solutions. Each adapter optimizes for specific use cases: | Adapter | Best For | Key Features | | --- | --- | --- | | [MongoDB](https://github.com/elizaos-plugins/adapter-mongodb) | Production deployments | Sharding, vector search, real-time participant management | | [PostgreSQL](https://github.com/elizaos-plugins/adapter-postgres) | Enterprise & vector search | Dynamic vector dimensions, fuzzy matching, comprehensive logging | | [SQLite](https://github.com/elizaos-plugins/adapter-sqlite) | Development & embedded | Lightweight, file-based, vector BLOB support | | [Supabase](https://github.com/elizaos-plugins/adapter-supabase) | Cloud-hosted vector DB | Multiple embedding sizes, real-time subscriptions, row-level security | | [PGLite](https://github.com/elizaos-plugins/adapter-pglite) | Browser environments | Lightweight PostgreSQL implementation, HNSW indexing | | [Qdrant](https://github.com/elizaos-plugins/adapter-qdrant) | Vector-focused deployments | Optimized for RAG applications, sophisticated preprocessing | | [SQL.js](https://github.com/elizaos-plugins/adapter-sqljs) | Browser environments | Full SQLite functionality in browser, complex queries | Core Functionality[​](#core-functionality "Direct link to Core Functionality") ------------------------------------------------------------------------------- All adapters extend the [`DatabaseAdapter`](/eliza/api/classes/DatabaseAdapter) base class and implement the [`IDatabaseAdapter`](/eliza/api/interfaces/IDatabaseAdapter) interface. Here's a comprehensive overview of available methods: | Category | Method | Description | Parameters | | --- | --- | --- | --- | | **Database Lifecycle** | | | | | | `init()` | Initialize database connection | \- | | | `close()` | Close database connection | \- | | **Memory Management** | | | | | | `createMemory()` | Store new memory | `memory: Memory, tableName: string, unique?: boolean` | | | `getMemoryById()` | Retrieve specific memory | `id: UUID` | | | `getMemories()` | Get memories matching criteria | `{ roomId: UUID, count?: number, unique?: boolean, tableName: string, agentId: UUID, start?: number, end?: number }` | | | `getMemoriesByIds()` | Get multiple memories by IDs | `memoryIds: UUID[], tableName?: string` | | | `getMemoriesByRoomIds()` | Get memories from multiple rooms | `{ agentId: UUID, roomIds: UUID[], tableName: string, limit?: number }` | | | `searchMemories()` | Search with vector similarity | `{ tableName: string, agentId: UUID, roomId: UUID, embedding: number[], match_threshold: number, match_count: number, unique: boolean }` | | | `searchMemoriesByEmbedding()` | Search memories by embedding vector | `embedding: number[], { match_threshold?: number, count?: number, roomId?: UUID, agentId?: UUID, unique?: boolean, tableName: string }` | | | `removeMemory()` | Remove specific memory | `memoryId: UUID, tableName: string` | | | `removeAllMemories()` | Remove all memories in room | `roomId: UUID, tableName: string` | | | `countMemories()` | Count memories in room | `roomId: UUID, unique?: boolean, tableName?: string` | | **Knowledge Management** | | | | | | `createKnowledge()` | Store new knowledge item | `knowledge: RAGKnowledgeItem` | | | `getKnowledge()` | Retrieve knowledge | `{ id?: UUID, agentId: UUID, limit?: number, query?: string, conversationContext?: string }` | | | `searchKnowledge()` | Semantic knowledge search | `{ agentId: UUID, embedding: Float32Array, match_threshold: number, match_count: number, searchText?: string }` | | | `removeKnowledge()` | Remove knowledge item | `id: UUID` | | | `clearKnowledge()` | Remove all knowledge | `agentId: UUID, shared?: boolean` | | **Room & Participants** | | | | | | `createRoom()` | Create new conversation room | `roomId?: UUID` | | | `getRoom()` | Get room by ID | `roomId: UUID` | | | `removeRoom()` | Remove room | `roomId: UUID` | | | `addParticipant()` | Add user to room | `userId: UUID, roomId: UUID` | | | `removeParticipant()` | Remove user from room | `userId: UUID, roomId: UUID` | | | `getParticipantsForRoom()` | List room participants | `roomId: UUID` | | | `getParticipantsForAccount()` | Get user's room participations | `userId: UUID` | | | `getRoomsForParticipant()` | Get rooms for user | `userId: UUID` | | | `getRoomsForParticipants()` | Get shared rooms for users | `userIds: UUID[]` | | | `getParticipantUserState()` | Get participant's state | `roomId: UUID, userId: UUID` | | | `setParticipantUserState()` | Update participant state | \`roomId: UUID, userId: UUID, state: "FOLLOWED" | | **Account Management** | | | | | | `createAccount()` | Create new user account | `account: Account` | | | `getAccountById()` | Retrieve user account | `userId: UUID` | | | `getActorDetails()` | Get actor information | `{ roomId: UUID }` | | **Relationships** | | | | | | `createRelationship()` | Create user connection | `{ userA: UUID, userB: UUID }` | | | `getRelationship()` | Get relationship details | `{ userA: UUID, userB: UUID }` | | | `getRelationships()` | Get all relationships | `{ userId: UUID }` | | **Goals** | | | | | | `createGoal()` | Create new goal | `goal: Goal` | | | `updateGoal()` | Update goal | `goal: Goal` | | | `updateGoalStatus()` | Update goal status | `{ goalId: UUID, status: GoalStatus }` | | | `getGoals()` | Get goals matching criteria | `{ agentId: UUID, roomId: UUID, userId?: UUID, onlyInProgress?: boolean, count?: number }` | | | `removeGoal()` | Remove specific goal | `goalId: UUID` | | | `removeAllGoals()` | Remove all goals in room | `roomId: UUID` | | **Caching & Embedding** | | | | | | `getCachedEmbeddings()` | Retrieve cached embeddings | `{ query_table_name: string, query_threshold: number, query_input: string, query_field_name: string, query_field_sub_name: string, query_match_count: number }` | | **Logging** | | | | | | `log()` | Log event or action | `{ body: { [key: string]: unknown }, userId: UUID, roomId: UUID, type: string }` | ### Implementation Notes[​](#implementation-notes "Direct link to Implementation Notes") Each adapter optimizes these methods for their specific database backend: * **MongoDB**: Uses aggregation pipelines for vector operations * **PostgreSQL**: Leverages pgvector extension * **SQLite**: Implements BLOB storage for vectors * **Qdrant**: Optimizes with HNSW indexing * **Supabase**: Adds real-time capabilities > Note: For detailed implementation examples, see each adapter's source repository ([https://github.com/elizaos-plugins](https://github.com/elizaos-plugins) > ) All adapters provide: interface IDatabaseAdapter { // Memory Management createMemory(memory: Memory, tableName: string): Promise; getMemories(params: { roomId: UUID; count?: number }): Promise; searchMemories(params: SearchParams): Promise; removeMemory(memoryId: UUID): Promise; // Account & Room Management createAccount(account: Account): Promise; getAccountById(userId: UUID): Promise; createRoom(roomId?: UUID): Promise; getRoom(roomId: UUID): Promise; // Participant Management addParticipant(userId: UUID, roomId: UUID): Promise; getParticipantsForRoom(roomId: UUID): Promise; // Knowledge Management createKnowledge(knowledge: RAGKnowledgeItem): Promise; searchKnowledge(params: SearchParams): Promise; // Goal Management createGoal(goal: Goal): Promise; updateGoalStatus(params: { goalId: UUID; status: GoalStatus }): Promise;} Relationship Management interface IDatabaseAdapter { // Room Management createRoom(roomId?: UUID): Promise; getRoom(roomId: UUID): Promise; getRoomsForParticipant(userId: UUID): Promise; // Participant Management addParticipant(userId: UUID, roomId: UUID): Promise; getParticipantsForRoom(roomId: UUID): Promise; getParticipantUserState(roomId: UUID, userId: UUID): Promise<"FOLLOWED" | "MUTED" | null>; // Relationship Tracking createRelationship(params: { userA: UUID; userB: UUID }): Promise; getRelationship(params: { userA: UUID; userB: UUID }): Promise;} Cache & Goal Management interface IDatabaseCacheAdapter { getCache(params: { agentId: UUID; key: string; }): Promise; setCache(params: { agentId: UUID; key: string; value: string; }): Promise;}interface IDatabaseAdapter { // Goal Management createGoal(goal: Goal): Promise; updateGoal(goal: Goal): Promise; getGoals(params: { agentId: UUID; roomId: UUID; userId?: UUID | null; onlyInProgress?: boolean; count?: number; }): Promise;} * * * Adapter Implementations[​](#adapter-implementations "Direct link to Adapter Implementations") ---------------------------------------------------------------------------------------------- ### Quick Start[​](#quick-start "Direct link to Quick Start") // MongoDBimport { MongoDBAdapter } from '@elizaos/adapter-mongodb';const mongoAdapter = new MongoDBAdapter({ uri: process.env.MONGODB_URI, dbName: process.env.MONGODB_DB_NAME});// PostgreSQLimport { PostgresAdapter } from '@elizaos/adapter-postgres';const pgAdapter = new PostgresAdapter({ connectionString: process.env.POSTGRES_URI});// SQLiteimport { SqliteDatabaseAdapter } from '@elizaos/adapter-sqlite';const sqliteAdapter = new SqliteDatabaseAdapter('path/to/database.db');// Supabaseimport { SupabaseAdapter } from '@elizaos/adapter-supabase';const supabaseAdapter = new SupabaseAdapter({ url: process.env.SUPABASE_URL, apiKey: process.env.SUPABASE_API_KEY}); Adapter Comparison[​](#adapter-comparison "Direct link to Adapter Comparison") ------------------------------------------------------------------------------- | Feature | MongoDB | PostgreSQL | SQLite | Supabase | | --- | --- | --- | --- | --- | | **Best For** | Production deployments | Enterprise & vector search | Development & embedded | Cloud-hosted vector DB | | **Vector Support** | Native sharding | Multiple dimensions (384d-1536d) | BLOB storage | Multi-dimension tables | | **Key Features** | Auto-sharding, Real-time tracking, Auto-reconnection | Fuzzy matching, UUID keys, Comprehensive logging | JSON validation, FK constraints, Built-in caching | Real-time subs, Row-level security, Type-safe queries | | **Setup Requirements** | None | pgvector extension | None | None | | **Collections/Tables** | rooms, participants, accounts, memories, knowledge | Same as MongoDB + vector extensions | Same as MongoDB + metadata JSON | Same as PostgreSQL + dimension-specific tables | Implementation Details[​](#implementation-details "Direct link to Implementation Details") ------------------------------------------------------------------------------------------- ### PostgreSQL Requirements[​](#postgresql-requirements "Direct link to PostgreSQL Requirements") CREATE EXTENSION IF NOT EXISTS vector;CREATE EXTENSION IF NOT EXISTS fuzzystrmatch; ### SQLite Schema[​](#sqlite-schema "Direct link to SQLite Schema") CREATE TABLE memories ( id TEXT PRIMARY KEY, type TEXT, content TEXT, embedding BLOB, userId TEXT FK, roomId TEXT FK, agentId TEXT FK);CREATE TABLE knowledge ( id TEXT PRIMARY KEY, content TEXT NOT NULL, embedding BLOB, metadata JSON); ### Supabase Vector Tables[​](#supabase-vector-tables "Direct link to Supabase Vector Tables") CREATE TABLE memories_1536 (id UUID PRIMARY KEY, embedding vector(1536));CREATE TABLE memories_1024 (id UUID PRIMARY KEY, embedding vector(1024)); Embedding Support[​](#embedding-support "Direct link to Embedding Support") ---------------------------------------------------------------------------- | Adapter | Supported Dimensions | | --- | --- | | MongoDB | All (as arrays) | | PostgreSQL | OpenAI (1536d), Ollama (1024d), GAIANET (768d), BGE (384d) | | SQLite | All (as BLOB) | | Supabase | Configurable (384d-1536d) | Source code: [elizaos-plugins](https://github.com/elizaos-plugins) * * * Transaction & Error Handling[​](#transaction--error-handling "Direct link to Transaction & Error Handling") ------------------------------------------------------------------------------------------------------------ All adapters extend the [`DatabaseAdapter`](/eliza/api/classes/DatabaseAdapter) base class which provides built-in transaction support and error handling through the [`CircuitBreaker`](/eliza/api/classes/CircuitBreaker) pattern. See [database.ts](https://github.com/elizaos-plugins/core/blob/main/src/database.ts) for implementation details, as well as the [PostgreSQL Adapter Implementation](https://github.com/elizaos-plugins/adapter-postgres/blob/main/src/index.ts) or [SQLite Adapter Implementation](https://github.com/elizaos-plugins/adapter-sqlite/blob/main/src/index.ts) for detailed examples. // Transaction handlingconst result = await adapter.withTransaction(async (client) => { await client.query("BEGIN"); // Perform multiple operations await client.query("COMMIT"); return result;});// Error handling with circuit breakerprotected async withCircuitBreaker( operation: () => Promise, context: string): Promise { try { return await this.circuitBreaker.execute(operation); } catch (error) { // Circuit breaker prevents cascading failures elizaLogger.error(`Circuit breaker error in ${context}:`, error); throw error; }} Implemented features include: * Automatic rollback on errors * Circuit breaker pattern to prevent cascading failures ([source](https://github.com/elizaOS/eliza/blob/main/packages/core/src/database/CircuitBreaker.ts) ) * Connection pool management * Error type classification * * * FAQ[​](#faq "Direct link to FAQ") ---------------------------------- ### How do I choose the right adapter?[​](#how-do-i-choose-the-right-adapter "Direct link to How do I choose the right adapter?") Select based on your deployment needs. Use MongoDB/PostgreSQL for production, SQLite for development, SQL.js/PGLite for browser environments, and Qdrant/Supabase for vector-focused applications. ### Can I switch adapters later?[​](#can-i-switch-adapters-later "Direct link to Can I switch adapters later?") Yes, all adapters implement the [`IDatabaseAdapter`](/eliza/api/interfaces/IDatabaseAdapter) interface. Data migration between adapters is possible but requires additional steps. ### How are vector embeddings handled?[​](#how-are-vector-embeddings-handled "Direct link to How are vector embeddings handled?") Each adapter implements vector storage based on its native capabilities - PostgreSQL/Supabase use native vector types, MongoDB uses array fields with indexes, SQLite uses BLOB storage, and Qdrant uses optimized vector stores. ### What about data migration?[​](#what-about-data-migration "Direct link to What about data migration?") Use the adapter's export/import methods defined in the [`DatabaseAdapter`](/eliza/api/classes/DatabaseAdapter) base class. ### How do I handle schema updates?[​](#how-do-i-handle-schema-updates "Direct link to How do I handle schema updates?") Run migrations using the adapter-specific CLI tools. Each adapter provides its own migration system - check the adapter's README in the [elizaos-plugins](https://github.com/elizaos-plugins) repository. ### How do I fix database connection issues?[​](#how-do-i-fix-database-connection-issues "Direct link to How do I fix database connection issues?") Check your connection string format, verify the database exists and is accessible, ensure proper adapter configuration, and consider using environment variables for credentials. ### How do I resolve embedding dimension mismatch errors?[​](#how-do-i-resolve-embedding-dimension-mismatch-errors "Direct link to How do I resolve embedding dimension mismatch errors?") Set USE\_OPENAI\_EMBEDDING=TRUE in your .env file. Different models use different vector dimensions (e.g., OpenAI uses 1536, some local models use 384). Clear your database when switching embedding models. ### How do I clear/reset my database?[​](#how-do-i-clearreset-my-database "Direct link to How do I clear/reset my database?") Delete the db.sqlite file in your data directory and restart the agent. For production databases, use proper database management tools for cleanup. ### Which database should I use in production?[​](#which-database-should-i-use-in-production "Direct link to Which database should I use in production?") PostgreSQL with vector extensions is recommended for production deployments. SQLite works well for development but may not scale as effectively for production loads. ### How do I migrate between different database adapters?[​](#how-do-i-migrate-between-different-database-adapters "Direct link to How do I migrate between different database adapters?") Use the export/import methods provided by the DatabaseAdapter base class. Each adapter implements these methods for data migration, though you may need to handle schema differences manually. Further Reading[​](#further-reading "Direct link to Further Reading") ---------------------------------------------------------------------- * [Memory Management](/eliza/docs/guides/memory-management) * [State Management](/eliza/docs/core/agents) * [Overview](#overview) * [Core Functionality](#core-functionality) * [Implementation Notes](#implementation-notes) * [Adapter Implementations](#adapter-implementations) * [Quick Start](#quick-start) * [Adapter Comparison](#adapter-comparison) * [Implementation Details](#implementation-details) * [PostgreSQL Requirements](#postgresql-requirements) * [SQLite Schema](#sqlite-schema) * [Supabase Vector Tables](#supabase-vector-tables) * [Embedding Support](#embedding-support) * [Transaction & Error Handling](#transaction--error-handling) * [FAQ](#faq) * [How do I choose the right adapter?](#how-do-i-choose-the-right-adapter) * [Can I switch adapters later?](#can-i-switch-adapters-later) * [How are vector embeddings handled?](#how-are-vector-embeddings-handled) * [What about data migration?](#what-about-data-migration) * [How do I handle schema updates?](#how-do-i-handle-schema-updates) * [How do I fix database connection issues?](#how-do-i-fix-database-connection-issues) * [How do I resolve embedding dimension mismatch errors?](#how-do-i-resolve-embedding-dimension-mismatch-errors) * [How do I clear/reset my database?](#how-do-i-clearreset-my-database) * [Which database should I use in production?](#which-database-should-i-use-in-production) * [How do I migrate between different database adapters?](#how-do-i-migrate-between-different-database-adapters) * [Further Reading](#further-reading) --- # 🎯 Fine-tuning Guide | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page What is Fine-tuning?[​](#what-is-fine-tuning "Direct link to What is Fine-tuning?") ------------------------------------------------------------------------------------ Fine-tuning is the process of taking an existing AI model and specializing it for your specific needs. Think of it like taking a general-purpose chef and training them to become an expert in your favorite cuisine - they keep their fundamental cooking skills but learn your specific recipes and preferences. With fine-tuning, you can create models that: * Write in your personal style * Specialize in your industry's terminology * Match your brand's voice * Understand your company's internal knowledge Getting Started[​](#getting-started "Direct link to Getting Started") ---------------------------------------------------------------------- Guide for generating custom AI [character files](/eliza/docs/core/characterfile) and training datasets using public data from Twitter and blogs. Just like choosing the right chef to train, picking the right base model is crucial. Together AI offers several options: **For Beginners:** * Llama 3 8B Instruct - Great for simpler tasks and smaller datasets * Good for: Personal projects, testing fine-tuning, simpler use cases **For Advanced Use Cases:** * Llama 3 70B Instruct - Best for complex tasks and larger datasets * Good for: Production applications, complex domain knowledge, nuanced interactions There are two ways to prepare your data: 1. **JSONL Format** (Recommended for Beginners) {"text": "Your training example here"}{"text": "Another training example"} * Simpler to create and understand * Works well for most use cases * Handled automatically by the system 2. **Parquet Format** (Advanced) * Pre-tokenized data * More control over training * Faster processing for multiple runs * Recommended when you need custom loss masking For this guide we're going to use JSONL format. Setup[​](#setup "Direct link to Setup") ---------------------------------------- We're going to use a tool to create a training dataset from sources like Twitter / Blogs: [https://github.com/elizaOS/twitter-scraper-finetune](https://github.com/elizaOS/twitter-scraper-finetune) . Alternatively you can also request a backup archive of your data from X and use this script: [https://github.com/elizaOS/characterfile/blob/main/scripts/tweets2character.js](https://github.com/elizaOS/characterfile/blob/main/scripts/tweets2character.js) , but then you'll miss the fine-tune parts of this guide. ### Prerequisites[​](#prerequisites "Direct link to Prerequisites") * Node.js v22+ * Twitter credentials (username, password, email) * Together AI API key * Together CLI installed (`pip install together`) 1. Clone repo and install dependencies: git clone git@github.com:elizaOS/twitter-scraper-finetune.gitcd twitter-scraper-finetunenpm install 2. Copy the `.env.example` into a `.env` file: # (Required) Twitter AuthenticationTWITTER_USERNAME= # your twitter usernameTWITTER_PASSWORD= # your twitter password# (Optional) Blog ConfigurationBLOG_URLS_FILE= # path to file containing blog URLs# (Optional) Scraping ConfigurationMAX_TWEETS= # max tweets to scrapeMAX_RETRIES= # max retries for scrapingRETRY_DELAY= # delay between retriesMIN_DELAY= # minimum delay between requestsMAX_DELAY= # maximum delay between requests Usage[​](#usage "Direct link to Usage") ---------------------------------------- ### Fetching Tweets[​](#fetching-tweets "Direct link to Fetching Tweets") First configure collection parameters in `.env`. Then to get tweets from a user: npm run twitter -- username This will: * Authenticate with Twitter * Collect tweets from the specified user * Save raw tweets and analytics to `pipeline/[username]/[date]/` * Generate engagement statistics and content analysis ### 2\. Generating Character Files[​](#2-generating-character-files "Direct link to 2. Generating Character Files") After collecting tweets, you can generate a character file: npm run character -- username This creates: * A character.json file with personality traits * Interaction style and behavioral patterns * Sample responses and communication style * System prompts for different contexts ### 3\. Creating Fine-tuning Datasets[​](#3-creating-fine-tuning-datasets "Direct link to 3. Creating Fine-tuning Datasets") The pipeline automatically creates fine-tuning datasets during tweet collection. The datasets are stored in: pipeline/[username]/[date]/processed/finetuning.jsonl The JSONL file contains processed tweets optimized for fine-tuning, with: * Cleaned text content * Removed URLs and special characters * Filtered based on engagement metrics * Formatted for training ### 4\. Fine-tuning Models[​](#4-fine-tuning-models "Direct link to 4. Fine-tuning Models") To start fine-tuning: npm run finetune tip Optional test mode: npm run finetune:test The fine-tuning process: 1. Validates the JSONL file format 2. Uploads data to Together AI 3. Initiates LoRA fine-tuning 4. Provides job ID for monitoring Default model: meta-llama/Meta-Llama-3-70B-Instruct You can monitor your fine-tuning job: together fine-tuning retrieve [job_id] Or check status at: [https://api.together.xyz/jobs](https://api.together.xyz/jobs) The fine-tuning script (`scripts/finetune.js`) allows configuration of: * Model selection * Training parameters * LoRA settings * Together AI options Output Structure[​](#output-structure "Direct link to Output Structure") ------------------------------------------------------------------------- pipeline/ └── [username]/ └── [date]/ β”œβ”€β”€ raw/ β”‚ β”œβ”€β”€ tweets.json β”‚ └── urls.txt β”œβ”€β”€ processed/ β”‚ └── finetuning.jsonl β”œβ”€β”€ analytics/ β”‚ └── stats.json β”œβ”€β”€ character/ β”‚ └── character.json └── exports/ └── summary.md FAQ[​](#faq "Direct link to FAQ") ---------------------------------- ### How much data do I need for good results?[​](#how-much-data-do-i-need-for-good-results "Direct link to How much data do I need for good results?") Collect at least 1000 tweets from accounts with consistent posting styles, and filter for high engagement examples. Remove irrelevant or low-quality content, and clean out any sensitive or private info. ### What should I do after generating a character file?[​](#what-should-i-do-after-generating-a-character-file "Direct link to What should I do after generating a character file?") Review and manually adjust the generated files, add specific behavioral examples, and fine-tune the system prompts for optimal outcomes. ### What are best practices for fine-tuning?[​](#what-are-best-practices-for-fine-tuning "Direct link to What are best practices for fine-tuning?") Start with test runs to validate your data, then closely monitor training metrics and thoroughly evaluate outputs before deployment. ### How can I make my agent's responses more natural/less bot-like?[​](#how-can-i-make-my-agents-responses-more-naturalless-bot-like "Direct link to How can I make my agent's responses more natural/less bot-like?") Fine-tune the character's bio, lore, and post examples in the character file. Consider using different model providers and adjusting interaction settings. Some models (like DeepSeek) are noted for more natural responses. ### Why am I getting Twitter authentication failures?[​](#why-am-i-getting-twitter-authentication-failures "Direct link to Why am I getting Twitter authentication failures?") Double-check your credentials in .env file, ensure your email is verified, and try adding rate limiting breaks between authentication attempts. ### Why isn't my data collection working?[​](#why-isnt-my-data-collection-working "Direct link to Why isn't my data collection working?") Verify your network connectivity is stable, confirm the target account is public, and try increasing the retry parameters in your configuration. ### What should I do if I get fine-tuning errors?[​](#what-should-i-do-if-i-get-fine-tuning-errors "Direct link to What should I do if I get fine-tuning errors?") First validate your JSONL file format is correct, then check your API key has proper permissions, and monitor any rate limits that may be affecting the process. * [What is Fine-tuning?](#what-is-fine-tuning) * [Getting Started](#getting-started) * [Setup](#setup) * [Prerequisites](#prerequisites) * [Usage](#usage) * [Fetching Tweets](#fetching-tweets) * [2\. Generating Character Files](#2-generating-character-files) * [3\. Creating Fine-tuning Datasets](#3-creating-fine-tuning-datasets) * [4\. Fine-tuning Models](#4-fine-tuning-models) * [Output Structure](#output-structure) * [FAQ](#faq) * [How much data do I need for good results?](#how-much-data-do-i-need-for-good-results) * [What should I do after generating a character file?](#what-should-i-do-after-generating-a-character-file) * [What are best practices for fine-tuning?](#what-are-best-practices-for-fine-tuning) * [How can I make my agent's responses more natural/less bot-like?](#how-can-i-make-my-agents-responses-more-naturalless-bot-like) * [Why am I getting Twitter authentication failures?](#why-am-i-getting-twitter-authentication-failures) * [Why isn't my data collection working?](#why-isnt-my-data-collection-working) * [What should I do if I get fine-tuning errors?](#what-should-i-do-if-i-get-fine-tuning-errors) --- # Part 3: Building a User Data Extraction Agent | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) In this third session of the AI Agent Dev School series, we dive into a practical application of providers and evaluators in the Eliza framework - building an agent that can extract key user data (name, location, job) through natural conversation. We explore: * The provider-evaluator loop for gathering information and triggering actions * Deep dive into evaluators and their role in agent self-reflection * Code walkthrough of real-world evaluators and providers * Building a user data extraction flow from scratch * Dynamic providers based on completion state * Q&A on advanced topics and use cases Key Sections ============ * [**00:00:00** - Intro & Housekeeping](https://www.youtube.com/watch?v=Y1DiqSVy4aU&t=0) * [**00:08:05** - Building a Form-Filling Agent](https://www.youtube.com/watch?v=Y1DiqSVy4aU&t=485) * [**00:16:15** - Deep Dive into Evaluators](https://www.youtube.com/watch?v=Y1DiqSVy4aU&t=975) * [**00:27:45** - Code walkthrough of the "Fact Evaluator"](https://www.youtube.com/watch?v=Y1DiqSVy4aU&t=1675) * [**00:36:07** - Building a User Data Evaluator](https://www.youtube.com/watch?v=Y1DiqSVy4aU&t=2167) * [**00:51:50** - Exploring Eliza's Cache Manager](https://www.youtube.com/watch?v=Y1DiqSVy4aU&t=3110) * [**01:06:01** - Using Claude AI for Code Generation](https://www.youtube.com/watch?v=Y1DiqSVy4aU&t=3961) * [**01:21:18** - Testing the User Data Flow](https://www.youtube.com/watch?v=Y1DiqSVy4aU&t=4878) * [**01:30:27** - Adding a Dynamic Provider Based on Completion](https://www.youtube.com/watch?v=Y1DiqSVy4aU&t=5427) * [**01:37:16** - Q&A with the Audience](https://www.youtube.com/watch?v=Y1DiqSVy4aU&t=5836) * [**01:47:31** - Outro and Next Steps](https://www.youtube.com/watch?v=Y1DiqSVy4aU&t=6451) The Provider-Evaluator Loop =========================== A key concept introduced in this session is the provider-evaluator loop for gathering information and triggering actions: 1. The provider checks the cache/database for information we already have 2. If information is missing, the provider indicates to the agent what it needs to extract 3. The evaluator extracts new information from user messages and stores it 4. Once all required information is gathered, the evaluator triggers a completion action This loop allows agents to dynamically gather required data through natural conversation, enabling powerful form-filling and user profiling applications. Deep Dive into Evaluators ========================= Evaluators in Eliza run after each agent action, allowing the agent to reflect on what happened and potentially trigger additional actions. Some key aspects of evaluators: * Defined by `validate` and `handler` functions * `validate` determines if the evaluator should run based on the current context * `handler` contains the core evaluator logic - state updates, data extraction, triggering actions, etc. * Evaluators work in close conjunction with providers to extract insights and inject them into future context Common use cases include extracting conversation facts, analyzing sentiment, identifying intents, and implementing feedback loops. Building the User Data Extraction Flow ====================================== The hands-on portion of the session focuses on building a user data extraction flow from scratch. Key steps include: 1. Creating a basic `UserDataEvaluator` and `UserDataProvider` 2. Registering them directly in the agent (without a plugin) 3. Leveraging Eliza's `CacheManager` for efficient key-value storage 4. Iteratively developing the extraction logic with the help of Claude AI 5. Testing the flow by interacting with the agent and inspecting logs/context 6. Adding a dynamic provider that triggers only after data collection is complete Through this process, we see how providers and evaluators work together to enable complex, stateful agent behaviors. Using AI Assistants in Development ================================== A notable aspect of the session is the use of Claude AI to aid in code development. By providing clear instructions and iterating based on the generated code, complex logic can be developed rapidly. This showcases the potential for AI pair programming and how future developers might interact with their AI counterparts to build sophisticated applications. Key Takeaways ============= * Providers and evaluators are the key to stateful, dynamic agent behaviors * The provider-evaluator loop is a powerful pattern for gathering information and triggering actions * Evaluators enable agent self-reflection and adaptation based on conversation context * AI assistants can significantly accelerate development by generating and refining code * The potential for provider-evaluator based applications is immense - form-filling, user profiling, dynamic content unlocking, and more With these tools in hand, developers have a solid foundation for building highly interactive, personalized agentic applications. The next frontier is to explore advanced use cases and further push the boundaries of what's possible with Eliza. --- # πŸ” Secrets Management | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page A comprehensive guide for managing API keys, credentials, and other sensitive configuration in Eliza. Core Concepts[​](#core-concepts "Direct link to Core Concepts") ---------------------------------------------------------------- ### Environment Variable Hierarchy[​](#environment-variable-hierarchy "Direct link to Environment Variable Hierarchy") Eliza uses a hierarchical environment variable system that retrieves settings in this order: 1. Character-specific secrets (highest priority) 2. Character-specific settings 3. Global environment variables 4. Default values (lowest priority) This allows you to override global settings for specific characters when needed. ### Common Secret Types[​](#common-secret-types "Direct link to Common Secret Types") # API Keys for Model ProvidersOPENAI_API_KEY=sk-* # OpenAI API keyANTHROPIC_API_KEY=your-key # Anthropic/Claude API keyGOOGLE_GENERATIVE_AI_API_KEY= # Gemini API keyGROQ_API_KEY=gsk-* # Groq API key# Client AuthenticationDISCORD_API_TOKEN= # Discord bot tokenTELEGRAM_BOT_TOKEN= # Telegram bot tokenTWITTER_USERNAME= # Twitter/X usernameTWITTER_PASSWORD= # Twitter/X password# Database CredentialsSUPABASE_URL= # Supabase URLSUPABASE_ANON_KEY= # Supabase anonymous keyMONGODB_CONNECTION_STRING= # MongoDB connection string# Blockchain RelatedEVM_PRIVATE_KEY= # EVM private key with "0x" prefixSOLANA_PRIVATE_KEY= # Solana wallet private keySOLANA_PUBLIC_KEY= # Solana wallet public key For a complete list of supported environment variables, see the [`.env.example`](https://github.com/elizaos/eliza/blob/main/.env.example) file in the project repository. Implementation[​](#implementation "Direct link to Implementation") ------------------------------------------------------------------- ### Setting Up Environment Variables[​](#setting-up-environment-variables "Direct link to Setting Up Environment Variables") 1. Create a `.env` file in your project root directory: cp .env.example .env 2. Add your secrets to this file: # Model ProviderOPENAI_API_KEY=sk-xxxxxxxxxxxxx# ClientsDISCORD_API_TOKEN=xxxxxxxxxxxxxxxx 3. The `.env` file is automatically excluded from Git via `.gitignore` to prevent accidental exposure. ### Accessing Secrets in Code[​](#accessing-secrets-in-code "Direct link to Accessing Secrets in Code") Use the `runtime.getSetting()` method to access configuration values: // In a plugin, action, or serviceconst apiKey = runtime.getSetting("OPENAI_API_KEY");if (!apiKey) { throw new Error("OpenAI API key not configured");}// With a fallback valueconst temperature = runtime.getSetting("TEMPERATURE") || "0.7"; This method automatically handles the environment variable hierarchy, checking character-specific secrets first, then character settings, and finally global environment variables. ### Character-Specific Secrets[​](#character-specific-secrets "Direct link to Character-Specific Secrets") Define secrets for individual characters in their character file: { "name": "FinancialAssistant", "settings": { "secrets": { "OPENAI_API_KEY": "sk-character-specific-key", "ALPHA_VANTAGE_API_KEY": "financial-data-api-key" } }} Alternatively, use namespaced environment variables with this format: CHARACTER..=value For example: CHARACTER.TraderAgent.OPENAI_API_KEY=sk-character-specific-key Best Practices[​](#best-practices "Direct link to Best Practices") ------------------------------------------------------------------- ### 1\. Environment Segregation[​](#1-environment-segregation "Direct link to 1. Environment Segregation") Keep separate environment files for different deployment contexts: .env.development # Local development settings.env.staging # Testing environment.env.production # Production settings Load the appropriate file based on your `NODE_ENV` or custom environment flag. ### 2\. Secret Validation[​](#2-secret-validation "Direct link to 2. Secret Validation") Validate required secrets before using them: function validateRequiredSecrets(runtime) { const required = ["OPENAI_API_KEY", "DATABASE_URL"]; const missing = required.filter(key => !runtime.getSetting(key)); if (missing.length > 0) { throw new Error(`Missing required secrets: ${missing.join(", ")}`); }} ### 3\. Secure Error Handling[​](#3-secure-error-handling "Direct link to 3. Secure Error Handling") Avoid exposing secrets in error messages or logs: try { const apiKey = runtime.getSetting("API_KEY"); // Use API key...} catch (error) { // Log without exposing the secret console.error("Error using API:", error.message); // Don't log the actual API key!} ### 4\. API Key Validation[​](#4-api-key-validation "Direct link to 4. API Key Validation") Validate API key formats before use: // OpenAI API key validationconst apiKey = runtime.getSetting("OPENAI_API_KEY");if (apiKey && !apiKey.startsWith("sk-")) { throw new Error("Invalid OpenAI API key format");}// Mask before loggingconst maskedKey = apiKey ? `${apiKey.substring(0, 5)}...` : "not set";console.log("Using API key:", maskedKey); Security Considerations[​](#security-considerations "Direct link to Security Considerations") ---------------------------------------------------------------------------------------------- ### Private Key Handling[​](#private-key-handling "Direct link to Private Key Handling") Take extra care with blockchain private keys: // Retrieve private key from settingsconst privateKey = runtime.getSetting("WALLET_PRIVATE_KEY");// Validate private key format (example for EVM)if (privateKey && !privateKey.match(/^(0x)?[0-9a-fA-F]{64}$/)) { throw new Error("Invalid private key format");}// Use private key securely - NEVER log the actual keyconsole.log("Using wallet with address:", getAddressFromPrivateKey(privateKey)); ### Secret Rotation[​](#secret-rotation "Direct link to Secret Rotation") Implement periodic key rotation for production deployments: 1. Generate new API keys/credentials 2. Update environment variables or character secrets 3. Verify functionality with new credentials 4. Revoke old credentials ### Cloud Deployment Security[​](#cloud-deployment-security "Direct link to Cloud Deployment Security") When deploying to cloud environments: 1. Use the platform's secrets management service: * AWS: Secrets Manager or Parameter Store * Google Cloud: Secret Manager * Azure: Key Vault * Vercel/Netlify: Environment Variables UI 2. Minimize secret access: * Restrict which services can access which secrets * Use short-lived credentials when possible * Configure proper IAM roles and permissions Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ---------------------------------------------------------------------- ### Common Issues[​](#common-issues "Direct link to Common Issues") #### 1\. Missing Environment Variables[​](#1-missing-environment-variables "Direct link to 1. Missing Environment Variables") If settings aren't being found: * Check that the `.env` file exists in the project root * Verify variable names match exactly (they're case-sensitive) * Ensure the file is properly formatted with no spaces around equals signs #### 2\. Character-Specific Secrets Not Working[​](#2-character-specific-secrets-not-working "Direct link to 2. Character-Specific Secrets Not Working") If character-specific secrets aren't being applied: * Verify the character name in your namespaced variable matches exactly * Check JSON syntax in the character file's `settings.secrets` object * Restart the application after changes to environment variables #### 3\. Environment File Not Loading[​](#3-environment-file-not-loading "Direct link to 3. Environment File Not Loading") If your entire `.env` file isn't being loaded: // Add this near the start of your applicationimport dotenv from 'dotenv';dotenv.config({ path: '.env.development' }); // Specify exact path if needed Related Resources[​](#related-resources "Direct link to Related Resources") ---------------------------------------------------------------------------- * [Configuration Guide](/eliza/docs/guides/configuration) - General application configuration * [Character Files](/eliza/docs/core/characterfile) - Character-specific configuration * [Local Development](/eliza/docs/guides/local-development) - Development environment setup * [Deployment Guide](/eliza/docs/guides/remote-deployment) - Secure production deployment * [Core Concepts](#core-concepts) * [Environment Variable Hierarchy](#environment-variable-hierarchy) * [Common Secret Types](#common-secret-types) * [Implementation](#implementation) * [Setting Up Environment Variables](#setting-up-environment-variables) * [Accessing Secrets in Code](#accessing-secrets-in-code) * [Character-Specific Secrets](#character-specific-secrets) * [Best Practices](#best-practices) * [1\. Environment Segregation](#1-environment-segregation) * [2\. Secret Validation](#2-secret-validation) * [3\. Secure Error Handling](#3-secure-error-handling) * [4\. API Key Validation](#4-api-key-validation) * [Security Considerations](#security-considerations) * [Private Key Handling](#private-key-handling) * [Secret Rotation](#secret-rotation) * [Cloud Deployment Security](#cloud-deployment-security) * [Troubleshooting](#troubleshooting) * [Common Issues](#common-issues) * [Related Resources](#related-resources) --- # βš™οΈ Configuration Guide | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page This guide covers how to configure Eliza for different use cases and environments. We'll walk through all available configuration options and best practices. Environment Configuration[​](#environment-configuration "Direct link to Environment Configuration") ---------------------------------------------------------------------------------------------------- ### Basic Setup[​](#basic-setup "Direct link to Basic Setup") The first step is creating your environment configuration file: cp .env.example .env Then edit the `.env` file to add your specific configuration values. * * * Character Configuration[​](#character-configuration "Direct link to Character Configuration") ---------------------------------------------------------------------------------------------- Character files define your agent's personality and behavior. Create them in the `characters/` directory: { "name": "AgentName", "clients": ["discord", "twitter"], "modelProvider": "openrouter", "settings": { "model": "openai/gpt-4o", "temperature": 0.7, "maxTokens": 2000, "secrets": { "OPENAI_API_KEY": "character-specific-key", "DISCORD_TOKEN": "bot-specific-token" } }} ### Secrets for Multiple Characters[​](#secrets-for-multiple-characters "Direct link to Secrets for Multiple Characters") If you don't want to have secrets in your character files because you would like to utilize source control for collaborative development on multiple characters, then you can put all character secrets in `.env` by prepending `CHARACTER.NAME.` before the key name and value. For example: # C3POCHARACTER.C3PO.DISCORD_APPLICATION_ID=abcCHARACTER.C3PO.DISCORD_API_TOKEN=xyz# DOBBYCHARACTER.DOBBY.DISCORD_APPLICATION_ID=123CHARACTER.DOBBY.DISCORD_API_TOKEN=369 * * * Custom Actions[​](#custom-actions "Direct link to Custom Actions") ------------------------------------------------------------------- ### Adding Custom Actions[​](#adding-custom-actions "Direct link to Adding Custom Actions") 1. Create a `custom_actions` directory 2. Add your action files there 3. Configure in `elizaConfig.yaml`: actions: - name: myCustomAction path: ./custom_actions/myAction.ts See the [actions](/eliza/docs/core/actions) page for more info. * * * Advanced Configuration[​](#advanced-configuration "Direct link to Advanced Configuration") ------------------------------------------------------------------------------------------- ### Cloudflare AI Gateway Integration[​](#cloudflare-ai-gateway-integration "Direct link to Cloudflare AI Gateway Integration") Eliza supports routing API calls through [Cloudflare AI Gateway](https://developers.cloudflare.com/ai-gateway/) , which provides several benefits: * Detailed analytics and monitoring of message traffic and response times * Cost optimization through request caching and usage tracking across providers * Improved latency through Cloudflare's global network * Comprehensive visibility into message content and token usage When enabled, Eliza will automatically route requests through your Cloudflare AI Gateway endpoint. If the gateway configuration is incomplete or disabled, Eliza will fall back to direct API calls. ### Logging[​](#logging "Direct link to Logging") DEFAULT_LOG_LEVEL=info # Options: debug, info, warn, errorLOG_JSON_FORMAT=false # Set to true for JSON formatted logs ### Performance Settings[​](#performance-settings "Direct link to Performance Settings") Fine-tune runtime behavior: const settings = { // Performance MAX_CONCURRENT_REQUESTS: 5, REQUEST_TIMEOUT: 30000, // Memory MEMORY_TTL: 3600, MAX_MEMORY_ITEMS: 1000,}; * * * Environment Variables Reference[​](#environment-variables-reference "Direct link to Environment Variables Reference") ---------------------------------------------------------------------------------------------------------------------- Click to expand .env.example file # Eliza Environment Variables - Compact Reference## SERVER & DATABASECACHE_STORE=database # Options: database|redis|filesystemCACHE_DIR=./data/cache # For filesystem cacheREDIS_URL= # Redis connection stringPGLITE_DATA_DIR= # ../pgLite/ or memory://SERVER_URL=http://localhost # Base URLSERVER_PORT=3000 # Port numberSUPABASE_URL= # Supabase URLSUPABASE_ANON_KEY= # Supabase keyMONGODB_CONNECTION_STRING= # MongoDB connectionMONGODB_DATABASE= # Default: elizaAgentREMOTE_CHARACTER_URLS= # Comma-separated URLsUSE_CHARACTER_STORAGE=false # Store characters in data/characterDEFAULT_LOG_LEVEL=info # Log levelLOG_JSON_FORMAT=false # JSON format for logs## CLIENT INTEGRATIONS# BitMindBITMIND=true # Enable BitMindBITMIND_API_TOKEN= # API token# DiscordDISCORD_APPLICATION_ID= # App IDDISCORD_API_TOKEN= # Bot tokenDISCORD_VOICE_CHANNEL_ID= # Voice channel# DevinDEVIN_API_TOKEN= # API token# GelatoGELATO_RELAY_API_KEY= # API key# FarcasterFARCASTER_FID= # FID for accountFARCASTER_NEYNAR_API_KEY= # API keyFARCASTER_NEYNAR_SIGNER_UUID= # Signer UUIDFARCASTER_DRY_RUN=false # Run without publishingFARCASTER_POLL_INTERVAL=120 # Check interval (sec)# TelegramTELEGRAM_BOT_TOKEN= # Bot tokenTELEGRAM_ACCOUNT_PHONE= # Phone numberTELEGRAM_ACCOUNT_APP_ID= # App API IDTELEGRAM_ACCOUNT_APP_HASH= # App API hashTELEGRAM_ACCOUNT_DEVICE_MODEL= # Device modelTELEGRAM_ACCOUNT_SYSTEM_VERSION= # System version# Twitter/XTWITTER_DRY_RUN=false # Simulate without postingTWITTER_USERNAME= # Account usernameTWITTER_PASSWORD= # Account passwordTWITTER_EMAIL= # Account emailTWITTER_2FA_SECRET= # 2FA secretTWITTER_COOKIES_AUTH_TOKEN= # Auth tokenTWITTER_COOKIES_CT0= # Cookie CT0TWITTER_COOKIES_GUEST_ID= # Guest ID cookieTWITTER_POLL_INTERVAL=120 # Check interval (sec)TWITTER_SEARCH_ENABLE=FALSE # Enable timeline searchTWITTER_TARGET_USERS= # Usernames to interact withTWITTER_RETRY_LIMIT= # Max retry attemptsTWITTER_SPACES_ENABLE=false # Enable SpacesENABLE_TWITTER_POST_GENERATION=true # Auto tweet generationPOST_INTERVAL_MIN= # Min post interval (min), default: 90POST_INTERVAL_MAX= # Max post interval (min), default: 180POST_IMMEDIATELY= # Post immediately, default: falseACTION_INTERVAL= # Action processing interval (min), default: 5ENABLE_ACTION_PROCESSING=false # Enable action processingMAX_ACTIONS_PROCESSING=1 # Max actions per cycleACTION_TIMELINE_TYPE=foryou # Timeline type: foryou|followingTWITTER_APPROVAL_DISCORD_CHANNEL_ID= # Discord channel IDTWITTER_APPROVAL_DISCORD_BOT_TOKEN= # Discord bot tokenTWITTER_APPROVAL_ENABLED= # Enable approval, default: falseTWITTER_APPROVAL_CHECK_INTERVAL=60000 # Check interval (ms)# WhatsAppWHATSAPP_ACCESS_TOKEN= # Access tokenWHATSAPP_PHONE_NUMBER_ID= # Phone number IDWHATSAPP_BUSINESS_ACCOUNT_ID= # Business Account IDWHATSAPP_WEBHOOK_VERIFY_TOKEN= # Webhook tokenWHATSAPP_API_VERSION=v17.0 # API version# AlexaALEXA_SKILL_ID= # Skill IDALEXA_CLIENT_ID= # OAuth2 Client IDALEXA_CLIENT_SECRET= # OAuth2 Client Secret# SimsAISIMSAI_API_KEY= # API keySIMSAI_AGENT_ID= # Agent IDSIMSAI_USERNAME= # UsernameSIMSAI_DRY_RUN= # Test without API calls# Direct ClientEXPRESS_MAX_PAYLOAD= # Max payload, default: 100kb# InstagramINSTAGRAM_DRY_RUN=false # Simulate without postingINSTAGRAM_USERNAME= # UsernameINSTAGRAM_PASSWORD= # PasswordINSTAGRAM_APP_ID= # App ID (required)INSTAGRAM_APP_SECRET= # App Secret (required)INSTAGRAM_BUSINESS_ACCOUNT_ID= # Business Account IDINSTAGRAM_POST_INTERVAL_MIN=60 # Min interval (min)INSTAGRAM_POST_INTERVAL_MAX=120 # Max interval (min)INSTAGRAM_ENABLE_ACTION_PROCESSING=false # Enable actionsINSTAGRAM_ACTION_INTERVAL=5 # Action interval (min)INSTAGRAM_MAX_ACTIONS=1 # Max actions per cycle## MODEL PROVIDERS# OpenAIOPENAI_API_KEY= # API key (sk-*)OPENAI_API_URL= # API endpoint, default: https://api.openai.com/v1SMALL_OPENAI_MODEL= # Default: gpt-4o-miniMEDIUM_OPENAI_MODEL= # Default: gpt-4oLARGE_OPENAI_MODEL= # Default: gpt-4oEMBEDDING_OPENAI_MODEL= # Default: text-embedding-3-smallIMAGE_OPENAI_MODEL= # Default: dall-e-3USE_OPENAI_EMBEDDING= # TRUE for OpenAI embeddingsENABLE_OPEN_AI_COMMUNITY_PLUGIN=false # Enable community pluginOPENAI_DEFAULT_MODEL= # Default modelOPENAI_MAX_TOKENS= # Max tokensOPENAI_TEMPERATURE= # Temperature# Atoma SDKATOMASDK_BEARER_AUTH= # Bearer tokenATOMA_API_URL= # Default: https://api.atoma.network/v1SMALL_ATOMA_MODEL= # Default: meta-llama/Llama-3.3-70B-InstructMEDIUM_ATOMA_MODEL= # Default: meta-llama/Llama-3.3-70B-InstructLARGE_ATOMA_MODEL= # Default: meta-llama/Llama-3.3-70B-Instruct# Eternal AIETERNALAI_URL= # Service URLETERNALAI_MODEL= # Default: NousResearch/Hermes-3-Llama-3.1-70B-FP8ETERNALAI_CHAIN_ID=8453 # Default: 8453ETERNALAI_RPC_URL= # RPC URLETERNALAI_AGENT_CONTRACT_ADDRESS= # Contract addressETERNALAI_AGENT_ID= # Agent IDETERNALAI_API_KEY= # API keyETERNALAI_LOG=false # Enable logging# HyperbolicHYPERBOLIC_API_KEY= # API keyHYPERBOLIC_MODEL= # Model nameIMAGE_HYPERBOLIC_MODEL= # Default: FLUX.1-devSMALL_HYPERBOLIC_MODEL= # Default: meta-llama/Llama-3.2-3B-InstructMEDIUM_HYPERBOLIC_MODEL= # Default: meta-llama/Meta-Llama-3.1-70B-InstructLARGE_HYPERBOLIC_MODEL= # Default: meta-llama/Meta-Llama-3.1-405-InstructHYPERBOLIC_ENV=production # EnvironmentHYPERBOLIC_GRANULAR_LOG=true # Granular loggingHYPERBOLIC_SPASH=true # Show splashHYPERBOLIC_LOG_LEVEL=debug # Log level# InferaINFERA_API_KEY= # API keyINFERA_MODEL= # Default: llama3.2:latestINFERA_SERVER_URL= # Default: https://api.infera.org/SMALL_INFERA_MODEL= # Recommended: llama3.2:latestMEDIUM_INFERA_MODEL= # Recommended: mistral-nemo:latestLARGE_INFERA_MODEL= # Recommended: mistral-small:latest# VeniceVENICE_API_KEY= # API keySMALL_VENICE_MODEL= # Default: llama-3.3-70bMEDIUM_VENICE_MODEL= # Default: llama-3.3-70bLARGE_VENICE_MODEL= # Default: llama-3.1-405bIMAGE_VENICE_MODEL= # Default: fluently-xl# Nineteen.aiNINETEEN_AI_API_KEY= # API keySMALL_NINETEEN_AI_MODEL= # Default: unsloth/Llama-3.2-3B-InstructMEDIUM_NINETEEN_AI_MODEL= # Default: unsloth/Meta-Llama-3.1-8B-InstructLARGE_NINETEEN_AI_MODEL= # Default: hugging-quants/Meta-Llama-3.1-70B-Instruct-AWQ-INT4IMAGE_NINETEEN_AI_MODE= # Default: dataautogpt3/ProteusV0.4-Lightning# Akash Chat APIAKASH_CHAT_API_KEY= # API keySMALL_AKASH_CHAT_API_MODEL= # Default: Meta-Llama-3-2-3B-InstructMEDIUM_AKASH_CHAT_API_MODEL= # Default: Meta-Llama-3-3-70B-InstructLARGE_AKASH_CHAT_API_MODEL= # Default: Meta-Llama-3-1-405B-Instruct-FP8# LivepeerLIVEPEER_GATEWAY_URL=https://dream-gateway.livepeer.cloud # Gateway URLIMAGE_LIVEPEER_MODEL= # Default: ByteDance/SDXL-LightningSMALL_LIVEPEER_MODEL= # Default: meta-llama/Meta-Llama-3.1-8B-InstructMEDIUM_LIVEPEER_MODEL= # Default: meta-llama/Meta-Llama-3.1-8B-InstructLARGE_LIVEPEER_MODEL= # Default: meta-llama/Meta-Llama-3.1-8B-Instruct# Speech & TranscriptionELEVENLABS_XI_API_KEY= # ElevenLabs API keyELEVENLABS_MODEL_ID=eleven_multilingual_v2 # Model IDELEVENLABS_VOICE_ID=21m00Tcm4TlvDq8ikWAM # Voice IDELEVENLABS_VOICE_STABILITY=0.5 # StabilityELEVENLABS_VOICE_SIMILARITY_BOOST=0.9 # Similarity boostELEVENLABS_VOICE_STYLE=0.66 # Style valueELEVENLABS_VOICE_USE_SPEAKER_BOOST=false # Speaker boostELEVENLABS_OPTIMIZE_STREAMING_LATENCY=4 # Latency levelELEVENLABS_OUTPUT_FORMAT=pcm_16000 # Output formatTRANSCRIPTION_PROVIDER= # Default: local, options: openai|deepgram|localDEEPGRAM_API_KEY= # Deepgram API key# OpenRouterOPENROUTER_API_KEY= # API keyOPENROUTER_MODEL= # Default: uses hermes 70b/405bSMALL_OPENROUTER_MODEL= # Small modelMEDIUM_OPENROUTER_MODEL= # Medium modelLARGE_OPENROUTER_MODEL= # Large model# REDPILLREDPILL_API_KEY= # API keyREDPILL_MODEL= # Model nameSMALL_REDPILL_MODEL= # Default: gpt-4o-miniMEDIUM_REDPILL_MODEL= # Default: gpt-4oLARGE_REDPILL_MODEL= # Default: gpt-4o# GrokGROK_API_KEY= # API keySMALL_GROK_MODEL= # Default: grok-2-1212MEDIUM_GROK_MODEL= # Default: grok-2-1212LARGE_GROK_MODEL= # Default: grok-2-1212EMBEDDING_GROK_MODEL= # Default: grok-2-1212# OllamaOLLAMA_SERVER_URL= # Default: localhost:11434OLLAMA_MODEL= # Model nameUSE_OLLAMA_EMBEDDING= # TRUE for Ollama embeddingsOLLAMA_EMBEDDING_MODEL= # Default: mxbai-embed-largeSMALL_OLLAMA_MODEL= # Default: llama3.2MEDIUM_OLLAMA_MODEL= # Default: hermes3LARGE_OLLAMA_MODEL= # Default: hermes3:70b# GoogleGOOGLE_MODEL= # Model nameSMALL_GOOGLE_MODEL= # Default: gemini-1.5-flash-latestMEDIUM_GOOGLE_MODEL= # Default: gemini-1.5-flash-latestLARGE_GOOGLE_MODEL= # Default: gemini-1.5-pro-latestEMBEDDING_GOOGLE_MODEL= # Default: text-embedding-004GOOGLE_GENERATIVE_AI_API_KEY= # Gemini API key# MistralMISTRAL_MODEL= # Model nameSMALL_MISTRAL_MODEL= # Default: mistral-small-latestMEDIUM_MISTRAL_MODEL= # Default: mistral-large-latestLARGE_MISTRAL_MODEL= # Default: mistral-large-latest# GroqGROQ_API_KEY= # API key (gsk_*)SMALL_GROQ_MODEL= # Default: llama-3.1-8b-instantMEDIUM_GROQ_MODEL= # Default: llama-3.3-70b-versatileLARGE_GROQ_MODEL= # Default: llama-3.2-90b-vision-previewEMBEDDING_GROQ_MODEL= # Default: llama-3.1-8b-instant# LlamaLocalLLAMALOCAL_PATH= # Default: current directory# NanoGPTSMALL_NANOGPT_MODEL= # Default: gpt-4o-miniMEDIUM_NANOGPT_MODEL= # Default: gpt-4oLARGE_NANOGPT_MODEL= # Default: gpt-4oNANOGPT_API_KEY= # API key# AnthropicANTHROPIC_API_KEY= # API keyANTHROPIC_API_URL= # API URLSMALL_ANTHROPIC_MODEL= # Default: claude-3-haiku-20240307MEDIUM_ANTHROPIC_MODEL= # Default: claude-3-5-sonnet-20241022LARGE_ANTHROPIC_MODEL= # Default: claude-3-5-sonnet-20241022# HeuristHEURIST_API_KEY= # API keySMALL_HEURIST_MODEL= # Default: meta-llama/llama-3-70b-instructMEDIUM_HEURIST_MODEL= # Default: meta-llama/llama-3-70b-instructLARGE_HEURIST_MODEL= # Default: meta-llama/llama-3.3-70b-instructHEURIST_IMAGE_MODEL= # Default: FLUX.1-devHEURIST_EMBEDDING_MODEL= # Default: BAAI/bge-large-en-v1.5USE_HEURIST_EMBEDDING= # TRUE for Heurist embeddings# GaianetGAIANET_MODEL= # Model nameGAIANET_SERVER_URL= # Server URLSMALL_GAIANET_MODEL= # Default: llama3bSMALL_GAIANET_SERVER_URL= # Default: https://llama3b.gaia.domains/v1MEDIUM_GAIANET_MODEL= # Default: llamaMEDIUM_GAIANET_SERVER_URL= # Default: https://llama8b.gaia.domains/v1LARGE_GAIANET_MODEL= # Default: qwen72bLARGE_GAIANET_SERVER_URL= # Default: https://qwen72b.gaia.domains/v1GAIANET_EMBEDDING_MODEL= # Embedding modelUSE_GAIANET_EMBEDDING= # TRUE for Gaianet embeddings# VolcengineVOLENGINE_API_URL= # Default: https://open.volcengineapi.com/api/v3/VOLENGINE_MODEL= # Model nameSMALL_VOLENGINE_MODEL= # Default: doubao-lite-128kMEDIUM_VOLENGINE_MODEL= # Default: doubao-pro-128kLARGE_VOLENGINE_MODEL= # Default: doubao-pro-256kVOLENGINE_EMBEDDING_MODEL= # Default: doubao-embedding# DeepSeekDEEPSEEK_API_KEY= # API keyDEEPSEEK_API_URL= # Default: https://api.deepseek.comSMALL_DEEPSEEK_MODEL= # Default: deepseek-chatMEDIUM_DEEPSEEK_MODEL= # Default: deepseek-chatLARGE_DEEPSEEK_MODEL= # Default: deepseek-chat# fal.aiFAL_API_KEY= # API keyFAL_AI_LORA_PATH= # LoRA models path# LetzAILETZAI_API_KEY= # API keyLETZAI_MODELS= # Models list (e.g., @modelname1, @modelname2)# GaladrielGALADRIEL_API_KEY= # API key (gal-*)SMALL_GALADRIEL_MODEL= # Default: gpt-4o-miniMEDIUM_GALADRIEL_MODEL= # Default: gpt-4oLARGE_GALADRIEL_MODEL= # Default: gpt-4oGALADRIEL_FINE_TUNE_API_KEY= # OpenAI key for fine-tuned models# LM StudioLMSTUDIO_SERVER_URL= # Default: http://localhost:1234/v1LMSTUDIO_MODEL= # Model nameSMALL_LMSTUDIO_MODEL= # Default: hermes-3-llama-3.1-8bMEDIUM_LMSTUDIO_MODEL= # Default: hermes-3-llama-3.1-8bLARGE_LMSTUDIO_MODEL= # Default: hermes-3-llama-3.1-8b# Secret AISECRET_AI_API_KEY= # API keySECRET_AI_URL= # Default: https://ai1.scrtlabs.com:21434SMALL_SECRET_AI_MODEL= # Default: deepseek-r1:70bMEDIUM_SECRET_AI_MODEL= # Default: deepseek-r1:70bLARGE_SECRET_AI_MODEL= # Default: deepseek-r1:70b# NEAR AINEARAI_API_URL= # Default: https://api.near.ai/v1NEARAI_API_KEY= # API keyNEARAI_MODEL= # Model nameSMALL_NEARAI_MODEL= # Default: fireworks::accounts/fireworks/models/llama-v3p2-3b-instructMEDIUM_NEARAI_MODEL= # Default: fireworks::accounts/fireworks/models/llama-v3p1-70b-instructLARGE_NEARAI_MODEL= # Default: fireworks::accounts/fireworks/models/llama-v3p1-405b-instructIMAGE_NEARAI_MODEL= # Default: fireworks::accounts/fireworks/models/playground-v2-5-1024px-aesthetic# Other API KeysALI_BAILIAN_API_KEY= # Ali Bailian API keyTOGETHER_API_KEY= # Together API key## CRYPTO PLUGINS# Market Data APIsCOINMARKETCAP_API_KEY= # CoinMarketCap API keyZERION_API_KEY= # Zerion API keyCOINGECKO_API_KEY= # CoinGecko API key (free)COINGECKO_PRO_API_KEY= # CoinGecko Pro API keyMORALIS_API_KEY= # Moralis API keyCHAINBASE_API_KEY= # Chainbase API key (demo for free tier)BIRDEYE_API_KEY= # Birdeye API key# EVM ChainsEVM_PRIVATE_KEY= # Private key (with 0x prefix)EVM_PROVIDER_URL= # RPC provider URLALCHEMY_HTTP_TRANSPORT_URL= # Alchemy HTTP URLZERO_EX_API_KEY= # 0x API key# ZilliqaZILLIQA_PRIVATE_KEY= # Private keyZILLIQA_PROVIDER_URL= # Provider URL# AvalancheAVALANCHE_PRIVATE_KEY= # Private keyAVALANCHE_PUBLIC_KEY= # Public key# ArtheraARTHERA_PRIVATE_KEY= # Private key# SolanaSOLANA_PRIVATE_KEY= # Private keySOLANA_PUBLIC_KEY= # Public keySOLANA_CLUSTER= # Options: devnet|testnet|mainnet-beta, default: devnetSOLANA_ADMIN_PRIVATE_KEY= # Admin private key for NFT verificationSOLANA_ADMIN_PUBLIC_KEY= # Admin public key for NFT verificationSOLANA_VERIFY_TOKEN= # Verification API tokenSOL_ADDRESS=So11111111111111111111111111111111111111112 # SOL token addressSLIPPAGE=1 # Slippage percentageBASE_MINT=So11111111111111111111111111111111111111112 # Base token addressSOLANA_RPC_URL=https://api.mainnet-beta.solana.com # RPC URLHELIUS_API_KEY= # Helius API key# InjectiveINJECTIVE_PRIVATE_KEY= # Private keyINJECTIVE_PUBLIC_KEY= # Public keyINJECTIVE_NETWORK= # Network setting# Legacy Wallet (deprecated)WALLET_PRIVATE_KEY= # Private keyWALLET_PUBLIC_KEY= # Public key# AbstractABSTRACT_ADDRESS= # AddressABSTRACT_PRIVATE_KEY= # Private keyABSTRACT_RPC_URL=https://api.testnet.abs.xyz # RPC URL# StarknetSTARKNET_ADDRESS= # AddressSTARKNET_PRIVATE_KEY= # Private keySTARKNET_RPC_URL=https://rpc.starknet-testnet.lava.build # RPC URL# Lens NetworkLENS_ADDRESS= # AddressLENS_PRIVATE_KEY= # Private key# VictionVICTION_ADDRESS= # AddressVICTION_PRIVATE_KEY= # Private keyVICTION_RPC_URL= # RPC URL# Form ChainFORM_PRIVATE_KEY= # Character account private keyFORM_TESTNET=true # true=Testnet, false=Mainnet# CoinbaseCOINBASE_COMMERCE_KEY= # Commerce keyCOINBASE_API_KEY= # API keyCOINBASE_PRIVATE_KEY= # Private keyCOINBASE_GENERATED_WALLET_ID= # Generated wallet IDCOINBASE_GENERATED_WALLET_HEX_SEED= # Wallet hex seedCOINBASE_NOTIFICATION_URI= # Webhook URI# Coinbase AgentKitCDP_API_KEY_NAME= # API key nameCDP_API_KEY_PRIVATE_KEY= # Private keyCDP_AGENT_KIT_NETWORK=base-sepolia # Default: base-sepolia# CharityIS_CHARITABLE=false # Enable charity donationsCHARITY_ADDRESS_BASE= # Base network addressCHARITY_ADDRESS_SOL= # Solana addressCHARITY_ADDRESS_ETH= # Ethereum addressCHARITY_ADDRESS_ARB= # Arbitrum addressCHARITY_ADDRESS_POL= # Polygon address# ThirdwebTHIRDWEB_SECRET_KEY= # Secret key# ConfluxCONFLUX_CORE_PRIVATE_KEY= # Core private keyCONFLUX_CORE_SPACE_RPC_URL= # Core RPC URLCONFLUX_ESPACE_PRIVATE_KEY= # eSpace private keyCONFLUX_ESPACE_RPC_URL= # eSpace RPC URLCONFLUX_MEME_CONTRACT_ADDRESS= # Meme contract address# Mind NetworkMIND_HOT_WALLET_PRIVATE_KEY= # Hot wallet private keyMIND_COLD_WALLET_ADDRESS= # Cold wallet address# ZeroGZEROG_INDEXER_RPC= # Indexer RPCZEROG_EVM_RPC= # EVM RPCZEROG_PRIVATE_KEY= # Private keyZEROG_FLOW_ADDRESS= # Flow address# IQ6900IQ_WALLET_ADDRESS= # Wallet addressIQSOlRPC= # Solana RPC# Squid RouterSQUID_SDK_URL=https://apiplus.squidrouter.com # Default SDK URLSQUID_INTEGRATOR_ID= # Integrator IDSQUID_EVM_ADDRESS= # EVM addressSQUID_EVM_PRIVATE_KEY= # EVM private keySQUID_API_THROTTLE_INTERVAL=1000 # Throttle interval (ms)# TEE ConfigurationTEE_MODE=OFF # Options: LOCAL|DOCKER|PRODUCTION|OFFWALLET_SECRET_SALT= # Salt for wallet secretsTEE_LOG_DB_PATH= # Default: ./data/tee_log.sqliteVLOG= # Enable TEE Verifiable Log if "true"ENABLE_TEE_LOG=false # Enable TEE logging (TEE mode only)TEE_MARLIN= # Set "yes" to enable Marlin pluginTEE_MARLIN_ATTESTATION_ENDPOINT= # Default: http://127.0.0.1:1350# Flow BlockchainFLOW_ADDRESS= # Flow addressFLOW_PRIVATE_KEY= # Private key for SHA3-256 + P256 ECDSAFLOW_NETWORK= # Default: mainnetFLOW_ENDPOINT_URL= # Default: https://mainnet.onflow.org# Internet Computer ProtocolINTERNET_COMPUTER_PRIVATE_KEY= # ICP private keyINTERNET_COMPUTER_ADDRESS= # ICP address# Cloudflare AICLOUDFLARE_GW_ENABLED= # Enable Cloudflare AI GatewayCLOUDFLARE_AI_ACCOUNT_ID= # Account IDCLOUDFLARE_AI_GATEWAY_ID= # Gateway ID# AptosAPTOS_PRIVATE_KEY= # Private keyAPTOS_NETWORK= # Options: mainnet|testnet# MultiversXMVX_PRIVATE_KEY= # Private keyMVX_NETWORK= # Options: mainnet|devnet|testnetACCESS_TOKEN_MANAGEMENT_TO=everyone # Limit token management# NEARNEAR_WALLET_SECRET_KEY= # Secret keyNEAR_WALLET_PUBLIC_KEY= # Public keyNEAR_ADDRESS= # AddressNEAR_SLIPPAGE=1 # Slippage percentageNEAR_RPC_URL=https://near-testnet.lava.build # RPC URLNEAR_NETWORK=testnet # Options: testnet|mainnet# ZKsync EraZKSYNC_ADDRESS= # AddressZKSYNC_PRIVATE_KEY= # Private key# HoldStationHOLDSTATION_PRIVATE_KEY= # Private key# Avail DAAVAIL_ADDRESS= # AddressAVAIL_SEED= # SeedAVAIL_APP_ID=0 # App IDAVAIL_RPC_URL=wss://avail-turing.public.blastapi.io/ # Default RPC URL# TONTON_PRIVATE_KEY= # Mnemonic joined with empty stringTON_RPC_URL= # RPC URLTON_RPC_API_KEY= # RPC API keyTON_NFT_IMAGES_FOLDER= # NFT images folderTON_NFT_METADATA_FOLDER= # NFT metadata folderPINATA_API_KEY= # Pinata API keyPINATA_API_SECRET= # Pinata API secretPINATA_JWT= # Pinata JWT# SuiSUI_PRIVATE_KEY= # Private key/mnemonicSUI_NETWORK= # Options: mainnet|testnet|devnet|localnet# MinaMINA_PRIVATE_KEY= # Mnemonic seed phraseMINA_NETWORK=devnet # Options: mainnet|testnet|devnet|localnet# StorySTORY_PRIVATE_KEY= # Private keySTORY_API_BASE_URL= # API base URLSTORY_API_KEY= # API key# CosmosCOSMOS_RECOVERY_PHRASE= # 12-word recovery phraseCOSMOS_AVAILABLE_CHAINS= # Chain list (comma-separated)# Cronos zkEVMCRONOSZKEVM_ADDRESS= # AddressCRONOSZKEVM_PRIVATE_KEY= # Private key# Fuel EcosystemFUEL_WALLET_PRIVATE_KEY= # Private key# SpheronSPHERON_PRIVATE_KEY= # Private keySPHERON_PROVIDER_PROXY_URL= # Provider proxy URLSPHERON_WALLET_ADDRESS= # Wallet address# StargazeSTARGAZE_ENDPOINT= # GraphQL endpoint# GenLayerGENLAYER_PRIVATE_KEY= # Private key (0x format)# BNB ChainBNB_PRIVATE_KEY= # Private keyBNB_PUBLIC_KEY= # Public keyBSC_PROVIDER_URL= # BNB Smart Chain RPC URLOPBNB_PROVIDER_URL= # OPBNB RPC URL# AlloraALLORA_API_KEY= # API key (UP-* format)ALLORA_CHAIN_SLUG= # Options: mainnet|testnet, default: testnet# B2 NetworkB2_PRIVATE_KEY= # Private key# Opacity zkTLSOPACITY_TEAM_ID=f309ac8ae8a9a14a7e62cd1a521b1c5f # Team IDOPACITY_CLOUDFLARE_NAME=eigen-test # Cloudflare nameOPACITY_PROVER_URL=https://opacity-ai-zktls-demo.vercel.app # Prover URL# SEI NetworkSEI_PRIVATE_KEY= # Private keySEI_NETWORK= # Options: mainnet|testnet|devnetSEI_RPC_URL= # Custom RPC URL# OmniflixOMNIFLIX_API_URL= # https://rest.omniflix.networkOMNIFLIX_MNEMONIC= # 12/24-word mnemonicOMNIFLIX_RPC_ENDPOINT= # https://rpc.omniflix.networkOMNIFLIX_PRIVATE_KEY= # Private key# HyperliquidHYPERLIQUID_PRIVATE_KEY= # Private keyHYPERLIQUID_TESTNET= # true/false, default: false# Lit ProtocolFUNDING_PRIVATE_KEY= # Funding private keyEVM_RPC_URL= # RPC URL# EthStorage DAETHSTORAGE_PRIVATE_KEY= # Private keyETHSTORAGE_ADDRESS=0x64003adbdf3014f7E38FC6BE752EB047b95da89A # AddressETHSTORAGE_RPC_URL=https://rpc.beta.testnet.l2.quarkchain.io:8545 # RPC URL# DCAPDCAP_EVM_PRIVATE_KEY= # Private keyDCAP_MODE= # Options: OFF|PLUGIN-SGX|PLUGIN-TEE|MOCK# QuickIntelQUICKINTEL_API_KEY= # Token security analysis API key# News APINEWS_API_KEY= # From https://newsapi.org/# BTCFUNBTCFUN_API_URL= # Default: https://api-testnet-new.btc.funBTC_PRIVATE_KEY_WIF= # BTC private key in WIF formatBTC_ADDRESS= # BTC addressBTC_MINT_CAP=10000 # Maximum mint amountBTC_MINT_DEADLINE=864000 # Deadline in secondsBTC_FUNDRAISING_CAP=100 # Maximum fundraising amount# TrikonTRIKON_WALLET_ADDRESS= # Valid 64-char hex with 0x prefixTRIKON_INITIAL_BALANCE= # Optional, default: 0# ArbitrageARBITRAGE_ETHEREUM_WS_URL= # Ethereum WebSocket URLARBITRAGE_EVM_PROVIDER_URL= # Ethereum RPC URLARBITRAGE_EVM_PRIVATE_KEY= # Private key for transactionsFLASHBOTS_RELAY_SIGNING_KEY= # Flashbots signing keyBUNDLE_EXECUTOR_ADDRESS= # Bundle executor contract address# DESK ExchangeDESK_EXCHANGE_PRIVATE_KEY= # Private keyDESK_EXCHANGE_NETWORK= # mainnet or testnet# CompassCOMPASS_WALLET_PRIVATE_KEY= # Private keyCOMPASS_ARBITRUM_RPC_URL= # Arbitrum RPC URLCOMPASS_ETHEREUM_RPC_URL= # Ethereum RPC URLCOMPASS_BASE_RPC_URL= # Base RPC URL# d.a.t.aDATA_API_KEY= # API keyDATA_AUTH_TOKEN= # Auth token# NKNNKN_CLIENT_PRIVATE_KEY= # Required client private keyNKN_CLIENT_ID= # Optional client ID# Router Nitro EVMROUTER_NITRO_EVM_ADDRESS= # AddressROUTER_NITRO_EVM_PRIVATE_KEY= # Private key# OriginTrail DKGDKG_ENVIRONMENT= # Options: development|testnet|mainnetDKG_HOSTNAME= # HostnameDKG_PORT=8900 # PortDKG_PUBLIC_KEY= # Public keyDKG_PRIVATE_KEY= # Private keyDKG_BLOCKCHAIN_NAME= # Chain configs# InitiaINITIA_PRIVATE_KEY= # Wallet private keyINITIA_NODE_URL= # Node URL, default: testnetINITIA_CHAIN_ID=initia-test # Chain ID, default: testnet# NVIDIANVIDIA_NIM_ENV=production # EnvironmentNVIDIA_NIM_SPASH=false # Show splashNVIDIA_NIM_API_KEY= # NIM API keyNVIDIA_NGC_API_KEY= # NGC API keyNVIDIA_NIM_MAX_RETRIES=3 # Max retriesNVIDIA_NIM_RETRY_DELAY=1000 # Retry delay (ms)NVIDIA_NIM_TIMEOUT=5000 # Timeout (ms)NVIDIA_GRANULAR_LOG=true # Granular loggingNVIDIA_LOG_LEVEL=debug # Log levelNVIDIA_OFFTOPIC_SYSTEM= # Off-topic systemNVIDIA_OFFTOPIC_USER= # Off-topic userNVIDIA_NIM_BASE_VISION_URL=https://ai.api.nvidia.com/v1/vlm # Vision URLNVIDIA_COSMOS_MODEL=nvidia/cosmos-nemotron-34b # Model nameNVIDIA_COSMOS_INVOKE_URL=https://ai.api.nvidia.com/v1/vlm/nvidia/cosmos-nemotron-34b # Invoke URLNVIDIA_COSMOS_ASSET_URL=https://api.nvcf.nvidia.com/v2/nvcf/assets # Asset URLNVIDIA_COSMOS_MAX_TOKENS=1000 # Max tokens# EmailEMAIL_OUTGOING_SERVICE=smtp # Options: smtp|gmailEMAIL_OUTGOING_HOST=smtp.example.com # SMTP hostEMAIL_OUTGOING_PORT=465 # Default: 465 (secure), 587 (TLS)EMAIL_OUTGOING_USER= # UsernameEMAIL_OUTGOING_PASS= # Password/app passwordEMAIL_INCOMING_SERVICE=imap # Service typeEMAIL_INCOMING_HOST=imap.example.com # IMAP hostEMAIL_INCOMING_PORT=993 # Default port for secure IMAPEMAIL_INCOMING_USER= # UsernameEMAIL_INCOMING_PASS= # Password# Email AutomationRESEND_API_KEY= # Resend API keyDEFAULT_TO_EMAIL= # Default recipientDEFAULT_FROM_EMAIL= # Default senderEMAIL_AUTOMATION_ENABLED=false # Enable AI detectionEMAIL_EVALUATION_PROMPT= # Custom detection criteria# ANKRANKR_ENV=production # EnvironmentANKR_WALLET= # WalletANKR_MAX_RETRIES=3 # Max retriesANKR_RETRY_DELAY=1000 # Retry delay (ms)ANKR_TIMEOUT=5000 # Timeout (ms)ANKR_GRANULAR_LOG=true # Granular loggingANKR_LOG_LEVEL=debug # Log levelANKR_RUNTIME_CHECK_MODE=false # Check modeANKR_SPASH=true # Show splash# Quai NetworkQUAI_PRIVATE_KEY= # Private keyQUAI_RPC_URL=https://rpc.quai.network # RPC URL# TokenizerTOKENIZER_MODEL= # Tokenizer modelTOKENIZER_TYPE= # Options: tiktoken|auto, default: tiktoken# AWS ServicesAWS_ACCESS_KEY_ID= # Access key IDAWS_SECRET_ACCESS_KEY= # Secret access keyAWS_REGION= # AWS regionAWS_S3_BUCKET= # S3 bucket nameAWS_S3_UPLOAD_PATH= # S3 upload pathAWS_S3_ENDPOINT= # S3 endpointAWS_S3_SSL_ENABLED= # Enable SSLAWS_S3_FORCE_PATH_STYLE= # Force path style# DevaDEVA_API_KEY= # API key from deva.me/settings/appsDEVA_API_BASE_URL=https://api.deva.me # Default URL# Verifiable InferenceVERIFIABLE_INFERENCE_ENABLED=false # Enable verificationVERIFIABLE_INFERENCE_PROVIDER=opacity # Provider option# QdrantQDRANT_URL= # Qdrant instance URLQDRANT_KEY= # API keyQDRANT_PORT=443 # Port (443 cloud, 6333 local)QDRANT_VECTOR_SIZE=1536 # Vector size# AutonomeAUTONOME_JWT_TOKEN= # JWT tokenAUTONOME_RPC=https://wizard-bff-rpc.alt.technology/v1/bff/aaa/apps # RPC URL# Akash NetworkAKASH_ENV=mainnet # EnvironmentAKASH_NET=https://raw.githubusercontent.com/ovrclk/net/master/mainnet # NetworkRPC_ENDPOINT=https://rpc.akashnet.net:443 # RPC endpointAKASH_GAS_PRICES=0.025uakt # Gas pricesAKASH_GAS_ADJUSTMENT=1.5 # Gas adjustmentAKASH_KEYRING_BACKEND=os # Keyring backendAKASH_FROM=default # From accountAKASH_FEES=20000uakt # FeesAKASH_DEPOSIT=500000uakt # DepositAKASH_MNEMONIC= # MnemonicAKASH_WALLET_ADDRESS= # Wallet addressAKASH_PRICING_API_URL=https://console-api.akash.network/v1/pricing # Pricing APIAKASH_DEFAULT_CPU=1000 # Default CPUAKASH_DEFAULT_MEMORY=1000000000 # Default memoryAKASH_DEFAULT_STORAGE=1000000000 # Default storageAKASH_SDL=example.sdl.yml # SDL fileAKASH_CLOSE_DEP=closeAll # Close deploymentAKASH_CLOSE_DSEQ=19729929 # Close DSEQAKASH_PROVIDER_INFO=akash1ccktptfkvdc67msasmesuy5m7gpc76z75kukpz # Provider infoAKASH_DEP_STATUS=dseq # Deployment statusAKASH_DEP_DSEQ=19729929 # Deployment DSEQAKASH_GAS_OPERATION=close # Gas operationAKASH_GAS_DSEQ=19729929 # Gas DSEQAKASH_MANIFEST_MODE=auto # Manifest modeAKASH_MANIFEST_PATH= # Manifest pathAKASH_MANIFEST_VALIDATION_LEVEL=strict # Validation level# PythPYTH_NETWORK_ENV=mainnet # Network environmentPYTH_MAINNET_HERMES_URL=https://hermes.pyth.network # Mainnet Hermes URLPYTH_MAINNET_WSS_URL=wss://hermes.pyth.network/ws # Mainnet WSS URLPYTH_MAINNET_PYTHNET_URL=https://pythnet.rpcpool.com # Mainnet Pythnet URLPYTH_MAINNET_CONTRACT_REGISTRY=https://pyth.network/developers/price-feed-ids # RegistryPYTH_MAINNET_PROGRAM_KEY= # Program keyPYTH_TESTNET_HERMES_URL=https://hermes.pyth.network # Testnet Hermes URLPYTH_TESTNET_WSS_URL=wss://hermes.pyth.network/ws # Testnet WSS URLPYTH_TESTNET_PYTHNET_URL=https://pythnet.rpcpool.com # Testnet Pythnet URLPYTH_TESTNET_CONTRACT_REGISTRY=https://pyth.network/developers/price-feed-ids#testnet # RegistryPYTH_TESTNET_PROGRAM_KEY= # Program keyPYTH_MAX_RETRIES=3 # Max retriesPYTH_RETRY_DELAY=1000 # Retry delay (ms)PYTH_TIMEOUT=5000 # Timeout (ms)PYTH_GRANULAR_LOG=true # Granular loggingPYTH_LOG_LEVEL=debug # Log level for debuggingPYTH_LOG_LEVEL=info # Log level for productionPYTH_ENABLE_PRICE_STREAMING=true # Enable price streamingPYTH_MAX_PRICE_STREAMS=2 # Max price streamsPYTH_TEST_ID01=0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43 # Test IDPYTH_TEST_ID02=0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace # Test ID# Misc PluginsINTIFACE_WEBSOCKET_URL=ws://localhost:12345 # Intiface WebSocket URLGIPHY_API_KEY= # API key from giphyOPEN_WEATHER_API_KEY= # OpenWeather API keyPASSPORT_API_KEY= # Gitcoin Passport keyPASSPORT_SCORER= # Scorer numberTAVILY_API_KEY= # Web search API keyECHOCHAMBERS_API_URL=http://127.0.0.1:3333 # API URLECHOCHAMBERS_API_KEY=testingkey0011 # API keyECHOCHAMBERS_USERNAME=eliza # UsernameECHOCHAMBERS_ROOMS=general # Comma-separated room listECHOCHAMBERS_POLL_INTERVAL=60 # Poll interval (sec)ECHOCHAMBERS_MAX_MESSAGES=10 # Max messagesECHOCHAMBERS_CONVERSATION_STARTER_INTERVAL=300 # Check interval (sec)ECHOCHAMBERS_QUIET_PERIOD=900 # Quiet period (sec)SUNO_API_KEY= # Suno AI music generationUDIO_AUTH_TOKEN= # Udio AI music generationFOOTBALL_API_KEY= # Football-Data.org API keyIMGFLIP_USERNAME= # Imgflip usernameIMGFLIP_PASSWORD= # Imgflip passwordRUNTIME_CHECK_MODE=false # Runtime check mode * * * FAQ[​](#faq "Direct link to FAQ") ---------------------------------- ### How do I configure different model providers?[​](#how-do-i-configure-different-model-providers "Direct link to How do I configure different model providers?") Set `modelProvider` in your character.json and add corresponding API keys in `.env` or character secrets. Supports Anthropic, OpenAI, DeepSeek, and others. ### How do I adjust the temperature setting in my character file?[​](#how-do-i-adjust-the-temperature-setting-in-my-character-file "Direct link to How do I adjust the temperature setting in my character file?") The temperature setting controls response randomness and can be configured in your character's JSON file: { "modelProvider": "openrouter", "temperature": 0.7, "settings": { "model": "openai/gpt-4o-mini" "maxInputTokens": 200000, "maxOutputTokens": 8192 }} Increase temperature for more creative responses, decrease for more consistent outputs. ### I'm getting an authentication error ("No auth credentials found"). What should I do?[​](#im-getting-an-authentication-error-no-auth-credentials-found-what-should-i-do "Direct link to I'm getting an authentication error ("No auth credentials found"). What should I do?") Check these common issues: 1. Verify API keys in your .env file 2. Ensure keys are properly formatted (OpenAI keys start with `sk-`, Groq with `gsk_`, etc.) 3. Check logs for specific authentication errors 4. Try restarting the application after updating credentials 5. For character-specific providers, ensure they have access to the needed keys ### How do I debug when my agent isn't responding?[​](#how-do-i-debug-when-my-agent-isnt-responding "Direct link to How do I debug when my agent isn't responding?") 1. Enable debug logging: `DEBUG=eliza:*` in your .env file 2. Check database for saved messages 3. Verify model provider connectivity 4. Review logs for error messages ### How do I control my agent's behavior across platforms?[​](#how-do-i-control-my-agents-behavior-across-platforms "Direct link to How do I control my agent's behavior across platforms?") Configure platform-specific settings in `.env` (like `TWITTER_TARGET_USERS`) and adjust response templates in your character file. * [Environment Configuration](#environment-configuration) * [Basic Setup](#basic-setup) * [Character Configuration](#character-configuration) * [Secrets for Multiple Characters](#secrets-for-multiple-characters) * [Custom Actions](#custom-actions) * [Adding Custom Actions](#adding-custom-actions) * [Advanced Configuration](#advanced-configuration) * [Cloudflare AI Gateway Integration](#cloudflare-ai-gateway-integration) * [Logging](#logging) * [Performance Settings](#performance-settings) * [Environment Variables Reference](#environment-variables-reference) * [FAQ](#faq) * [How do I configure different model providers?](#how-do-i-configure-different-model-providers) * [How do I adjust the temperature setting in my character file?](#how-do-i-adjust-the-temperature-setting-in-my-character-file) * [I'm getting an authentication error ("No auth credentials found"). What should I do?](#im-getting-an-authentication-error-no-auth-credentials-found-what-should-i-do) * [How do I debug when my agent isn't responding?](#how-do-i-debug-when-my-agent-isnt-responding) * [How do I control my agent's behavior across platforms?](#how-do-i-control-my-agents-behavior-across-platforms) --- # Building a Social AI Agent in 15 Minutes | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page In this tutorial, you'll learn how to quickly build your own social media AI agent that can autonomously post tweets, respond to interactions, and maintain its own unique personality. We'll be using the [Eliza framework](https://ai16z.github.io/eliza/) by a16z and TypeScript. Video: [https://youtu.be/6PZVwNTl5hI?si=0zB3OvYU4KiRQTxI](https://youtu.be/6PZVwNTl5hI?si=0zB3OvYU4KiRQTxI) Prerequisites[​](#prerequisites "Direct link to Prerequisites") ---------------------------------------------------------------- * Basic TypeScript knowledge * Twitter Developer account * (Optional) Anthropic API key Project Setup[​](#project-setup "Direct link to Project Setup") ---------------------------------------------------------------- 1. Clone the Eliza repo and check out the latest version: git clone https://github.com/elizaOS/eliza.gitcd elizagit checkout 2. Install dependencies: pnpm installpnpm build Environment Variables[​](#environment-variables "Direct link to Environment Variables") ---------------------------------------------------------------------------------------- 1. Copy `.env.example` to `.env`: cp .env.example .env 2. Open `.env` and set your Twitter credentials. You can use username/password or cookies. 3. (Optional) Set your Anthropic API key for the Claude model. 4. For Gaia, set: MODEL_LLM_API_URL=https://modelserverurl/MODEL_EMBEDDING_MODEL=embeddingmodelMODEL_EMBEDDING_ENABLED=true Customizing Your Character[​](#customizing-your-character "Direct link to Customizing Your Character") ------------------------------------------------------------------------------------------------------- 1. Create `agent/mainCharacter.ts`: import { DefaultCharacter } from "./defaultCharacter";import { clients } from "../globalClients";export const mainCharacter = { ...DefaultCharacter, clients: { twitter: clients.twitter }, modelProvider: modelProviders.anthropic,}; 2. Extend the character by overriding properties like `name`, `bio`, `systemPrompt` etc. 3. In `src/index.ts`, import `mainCharacter` and replace instances of `DefaultCharacter` with it. Running the Agent[​](#running-the-agent "Direct link to Running the Agent") ---------------------------------------------------------------------------- 1. Run `pnpm start` 2. The agent will post a tweet and start listening for replies. Test it out by replying to the tweet. Gaia Model Setup[​](#gaia-model-setup "Direct link to Gaia Model Setup") ------------------------------------------------------------------------- 1. In `mainCharacter.ts`, change the model provider: modelProvider: modelProviders.gaiaNet; 2. Customize the `systemPrompt` and `bio` for the new personality. 3. Delete the SQLite DB at `data/sqlite.db` to reset tweet history. 4. Run `pnpm start` again to see the updated agent in action! Next Steps[​](#next-steps "Direct link to Next Steps") ------------------------------------------------------- * Try integrating other extensions like databases, Discord, Telegram * Add on-chain capabilities with EVM, Solana, StarkNet adapters * Chat with your agent directly in the terminal Resources[​](#resources "Direct link to Resources") ---------------------------------------------------- * [Code Repo](https://github.com/dabit3/ai-agent-cognitivedriftt) * [Eliza Docs](https://ai16z.github.io/eliza/) * [Example Character File](https://github.com/ai16z/characterfile/blob/main/examples/example.character.json) * [Default Character](https://github.com/elizaOS/eliza/blob/8f4e2643dcb1a5aafb25267e80d22e7e12fd044a/packages/core/src/defaultCharacter.ts#L4) * [Environment Variables](https://gist.github.com/dabit3/7602e97f3abe0a93bdd84dc250f23021) * [Prerequisites](#prerequisites) * [Project Setup](#project-setup) * [Environment Variables](#environment-variables) * [Customizing Your Character](#customizing-your-character) * [Running the Agent](#running-the-agent) * [Gaia Model Setup](#gaia-model-setup) * [Next Steps](#next-steps) * [Resources](#resources) --- # Creating an AI Agent with Your Own Personality | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page In this tutorial, we'll explore how to create an AI agent that embodies your own personality using data from your Twitter archive, videos, markdown files, and PDFs. We'll leverage the [Characterfile](https://github.com/ai16z/characterfile) repo and [Eliza framework](https://github.com/elizaOS/eliza) to generate and integrate the character data. Video: [https://youtu.be/uouSdtcWXTQ?si=cm13L4T7DQUMXd0C](https://youtu.be/uouSdtcWXTQ?si=cm13L4T7DQUMXd0C) Prerequisites[​](#prerequisites "Direct link to Prerequisites") ---------------------------------------------------------------- * Twitter Developer account * Anthropic API key * Your Twitter archive (download instructions below) * (Optional) Videos, markdown files, PDFs about you Generating Your Character File[​](#generating-your-character-file "Direct link to Generating Your Character File") ------------------------------------------------------------------------------------------------------------------- ### From Twitter Archive[​](#from-twitter-archive "Direct link to From Twitter Archive") 1. Request your Twitter archive: * Go to your Twitter settings * Click "Download an archive of your data" * Wait to receive the archive (timing depends on your account age/activity) 2. Clone the Characterfile repo: git clone https://github.com/ai16z/characterfile.git 3. Run the `tweets-to-character` script: npx tweets-to-character path/to/archive.zip * Select model (e.g. Claude) * (Optional) Add any additional user information 4. Script will generate a `character.json` file from your Tweets ### From Other Files[​](#from-other-files "Direct link to From Other Files") 1. Put videos, PDFs, text, markdown, images in a folder 2. Run the `folder-to-knowledge` script: npx folder-to-knowledge path/to/folder 3. Run `knowledge-to-character` to add knowledge to your character file Setting Up the Agent[​](#setting-up-the-agent "Direct link to Setting Up the Agent") ------------------------------------------------------------------------------------- 1. Clone Eliza repo and check out latest version: git clone https://github.com/elizaOS/eliza.gitgit checkout 2. Install dependencies: pnpm installpnpm build 3. Add your character JSON file to `characters/` 4. Modify character file: * Add `clients`, `modelProvider`, `plugins` fields * Remove `voice` field 5. Set up `.env` with Twitter and Anthropic credentials Running the Agent[​](#running-the-agent "Direct link to Running the Agent") ---------------------------------------------------------------------------- 1. Start agent with your character file: pnpm start --character characters/yourcharacter.json 2. Agent will log in and post an initial tweet 3. Check your Twitter profile to see the agent in action! Next Steps[​](#next-steps "Direct link to Next Steps") ------------------------------------------------------- * Implement dynamic prompting to enhance agent interactions * Extend agent with additional plugins and integrations * [Prerequisites](#prerequisites) * [Generating Your Character File](#generating-your-character-file) * [From Twitter Archive](#from-twitter-archive) * [From Other Files](#from-other-files) * [Setting Up the Agent](#setting-up-the-agent) * [Running the Agent](#running-the-agent) * [Next Steps](#next-steps) --- # Memory Management | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page Overview[​](#overview "Direct link to Overview") ------------------------------------------------- ElizaOS implements a sophisticated memory management system powered by Retrieval-Augmented Generation (RAG). This system enables agents to maintain contextual awareness and knowledge persistence across interactions while optimizing for both performance and accuracy. The Eliza framework uses multiple types of memory to support an agent's long-term engagement, contextual understanding, and adaptive responses. Each type of memory serves a specific purpose: * **Message History**: Stores recent conversations to provide continuity within a session. This helps the agent maintain conversational context and avoid repetitive responses within short-term exchanges. * **Factual Memory**: Holds specific, context-based facts about the user or environment, such as user preferences, recent activities, or specific details mentioned in previous interactions. This type of memory enables the agent to recall user-specific information across sessions. * **Knowledge Base**: Contains general knowledge the agent might need to respond to broader queries or provide informative answers. This memory is more static, helping the agent retrieve pre-defined data, common responses, or static character lore. * **Relationship Tracking**: Manages the agent’s understanding of its relationship with users, including details like user-agent interaction frequency, sentiment, and connection history. It is particularly useful for building rapport and providing a more personalized interaction experience over time. * **RAG Integration**: Uses a vector search to perform contextual recall based on similarity matching. This enables the agent to retrieve relevant memory snippets or knowledge based on the content and intent of the current conversation, making its responses more contextually relevant. Memory Types[​](#memory-types "Direct link to Memory Types") ------------------------------------------------------------- 1. **Memory Managers**: * `messageManager`: Manages conversation history. * `descriptionManager`: Stores user descriptions. * `loreManager`: Handles character lore and background. * `documentsManager`: Manages large documents. * `knowledgeManager`: Stores searchable document fragments. * `ragKnowledgeManager`: Handles RAG-based knowledge retrieval. 2. **Short-term Memory (Message Context)** * Stores recent conversation history * Automatically managed with configurable retention * Used for maintaining immediate context * Implemented via the `messageManager` 3. **Long-term Memory (Descriptions)** * Persists learned information about users and contexts * Stores important facts and relationships * Managed through the `descriptionManager` * Supports semantic search via vector embeddings 4. **Static Knowledge (Lore)** * Contains character-specific information * Holds historical data and background context * Managed via the `loreManager` * Used for maintaining character consistency 5. **Document Storage** * Handles large document management * Supports multiple file formats * Managed through the `documentsManager` * Enables reference material integration 6. **RAG Knowledge Base** * Searchable document fragments * Optimized for semantic retrieval * Managed by `ragKnowledgeManager` * Supports dynamic knowledge integration * * * * * * Memory Systems[​](#memory-systems "Direct link to Memory Systems") ------------------------------------------------------------------- The Eliza framework uses multiple specialized memory managers to support different aspects of agent functionality: // Example memory manager usageconst memoryManager = runtime.getMemoryManager("messages");await memoryManager.createMemory({ id: messageId, content: { text: "Message content" }, userId: userId, roomId: roomId}); Memory managers support operations like: * `messageManager`: Manages conversation history. * `descriptionManager`: Stores user descriptions. * `loreManager`: Handles character lore and background. * `documentsManager`: Manages large documents. * `knowledgeManager`: Stores searchable document fragments. * `ragKnowledgeManager`: Handles RAG-based knowledge retrieval. * Embedding generation and storage * Memory search and retrieval * Memory creation and deletion * Memory counting and filtering Basic Configuration[​](#basic-configuration "Direct link to Basic Configuration") ---------------------------------------------------------------------------------- interface MemoryConfig { dimensions: number; // Vector dimensions (default: 1536 for OpenAI) matchThreshold: number; // Similarity threshold (0.0-1.0) maxMemories: number; // Maximum memories to retrieve retentionPeriod: string; // e.g., '30d', '6h'}const config: MemoryConfig = { dimensions: 1536, matchThreshold: 0.8, maxMemories: 10, retentionPeriod: '30d'}; ### Database Setup[​](#database-setup "Direct link to Database Setup") #### Development (SQLite)[​](#development-sqlite "Direct link to Development (SQLite)") const devConfig = { type: 'sqlite', database: './dev.db', vectorExtension: false // SQLite doesn't support vector operations natively}; #### Production (PostgreSQL)[​](#production-postgresql "Direct link to Production (PostgreSQL)") const prodConfig = { type: 'postgres', url: process.env.DATABASE_URL, vectorExtension: true, // Enable pgvector extension poolConfig: { max: 20, idleTimeoutMillis: 30000, connectionTimeoutMillis: 2000 }}; ### Memory Operations[​](#memory-operations "Direct link to Memory Operations") #### Creating Memories[​](#creating-memories "Direct link to Creating Memories") async function storeMemory(runtime: AgentRuntime, content: string, type: string) { const embedding = await runtime.embed(content); await runtime.messageManager.createMemory({ content: { text: content }, embedding, userId: runtime.agentId, roomId: runtime.roomId, type, metadata: { timestamp: new Date(), source: 'user-interaction' } });} #### Retrieving Memories[​](#retrieving-memories "Direct link to Retrieving Memories") async function retrieveRelevantMemories(runtime: AgentRuntime, query: string) { const embedding = await runtime.embed(query); return await runtime.messageManager.searchMemoriesByEmbedding(embedding, { match_threshold: 0.8, count: 10, include_metadata: true });} ### RAG Knowledge Integration[​](#rag-knowledge-integration "Direct link to RAG Knowledge Integration") 1. **Document Processing Pipeline** # Convert and process documentsnpx folder2knowledge ./docs/content# Integrate with character knowledgenpx knowledge2character ./characters/agent.json ./knowledge/processed 2. **Runtime Integration** // Load and index knowledgeawait runtime.ragKnowledgeManager.loadKnowledge({ path: './knowledge', types: ['markdown', 'text'], chunkSize: 1000});// Query knowledge baseconst context = await runtime.ragKnowledgeManager.search(query, { maxResults: 5, minScore: 0.7}); Performance Optimization[​](#performance-optimization "Direct link to Performance Optimization") ------------------------------------------------------------------------------------------------- ### Memory Indexing[​](#memory-indexing "Direct link to Memory Indexing") -- PostgreSQL vector indexingCREATE INDEX idx_memory_embedding ON memories USING ivfflat (embedding vector_cosine_ops)WITH (lists = 100);-- Composite index for common queriesCREATE INDEX idx_memory_metadata ON memories (user_id, room_id, created_at); ### Caching Strategy[​](#caching-strategy "Direct link to Caching Strategy") interface CacheConfig { maxAge: number; // Maximum age in milliseconds maxSize: number; // Maximum number of entries cleanupInterval: number; // Cleanup interval in milliseconds}const cacheConfig: CacheConfig = { maxAge: 3600000, // 1 hour maxSize: 1000, cleanupInterval: 300000 // 5 minutes}; ### Memory Cleanup[​](#memory-cleanup "Direct link to Memory Cleanup") // Implement regular cleanupasync function cleanupOldMemories(runtime: AgentRuntime) { const result = await runtime.messageManager.cleanup({ olderThan: '30d', excludeTypes: ['critical', 'permanent'], batchSize: 1000 }); console.log(`Cleaned up ${result.count} memories`);} Monitoring and Debugging[​](#monitoring-and-debugging "Direct link to Monitoring and Debugging") ------------------------------------------------------------------------------------------------- ### Logging Configuration[​](#logging-configuration "Direct link to Logging Configuration") const logging = { level: 'debug', components: ['memory', 'rag', 'embedding'], format: 'json', destination: './logs/memory.log'}; ### Health Checks[​](#health-checks "Direct link to Health Checks") async function checkMemoryHealth(runtime: AgentRuntime) { const stats = await runtime.messageManager.getStats(); const health = { totalMemories: stats.count, oldestMemory: stats.oldestTimestamp, averageEmbeddingTime: stats.avgEmbeddingMs, cacheHitRate: stats.cacheHitRate }; return health;} * * * Best Practices[​](#best-practices "Direct link to Best Practices") ------------------------------------------------------------------- 1. **Memory Management** * Implement regular cleanup routines * Use appropriate retention policies * Monitor memory usage and performance 2. **Knowledge Base** * Structure documents for efficient retrieval * Regular updates and maintenance * Version control for knowledge base 3. **Security** * Implement proper access controls * Sanitize input data * Regular security audits 4. **Scalability** * Use connection pooling * Implement proper caching * Monitor and optimize performance ### Common Issues and Solutions[​](#common-issues-and-solutions "Direct link to Common Issues and Solutions") 1. **Embedding Dimension Mismatch** * Verify model configuration matches database schema * Check for mixed embedding models in existing data * Solution: Migration script for standardizing dimensions 2. **Memory Leaks** * Implement proper cleanup routines * Monitor memory usage patterns * Use connection pooling effectively 3. **Search Performance** * Optimize index configuration * Tune match thresholds * Implement efficient caching 4. **Data Consistency** * Use transactions for related operations * Implement retry logic for failures * Regular integrity checks * * * FAQ[​](#faq "Direct link to FAQ") ---------------------------------- ### How do I fix embedding/vector dimension mismatch errors?[​](#how-do-i-fix-embeddingvector-dimension-mismatch-errors "Direct link to How do I fix embedding/vector dimension mismatch errors?") Set `USE_OPENAI_EMBEDDING=TRUE` in .env file or ensure consistent embedding models across your setup. ### How do I reset my agent's memory?[​](#how-do-i-reset-my-agents-memory "Direct link to How do I reset my agent's memory?") Delete db.sqlite in the agent/data directory and restart the agent. For a complete reset, run `pnpm clean` followed by `pnpm install`. ### What storage options exist for agent memory?[​](#what-storage-options-exist-for-agent-memory "Direct link to What storage options exist for agent memory?") SQLite for simple deployments, PostgreSQL/Supabase for complex needs. MongoDB also supported. ### Where should I store static knowledge vs dynamic memory?[​](#where-should-i-store-static-knowledge-vs-dynamic-memory "Direct link to Where should I store static knowledge vs dynamic memory?") Static knowledge goes in character.json's knowledge section. Dynamic memory uses database storage through memory system. ### How do I enable RAG (Retrieval Augmented Generation)?[​](#how-do-i-enable-rag-retrieval-augmented-generation "Direct link to How do I enable RAG (Retrieval Augmented Generation)?") Set `"ragKnowledge": true` in character file. Use folder2knowledge to convert documents into knowledge, then knowledge2character to create character files. ### Do I need different memory setup for production?[​](#do-i-need-different-memory-setup-for-production "Direct link to Do I need different memory setup for production?") Yes - PostgreSQL is recommended over SQLite for production deployments. ### How do I configure database adapters for memory?[​](#how-do-i-configure-database-adapters-for-memory "Direct link to How do I configure database adapters for memory?") Set up database URL in .env file and run proper migration scripts with required schema/functions. ### How do I handle large knowledge datasets?[​](#how-do-i-handle-large-knowledge-datasets "Direct link to How do I handle large knowledge datasets?") Use proper database storage rather than storing directly in character file. Consider implementing custom vector database for larger datasets. ### How can I manage memory for multiple agents running simultaneously?[​](#how-can-i-manage-memory-for-multiple-agents-running-simultaneously "Direct link to How can I manage memory for multiple agents running simultaneously?") Each agent maintains its own memory system. Plan for ~2GB RAM per agent. ### How do I clear memory when changing models?[​](#how-do-i-clear-memory-when-changing-models "Direct link to How do I clear memory when changing models?") When switching between embedding models, delete the database and cached data before restarting the agent. ### How do I customize the memory system?[​](#how-do-i-customize-the-memory-system "Direct link to How do I customize the memory system?") Use different database adapters (PostgreSQL, Supabase, MongoDB) and configure vector stores for knowledge management. ### How do I troubleshoot memory-related issues?[​](#how-do-i-troubleshoot-memory-related-issues "Direct link to How do I troubleshoot memory-related issues?") Check runtime logs, verify database connections, and consider clearing cache and database if behavior seems cached. * * * Further Reading[​](#further-reading "Direct link to Further Reading") ---------------------------------------------------------------------- * [Configuration Guide](/eliza/docs/guides/configuration) * [Overview](#overview) * [Memory Types](#memory-types) * [Memory Systems](#memory-systems) * [Basic Configuration](#basic-configuration) * [Database Setup](#database-setup) * [Memory Operations](#memory-operations) * [RAG Knowledge Integration](#rag-knowledge-integration) * [Performance Optimization](#performance-optimization) * [Memory Indexing](#memory-indexing) * [Caching Strategy](#caching-strategy) * [Memory Cleanup](#memory-cleanup) * [Monitoring and Debugging](#monitoring-and-debugging) * [Logging Configuration](#logging-configuration) * [Health Checks](#health-checks) * [Best Practices](#best-practices) * [Common Issues and Solutions](#common-issues-and-solutions) * [FAQ](#faq) * [How do I fix embedding/vector dimension mismatch errors?](#how-do-i-fix-embeddingvector-dimension-mismatch-errors) * [How do I reset my agent's memory?](#how-do-i-reset-my-agents-memory) * [What storage options exist for agent memory?](#what-storage-options-exist-for-agent-memory) * [Where should I store static knowledge vs dynamic memory?](#where-should-i-store-static-knowledge-vs-dynamic-memory) * [How do I enable RAG (Retrieval Augmented Generation)?](#how-do-i-enable-rag-retrieval-augmented-generation) * [Do I need different memory setup for production?](#do-i-need-different-memory-setup-for-production) * [How do I configure database adapters for memory?](#how-do-i-configure-database-adapters-for-memory) * [How do I handle large knowledge datasets?](#how-do-i-handle-large-knowledge-datasets) * [How can I manage memory for multiple agents running simultaneously?](#how-can-i-manage-memory-for-multiple-agents-running-simultaneously) * [How do I clear memory when changing models?](#how-do-i-clear-memory-when-changing-models) * [How do I customize the memory system?](#how-do-i-customize-the-memory-system) * [How do I troubleshoot memory-related issues?](#how-do-i-troubleshoot-memory-related-issues) * [Further Reading](#further-reading) --- # How to Build an API Plugin | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page This guide walks you through creating a custom plugin for the Eliza AI framework that integrates with NASA's API to fetch space photos. You'll learn how to set up the project structure, implement the required components, and test your plugin across different interfaces. Video Tutorial[​](#video-tutorial "Direct link to Video Tutorial") ------------------------------------------------------------------- Code: [https://github.com/dabit3/eliza-nasa-plugin](https://github.com/dabit3/eliza-nasa-plugin) **Key Timestamps** * **0:00** - Introduction to Eliza plugins and their importance * **3:36** - Overview of the NASA API plugin we'll be building * **6:40** - Setting up the project structure * **12:26** - Creating the basic plugin files * **18:64** - Understanding plugin components * **32:84** - Implementing the NASA API service * **43:22** - Setting up environment variables * **59:12** - Testing the plugin in web interface * **1:15:00** - Testing the plugin with Twitter integration Why Build Plugins?[​](#why-build-plugins "Direct link to Why Build Plugins?") ------------------------------------------------------------------------------ Plugins are powerful extensions to the Eliza framework that allow you to: * Integrate custom functionality into agent workflows * Share reusable components with other developers * Expand the capabilities of your AI agents * Distribute your software products to developers * Take advantage of growing opportunities in the agent space Development Approaches[​](#development-approaches "Direct link to Development Approaches") ------------------------------------------------------------------------------------------- You have two options for developing an Eliza plugin: ### Option 1: Using the Starter Template[​](#option-1-using-the-starter-template "Direct link to Option 1: Using the Starter Template") warning Untested in over a month, this might not work! git clone https://github.com/elizaOS/eliza-plugin-starter.gitcd eliza-plugin-starterpnpm installpnpm tscpnpm mock-eliza --characters=./characters/eternalai.character.json ### Option 2: Building from Scratch[​](#option-2-building-from-scratch "Direct link to Option 2: Building from Scratch") If you prefer to understand every component by building from scratch (as shown in the video tutorial), follow the manual setup process below. ### Project Structure[​](#project-structure "Direct link to Project Structure") For building from scratch, your project structure will look like this: plugin-name/β”œβ”€β”€ package.jsonβ”œβ”€β”€ tsconfig.jsonβ”œβ”€β”€ tsup.config.ts└── src/ β”œβ”€β”€ index.ts # Main plugin entry β”œβ”€β”€ types.ts # Type definitions β”œβ”€β”€ environment.ts # Environment config β”œβ”€β”€ services/ # API services β”œβ”€β”€ actions/ # Plugin actions └── examples/ # Usage examples > When using the starter template, you'll find additional directories like `common/` for shared utilities and mocked client capabilities for testing. Setup Steps[​](#setup-steps "Direct link to Setup Steps") ---------------------------------------------------------- 1. **Create and Initialize Project** # Create project directorymkdir eliza-plugin-nasacd eliza-plugin-nasa# Clone Eliza repositorygit clone git@github.com:elizaOS/eliza.gitcd elizagit checkout $(git describe --tags --abbrev=0) 2. **Create Project Directory** cd packagesmkdir eliza-plugin-nasacd eliza-plugin-nasa 3. **Create Base Configuration Files** Create `package.json`: { "name": "@elizaos/plugin-nasa", "version": "1.0.0", "main": "dist/index.js", "types": "dist/index.d.ts", "dependencies": { "@elizaos/core": "latest" }, "peerDependencies": { "@elizaos/core": "^1.0.0" }} Create `tsconfig.json`: { "extends": "../../tsconfig.json", "compilerOptions": { "outDir": "./dist", "rootDir": "./src" }, "include": ["src"]} Create `tsup.config.ts`: import { defineConfig } from 'tsup'export default defineConfig({ entry: ['src/index.ts'], format: ['cjs', 'esm'], dts: true, splitting: false, sourcemap: true, clean: true,}) 4. **Create Project Structure** # Create directoriesmkdir srcmkdir src/actions# Create essential filestouch package.json tsconfig.json tsup.config.tstouch src/index.ts src/types.ts src/examples.tstouch src/services.ts src/environment.tstouch src/actions/getMarsRoverPhoto.ts src/actions/getApod.ts 4. **Configure Character File** Create `src/characters/natter.character.ts`: import { ModelProviderName, Clients } from "@elizaos/core";import { nasaPlugin } from '@elizaos/plugin-nasa'export const mainCharacter = { name: "sound_craft_", clients: [Clients.TWITTER], modelProvider: ModelProviderName.HYPERBOLIC, plugins: [nasaPlugin], // ... rest of character configuration}; See example: [https://github.com/dabit3/eliza-nasa-plugin/blob/main/agent/src/nader.character.ts](https://github.com/dabit3/eliza-nasa-plugin/blob/main/agent/src/nader.character.ts) * * * Core Components[​](#core-components "Direct link to Core Components") ---------------------------------------------------------------------- ### Types[​](#types "Direct link to Types") Source: `src/types.ts` interface ApodResponse { url: string; title: string; explanation: string; date: string;}interface MarsRoverResponse { photos: Array<{ img_src: string; earth_date: string; camera: { name: string; } }>;} ### Plugin Entry[​](#plugin-entry "Direct link to Plugin Entry") Source: `src/index.ts` import type { Plugin } from "@elizaos/core";import { getMarsRoverPhoto } from './actions/getMarsRoverPhoto';import { getApod } from './actions/getApod';export const nasaPlugin: Plugin = { name: "nasa-plugin", description: "NASA API integration for space photos", actions: [getMarsRoverPhoto, getApod]}; ### Actions[​](#actions "Direct link to Actions") Actions define how your plugin responds to messages: import { Action, IAgentRuntime } from "@elizaos/core";export const getMarsRoverPhoto: Action = { name: "NASA_GET_MARS_PHOTO", similes: ["SHOW_MARS_PICTURE"], description: "Fetches a photo from Mars rovers", validate: async (runtime: IAgentRuntime) => { return validateNasaConfig(runtime); }, handler: async (runtime: IAgentRuntime, state: any, callback: any) => { const data = await getNasaService(runtime).getMarsRoverPhoto(); await callback(`Here's a photo from Mars rover ${data.rover}...`); return true; }}; Source: `src/actions/getMarsRoverPhoto.ts` ### Services[​](#services "Direct link to Services") Services handle API interactions: const nasaService = (config: NasaConfig) => ({ getMarsRoverPhoto: async () => { const response = await fetch( `https://api.nasa.gov/mars-photos/api/v1/rovers/curiosity/photos?api_key=${config.apiKey}` ); return response.json(); }}); ### Environment Configuration[​](#environment-configuration "Direct link to Environment Configuration") Create `.env` in the root directory: NASA_API_KEY=your_api_key_hereTWITTER_USERNAME=your_twitter_usernameTWITTER_PASSWORD=your_twitter_passwordTWITTER_EMAIL=your_twitter_email const validateNasaConfig = (runtime: IAgentRuntime) => { const config = { apiKey: runtime.getSetting("NASA_API_KEY") }; if (!config.apiKey) { throw new Error("NASA API key not configured"); } return config;}; Testing Your Plugin[​](#testing-your-plugin "Direct link to Testing Your Plugin") ---------------------------------------------------------------------------------- > See 00:12:39 in the video ### Development Testing[​](#development-testing "Direct link to Development Testing") # Using mock clientpnpm mock-eliza --characters=./characters/eternalai.character.json ### Production Testing[​](#production-testing "Direct link to Production Testing") # Web interfacepnpm start client# Visit localhost:5173# Twitter integration# Ensure Twitter credentials are configured in .envpnpm start * * * FAQ[​](#faq "Direct link to FAQ") ---------------------------------- ### How should I handle errors in my plugin?[​](#how-should-i-handle-errors-in-my-plugin "Direct link to How should I handle errors in my plugin?") Validate environment variables before making API calls and provide meaningful error messages. Implement retry logic for failed requests to improve reliability. ### What's the best way to ensure type safety?[​](#whats-the-best-way-to-ensure-type-safety "Direct link to What's the best way to ensure type safety?") Define interfaces for API responses and use TypeScript throughout your plugin to maintain type consistency and get better development experience. ### How should I organize my plugin code?[​](#how-should-i-organize-my-plugin-code "Direct link to How should I organize my plugin code?") Separate concerns into distinct files, follow consistent naming conventions, and thoroughly document your code for maintainability. ### Why isn't my plugin loading?[​](#why-isnt-my-plugin-loading "Direct link to Why isn't my plugin loading?") Verify your package.json configuration, check that the plugin is properly registered in the character file, and ensure all dependencies are installed correctly. ### Why isn't my action triggering?[​](#why-isnt-my-action-triggering "Direct link to Why isn't my action triggering?") Review your action examples for accuracy, check the validate function logic, and verify that the action is properly registered in your plugin. ### What should I do if I have API integration issues?[​](#what-should-i-do-if-i-have-api-integration-issues "Direct link to What should I do if I have API integration issues?") Confirm your API key is properly configured, verify the API endpoint URLs are correct, and check that responses are being handled appropriately. * [Video Tutorial](#video-tutorial) * [Why Build Plugins?](#why-build-plugins) * [Development Approaches](#development-approaches) * [Option 1: Using the Starter Template](#option-1-using-the-starter-template) * [Option 2: Building from Scratch](#option-2-building-from-scratch) * [Project Structure](#project-structure) * [Setup Steps](#setup-steps) * [Core Components](#core-components) * [Types](#types) * [Plugin Entry](#plugin-entry) * [Actions](#actions) * [Services](#services) * [Environment Configuration](#environment-configuration) * [Testing Your Plugin](#testing-your-plugin) * [Development Testing](#development-testing) * [Production Testing](#production-testing) * [FAQ](#faq) * [How should I handle errors in my plugin?](#how-should-i-handle-errors-in-my-plugin) * [What's the best way to ensure type safety?](#whats-the-best-way-to-ensure-type-safety) * [How should I organize my plugin code?](#how-should-i-organize-my-plugin-code) * [Why isn't my plugin loading?](#why-isnt-my-plugin-loading) * [Why isn't my action triggering?](#why-isnt-my-action-triggering) * [What should I do if I have API integration issues?](#what-should-i-do-if-i-have-api-integration-issues) --- # WSL Setup Guide | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page Steps to run Eliza on Windows computer using WSL. [AI Dev School Tutorial](https://www.youtube.com/watch?v=ArptLpQiKfI) Install WSL[​](#install-wsl "Direct link to Install WSL") ---------------------------------------------------------- 1. Open PowerShell as Administrator and run: wsl --install 2. Restart your computer 3. Launch Ubuntu from the Start menu and create your Linux username/password Install Dependencies[​](#install-dependencies "Direct link to Install Dependencies") ------------------------------------------------------------------------------------- 1. Update Ubuntu packages: sudo apt update && sudo apt upgrade -y 2. Install system dependencies: sudo apt install -y \ build-essential \ python3 \ python3-pip \ git \ curl \ ffmpeg \ libtool-bin \ autoconf \ automake \ libopus-dev 3. Install Node.js via nvm: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bashsource ~/.bashrcnvm install 23nvm use 23 4. Install pnpm: curl -fsSL https://get.pnpm.io/install.sh | sh -source ~/.bashrc Optional: CUDA Support[​](#optional-cuda-support "Direct link to Optional: CUDA Support") ------------------------------------------------------------------------------------------ If you have an NVIDIA GPU and want CUDA support: 1. Install CUDA Toolkit on Windows from [NVIDIA's website](https://developer.nvidia.com/cuda-downloads) 2. WSL will automatically detect and use the Windows CUDA installation Clone and Setup Eliza[​](#clone-and-setup-eliza "Direct link to Clone and Setup Eliza") ---------------------------------------------------------------------------------------- Follow the [Quickstart Guide](/eliza/docs/quickstart) starting from the "Installation" section. Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ---------------------------------------------------------------------- * If you encounter `node-gyp` errors, ensure build tools are installed: sudo apt install -y nodejs-dev node-gyp * For audio-related issues, verify ffmpeg installation: ffmpeg -version * For permission issues, ensure your user owns the project directory: sudo chown -R $USER:$USER ~/path/to/eliza * [Install WSL](#install-wsl) * [Install Dependencies](#install-dependencies) * [Optional: CUDA Support](#optional-cuda-support) * [Clone and Setup Eliza](#clone-and-setup-eliza) * [Troubleshooting](#troubleshooting) --- # 🀝 Trust Engine | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page Overview[​](#overview "Direct link to Overview") ------------------------------------------------- The Trust Engine is a sophisticated system for evaluating, tracking, and managing trust scores for token recommendations and trading activity. It combines on-chain analysis, trader metrics, and historical performance to create a comprehensive trust framework. Core Components[​](#core-components "Direct link to Core Components") ---------------------------------------------------------------------- ### Trust Score Database[​](#trust-score-database "Direct link to Trust Score Database") The database schema manages various aspects of trust: interface TrustScoreDatabase { // Core data structures recommenders: Recommender[]; metrics: RecommenderMetrics[]; tokenPerformance: TokenPerformance[]; recommendations: TokenRecommendation[];}interface Recommender { id: string; address: string; solanaPubkey?: string; telegramId?: string; discordId?: string; twitterId?: string; ip?: string;}interface RecommenderMetrics { recommenderId: string; trustScore: number; totalRecommendations: number; successfulRecs: number; avgTokenPerformance: number; riskScore: number; consistencyScore: number; virtualConfidence: number; lastActiveDate: Date;} ### Token Analysis[​](#token-analysis "Direct link to Token Analysis") The system tracks comprehensive token metrics: interface TokenPerformance { tokenAddress: string; priceChange24h: number; volumeChange24h: number; trade_24h_change: number; liquidity: number; liquidityChange24h: number; holderChange24h: number; rugPull: boolean; isScam: boolean; marketCapChange24h: number; sustainedGrowth: boolean; rapidDump: boolean; suspiciousVolume: boolean; validationTrust: number; lastUpdated: Date;} Trust Scoring System[​](#trust-scoring-system "Direct link to Trust Scoring System") ------------------------------------------------------------------------------------- ### Score Calculation[​](#score-calculation "Direct link to Score Calculation") async function calculateTrustScore( recommenderId: string, metrics: RecommenderMetrics,): Promise { const weights = { successRate: 0.3, avgPerformance: 0.2, consistency: 0.2, riskMetric: 0.15, timeDecay: 0.15, }; const successRate = metrics.successfulRecs / metrics.totalRecommendations; const normalizedPerformance = normalizePerformance( metrics.avgTokenPerformance, ); const timeDecayFactor = calculateTimeDecay(metrics.lastActiveDate); return ( (successRate * weights.successRate + normalizedPerformance * weights.avgPerformance + metrics.consistencyScore * weights.consistency + (1 - metrics.riskScore) * weights.riskMetric + timeDecayFactor * weights.timeDecay) * 100 );} ### Token Validation[​](#token-validation "Direct link to Token Validation") async function validateToken( tokenAddress: string, performance: TokenPerformance,): Promise { // Minimum requirements const requirements = { minLiquidity: 1000, // $1000 USD minHolders: 100, maxOwnership: 0.2, // 20% max single holder minVolume: 500, // $500 USD daily volume }; // Red flags if ( performance.rugPull || performance.isScam || performance.rapidDump || performance.suspiciousVolume ) { return false; } // Basic requirements return ( performance.liquidity >= requirements.minLiquidity && !performance.rapidDump && performance.validationTrust > 0.5 );} Trade Management[​](#trade-management "Direct link to Trade Management") ------------------------------------------------------------------------- ### Trade Performance Tracking[​](#trade-performance-tracking "Direct link to Trade Performance Tracking") interface TradePerformance { token_address: string; recommender_id: string; buy_price: number; sell_price: number; buy_timeStamp: string; sell_timeStamp: string; profit_usd: number; profit_percent: number; market_cap_change: number; liquidity_change: number; rapidDump: boolean;}async function recordTradePerformance( trade: TradePerformance, isSimulation: boolean,): Promise { const tableName = isSimulation ? "simulation_trade" : "trade"; await db.query( ` INSERT INTO ${tableName} ( token_address, recommender_id, buy_price, sell_price, buy_timeStamp, sell_timeStamp, profit_usd, profit_percent, market_cap_change, liquidity_change, rapidDump ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11) `, [ /* parameters */ ], );} ### Risk Management[​](#risk-management "Direct link to Risk Management") async function assessTradeRisk( token: TokenPerformance, recommender: RecommenderMetrics,): Promise<{ riskLevel: "LOW" | "MEDIUM" | "HIGH"; maxPositionSize: number;}> { const riskFactors = { tokenTrust: token.validationTrust, recommenderTrust: recommender.trustScore, marketMetrics: { liquidity: token.liquidity, volume: token.volumeChange24h, holders: token.holderChange24h, }, }; // Calculate composite risk score const riskScore = calculateRiskScore(riskFactors); // Determine position sizing const maxPosition = determinePositionSize(riskScore); return { riskLevel: getRiskLevel(riskScore), maxPositionSize: maxPosition, };} Recommendation Analysis[​](#recommendation-analysis "Direct link to Recommendation Analysis") ---------------------------------------------------------------------------------------------- ### Pattern Detection[​](#pattern-detection "Direct link to Pattern Detection") async function analyzeRecommendationPatterns( recommenderId: string,): Promise { const history = await getRecommenderHistory(recommenderId); return { timeOfDay: analyzeTimingPatterns(history), tokenTypes: analyzeTokenPreferences(history), successRateByType: calculateTypeSuccessRates(history), riskProfile: assessRiskProfile(history), };} ### Performance Metrics[​](#performance-metrics "Direct link to Performance Metrics") interface PerformanceMetrics { profitability: number; consistency: number; riskAdjustedReturn: number; maxDrawdown: number; winRate: number;}async function calculatePerformanceMetrics( recommendations: TokenRecommendation[],): Promise { const trades = await getTradesFromRecommendations(recommendations); return { profitability: calculateProfitability(trades), consistency: calculateConsistency(trades), riskAdjustedReturn: calculateSharpeRatio(trades), maxDrawdown: calculateMaxDrawdown(trades), winRate: calculateWinRate(trades), };} Integration with Trading System[​](#integration-with-trading-system "Direct link to Integration with Trading System") ---------------------------------------------------------------------------------------------------------------------- ### Trade Execution[​](#trade-execution "Direct link to Trade Execution") async function executeTrade( recommendation: TokenRecommendation, trustScore: number,): Promise { const riskAssessment = await assessTradeRisk( recommendation.tokenAddress, recommendation.recommenderId, ); // Calculate position size based on trust score const positionSize = calculatePositionSize( trustScore, riskAssessment.maxPositionSize, ); if (positionSize > 0) { await executeSwap({ inputToken: "SOL", outputToken: recommendation.tokenAddress, amount: positionSize, }); await recordTradeEntry(recommendation, positionSize); return true; } return false;} ### Position Management[​](#position-management "Direct link to Position Management") async function managePosition( position: TradePosition, metrics: TokenPerformance,): Promise { // Exit conditions if ( metrics.rapidDump || metrics.suspiciousVolume || calculateDrawdown(position) > MAX_DRAWDOWN ) { await executeExit(position); return; } // Position sizing adjustments const newSize = recalculatePosition(position, metrics); if (newSize !== position.size) { await adjustPosition(position, newSize); }} Monitoring and Alerts[​](#monitoring-and-alerts "Direct link to Monitoring and Alerts") ---------------------------------------------------------------------------------------- ### Performance Monitoring[​](#performance-monitoring "Direct link to Performance Monitoring") async function monitorTrustMetrics(): Promise { // Monitor trust score changes const scoreChanges = await getTrustScoreChanges(); for (const change of scoreChanges) { if (Math.abs(change.delta) > TRUST_THRESHOLD) { await notifyTrustChange(change); } } // Monitor trading performance const performanceMetrics = await getPerformanceMetrics(); for (const metric of performanceMetrics) { if (metric.drawdown > MAX_DRAWDOWN) { await notifyRiskAlert(metric); } }} ### Alert System[​](#alert-system "Direct link to Alert System") interface TrustAlert { type: "SCORE_CHANGE" | "RISK_LEVEL" | "PERFORMANCE"; severity: "LOW" | "MEDIUM" | "HIGH"; message: string; data: any;}async function handleAlert(alert: TrustAlert): Promise { switch (alert.severity) { case "HIGH": await sendImmediateNotification(alert); await pauseTrading(alert.data); break; case "MEDIUM": await sendNotification(alert); await adjustRiskLevels(alert.data); break; case "LOW": await logAlert(alert); break; }} Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ---------------------------------------------------------------------- ### Common Issues[​](#common-issues "Direct link to Common Issues") 1. **Trust Score Anomalies** async function investigateTrustAnomaly( recommenderId: string,): Promise { const history = await getRecommenderHistory(recommenderId); const metrics = await getRecommenderMetrics(recommenderId); const trades = await getRecommenderTrades(recommenderId); return analyzeAnomalies(history, metrics, trades);} 2. **Trade Execution Failures** async function handleTradeFailure( error: Error, trade: TradeAttempt,): Promise { await logTradeError(error, trade); await adjustTrustScore(trade.recommenderId, "FAILURE"); await notifyTradeFailure(trade);} * [Overview](#overview) * [Core Components](#core-components) * [Trust Score Database](#trust-score-database) * [Token Analysis](#token-analysis) * [Trust Scoring System](#trust-scoring-system) * [Score Calculation](#score-calculation) * [Token Validation](#token-validation) * [Trade Management](#trade-management) * [Trade Performance Tracking](#trade-performance-tracking) * [Risk Management](#risk-management) * [Recommendation Analysis](#recommendation-analysis) * [Pattern Detection](#pattern-detection) * [Performance Metrics](#performance-metrics) * [Integration with Trading System](#integration-with-trading-system) * [Trade Execution](#trade-execution) * [Position Management](#position-management) * [Monitoring and Alerts](#monitoring-and-alerts) * [Performance Monitoring](#performance-monitoring) * [Alert System](#alert-system) * [Troubleshooting](#troubleshooting) * [Common Issues](#common-issues) --- # πŸ“ˆ Autonomous Trading | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page Overview[​](#overview "Direct link to Overview") ------------------------------------------------- Eliza's autonomous trading system enables automated token trading on the Solana blockchain. The system integrates with Jupiter aggregator for efficient swaps, implements smart order routing, and includes risk management features. Core Components[​](#core-components "Direct link to Core Components") ---------------------------------------------------------------------- ### Token Provider[​](#token-provider "Direct link to Token Provider") Manages token information and market data: class TokenProvider { constructor( private tokenAddress: string, private walletProvider: WalletProvider, ) { this.cache = new NodeCache({ stdTTL: 300 }); // 5 minutes cache } async fetchPrices(): Promise { const { SOL, BTC, ETH } = TOKEN_ADDRESSES; // Fetch current prices return { solana: { usd: "0" }, bitcoin: { usd: "0" }, ethereum: { usd: "0" }, }; } async getProcessedTokenData(): Promise { return { security: await this.fetchTokenSecurity(), tradeData: await this.fetchTokenTradeData(), holderDistributionTrend: await this.analyzeHolderDistribution(), highValueHolders: await this.filterHighValueHolders(), recentTrades: await this.checkRecentTrades(), dexScreenerData: await this.fetchDexScreenerData(), }; }} ### Swap Execution[​](#swap-execution "Direct link to Swap Execution") Implementation of token swaps using Jupiter: async function swapToken( connection: Connection, walletPublicKey: PublicKey, inputTokenCA: string, outputTokenCA: string, amount: number,): Promise { // Get token decimals const decimals = await getTokenDecimals(connection, inputTokenCA); const adjustedAmount = amount * 10 ** decimals; // Fetch quote const quoteResponse = await fetch( `https://quote-api.jup.ag/v6/quote?inputMint=${inputTokenCA}` + `&outputMint=${outputTokenCA}` + `&amount=${adjustedAmount}` + `&slippageBps=50`, ); // Execute swap const swapResponse = await fetch("https://quote-api.jup.ag/v6/swap", { method: "POST", body: JSON.stringify({ quoteResponse: await quoteResponse.json(), userPublicKey: walletPublicKey.toString(), wrapAndUnwrapSol: true, }), }); return swapResponse.json();} Position Management[​](#position-management "Direct link to Position Management") ---------------------------------------------------------------------------------- ### Order Book System[​](#order-book-system "Direct link to Order Book System") interface Order { userId: string; ticker: string; contractAddress: string; timestamp: string; buyAmount: number; price: number;}class OrderBookProvider { async addOrder(order: Order): Promise { let orderBook = await this.readOrderBook(); orderBook.push(order); await this.writeOrderBook(orderBook); } async calculateProfitLoss(userId: string): Promise { const orders = await this.getUserOrders(userId); return orders.reduce((total, order) => { const currentPrice = this.getCurrentPrice(order.ticker); const pl = (currentPrice - order.price) * order.buyAmount; return total + pl; }, 0); }} ### Position Sizing[​](#position-sizing "Direct link to Position Sizing") async function calculatePositionSize( tokenData: ProcessedTokenData, riskLevel: "LOW" | "MEDIUM" | "HIGH",): Promise { const { liquidity, marketCap } = tokenData.dexScreenerData.pairs[0]; // Impact percentages based on liquidity const impactPercentages = { LOW: 0.01, // 1% of liquidity MEDIUM: 0.05, // 5% of liquidity HIGH: 0.1, // 10% of liquidity }; return { none: 0, low: liquidity.usd * impactPercentages.LOW, medium: liquidity.usd * impactPercentages.MEDIUM, high: liquidity.usd * impactPercentages.HIGH, };} Risk Management[​](#risk-management "Direct link to Risk Management") ---------------------------------------------------------------------- ### Token Validation[​](#token-validation "Direct link to Token Validation") async function validateToken(token: TokenPerformance): Promise { const security = await fetchTokenSecurity(token.tokenAddress); // Red flags check if ( security.rugPull || security.isScam || token.rapidDump || token.suspiciousVolume || token.liquidity.usd < 1000 || // Minimum $1000 liquidity token.marketCap < 100000 // Minimum $100k market cap ) { return false; } // Holder distribution check const holderData = await fetchHolderList(token.tokenAddress); const topHolderPercent = calculateTopHolderPercentage(holderData); if (topHolderPercent > 0.5) { // >50% held by top holders return false; } return true;} ### Trade Management[​](#trade-management "Direct link to Trade Management") interface TradeManager { async executeTrade(params: { inputToken: string, outputToken: string, amount: number, slippage: number }): Promise; async monitorPosition(params: { tokenAddress: string, entryPrice: number, stopLoss: number, takeProfit: number }): Promise; async closePosition(params: { tokenAddress: string, amount: number }): Promise;} Market Analysis[​](#market-analysis "Direct link to Market Analysis") ---------------------------------------------------------------------- ### Price Data Collection[​](#price-data-collection "Direct link to Price Data Collection") async function collectMarketData( tokenAddress: string,): Promise { return { price: await fetchCurrentPrice(tokenAddress), volume_24h: await fetch24HourVolume(tokenAddress), price_change_24h: await fetch24HourPriceChange(tokenAddress), liquidity: await fetchLiquidity(tokenAddress), holder_data: await fetchHolderData(tokenAddress), trade_history: await fetchTradeHistory(tokenAddress), };} ### Technical Analysis[​](#technical-analysis "Direct link to Technical Analysis") function analyzeMarketConditions(tradeData: TokenTradeData): MarketAnalysis { return { trend: analyzePriceTrend(tradeData.price_history), volume_profile: analyzeVolumeProfile(tradeData.volume_history), liquidity_depth: analyzeLiquidityDepth(tradeData.liquidity), holder_behavior: analyzeHolderBehavior(tradeData.holder_data), };} Trade Execution[​](#trade-execution "Direct link to Trade Execution") ---------------------------------------------------------------------- ### Swap Implementation[​](#swap-implementation "Direct link to Swap Implementation") async function executeSwap( runtime: IAgentRuntime, input: { tokenIn: string; tokenOut: string; amountIn: number; slippage: number; },): Promise { // Prepare transaction const { swapTransaction: transaction } = await getSwapTransaction(input); // Sign transaction const keypair = getKeypairFromPrivateKey( runtime.getSetting("SOLANA_PRIVATE_KEY") ?? runtime.getSetting("WALLET_PRIVATE_KEY"), ); transaction.sign([keypair]); // Execute swap const signature = await connection.sendTransaction(transaction); // Confirm transaction await connection.confirmTransaction({ signature, blockhash: latestBlockhash.blockhash, lastValidBlockHeight: latestBlockhash.lastValidBlockHeight, }); return signature;} ### DAO Integration[​](#dao-integration "Direct link to DAO Integration") async function executeSwapForDAO( runtime: IAgentRuntime, params: { inputToken: string; outputToken: string; amount: number; },): Promise { const authority = getAuthorityKeypair(runtime); const [statePDA, walletPDA] = await derivePDAs(authority); // Prepare instruction data const instructionData = prepareSwapInstruction(params); // Execute swap through DAO return invokeSwapDao( connection, authority, statePDA, walletPDA, instructionData, );} Monitoring & Safety[​](#monitoring--safety "Direct link to Monitoring & Safety") --------------------------------------------------------------------------------- ### Health Checks[​](#health-checks "Direct link to Health Checks") async function performHealthChecks(): Promise { return { connection: await checkConnectionStatus(), wallet: await checkWalletBalance(), orders: await checkOpenOrders(), positions: await checkPositions(), };} ### Safety Limits[​](#safety-limits "Direct link to Safety Limits") const SAFETY_LIMITS = { MAX_POSITION_SIZE: 0.1, // 10% of portfolio MAX_SLIPPAGE: 0.05, // 5% slippage MIN_LIQUIDITY: 1000, // $1000 minimum liquidity MAX_PRICE_IMPACT: 0.03, // 3% price impact STOP_LOSS: 0.15, // 15% stop loss}; Error Handling[​](#error-handling "Direct link to Error Handling") ------------------------------------------------------------------- ### Transaction Errors[​](#transaction-errors "Direct link to Transaction Errors") async function handleTransactionError( error: Error, transaction: Transaction,): Promise { if (error.message.includes("insufficient funds")) { await handleInsufficientFunds(); } else if (error.message.includes("slippage tolerance exceeded")) { await handleSlippageError(transaction); } else { await logTransactionError(error, transaction); }} ### Recovery Procedures[​](#recovery-procedures "Direct link to Recovery Procedures") async function recoverFromError( error: Error, context: TradingContext,): Promise { // Stop all active trades await stopActiveTrades(); // Close risky positions await closeRiskyPositions(); // Reset system state await resetTradingState(); // Notify administrators await notifyAdministrators(error, context);} * [Overview](#overview) * [Core Components](#core-components) * [Token Provider](#token-provider) * [Swap Execution](#swap-execution) * [Position Management](#position-management) * [Order Book System](#order-book-system) * [Position Sizing](#position-sizing) * [Risk Management](#risk-management) * [Token Validation](#token-validation) * [Trade Management](#trade-management) * [Market Analysis](#market-analysis) * [Price Data Collection](#price-data-collection) * [Technical Analysis](#technical-analysis) * [Trade Execution](#trade-execution) * [Swap Implementation](#swap-implementation) * [DAO Integration](#dao-integration) * [Monitoring & Safety](#monitoring--safety) * [Health Checks](#health-checks) * [Safety Limits](#safety-limits) * [Error Handling](#error-handling) * [Transaction Errors](#transaction-errors) * [Recovery Procedures](#recovery-procedures) --- # Page Not Found | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) Page Not Found ============== We could not find what you were looking for. Please contact the owner of the site that linked you to the original URL and let them know their link is broken. --- # Page Not Found | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) Page Not Found ============== We could not find what you were looking for. Please contact the owner of the site that linked you to the original URL and let them know their link is broken. --- # πŸ«– Eliza in TEE | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page ![](/eliza/assets/images/eliza_in_tee-9d4ac74fe40ee5b815cc350c5168c6c5.jpg) Overview[​](#overview "Direct link to Overview") ------------------------------------------------- The Eliza agent can be deployed in a TEE environment to ensure the security and privacy of the agent's data. This guide will walk you through the process of setting up and running an Eliza agent in a TEE environment by utilizing the TEE Plugin in the Eliza Framework. ### Background[​](#background "Direct link to Background") The TEE Plugin in the Eliza Framework is built on top of the [Dstack SDK](https://github.com/Dstack-TEE/dstack) , which is designed to simplify the steps for developers to deploy programs to CVM (Confidential VM), and to follow the security best practices by default. The main features include: * Convert any docker container to a CVM image to deploy on supported TEEs * Remote Attestation API and a chain-of-trust visualization on Web UI * Automatic RA-HTTPS wrapping with content addressing domain on 0xABCD.dstack.host * Decouple the app execution and state persistent from specific hardware with decentralized Root-of-Trust * * * Core Components[​](#core-components "Direct link to Core Components") ---------------------------------------------------------------------- Eliza's TEE implementation consists of two primary providers that handle secure key management operations and remote attestations. These components work together to provide: 1. Secure key derivation within the TEE 2. Verifiable proof of TEE execution 3. Support for both development (simulator) and production environments The providers are typically used together, as seen in the wallet key derivation process where each derived key includes an attestation quote to prove it was generated within the TEE environment. * * * ### Derive Key Provider[​](#derive-key-provider "Direct link to Derive Key Provider") The DeriveKeyProvider enables secure key derivation within TEE environments. It supports: * Multiple TEE modes: * `LOCAL`: Connects to simulator at `localhost:8090` for local development on Mac/Windows * `DOCKER`: Connects to simulator via `host.docker.internal:8090` for local development on Linux * `PRODUCTION`: Connects to actual TEE environment when deployed to the [TEE Cloud](https://teehouse.vercel.app) Key features: * Support to deriveEd25519 (Solana) and ECDSA (EVM) keypairs * Generates deterministic keys based on a secret salt and agent ID * Includes remote attestation for each derived key * Supports raw key derivation for custom use cases Example usage: const provider = new DeriveKeyProvider(teeMode);// For Solanaconst { keypair, attestation } = await provider.deriveEd25519Keypair( secretSalt, "solana", agentId,);// For EVMconst { keypair, attestation } = await provider.deriveEcdsaKeypair( secretSalt, "evm", agentId,);// For raw key derivationconst rawKey = await provider.deriveRawKey( secretSalt, "raw",); * * * ### Remote Attestation Provider[​](#remote-attestation-provider "Direct link to Remote Attestation Provider") The RemoteAttestationProvider handles TEE environment verification and quote generation. It: * Connects to the same TEE modes as DeriveKeyProvider * Generates TDX quotes with replay protection (RTMRs) * Provides attestation data that can be verified by third parties Key features: * Generates attestation quotes with custom report data * Includes timestamp for quote verification * Supports both simulator and production environments Example usage: const provider = new RemoteAttestationProvider(teeMode);const quote = await provider.generateAttestation(reportData); Tutorial[​](#tutorial "Direct link to Tutorial") ------------------------------------------------- * * * ### Prerequisites[​](#prerequisites "Direct link to Prerequisites") Before getting started with Eliza, ensure you have: * [Docker Desktop](https://www.docker.com/products/docker-desktop/) or [Orbstack](https://orbstack.dev/) (Orbstack is recommended) * For Mac/Windows: Check the prerequisites from [Quickstart Guide](/eliza/docs/quickstart) * For Linux: You just need Docker * * * ### Environment Setup[​](#environment-setup "Direct link to Environment Setup") To set up your environment for TEE development: 1. **Configure TEE Mode** Set the `TEE_MODE` environment variable to one of: # For Mac/Windows local developmentTEE_MODE=LOCAL# For Linux/Docker local developmentTEE_MODE=DOCKER# For production deploymentTEE_MODE=PRODUCTION 2. **Set Required Environment Variables** # Required for key derivationWALLET_SECRET_SALT=your_secret_salt 3. **Start the TEE Simulator** docker pull phalanetwork/tappd-simulator:latest# by default the simulator is available in localhost:8090docker run --rm -p 8090:8090 phalanetwork/tappd-simulator:latest ### Run an Eliza Agent Locally with TEE Simulator[​](#run-an-eliza-agent-locally-with-tee-simulator "Direct link to Run an Eliza Agent Locally with TEE Simulator") 1. **Configure Eliza Agent** Go through the [configuration guide](/eliza/docs/guides/configuration) to set up your Eliza agent. 2. **Start the TEE Simulator** Follow the simulator setup instructions above based on your TEE mode. 3. **For Mac/Windows** Make sure to set the `TEE_MODE` environment variable to `LOCAL`. Then you can install the dependencies and run the agent locally: pnpm ipnpm buildpnpm start --character=./characters/yourcharacter.character.json 4. **Verify TEE Attestation** You can verify the TEE attestation quote by going to the [TEE RA Explorer](https://proof.t16z.com/) and pasting the attestation quote from the agent logs. Here's an example of interacting with the Eliza agent to ask for the agent's wallet address: You: what's your wallet address? Log output from the agent: Generating attestation for: {"agentId":"025e0996-69d7-0dce-8189-390e354fd1c1","publicKey":"9yZBmCRRFEBtA3KYokxC24igv1ijFp6tyvzKxRs3khTE"}rtmr0: a4a17452e7868f62f77ea2039bd2840e7611a928c26e87541481256f57bfbe3647f596abf6e8f6b5a0e7108acccc6e89rtmr1: db6bcc74a3ac251a6398eca56b2fcdc8c00a9a0b36bc6299e06fb4bb766cb9ecc96de7e367c56032c7feff586f9e557ertmr2: 2cbe156e110b0cc4b2418600dfa9fb33fc60b3f04b794ec1b8d154b48f07ba8c001cd31f75ca0d0fb516016552500d07rtmr3: eb7110de9956d7b4b1a3397f843b39d92df4caac263f5083e34e3161e4d6686c46c3239e7fbf61241a159d8da6dc6bd1fRemote attestation quote: {quote: '0x0400030081000000736940f888442c8ca8cb432d7a87145f9b7aeab1c5d129ce901716a7506375426ea8741ca69be68e92c5df29f539f103eb60ab6780c56953b0d81af523a031617b32d5e8436cceb019177103f4aceedbf114a846baf8e8e2b8e6d3956e96d6b89d94a0f1a366e6c309d77c77c095a13d2d5e2f8e2d7f51ece4ae5ffc5fe8683a37387bfdb9acb8528f37342360abb64ec05ff438f7e4fad73c69a627de245a31168f69823883ed8ba590c454914690946b7b07918ded5b89dc663c70941f8704978b91a24b54d88038c30d20d14d85016a524f7176c7a7cff7233a2a4405da9c31c8569ac3adfe5147bdb92faee0f075b36e8ce794aaf596facd881588167fbcf5a7d059474c1e4abff645bba8a813f3083c5a425fcc88cd706b19494dedc04be2bc3ab1d71b2a062ddf62d0393d8cb421393cccc932a19d43e315a18a10d216aea4a1752cf3f3b0b2fb36bea655822e2b27c6156970d18e345930a4a589e1850fe84277e0913ad863dffb1950fbeb03a4a17452e7868f62f77ea2039bd2840e7611a928c26e87541481256f57bfbe3647f596abf6e8f6b5a0e7108acccc6e89db6bcc74a3ac251a6398eca56b2fcdc8c00a9a0b36bc6299e06fb4bb766cb9ecc96de7e367c56032c7feff586f9e557e2cbe156e110b0cc4b2418600dfa9fb33fc60b3f04b794ec1b8d154b48f07ba8c001cd31f75ca0d0fb516016552500d07eb7110de9956d7b4b1a3397f843b39d92df4caac263f5083e34e3161e4d6686c46c3239e7fbf61241a159d8da6dc6bd13df734883d4d0d78d670a1d17e28ef09dffbbfbd15063b73113cb5bed692d68cc30c38cb9389403fe6a1c32c35dbac75464b77597e27b854839db51dfde0885462020000530678b9eb99d1b9e08a6231ef00055560f7d3345f54ce355da68725bb38cab0caf84757ddb93db87577758bb06de7923c4ee3583453f284c8b377a1ec2ef613491e051c801a63da5cb42b9c12e26679fcf489f3b14bd5e8f551227b09d976975e0fbd68dcdf129110a5ca8ed8d163dafb60e1ec4831d5285a7fbae81d0e39580000dc010000ebb282d5c6aca9053a21814e9d65a1516ebeaacf6fc88503e794d75cfc5682e86aa04e9d6e58346e013c5c1203afc5c72861e2a7052afcdcb3ddcccd102dd0daeb595968edb6a6c513db8e2155fc302eeca7a34c9ba81289d6941c4c813db9bf7bd0981d188ab131e5ae9c4bb831e4243b20edb7829a6a7a9cf0eae1214b450109d990e2c824c2a60a47faf90c24992583bc5c3da3b58bd8830a4f0ad5c650aa08ae0e067d4251d251e56d70972ad901038082ee9340f103fd687ec7d91a9b8b8652b1a2b7befb4cbfdb6863f00142e0b2e67198ddc8ddbe96dc02762d935594394f173114215cb5abcf55b9815eb545683528c990bfae34c34358dbb19dfc1426f56cba12af325d7a2941c0d45d0ea4334155b790554d3829e3be618eb1bfc6f3a06f488bbeb910b33533c6741bff6c8a0ca43eb2417eec5ecc2f50f65c3b40d26174376202915337c7992cdd44471dee7a7b2038605415a7af593fd9066661e594b26f4298baf6d001906aa8fc1c460966fbc17b2c35e0973f613399936173802cf0453a4e7d8487b6113a77947eef190ea8d47ba531ce51abf5166448c24a54de09d671fd57cbd68154f5995aee6c2ccfd6738387cf3ad9f0ad5e8c7d46fb0a0000000000000000000000bd920a00000000000000000000000000',timestamp: 1733606453433} Take the `quote` field and paste it into the [TEE RA Explorer](https://ra-quote-explorer.vercel.app/) to verify the attestation. **Note**: The verification will be unverified since the quote is generated from the TEE simulator. ![](https://i.imgur.com/xYGMeP4.png) ![](https://i.imgur.com/BugdNUy.png) ### Build, Test, and Publish an Eliza Agent Docker Image[​](#build-test-and-publish-an-eliza-agent-docker-image "Direct link to Build, Test, and Publish an Eliza Agent Docker Image") Now that we have run the Eliza agent in the TEE simulator, we can build and publish an Eliza agent Docker image to prepare for deployment to a real TEE environment. First, you need to create a Docker account and publish your image to a container registry. Here we will use [Docker Hub](https://hub.docker.com/) as an example. Login to Docker Hub: docker login Build the Docker image: # For Linux/AMD64 machines rundocker build -t username/eliza-agent:latest .# For architecture other than AMD64, rundocker buildx build --platform=linux/amd64 -t username/eliza-agent:latest . For Linux/AMD64 machines, you can now test the agent locally by updating the `TEE_MODE` environment variable to `DOCKER` and setting the environment variables in the [docker-compose.yaml](https://github.com/elizaos/eliza/blob/main/docker-compose.yaml) file. Once you have done that, you can start the agent by running: > **Note**: Make sure the TEE simulator is running before starting the agent through docker compose. docker compose up Publish the Docker image to a container registry: docker push username/eliza-agent:latest Now we are ready to deploy the Eliza agent to a real TEE environment. ### Run an Eliza Agent in a Real TEE Environment[​](#run-an-eliza-agent-in-a-real-tee-environment "Direct link to Run an Eliza Agent in a Real TEE Environment") Before deploying the Eliza agent to a real TEE environment, you need to create a new TEE account on the [TEE Cloud](https://cloud.phala.network/login) . Reach out to Phala Network on [Discord](https://discord.gg/phalanetwork) if you need help. Next, you will need to take the docker-compose.yaml file in the root folder of the project and edit it based on your agent configuration. > **Note**: The API Keys and other secret environment variables should be set in your secret environment variables configuration in the TEE Cloud dashboard. # docker-compose.yamlservices: tee: command: [ "pnpm", "start", "--character=./characters/yourcharacter.character.json", ] image: username/eliza-agent:latest stdin_open: true tty: true volumes: - /var/run/tappd.sock:/var/run/tappd.sock - tee:/app/packages/client-twitter/src/tweetcache - tee:/app/db.sqlite environment: - REDPILL_API_KEY=$REDPILL_API_KEY - SMALL_REDPILL_MODEL=anthropic/claude-3-5-sonnet - MEDIUM_REDPILL_MODEL=anthropic/claude-3-5-sonnet - LARGE_REDPILL_MODEL=anthropic/claude-3-opus - ELEVENLABS_XI_API_KEY=$ELEVENLABS_XI_API_KEY - ELEVENLABS_MODEL_ID=eleven_multilingual_v2 - ELEVENLABS_VOICE_ID=21m00Tcm4TlvDq8ikWAM - ELEVENLABS_VOICE_STABILITY=0.5 - ELEVENLABS_VOICE_SIMILARITY_BOOST=0.9 - ELEVENLABS_VOICE_STYLE=0.66 - ELEVENLABS_VOICE_USE_SPEAKER_BOOST=false - ELEVENLABS_OPTIMIZE_STREAMING_LATENCY=4 - ELEVENLABS_OUTPUT_FORMAT=pcm_16000 - TWITTER_DRY_RUN=false - TWITTER_USERNAME=$TWITTER_USERNAME - TWITTER_PASSWORD=$TWITTER_PASSWORD - TWITTER_EMAIL=$TWITTER_EMAIL - X_SERVER_URL=$X_SERVER_URL - BIRDEYE_API_KEY=$BIRDEYE_API_KEY - SOL_ADDRESS=So11111111111111111111111111111111111111112 - SLIPPAGE=1 - SOLANA_RPC_URL=https://api.mainnet-beta.solana.com - HELIUS_API_KEY=$HELIUS_API_KEY - SERVER_PORT=3000 - WALLET_SECRET_SALT=$WALLET_SECRET_SALT - TEE_MODE=PRODUCTION ports: - "3000:80" restart: alwaysvolumes: tee: Now you can deploy the Eliza agent to a real TEE environment. Go to the [TEE Cloud](https://cloud.phala.network/login) and click on the `Create VM` button to configure your Eliza agent deployment. Click on the `Compose Manifest Mode` tab and paste the docker-compose.yaml file content into the `Compose Manifest` field. ![Compose Manifest](https://i.imgur.com/wl6pddX.png) Next, go to the `Resources` tab and configure your VM resources. > **Note**: The `CPU` and `Memory` resources should be greater than the minimum requirements for your agent configuration (Recommended: 2 CPU, 4GB Memory, 50GB Disk). ![Resources](https://i.imgur.com/HsmupO1.png) Finally, click on the `Submit` button to deploy your Eliza agent. This will take a few minutes to complete. Once the deployment is complete, you can click on the `View` button to view your Eliza agent. Here is an example of a deployed agent named `vitalik2077`: ![Deployed Agent](https://i.imgur.com/ie8gpg9.png) I can go to the dashboard and view the remote attestation info: ![Agent Dashboard](https://i.imgur.com/vUqHGjF.png) Click on the `Logs` tab to view the agent logs. ![Agent Logs](https://i.imgur.com/aU3i0Dv.png) Now we can verify the REAL TEE attestation quote by going to the [TEE RA Explorer](https://proof.t16z.com/) and pasting the attestation quote from the agent logs. ![TEE RA Explorer](https://i.imgur.com/TJ5299l.png) Congratulations! You have successfully run an Eliza agent in a real TEE environment. * [Overview](#overview) * [Background](#background) * [Core Components](#core-components) * [Derive Key Provider](#derive-key-provider) * [Remote Attestation Provider](#remote-attestation-provider) * [Tutorial](#tutorial) * [Prerequisites](#prerequisites) * [Environment Setup](#environment-setup) * [Run an Eliza Agent Locally with TEE Simulator](#run-an-eliza-agent-locally-with-tee-simulator) * [Build, Test, and Publish an Eliza Agent Docker Image](#build-test-and-publish-an-eliza-agent-docker-image) * [Run an Eliza Agent in a Real TEE Environment](#run-an-eliza-agent-in-a-real-tee-environment) --- # Page Not Found | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) Page Not Found ============== We could not find what you were looking for. Please contact the owner of the site that linked you to the original URL and let them know their link is broken. --- # πŸͺͺ Verified Inference | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page Overview[​](#overview "Direct link to Overview") ------------------------------------------------- With verified inference, you can turn your Eliza agent fully verifiable on-chain on Solana with an OpenAI-compatible TEE API. This proves that your agent’s thoughts and outputs are free from human control thus increasing the trust of the agent. Compared to [fully deploying the agent in a TEE](https://elizaos.github.io/eliza/docs/advanced/eliza-in-tee/) , this is a more light-weight solution which only verifies the inference calls and only needs a single line of code change. The API supports all OpenAI models out of the box, including your fine-tuned models. The following guide will walk you through how to use verified inference API with Eliza. Background[​](#background "Direct link to Background") ------------------------------------------------------- The API is built on top of [Sentience Stack](https://github.com/galadriel-ai/Sentience) , which cryptographically verifies the agent's LLM inferences inside TEEs, posts those proofs on-chain on Solana, and makes the verified inference logs available to read and display to users. Here’s how it works: ![](https://i.imgur.com/SNwSHam.png) 1. The agent sends a request containing a message with the desired LLM model to the TEE. 2. The TEE securely processes the request by calling the LLM API. 3. The TEE sends back the `{Message, Proof}` to the agent. 4. The TEE submits the attestation with `{Message, Proof}` to Solana. 5. The Proof of Sentience SDK is used to read the attestation from Solana and verify it with `{Message, Proof}`. The proof log can be added to the agent's website/app. To verify the code running inside the TEE, use instructions [from here](https://github.com/galadriel-ai/sentience/tree/main/verified-inference/verify) . Tutorial[​](#tutorial "Direct link to Tutorial") ------------------------------------------------- 1. **Create a free API key on [Galadriel dashboard](https://dashboard.galadriel.com/login) ** 2. **Configure the environment variables** GALADRIEL_API_KEY=gal-* # Get from https://dashboard.galadriel.com/# Use any model supported by OpenAISMALL_GALADRIEL_MODEL= # Default: gpt-4o-miniMEDIUM_GALADRIEL_MODEL= # Default: gpt-4oLARGE_GALADRIEL_MODEL= # Default: gpt-4o# If you wish to use a fine-tuned model you will need to provide your own OpenAI API keyGALADRIEL_FINE_TUNE_API_KEY= # starting with sk- 3. **Configure your character to use `galadriel`** In your character file set the `modelProvider` as `galadriel`. "modelProvider": "galadriel" 4. **Run your agent.** Reminder of how to run an agent is [here](https://elizaos.github.io/eliza/docs/quickstart/#create-your-first-agent) . pnpm start --character="characters/.json"pnpm start:client 5. **Get the history of all of your verified inference calls** const url = 'https://api.galadriel.com/v1/verified/chat/completions?limit=100&filter=mine';const headers = {'accept': 'application/json','Authorization': 'Bearer '// Replace with your Galadriel API key};const response = await fetch(url, { method: 'GET', headers });const data = await response.json();console.log(data); Use this to build a verified logs terminal to your agent front end, for example: ![](https://i.imgur.com/yejIlao.png) 6. **Check your inferences in the explorer.** You can also see your inferences with proofs in the [Galadriel explorer](https://explorer.galadriel.com/) . For specific inference responses use `https://explorer.galadriel.com/details/` The `hash` param is returned with every inference request. ![](https://i.imgur.com/QazDxbE.png) 7. **Check proofs posted on Solana.** You can also see your inferences with proofs on Solana. For specific inference responses: `https://explorer.solana.com/tx/<>tx_hash?cluster=devnet` The `tx_hash` param is returned with every inference request. * [Overview](#overview) * [Background](#background) * [Tutorial](#tutorial) --- # Page Not Found | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) Page Not Found ============== We could not find what you were looking for. Please contact the owner of the site that linked you to the original URL and let them know their link is broken. --- # Fact Evaluator: Memory Formation System | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) On this page The Fact Evaluator serves as the agent's "episodic memory formation" system - similar to how humans process conversations and form memories. Just as you might reflect after a conversation "Oh, I learned something new about Sarah today", the Fact Evaluator systematically processes conversations to build up the agent's understanding of the world and the people in it. How It Works[​](#how-it-works "Direct link to How It Works") ------------------------------------------------------------- ### 1\. Triggering (The "When to Reflect" System)[​](#1-triggering-the-when-to-reflect-system "Direct link to 1. Triggering (The "When to Reflect" System)") validate: async (runtime: IAgentRuntime, message: Memory): Promise => { const messageCount = await runtime.messageManager.countMemories(message.roomId); const reflectionCount = Math.ceil(runtime.getConversationLength() / 2); return messageCount % reflectionCount === 0;} Just like humans don't consciously analyze every single word in real-time, the Fact Evaluator runs periodically rather than after every message. It triggers a "reflection" phase every few messages to process what's been learned. ### 2\. Fact Extraction (The "What Did I Learn?" System)[​](#2-fact-extraction-the-what-did-i-learn-system "Direct link to 2. Fact Extraction (The "What Did I Learn?" System)") The evaluator uses a template-based approach to extract three types of information: * **Facts**: Unchanging truths about the world or people * "Bob lives in New York" * "Sarah has a degree in Computer Science" * **Status**: Temporary or changeable states * "Bob is currently working on a new project" * "Sarah is visiting Paris this week" * **Opinions**: Subjective views, feelings, or non-factual statements * "Bob thinks the project will be successful" * "Sarah loves French cuisine" ### 3\. Memory Deduplication (The "Is This New?" System)[​](#3-memory-deduplication-the-is-this-new-system "Direct link to 3. Memory Deduplication (The "Is This New?" System)") const filteredFacts = facts.filter((fact) => { return ( !fact.already_known && fact.type === "fact" && !fact.in_bio && fact.claim && fact.claim.trim() !== "" );}); Just as humans don't need to consciously re-learn things they already know, the Fact Evaluator: * Checks if information is already known * Verifies if it's in the agent's existing knowledge (bio) * Filters out duplicate or corrupted facts ### 4\. Memory Storage (The "Remember This" System)[​](#4-memory-storage-the-remember-this-system "Direct link to 4. Memory Storage (The "Remember This" System)") const factMemory = await factsManager.addEmbeddingToMemory({ userId: agentId!, agentId, content: { text: fact }, roomId, createdAt: Date.now(),}); Facts are stored with embeddings to enable: * Semantic search of related facts * Context-aware recall * Temporal tracking (when the fact was learned) Example Processing[​](#example-processing "Direct link to Example Processing") ------------------------------------------------------------------------------- Given this conversation: User: "I just moved to Seattle last month!"Agent: "How are you finding the weather there?"User: "It's rainy, but I love my new job at the tech startup" The Fact Evaluator might extract: [ { "claim": "User moved to Seattle last month", "type": "fact", "in_bio": false, "already_known": false }, { "claim": "User works at a tech startup", "type": "fact", "in_bio": false, "already_known": false }, { "claim": "User enjoys their new job", "type": "opinion", "in_bio": false, "already_known": false }] Key Design Considerations[​](#key-design-considerations "Direct link to Key Design Considerations") ---------------------------------------------------------------------------------------------------- 1. **Episodic vs Semantic Memory** * Facts build up the agent's semantic memory (general knowledge) * The raw conversation remains in episodic memory (specific experiences) 2. **Temporal Awareness** * Facts are timestamped to track when they were learned * Status facts can be updated as they change 3. **Confidence and Verification** * Multiple mentions of a fact increase confidence * Contradictory facts can be flagged for verification 4. **Privacy and Relevance** * Only stores relevant, conversation-appropriate facts * Respects explicit and implicit privacy boundaries Integration with Other Systems[​](#integration-with-other-systems "Direct link to Integration with Other Systems") ------------------------------------------------------------------------------------------------------------------- The Fact Evaluator works alongside other evaluators and systems: * **Goal Evaluator**: Facts may influence goal progress * **Trust Evaluator**: Fact consistency affects trust scoring * **Memory Manager**: Facts enhance context for future conversations * **Providers**: Facts inform response generation Common Patterns[​](#common-patterns "Direct link to Common Patterns") ---------------------------------------------------------------------- 1. **Progressive Learning** // First conversation"I live in Seattle" -> Stores as fact// Later conversation"I live in the Ballard neighborhood" -> Updates/enhances existing fact 2. **Fact Chaining** // Original facts"Works at tech startup""Startup is in Seattle"// Inference potential"Works in Seattle tech industry" 3. **Temporal Tracking** // Status trackingt0: "Looking for a job" (status)t1: "Got a new job" (fact)t2: "Been at job for 3 months" (status) Best Practices[​](#best-practices "Direct link to Best Practices") ------------------------------------------------------------------- 1. **Validate Facts** * Cross-reference with existing knowledge * Consider source reliability * Track fact confidence levels 2. **Manage Memory Growth** * Prioritize important facts * Consolidate related facts * Archive outdated status facts 3. **Handle Contradictions** * Flag conflicting facts * Maintain fact history * Update based on newest information 4. **Respect Privacy** * Filter sensitive information * Consider contextual appropriateness * Follow data retention policies * [How It Works](#how-it-works) * [1\. Triggering (The "When to Reflect" System)](#1-triggering-the-when-to-reflect-system) * [2\. Fact Extraction (The "What Did I Learn?" System)](#2-fact-extraction-the-what-did-i-learn-system) * [3\. Memory Deduplication (The "Is This New?" System)](#3-memory-deduplication-the-is-this-new-system) * [4\. Memory Storage (The "Remember This" System)](#4-memory-storage-the-remember-this-system) * [Example Processing](#example-processing) * [Key Design Considerations](#key-design-considerations) * [Integration with Other Systems](#integration-with-other-systems) * [Common Patterns](#common-patterns) * [Best Practices](#best-practices) --- # Page Not Found | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) Page Not Found ============== We could not find what you were looking for. Please contact the owner of the site that linked you to the original URL and let them know their link is broken. --- # Page Not Found | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) Page Not Found ============== We could not find what you were looking for. Please contact the owner of the site that linked you to the original URL and let them know their link is broken. --- # Page Not Found | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) Page Not Found ============== We could not find what you were looking for. Please contact the owner of the site that linked you to the original URL and let them know their link is broken. --- # Page Not Found | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) Page Not Found ============== We could not find what you were looking for. Please contact the owner of the site that linked you to the original URL and let them know their link is broken. --- # Page Not Found | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) Page Not Found ============== We could not find what you were looking for. Please contact the owner of the site that linked you to the original URL and let them know their link is broken. --- # Page Not Found | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) Page Not Found ============== We could not find what you were looking for. Please contact the owner of the site that linked you to the original URL and let them know their link is broken. --- # Page Not Found | eliza [Skip to main content](#__docusaurus_skipToContent_fallback) Page Not Found ============== We could not find what you were looking for. Please contact the owner of the site that linked you to the original URL and let them know their link is broken. ---