Delete Agent

Endpoint

DELETE /agents/{agentId}

Permanently removes an agent from your elizaOS deployment. This action deletes the agent’s configuration, memory, and all associated data.

This action is irreversible. All agent data, including conversation history and memories, will be permanently deleted.

Request

Path Parameters

agentId

string

required

Unique identifier (UUID) of the agent to delete

Headers

Authorization

string

Bearer token for authentication (if required)

Response

success

boolean

required

Indicates if the deletion was successful

message

string

Confirmation message

data

object

Deletion details

data.agentId

string

ID of the deleted agent

data.deletedAt

number

Unix timestamp when the agent was deleted

Examples

Basic Request

curl -X DELETE http://localhost:3000/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json"

With Authentication

curl -X DELETE http://localhost:3000/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

Success Response

{
  "success": true,
  "message": "Agent deleted successfully",
  "data": {
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "deletedAt": 1709683200000
  }
}

Code Examples

JavaScript/Node.js

const agentId = "550e8400-e29b-41d4-a716-446655440000";

const response = await fetch(`http://localhost:3000/agents/${agentId}`, {
  method: 'DELETE',
  headers: {
    'Content-Type': 'application/json'
  }
});

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

if (success) {
  console.log(message);
}

Python

import requests

agent_id = "550e8400-e29b-41d4-a716-446655440000"

response = requests.delete(f'http://localhost:3000/agents/{agent_id}')
data = response.json()

if data['success']:
    print(data['message'])

TypeScript

interface DeleteAgentResponse {
  success: boolean;
  message: string;
  data?: {
    agentId: string;
    deletedAt: number;
  };
}

const agentId = "550e8400-e29b-41d4-a716-446655440000";

const response = await fetch(`http://localhost:3000/agents/${agentId}`, {
  method: 'DELETE',
  headers: { 'Content-Type': 'application/json' }
});

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

if (result.success) {
  console.log(result.message);
}

Error Responses

404 Not Found

{
  "success": false,
  "error": "Agent not found"
}

400 Bad Request

{
  "success": false,
  "error": "Invalid agent ID format"
}

409 Conflict

{
  "success": false,
  "error": "Cannot delete a running agent. Stop the agent first."
}

500 Internal Server Error

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

Best Practices

Stop Agent Before Deletion

Always stop a running agent before attempting to delete it:

// Stop the agent first
await fetch(`http://localhost:3000/agents/${agentId}/stop`, {
  method: 'POST'
});

// Then delete it
await fetch(`http://localhost:3000/agents/${agentId}`, {
  method: 'DELETE'
});

Backup Important Data

Export agent configuration and conversations before deletion if you need to preserve them:

// Get agent details for backup
const agent = await fetch(`http://localhost:3000/agents/${agentId}`);
const agentData = await agent.json();

// Save to file or database
fs.writeFileSync('agent-backup.json', JSON.stringify(agentData));

// Then proceed with deletion
await fetch(`http://localhost:3000/agents/${agentId}`, {
  method: 'DELETE'
});

Confirm Before Deletion

Implement a confirmation step in your UI:

const deleteAgent = async (agentId: string) => {
  const confirmed = confirm(
    'Are you sure you want to delete this agent? This action cannot be undone.'
  );
  
  if (!confirmed) {
    return;
  }
  
  const response = await fetch(`http://localhost:3000/agents/${agentId}`, {
    method: 'DELETE'
  });
  
  const result = await response.json();
  
  if (result.success) {
    console.log('Agent deleted successfully');
  }
};

What Gets Deleted

When you delete an agent, the following data is permanently removed:

Agent character configuration
All conversation history
Agent memories and embeddings
Room memberships
Agent settings and secrets
Plugin configurations
Action history

Next Steps

List Agents

View remaining agents

Create Agent

Create a new agent

Stop Agent

Stop an agent before deletion

Overview

Agents

Messaging

Endpoint

Request

Path Parameters

Headers

Response

Examples

Basic Request

With Authentication

Response Example

Success Response

Code Examples

JavaScript/Node.js

Python

TypeScript

Error Responses

404 Not Found

400 Bad Request

409 Conflict

500 Internal Server Error

Best Practices

Stop Agent Before Deletion

Backup Important Data

Confirm Before Deletion

What Gets Deleted

Next Steps

List Agents

Create Agent

Stop Agent

Build docs developers (and LLMs) love

Overview

Agents

Messaging

​Endpoint

​Request

​Path Parameters

​Headers

​Response

​Examples

​Basic Request

​With Authentication

​Response Example

​Success Response

​Code Examples

​JavaScript/Node.js

​Python

​TypeScript

​Error Responses

​404 Not Found

​400 Bad Request

​409 Conflict

​500 Internal Server Error

​Best Practices

​Stop Agent Before Deletion

​Backup Important Data

​Confirm Before Deletion

​What Gets Deleted

​Next Steps

List Agents

Create Agent

Stop Agent

Build docs developers (and LLMs) love

Endpoint

Request

Path Parameters

Headers

Response

Examples

Basic Request

With Authentication

Response Example

Success Response

Code Examples

JavaScript/Node.js

Python

TypeScript

Error Responses

404 Not Found

400 Bad Request

409 Conflict

500 Internal Server Error

Best Practices

Stop Agent Before Deletion

Backup Important Data

Confirm Before Deletion

What Gets Deleted

Next Steps