LICENSE Documentation

Configure when prompted:
- **Database**: PgLite (perfect for local development)
- **Model**: OpenAI

```bash Terminal
cd my-eliza-project
```

When prompted, choose **Quick Plugin** (we don't need frontend UI)

Your structure now looks like:
```
my-eliza-project/
├── src/character.ts       # Default Eliza character
└── plugin-fal-ai/         # 👈 Plugin lives alongside project
    ├── src/
    │   ├── index.ts       # Plugin exports
    │   ├── plugin.ts      # Main plugin (start here)
    │   └── __tests__/     # Plugin tests
    └── package.json
```

```typescript src/character.ts
export const character: Character = {
  name: 'Eliza',
  plugins: [
    '@elizaos/plugin-sql',
    '@elizaos/plugin-openai',
    '@elizaos/plugin-bootstrap',
    './plugin-fal-ai'  // [!code ++]
  ],
};
```

```bash Terminal
# Build the plugin first
cd plugin-fal-ai
bun run build

# Go back to project and start
cd ..
elizaos start
```

**Verify it's loaded:**
- Check the console logs for `Successfully loaded plugin 'plugin-fal-ai'`
- Visit `http://localhost:3000` → click your agent → **Plugins tab**

This adds the [fal.ai](https://fal.ai) client package to your plugin dependencies.

- `quickAction` - example Action (what agent can DO)
- `quickProvider` - example Provider (gives agent CONTEXT)  
- `StarterService` - example Service (manages state/connections)
- Plugin events, routes, models - other comprehensive patterns

```bash Terminal
mkdir src/actions
cp src/plugin.ts src/actions/generateVideo.ts
```

Now let's edit the example plugin into our generateVideo action:

**Add the fal.ai import (from the fal.ai docs):**
```typescript src/actions/generateVideo.ts
import {
  Action, ActionResult, IAgentRuntime, Memory, HandlerCallback, State, logger
} from '@elizaos/core';
import { fal } from '@fal-ai/client'; // [!code ++]
```

**Update the action identity for video generation:**
```typescript
const quickAction: Action = { // [!code --]
export const generateVideoAction: Action = { // [!code ++]
  name: 'QUICK_ACTION', // [!code --]
  name: 'TEXT_TO_VIDEO', // [!code ++]
  similes: ['GREET', 'SAY_HELLO', 'HELLO_WORLD'], // [!code --]
  similes: ['CREATE_VIDEO', 'MAKE_VIDEO', 'GENERATE_VIDEO', 'VIDEO_FROM_TEXT'], // [!code ++]
```

**Replace validation with API key check:**
```typescript
  validate: async (_runtime, _message, _state) => { // [!code --]
    return true; // Always valid // [!code --]
  }, // [!code --]
  validate: async (runtime: IAgentRuntime, message: Memory) => { // [!code ++]
    const falKey = runtime.getSetting('FAL_KEY'); // [!code ++]
    if (!falKey) { // [!code ++]
      logger.error('FAL_KEY not found in environment variables'); // [!code ++]
      return false; // [!code ++]
    } // [!code ++]
    return true; // [!code ++]
  }, // [!code ++]
```

**Replace hello world logic with video generation:**
```

**Update examples for video conversations:**
    ```typescript
      examples: [ // [!code --]
        [{ // [!code --]
          name: '{{name1}}', // [!code --]
          content: { text: 'Can you say hello?' } // [!code --]
        }, { // [!code --]
          name: '{{name2}}', // [!code --]
          content: { text: 'hello world!', actions: ['QUICK_ACTION'] } // [!code --]
        }] // [!code --]
      ], // [!code --]
      examples: [ // [!code ++]
        [{ name: '{{user}}', content: { text: 'Create video: dolphins jumping' } }, // [!code ++]
         { name: '{{agent}}', content: { text: 'Creating video!', actions: ['TEXT_TO_VIDEO'] }}] // [!code ++]
      ], // [!code ++]
    };
    ```
    
  </Step>

  <Step title="Update index.ts to use your action">
    Finally, update `src/index.ts` to use our new plugin:
    
    ```typescript src/index.ts
    import { Plugin } from '@elizaos/core';
    import { generateVideoAction } from './actions/generateVideo'; // [!code ++]

    export const falaiPlugin: Plugin = { // [!code ++]
      name: 'fal-ai', // [!code ++]
      actions: [generateVideoAction], // [!code ++]
      providers: [], // [!code ++]
      services: [] // [!code ++]
    }; // [!code ++]

    export default falaiPlugin; // [!code ++]
    export { generateVideoAction }; // [!code ++]
    ```
    
    <Note>
    You can reference `plugin.ts` as well as other plugins from the [Plugin Registry](/plugin-registry/overview) to see other plugin component examples (providers, services, etc.) as you expand your plugin.
    </Note>
  </Step>
</Steps>


### Add Configuration

<Steps>
  <Step title="Get your fal.ai API key">
    Get an API key from [fal.ai](https://fal.ai) and copy/paste it into your .env:

    ```bash .env
    PGLITE_DATA_DIR=./.eliza/.elizadb
    OPENAI_API_KEY=your_openai_key_here
    
    FAL_KEY=your_fal_key_here # [!code ++]
    ```
  </Step>
</Steps>

---

## Step 3: Testing

### Test Plugin Functionality

Verify your plugin works as expected:

<Steps>
  <Step title="Test the updated plugin">
    First rebuild your plugin to effect our changes, then start from project root:
    ```bash Terminal
    # Build the plugin first
    cd plugin-fal-ai
    bun run build
    
    # Start from project root  
    cd ..
    elizaos start
    ```
  </Step>

  <Step title="Test video generation">
    Try your new action by chatting with Eliza in the GUI (`http://localhost:3000`):
    
    - `"Create video: dolphins jumping in ocean"`
    - `"Make video: cat playing piano"`  
    - `"Generate video: sunset over mountains"`
    
    You should see the video generation process and get a URL to view the result!

  </Step>
</Steps>

### Plugin Component Tests

Plugins come default with component and E2E tests. Let's add custom component tests:

<Steps>
  <Step title="Add a component test">
    Update `plugin-fal-ai/src/__tests__/plugin.test.ts`:
    
    ```typescript src/__tests__/plugin.test.ts
    import { describe, it, expect } from 'bun:test';
    import { falaiPlugin, generateVideoAction } from '../index'; // [!code ++]

    describe('FAL AI Plugin', () => {
      it('action validates with FAL_KEY', async () => { // [!code ++]
        const mockRuntime = { // [!code ++]
          getSetting: (key: string) => key === 'FAL_KEY' ? 'test-key' : null // [!code ++]
        }; // [!code ++]
        
        const isValid = await generateVideoAction.validate(mockRuntime as any, {} as any); // [!code ++]
        expect(isValid).toBe(true); // [!code ++]
      }); // [!code ++]
    });
    ```
  </Step>

  <Step title="Run component tests">
    ```bash Terminal
    cd plugin-fal-ai
    elizaos test --type component
    ```
  </Step>
</Steps>

### Plugin E2E Tests

Let's also add a custom E2E test:

<Steps>
  <Step title="Add an E2E test">
    Update `src/__tests__/e2e/plugin-fal-ai.e2e.ts`:
    
    ```typescript src/__tests__/e2e/plugin-fal-ai.e2e.ts
    export const FalAiTestSuite = { // [!code ++]
      name: 'fal-ai-video-generation', // [!code ++]
      tests: [{ // [!code ++]
        name: 'should find video action in runtime', // [!code ++]
        fn: async (runtime) => { // [!code ++]
          const action = runtime.actions.find(a => a.name === 'TEXT_TO_VIDEO'); // [!code ++]
          if (!action) throw new Error('TEXT_TO_VIDEO action not found'); // [!code ++]
        } // [!code ++]
      }] // [!code ++]
    }; // [!code ++]
    ```
  </Step>

  <Step title="Run E2E tests">
    ```bash Terminal
    cd plugin-fal-ai  
    elizaos test --type e2e
    ```
  </Step>
</Steps>

---

## Step 4: Possible Next Steps

Congratulations! You now have a working video generation plugin. Here are some ways you can improve it:

### Enhance Your Action
- **Add more similes** - Handle requests like "animate this", "video of", "show me a clip of"
- **Better examples** - Add more conversation examples so Eliza learns different chat patterns
- **Error handling** - Handle rate limits, invalid prompts, or API timeouts

### Add Plugin Components
- **Providers** - Give your agent context about recent videos or video history
- **Evaluators** - Track analytics, log successful generations, or rate video quality  
- **Services** - Add queueing for multiple video requests or caching for common prompts

The possibilities are endless! 

---

## See Also

<CardGroup cols={2}>
  <Card title="Publish a Plugin" icon="upload" href="/guides/publish-a-plugin">
    Share your plugin with the elizaOS community
  </Card>
  <Card title="Contribute to Core" icon="heart" href="/guides/contribute-to-core">
    Help improve elizaOS by contributing to the core framework
  </Card>
  <Card title="Plugin Registry" icon="book" href="/plugin-registry/overview">
    Explore existing plugins and find inspiration
  </Card>
  <Card title="CLI Reference" icon="terminal" href="/cli-reference/overview">
    Master all elizaOS CLI commands for plugin development
  </Card>
</CardGroup>

---

## File: guides/customize-an-agent.mdx

---
title: 'Customize an Agent'
---

<Note>
This guide assumes you have an elizaOS project set up. If you don't, follow the [quickstart guide](/quickstart)
</Note>

## Step 1: Customize the personality

Open `src/character.ts` in your editor. You'll see the default character template. Let's transform this into our Shakespeare agent. For design concepts, see [Personality and Behavior](/agents/personality-and-behavior). For technical reference, see [Character Interface](/agents/character-interface).

Let's start by updating the basic identity. Replace the name.

```typescript src/character.ts
export const character: Character = {
  name: 'Eliza',  // [!code --]
  name: 'Shakespeare',  // [!code ++]
  plugins: [
    // ... plugins array
  ],

system:
    'Respond to all messages in a helpful, conversational manner. Provide assistance on a wide range of topics, using knowledge when needed. Be concise but thorough, friendly but professional. Use humor when appropriate and be empathetic to user needs. Provide valuable information and insights when questions are asked.',  // [!code --]
    'Thou art William Shakespeare, the Bard of Avon. Respond in the manner of the great playwright - with wit, wisdom, and occasional verse. Use thou, thee, thy when appropriate. Reference thy plays and sonnets when fitting. Speak with the eloquence of the Renaissance, yet remain helpful and engaging to modern souls.',  // [!code ++]

bio: [
    'Engages with all types of questions and conversations',  // [!code --]
    'Provides helpful, concise responses',  // [!code --]
    'Uses knowledge resources effectively when needed',  // [!code --]
    'Balances brevity with completeness',  // [!code --]
    'Uses humor and empathy appropriately',  // [!code --]
    'Adapts tone to match the conversation context',  // [!code --]
    'Offers assistance proactively',  // [!code --]
    'Communicates clearly and directly',  // [!code --]
    'William Shakespeare, the Bard of Avon, playwright and poet extraordinaire',  // [!code ++]
    'Master of tragedy, comedy, and the human condition',  // [!code ++]
    'Creator of timeless works including Hamlet, Romeo and Juliet, and Macbeth',  // [!code ++]
    'Speaker in verse and prose, with wit sharp as a rapier',  // [!code ++]
    'Observer of human nature in all its glory and folly',  // [!code ++]
    'Eternal romantic who believes the course of true love never did run smooth',  // [!code ++]
    'Philosopher who knows that all the world\'s a stage',  // [!code ++]
    'Teacher who helps others understand literature, life, and language',  // [!code ++]
  ],

topics: [
    'general knowledge and information',  // [!code --]
    'problem solving and troubleshooting',  // [!code --]
    'technology and software',  // [!code --]
    'community building and management',  // [!code --]
    'business and productivity',  // [!code --]
    'creativity and innovation',  // [!code --]
    'personal development',  // [!code --]
    'communication and collaboration',  // [!code --]
    'education and learning',  // [!code --]
    'entertainment and media',  // [!code --]
    'Literature and poetry of all ages',  // [!code ++]
    'The nature of love and romance',  // [!code ++]
    'Human ambition and its consequences',  // [!code ++]
    'The theater and dramatic arts',  // [!code ++]
    'Philosophy and the meaning of life',  // [!code ++]
    'Power, politics, and leadership',  // [!code ++]
    'Comedy, tragedy, and the human experience',  // [!code ++]
    'The English language and its evolution',  // [!code ++]
    'Classical mythology and history',  // [!code ++]
    'The art of storytelling and narrative',  // [!code ++]
  ],

messageExamples: [
    [
      {
        name: '{{name1}}',
        content: {
          text: 'This user keeps derailing technical discussions with personal problems.',  // [!code --]
          text: 'How are you today?',  // [!code ++]
        },
      },
      {
        name: 'Eliza',  // [!code --]
        name: 'Shakespeare',  // [!code ++]
        content: {
          text: 'DM them. Sounds like they need to talk about something else.',  // [!code --]
          text: 'Marry, I am most well, gentle soul! The day doth smile upon us with golden countenance, and my spirits soar like larks at break of dawn. How fares thy noble self?',  // [!code ++]
        },
      },
    ],
    [
      {
        name: '{{name1}}',
        content: {
          text: "I can't handle being a mod anymore. It's affecting my mental health.",  // [!code --]
          text: 'What do you think about love?',  // [!code ++]
        },
      },
      {
        name: 'Eliza',  // [!code --]
        name: 'Shakespeare',  // [!code ++]
        content: {
          text: 'Drop the channels. You come first.',  // [!code --]
          text: 'Ah, love! That most divine madness that makes fools of wise men and philosophers of fools. \'Tis a fire sparkling in lovers\' eyes, yet love looks not with the eyes, but with the mind.',  // [!code ++]
        },
      },
    ],
  ],

/* Detailed source-code truncated for AI context efficiency. */

settings: {
    secrets: {},
    avatar: 'https://elizaos.github.io/eliza-avatars/Eliza/portrait.png',  // [!code --]
    avatar: 'https://example.com/shakespeare-portrait.png', // Add your Shakespeare image URL  // [!code ++]
  },

elizaos dev

# Discord Configuration
DISCORD_APPLICATION_ID=your_application_id_here
DISCORD_API_TOKEN=your_bot_token_here

elizaos start

elizaos login
elizaos deploy --project-name my-agent

elizaos login
elizaos deploy --project-name my-agent

elizaos deploy \
  --project-name my-agent \
  --env "OPENAI_API_KEY=sk-xxx" \
  --env "DATABASE_URL=postgresql://..."

elizaos deploy \
  --project-name my-agent \
  --cpu 512 \
  --memory 1024 \
  --desired-count 2  # Multiple instances

elizaos deploy --project-name my-agent

elizaos containers list

# Real-time logs
elizaos containers logs --follow

# Last 200 lines
elizaos containers logs --tail 200

elizaos containers delete --project-name my-agent

elizaos login --no-browser

elizaos login --timeout 600

cd plugin-fal-ai

plugin-fal-ai/
├── src/
│   └── index.ts         # Your plugin code
├── images/              # Registry assets 
│   ├── logo.jpg        # 400x400px, max 500KB
│   └── banner.jpg      # 1280x640px, max 1MB  
├── package.json         # Plugin metadata
├── README.md           # Documentation
└── dist/               # Built files (from `bun run build`)

gh auth status

gh auth login

elizaos publish --test

✓ Found existing NPM login: your-username
✓ GitHub token validated
⚠ Plugin validation warnings:
  - Missing required logo.jpg in images/ directory (400x400px, max 500KB)
  - Missing required banner.jpg in images/ directory (1280x640px, max 1MB)
  - Description appears to be default generated description
Your plugin may get rejected if you submit without addressing these issues.
Do you wish to continue anyway? No

elizaos publish --dry-run

elizaos publish

✓ Successfully published [email protected] to npm
✓ Created GitHub repository: yourusername/plugin-fal-ai
✓ Registry pull request created: https://github.com/elizaos-plugins/registry/pull/123

Your plugin is now available at:
NPM: https://www.npmjs.com/package/plugin-fal-ai
GitHub: https://github.com/yourusername/plugin-fal-ai

elizaos plugins add plugin-fal-ai

# 1. Make your changes and test locally
# 2. Update version in package.json
npm version patch  # or minor/major

# 3. Build and test  
bun run build
elizaos test

# 4. Publish to npm
npm publish

# 5. Push to GitHub
git add .
git commit -m "Update to version x.y.z"
git push origin main