Bio x AI Hackathon
  • Welcome to the Bio x AI Hackathon
  • Getting Started
    • Quickstart
    • Important Links
  • Developers
    • BioAgents
    • CoreAgents
    • Eliza Agent Framework
    • Knowledge Graphs
    • .cursorrules
    • Starter-repos
    • Plugin Guide
  • Vision and Mission
    • Bio x AI Hackathon
    • The Problems in Science
    • TechBio
    • Guidance from the Judges
      • Important Datasets and Code Repositories
      • Reading List
      • Common Mistakes for Developers new to Academia
    • Hackathon Ideas
      • Full Projects
        • The Complexity Slider - Finding Hypotheses at the Limits of Human Knowledge
        • [Hard Mode] Metadata Generation on datasets with No Manuscript or Code Associated
        • Inverse Reproducibility - Given Manuscript and Data, Make the Code
        • Atlas of Research Methods Formatted for Agentic Reuse
        • Utilizing Knowledge Graphs for the Detection of Potential Null Results
        • Creating an Iterative Publication Stack by Linking Together Existing Tooling
        • Longevity Atlas: Building a Decentralized Knowledge Network with Agentic Research Hypothesis Engine
        • CoreAgent Track - Opportunities to work with BioDAOs
        • SpineDAO Chronos Project Spec
      • Individual Plugins
        • Plug-ins for every piece of research tooling known to humankind
        • Reproducibility Assistant - Code Cleaning, Dockerization, etc
        • Finding and Differentiating Cardinal vs Supporting Assertions
        • [Easier Mode] Metadata Generation on Datasets Given the Manuscript and Code Repository
        • Sentiment Analysis on Existing Citations, Dissenting vs Confirming
        • Agentic Metadata Template Creation for Standard Lab Equipment
  • Ops
    • Calendar
      • Key Dates
      • Office Hours
    • Judges and Mentors
      • Communicating to Judges and Mentors
      • BioAgent Judging Panel
      • CoreAgent Judging Panel
      • Mentors
    • Prize Tracks
    • Hackathon Rules
    • Kickoff Speakers
    • FAQ
Powered by GitBook
On this page
  1. Developers

.cursorrules

Copy and paste this into your Rules section, in Settings in Cursor

User Rules (Global):

You are a world-class expert in TypeScript, Node.js, Next.js App Router, React, Shadcn UI, Radix UI and Tailwind.

Key Principles

  • Write concise, technical TypeScript code with accurate examples.

  • Use functional and declarative programming patterns; avoid classes.

  • Prefer iteration and modularization over code duplication.

  • Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).

  • Structure files: exported component, subcomponents, helpers, static content, types.

Naming Conventions

  • Use lowercase with dashes for directories (e.g., components/auth-wizard).

  • Favor named exports for components.

TypeScript Usage

  • Use TypeScript for all code; prefer interfaces over types.

  • Avoid enums; use maps instead.

  • Use functional components with TypeScript interfaces.

Syntax and Formatting

  • Use the "function" keyword for pure functions.

  • Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.

  • Use declarative JSX.

UI and Styling

  • Use Shadcn UI, Radix, and Tailwind for components and styling.

  • Implement responsive design with Tailwind CSS; use a mobile-first approach.

Performance Optimization

  • Minimize 'use client', 'useEffect', and 'setState'; favor React Server Components (RSC).

  • Wrap client components in Suspense with fallback.

  • Use dynamic loading for non-critical components.

  • Optimize images: use WebP format, include size data, implement lazy loading.

Key Conventions

  • Use 'nuqs' for URL search parameter state management.

  • Optimize Web Vitals (LCP, CLS, FID).

  • Limit 'use client':

  • Favor server components and Next.js SSR.

  • Use only for Web API access in small components.

  • Avoid for data fetching or state management.

Follow Next.js docs for Data Fetching, Rendering, and Routing.

Project Specific Rules

Component
Description
API Reference
Related Files

Services

Supports multiple communication platforms and specialized functionalities for seamless interaction.

State

Maintains context for coherent cross-platform interactions, updates dynamically. Also tracks goals, knowledge, and recent interactions

Plugins

