packages/cloud-frontend/content/character-json.mdx
import { Callout, Cards } from "@/docs/components";
Define your agent's personality and behavior with the character JSON format.
<div className="status-badge status-stable">Stable</div>The character JSON is the core configuration for an elizaOS agent. It defines:
{
"name": "Agent Name",
"description": "Brief description",
"bio": ["First bio statement", "Second bio statement"],
"lore": ["Background story element", "Another lore element"],
"style": {
"all": ["Global style instruction"],
"chat": ["Chat-specific style"],
"post": ["Social media style"]
},
"topics": ["topic1", "topic2"],
"adjectives": ["helpful", "friendly"],
"modelProvider": "openai",
"settings": {
"model": "gpt-4o",
"temperature": 0.7,
"maxTokens": 4096
},
"plugins": [],
"clients": []
}
| Field | Type | Required | Description |
|---|---|---|---|
name | string | ✓ | Agent display name |
description | string | Brief description | |
bio | string[] | ✓ | Background statements |
lore | string[] | Backstory elements |
| Field | Type | Required | Description |
|---|---|---|---|
style.all | string[] | Global style rules | |
style.chat | string[] | Chat interaction style | |
style.post | string[] | Social media style | |
topics | string[] | Expertise areas | |
adjectives | string[] | Personality traits |
| Field | Type | Required | Description |
|---|---|---|---|
modelProvider | string | ✓ | AI provider |
settings.model | string | Specific model | |
settings.temperature | number | Creativity (0-2) | |
settings.maxTokens | number | Max response length |
The bio array defines your agent's background:
{
"bio": [
"Expert in machine learning and data science",
"10 years of experience in AI research",
"Published author and conference speaker",
"Passionate about explaining complex topics simply"
]
}
Best Practices:
style.all)Applies to all interactions:
{
"style": {
"all": [
"Be professional yet approachable",
"Use clear, concise language",
"Cite sources when making claims",
"Ask clarifying questions when needed"
]
}
}
style.chat)Specific to chat conversations:
{
"style": {
"chat": [
"Keep responses focused and concise",
"Use bullet points for complex topics",
"Provide examples when helpful",
"End with a question to continue the conversation"
]
}
}
style.post)For social media interactions:
{
"style": {
"post": [
"Keep posts under 280 characters",
"Use relevant hashtags",
"Be engaging and thought-provoking",
"Include a call to action"
]
}
}
| Provider | Models |
|---|---|
openai | OpenAI-compatible model ids from the current catalog |
anthropic | claude-sonnet-4-6, claude-opus-4-7 |
google | gemini-1.5-pro, gemini-1.5-flash |
{
"modelProvider": "openai",
"settings": {
"model": "gpt-4o",
"temperature": 0.7,
"maxTokens": 4096,
"topP": 0.9,
"frequencyPenalty": 0,
"presencePenalty": 0
}
}
Connect documents:
{
"settings": {
"knowledge": {
"enabled": true,
"documentIds": ["doc_abc123"],
"queryLimit": 5,
"minScore": 0.7
}
}
}
Enable MCP servers:
{
"settings": {
"mcp": {
"enabled": true,
"servers": [{ "id": "weather", "url": "https://mcp.eliza.ai/weather" }]
}
}
}
Configure voice synthesis:
{
"settings": {
"voice": {
"provider": "elevenlabs",
"voiceId": "voice_abc123",
"model": "eleven_multilingual_v2"
}
}
}
{
"name": "Support Assistant",
"bio": [
"Dedicated customer support specialist",
"Expert in troubleshooting and problem-solving",
"Patient and thorough in explanations"
],
"style": {
"all": [
"Always be polite and empathetic",
"Acknowledge the customer's issue",
"Provide step-by-step solutions"
],
"chat": [
"Ask for specifics when needed",
"Confirm understanding before solving",
"Follow up on resolution"
]
},
"topics": ["support", "troubleshooting", "product help"],
"modelProvider": "openai",
"settings": {
"model": "gpt-4o",
"temperature": 0.5
}
}
{
"name": "Research Assistant",
"bio": [
"Academic researcher with expertise in literature review",
"Skilled at synthesizing complex information",
"Trained on scientific methodology"
],
"style": {
"all": [
"Use academic language appropriately",
"Cite sources when possible",
"Be precise and thorough"
],
"chat": [
"Break down complex topics",
"Provide evidence for claims",
"Suggest further reading"
]
},
"topics": ["research", "analysis", "academic writing"],
"modelProvider": "anthropic",
"settings": {
"model": "claude-sonnet-4-6",
"temperature": 0.3
}
}
The character JSON is validated on upload. Common errors:
| Error | Cause | Solution |
|---|---|---|
name required | Missing name field | Add name |
invalid provider | Unknown modelProvider | Use supported provider |
invalid temperature | Outside 0-2 range | Adjust temperature |