Skip to main content
POST
/
agents
Create Agent
curl --request POST \
  --url https://api.example.com/agents \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "<string>",
  "bio": "<string>",
  "lore": [
    {}
  ],
  "messageExamples": [
    {}
  ],
  "style": {
    "style.all": [
      {}
    ],
    "style.chat": [
      {}
    ],
    "style.post": [
      {}
    ]
  },
  "topics": [
    {}
  ],
  "adjectives": [
    {}
  ],
  "settings": {
    "settings.model": "<string>",
    "settings.embeddingModel": "<string>"
  },
  "plugins": [
    {}
  ]
}
'
{
  "success": true,
  "data": {
    "data.agentId": "<string>",
    "data.name": "<string>",
    "data.status": "<string>",
    "data.createdAt": 123
  }
}

​
Endpoint

POST /agents
Creates a new agent in your elizaOS deployment. An agent requires a character configuration that defines its personality, knowledge, and behavior.

​
Request

​
Headers

​
Content-Type
string
required
Must be application/json
​
Authorization
string
Bearer token for authentication (if required)

​
Body Parameters

​
name
string
required
Name of the agent’s character
​
bio
string
Short biography or description of the agent
​
lore
array
Array of background story elements
​
messageExamples
array
Example conversations for the agent to learn from
​
style
object
Writing and communication style settings
​
style.all
array
General style guidelines
​
style.chat
array
Chat-specific style guidelines
​
style.post
array
Post-specific style guidelines
​
topics
array
Topics the agent is knowledgeable about
​
adjectives
array
Adjectives describing the agent’s personality
​
settings
object
Configuration settings for the agent
​
settings.model
string
LLM model to use (e.g., “gpt-4”, “claude-3-opus”)
​
settings.embeddingModel
string
Embedding model for semantic search
​
plugins
array
Array of plugin names to enable for this agent

​
Response

​
success
boolean
required
Indicates if the agent was created successfully
​
data
object
required
Created agent details
​
data.agentId
string
required
Unique identifier for the newly created agent (UUID)
​
data.name
string
required
Name of the agent
​
data.status
string
required
Initial status: inactive
​
data.createdAt
number
Unix timestamp when the agent was created

​
Examples

​
Minimal Agent

curl -X POST http://localhost:3000/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice",
    "bio": "A helpful AI assistant"
  }'

​
Complete Agent Configuration

curl -X POST http://localhost:3000/agents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "TechSupport",
    "bio": "A technical support specialist who helps users troubleshoot software issues",
    "lore": [
      "Has 10 years of experience in technical support",
      "Specializes in debugging complex software problems",
      "Known for patience and clear explanations"
    ],
    "topics": [
      "software troubleshooting",
      "system administration",
      "networking",
      "debugging"
    ],
    "adjectives": [
      "patient",
      "knowledgeable",
      "helpful",
      "thorough"
    ],
    "style": {
      "all": [
        "Use clear, jargon-free language",
        "Break down complex problems into simple steps",
        "Always confirm user understanding before moving forward"
      ],
      "chat": [
        "Be conversational and friendly",
        "Use analogies to explain technical concepts"
      ]
    },
    "settings": {
      "model": "gpt-4",
      "embeddingModel": "text-embedding-3-small"
    },
    "plugins": ["bootstrap"]
  }'

​
Response Example

​
Success Response

{
  "success": true,
  "data": {
    "agentId": "770e8400-e29b-41d4-a716-446655440002",
    "name": "TechSupport",
    "status": "inactive",
    "createdAt": 1709683200000
  }
}

​
Code Examples

​
JavaScript/Node.js

const agentConfig = {
  name: "Alice",
  bio: "A helpful AI assistant",
  topics: ["general knowledge", "conversation"],
  adjectives: ["friendly", "helpful", "empathetic"]
};

const response = await fetch('http://localhost:3000/agents', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(agentConfig)
});

const { success, data } = await response.json();

if (success) {
  console.log(`Agent created with ID: ${data.agentId}`);
}

​
Python

import requests

agent_config = {
    "name": "Alice",
    "bio": "A helpful AI assistant",
    "topics": ["general knowledge", "conversation"],
    "adjectives": ["friendly", "helpful", "empathetic"]
}

response = requests.post(
    'http://localhost:3000/agents',
    json=agent_config
)

data = response.json()

if data['success']:
    print(f"Agent created with ID: {data['data']['agentId']}")

​
TypeScript

interface CreateAgentRequest {
  name: string;
  bio?: string;
  lore?: string[];
  topics?: string[];
  adjectives?: string[];
  style?: {
    all?: string[];
    chat?: string[];
    post?: string[];
  };
  settings?: {
    model?: string;
    embeddingModel?: string;
  };
  plugins?: string[];
}

interface CreateAgentResponse {
  success: boolean;
  data: {
    agentId: string;
    name: string;
    status: string;
    createdAt: number;
  };
}

const agentConfig: CreateAgentRequest = {
  name: "Alice",
  bio: "A helpful AI assistant",
  topics: ["general knowledge"],
  adjectives: ["friendly", "helpful"]
};

const response = await fetch('http://localhost:3000/agents', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(agentConfig)
});

const result: CreateAgentResponse = await response.json();

​
Error Responses

​
400 Bad Request

{
  "success": false,
  "error": "Agent name is required"
}

​
409 Conflict

{
  "success": false,
  "error": "Agent with this name already exists"
}

​
500 Internal Server Error

{
  "success": false,
  "error": "Failed to create agent"
}

​
Next Steps

Start Agent

Start your newly created agent

Update Agent

Modify agent configuration

Send Message

Interact with your agent

Build docs developers (and LLMs) love

Get started for freeTalk to us