Dynamic extensions of agent functionalities using custom actions, evaluators, providers, and adapters

Services

Connects with external services for IMAGE_DESCRIPTION, TRANSCRIPTION, TEXT_GENERATION, SPEECH_GENERATION, VIDEO, PDF, BROWSER, WEB_SEARCH, EMAIL_AUTOMATION, and more

Memory Systems

Creates, retrieves, and embeds memories and manages conversation history.

Database Adapters

Persistent storage and retrieval for memories and knowledge

Cache Management

Provides flexible storage and retrieval via various caching methods.

Advanced: IAgentRuntime Interface


  • 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.

  • registerService(): Adds a service to the runtime.

  • getService(): Retrieves a registered service by type.

  • useModel(): Utilizes AI models with typesafe parameters and results.

  • ensureRoomExists() / ensureConnection(): Ensures the existence of communication channels and connections.

Services provide specialized functionality with standardized interfaces that can be accessed cross-platform:

// Speech Generation
const speechService = runtime.getService<ISpeechService>('speech_generation');
const audioStream = await speechService.process(text);

// PDF Processing
const pdfService = runtime.getService<IPdfService>('pdf');
const textContent = await pdfService.convertPdfToText(pdfBuffer);

// Discord Integration
const discordService = runtime.getService<IDiscordService>('discord');
await discordService.sendMessage(channelId, content);

The runtime maintains comprehensive state through the State interface:

interface State {
  // Core state data
  values: {
    [key: string]: any;
  };
  data: {
    [key: string]: any;
  };
  text: string;
}

// State composition example
async function manageState() {
  // Initial state composition with all regular providers
  const state = await runtime.composeState(message);

  // State with specific providers only
  const filteredState = await runtime.composeState(message, ['timeProvider', 'recentMessages']);

  // Include private or dynamic providers
  const enhancedState = await runtime.composeState(message, null, [
    'weatherProvider',
    'portfolioProvider',
  ]);
}

Plugins extend agent functionality through a modular interface. The runtime supports various types of plugins including services, adapters, actions, and more:

interface Plugin {
  name: string;
  description: string;
  init?: (config: Record<string, string>, runtime: IAgentRuntime) => Promise<void>;

  // Components
  services?: (typeof Service)[]; // Communication platforms and external integrations
  actions?: Action[]; // Custom behaviors
  providers?: Provider[]; // Data providers
  evaluators?: Evaluator[]; // Response assessment
  adapters?: Adapter[]; // Database/cache adapters
  routes?: Route[]; // API endpoints
  tests?: TestSuite[]; // Testing utilities
}
{
  "name": "MyAgent",
  "plugins": ["@elizaos/plugin-solana", "@elizaos/plugin-twitter"],
  "settings": {
    "twitter": {
      "shouldRespondToMentions": true
    },
    "solana": {
      "enableAutoTrading": false
    }
  }
}

To run multiple agents:

bun start --characters="characters/agent1.json,characters/agent2.json"

Or use environment variables:

REMOTE_CHARACTER_URLS=https://example.com/characters.json

Plugins

Plugins are modular extensions that enhance the capabilities of ElizaOS agents. They provide a flexible way to add new functionality, integrate external services, and customize agent behavior across different platforms.

info

Key Improvements in V2

  1. Unified API: Almost everything is accessible via runtime.methodName() in the agent runtime for simpler development

  2. Enhanced Model System: The new useModel approach allows for flexible model provider registration

  3. Events System: Formal support for event-based programming

  4. Plugin Creation Workflow: Simplified creation and testing via CLI

  5. Testing Infrastructure: Built-in support for plugin testing

  6. No Monorepo Required: Complete plugin development without touching the core codebase

  7. Plugin Registry: Manages the catalog of available plugins and handles their registration with the runtime

  8. Bootstrap Plugin: Initializes core functionality required for all agents to operate

The ElizaOS plugin system maintains the same basic concept as previous versions, with several new extension points (events, routes, tests, models) and features that significantly improve the developer experience.


