Overview
The Character type defines the personality, knowledge, and behavior of an elizaOS agent. Characters can be created programmatically or loaded from JSON files.
Character Type
interface Character {
id?: string;
name?: string;
username?: string;
system?: string;
templates?: Record<string, string>;
bio?: string[];
messageExamples?: MessageExampleGroup[];
postExamples?: string[];
topics?: string[];
adjectives?: string[];
knowledge?: KnowledgeSourceItem[];
plugins?: string[];
settings?: CharacterSettings;
secrets?: Record<string, string | number | boolean>;
style?: {
all?: string[];
chat?: string[];
post?: string[];
};
advancedPlanning?: boolean;
advancedMemory?: boolean;
}
Unique identifier for the character (optional - generated if not provided)
Character name displayed in conversations
Username for platforms that require one
System prompt override for the character
Custom templates for message generation (e.g., “messageHandlerTemplate”)
Array of biographical statements describing the character
Example conversations for few-shot learning
Example posts/tweets in the character’s style
Topics the character is knowledgeable about
Adjectives describing the character’s personality
Knowledge sources (files, directories) to embed
Plugin package names to load (e.g., “@elizaos/plugin-sql”)
Configuration settings and API keys
secrets
Record<string, string | number | boolean>
Secret values (API keys, tokens) separate from settings
Style guidelines for different communication contexts
Enable advanced action planning capabilities
Enable advanced memory management features
CharacterSettings
interface CharacterSettings {
ENABLE_AUTONOMY?: boolean | string;
DISABLE_BASIC_CAPABILITIES?: boolean | string;
ADVANCED_CAPABILITIES?: boolean | string;
secrets?: Record<string, string | boolean | number>;
[key: string]: JsonValue | undefined;
}
Enable autonomous operation mode
DISABLE_BASIC_CAPABILITIES
Disable bootstrap capabilities (reply, ignore, none)
Enable advanced features (facts, roles, settings)
MessageExample
interface MessageExample {
name: string;
content: Content;
}
interface MessageExampleGroup {
examples: MessageExample[];
}
Speaker name (usually “user” or the character name)
Message content with text and optional metadata
KnowledgeSourceItem
interface KnowledgeSourceItem {
item: {
case: "path" | "directory";
value: string | {
directory: string;
shared?: boolean;
};
};
}
Functions
createCharacter
Create a character from input data.
import { createCharacter } from "@elizaos/core";
const character = createCharacter({
name: "MyAgent",
bio: ["A helpful assistant"],
// ... other fields
});
Character object.
parseCharacter
Parse and validate a character from JSON or object.
import { parseCharacter } from "@elizaos/core";
const character = parseCharacter(jsonData);
input
string | object | Character
required
Character data to parse
Character object.
Throws: Error if validation fails with detailed error messages.
validateCharacterConfig
Validate a character configuration.
import { validateCharacterConfig } from "@elizaos/core";
const result = validateCharacterConfig(character);
if (!result.isValid) {
console.error("Validation errors:", result.errors);
}
isValid boolean and errors array.
mergeCharacterDefaults
Merge character with default values.
import { mergeCharacterDefaults } from "@elizaos/core";
const character = mergeCharacterDefaults(partialCharacter);
buildCharacterPlugins
Build plugin list from environment variables.
import { buildCharacterPlugins } from "@elizaos/core";
const plugins = buildCharacterPlugins(process.env);
// Returns plugins based on available API keys
@elizaos/plugin-sql (always)@elizaos/plugin-anthropic (if ANTHROPIC_API_KEY)@elizaos/plugin-openai (if OPENAI_API_KEY)@elizaos/plugin-openrouter (if OPENROUTER_API_KEY)@elizaos/plugin-google-genai (if GOOGLE_GENERATIVE_AI_API_KEY)@elizaos/plugin-discord (if DISCORD_API_TOKEN)@elizaos/plugin-telegram (if TELEGRAM_BOT_TOKEN)@elizaos/plugin-x (if X API credentials)@elizaos/plugin-ollama (fallback if no cloud provider)
Example Character
import { createCharacter } from "@elizaos/core";
const myCharacter = createCharacter({
name: "Eliza",
bio: [
"A knowledgeable AI assistant",
"Specializes in TypeScript and Node.js",
"Helpful and patient with users"
],
adjectives: [
"helpful",
"knowledgeable",
"patient",
"clear"
],
topics: [
"programming",
"typescript",
"nodejs",
"software-development"
],
messageExamples: [
{
examples: [
{
name: "user",
content: { text: "How do I install elizaOS?" }
},
{
name: "Eliza",
content: {
text: "Install elizaOS with: npm install @elizaos/core"
}
}
]
}
],
style: {
all: [
"Be concise and clear",
"Use examples when explaining"
],
chat: [
"Be conversational",
"Ask follow-up questions"
]
},
templates: {
messageHandlerTemplate: `# Context
{{providers}}
# Recent Messages
{{recentMessages}}
Respond as {{agentName}}:`
},
plugins: [
"@elizaos/plugin-sql",
"@elizaos/plugin-anthropic"
],
settings: {
ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY,
ENABLE_AUTONOMY: false
},
advancedPlanning: false,
advancedMemory: false
});
Loading from JSON
{
"name": "Eliza",
"bio": [
"A helpful AI assistant"
],
"messageExamples": [
[
{ "name": "user", "content": { "text": "Hello!" } },
{ "name": "Eliza", "content": { "text": "Hi! How can I help?" } }
]
],
"topics": ["programming", "ai"],
"adjectives": ["helpful", "friendly"],
"plugins": ["@elizaos/plugin-sql"]
}
import { parseCharacter } from "@elizaos/core";
import fs from "fs";
const characterJson = JSON.parse(
fs.readFileSync("./character.json", "utf-8")
);
const character = parseCharacter(characterJson);