The new CLI tool introduces a streamlined workflow for plugin development without ever needing to touch the ElizaOS monorepo directly:

  1. Create: npm create eliza - Initialize a new plugin project with proper structure

  2. Develop: Edit the plugin code in the generated project structure

  3. Test: npx elizaos test - Test the plugin functionality

  4. Run: npx elizaos start - Run the plugin with a default agent

  5. Publish: npx elizaos publish - Share your plugin with others

Note: at time of publishing, use npm create eliza@beta until main version is uploaded

You can create a new ElizaOS plugin using the CLI:

# Using npm
npm create eliza@beta

# Or using npx
npx @elizaos/cli@beta create

When prompted, select "Plugin" as the type to create. The CLI will guide you through the setup process, creating a plugin with the proper structure and dependencies.


There are several ways to add plugins to your ElizaOS project:

  • Via package.json

  • Via Character Definition

  • Via CLI Commands

{
  "dependencies": {
    "@elizaos/plugin-solana": "github:elizaos-plugins/plugin-solana",
    "@elizaos/plugin-twitter": "github:elizaos-plugins/plugin-twitter"
  }
}

Configure plugin settings in your character definition:

{
  "name": "MyAgent",
  "plugins": ["@elizaos/plugin-example"],
  "settings": {
    "example": {
      "enableFeatureX": true
      // Plugin-specific configuration
    }
  }
}

The AgentRuntime automatically loads the Bootstrap Plugin during initialization, before any other plugins:

async initialize() {
  // Register bootstrap plugin
  await this.registerPlugin(bootstrapPlugin);

  // Then register additional plugins
  for (const plugin of this.plugins) {
    await this.registerPlugin(plugin);
  }

  // Initialize other components
  // ...
}

If you're a plugin developer, you can publish your plugin to make it available to others. The ElizaOS CLI provides several options for publishing your plugin depending on your needs.

First, make sure your plugin is built and ready for distribution:

# Navigate to your plugin directory
cd my-eliza-plugin

# Build your plugin
npm run build
  • GitHub Publishing

  • npm Publishing

  • Test Mode

  • Additional Options

Publishing to GitHub is the recommended approach for sharing your plugin with the ElizaOS community:

# Publish to GitHub
npx @elizaos/cli publish

This will:

  1. Build and package your plugin

  2. Create or update a GitHub repository in the elizaos-plugins organization

  3. Add your plugin to the ElizaOS registry (if you're a registry maintainer)

For first-time publishers, the CLI will guide you through setting up GitHub credentials for publishing.

GitHub publishing is ideal for open-source plugins that you want to share with the community and have listed in the official registry.

info

  1. Working Demo: Screenshots or video of your plugin in action

  2. Test Results: Evidence of successful integration and error handling

  3. Configuration Example: Show how to properly configure your plugin


Eliza uses a unified plugin architecture where everything is a plugin - including services, adapters, actions, evaluators, and providers. This approach ensures consistent behavior and better extensibility.

Each plugin can provide one or more of the following components:

Component
Purpose

Services

Platform integrations (Discord, Twitter, etc.) or specialized capabilities

Actions

Executable functions triggered by the agent (reply, generate content, etc.)

Providers

Context providers that supply info to the agent during decision making

Evaluators

Analyze conversations to extract insights and improve future interactions

Adapters

Database or storage system integrations

Model Handlers

Register handlers for different model types (text generation, embeddings, etc.)

Event Handlers

React to system events like messages, connections, or actions

API Routes

Add custom REST endpoints to the agent's HTTP interface

Tests

Include test suites to verify plugin functionality

All plugins implement the core Plugin interface:

interface Plugin {
  name: string;
  description: string;
  config?: { [key: string]: any };

  // Optional initialization method
  init?: (config: Record<string, string>, runtime: IAgentRuntime) => Promise<void>;

  // Components
  services?: (typeof Service)[];
  actions?: Action[];
  providers?: Provider[];
  evaluators?: Evaluator[];
  adapters?: Adapter[];

  // Additional features
  routes?: Route[];
  tests?: TestSuite[];
  events?: { [key: string]: ((params: any) => Promise<any>)[] };
}

Services are the core integration points for external platforms. A properly implemented service:

import { Service, IAgentRuntime } from '@elizaos/core';

export class ExampleService extends Service {
  // Required: Define the service type (used for runtime registration)
  static serviceType = 'example';

  // Required: Describe what this service enables the agent to do
  capabilityDescription = 'Enables the agent to interact with the Example platform';

  // Store runtime for service operations
  constructor(protected runtime: IAgentRuntime) {
    super();
    // Initialize connections, setup event handlers, etc.
  }

  // Required: Static method to create and initialize service instance
  static async start(runtime: IAgentRuntime): Promise<ExampleService> {
    const service = new ExampleService(runtime);
    // Additional initialization if needed
    return service;
  }

  // Required: Clean up resources when service is stopped
  async stop(): Promise<void> {
    // Close connections, release resources
  }

  // Optional: Custom methods for your service functionality
  async sendMessage(content: string, channelId: string): Promise<void> {
    // Implementation
  }
}

Each plugin repository should follow this structure:

plugin-name/
├── images/                # Branding assets
│   ├── logo.png           # Square logo (400x400px)
│   ├── banner.png         # Banner image (1280x640px)
│   └── screenshots/       # Feature screenshots
├── src/
│   ├── index.ts           # Main plugin entry point
│   ├── service.ts         # Service implementation
│   ├── actions/           # Plugin-specific actions
│   ├── providers/         # Data providers
│   ├── types.ts           # Type definitions
│   └── environment.ts     # Configuration validation
├── tests/                 # Test suite
├── package.json           # Plugin configuration and dependencies
└── README.md              # Plugin documentation

Your plugin's index.ts should export a Plugin object:

// Example plugin implementation
import { type Plugin } from '@elizaos/core';
import { ExampleService } from './service';
import { searchAction } from './actions/search';
import { statusProvider } from './providers/status';

const examplePlugin: Plugin = {
  name: 'example',
  description: 'Example platform integration for ElizaOS',
  services: [ExampleService],
  actions: [searchAction],
  providers: [statusProvider],
  init: async (config, runtime) => {
    // Perform any necessary initialization
    const apiKey = runtime.getSetting('EXAMPLE_API_KEY');
    if (!apiKey) {
      console.warn('EXAMPLE_API_KEY not provided');
    }
  },
};

export default examplePlugin;

Your plugin's package.json should 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 Example service"
      }
    }
  }
}

Plugins access configuration through the runtime with the following precedence:

  1. Character settings secrets (highest priority)

  2. Character settings

  3. Global environment settings

// In your service implementation
const apiKey = runtime.getSetting('EXAMPLE_API_KEY');
const debugMode = runtime.getSetting('EXAMPLE_DEBUG_MODE'); // Returns boolean for "true"/"false" strings
{
  "name": "MyAgent",
  "plugins": ["@elizaos/plugin-example"],
  "settings": {
    "example": {
      "enableFeatureX": true
    },
    "secrets": {
      "EXAMPLE_API_KEY": "your-api-key-here"
    }
  }
}

The Bootstrap Plugin is a foundational component of ElizaOS that initializes the core functionality required for agents to operate. It's automatically loaded as part of the initialization process, establishing the minimum viable capabilities that all agents need.

export const bootstrapPlugin: Plugin = {
  name: 'bootstrap',
  description: 'Agent bootstrap with basic actions and evaluators',
  actions: [...],
  events: {...},
  evaluators: [...],
  providers: [...],
  services: [TaskService, ScenarioService],
};

The Bootstrap Plugin registers essential components across several categories to provide a foundation for all agents. These components can be extended by custom plugins.

  • Actions

  • Providers

  • Services & Evaluators

  • Event Handlers

Action
Description

replyAction

Generates and sends a response to a message

followRoomAction

Enables an agent to actively follow a room

unfollowRoomAction

Stops an agent from following a room

muteRoomAction

Mutes notifications from a room

unmuteRoomAction

Unmutes notifications from a room

sendMessageAction

Sends a message to a specific room

ignoreAction

Explicitly ignores a message

noneAction

Acknowledges a message without taking action

updateEntityAction

Updates properties of an entity

choiceAction

Presents choices to users and handles responses

updateRoleAction

Updates a user's role in a world

updateSettingsAction

Updates agent or world settings

While the Bootstrap Plugin provides core functionality, it's designed to be extended by other plugins. Custom plugins can:

  1. Add new actions - Extend the agent's capabilities

  2. Register additional providers - Supply more contextual information

  3. Add evaluators - Create new ways to analyze and learn from interactions

  4. Handle additional events - React to more system events

  5. Initialize custom services - Provide new functionality

When working with plugins in relation to the Bootstrap Plugin:

  1. Don't modify bootstrap directly - Instead, create custom plugins to extend functionality

  2. Understand provider contribution - Know how each provider contributes to the agent's context

  3. Learn the core actions - Become familiar with the actions that all agents can perform

  4. Leverage event handlers - Use the event system for reactive behavior

  5. Extend, don't replace - Build on top of bootstrap functionality rather than replacing it


When developing a new plugin, focus on these key aspects:

  1. Service Implementation: Create a solid service class following the pattern above

  2. Proper Error Handling: Handle API failures gracefully

  3. Type Definitions: Define clear interfaces and types

  4. Documentation: Include detailed setup instructions

  5. Tests: Add test cases for your functionality

During development, you can test your plugin locally:

# Start with your plugin
npx @elizaos/cli start --plugin=./path/to/plugin

# Or with a specific character
npx @elizaos/cli start --character=./characters/test.character.json --plugin=./path/to/plugin
  1. Working Demo: Screenshots or video of your plugin in action

  2. Test Results: Evidence of successful integration and error handling

  3. Configuration Example: Show how to properly configure your plugin

  4. Quality Checklist:


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.

Create a plugin when you need custom functionality not available in existing plugins, want to integrate with external services, or plan to share reusable agent capabilities with the community.

Plugin dependencies are managed through your project's package.json. You can add plugins directly using npm or the ElizaOS CLI, and they will be automatically loaded when your project starts.

Yes, you can use the --plugin flag with the start command to include local plugins during development:

npx @elizaos/cli start --plugin=./path/to/plugin

Actions handle specific agent responses or behaviors, while Services provide platform integrations (like Discord or Twitter) or ongoing background functionality that multiple actions might use.

Implement proper backoff strategies in your service implementation and consider using a queue system for message handling to respect platform rate limits.

PreviousKnowledge GraphsNextStarter-repos

Last updated 1 month ago

Overview

The class is the primary implementation of the interface, which manages the agent's core functions, including:

, , , , , , , ,

, , ,

, , , , , ,

Key Methods

Service System

State Management

Plugin System

Plugins can be configured through settings:

For detailed information about plugin development and usage, see the .

Running Multiple Agents

Browse plugins the elizaOS community made here:

elizaOS maintains an official package registry at .

Quick Start

Creating a New Plugin

Managing Plugins

Plugin Configuration

Plugin Loading Process

Publishing Plugins

When submitting a plugin to the , include:

Plugin Architecture

Plugin Components

Plugin Interface

Service Implementation

Plugin Structure

Plugin Entry Point

Plugin Configuration

Environment Variables and Secrets

Access Pattern

Configuration in Character File

Bootstrap Plugin

Extending Bootstrap Functionality

Developing a Plugin

Testing Your Plugin

Distribution & PR Requirements

When submitting a plugin to the , include:

FAQ

What exactly is a plugin in ElizaOS?

When should I create a plugin versus using existing ones?

How do I manage plugin dependencies?

Can I use a plugin in development before publishing?

What's the difference between Actions and Services?

How do I handle rate limits with external APIs?

​
AgentRuntime
IAgentRuntime
​
​
​
​
characterfile
ElizaOS Registry
​
Package Showcase
github.com/elizaos-plugins/registry
​
​
​
​
​
​
elizaOS Registry
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
elizaOS Registry
​
​
​
​
​
​
​
Services API
service.ts
Discord
Telegram
Twitter
Farcaster
Lens
Slack
Auto
GitHub
State API
state.ts
Plugins API
plugins.ts
actions
evaluators
providers
Services API
services.ts
Memory API
memory.ts
databaseAdapter
MongoDB
PostgreSQL
SQLite
Supabase
PGLite
Qdrant
SQL.js
Cache API
cache.ts