> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/kortix-ai/suna/llms.txt
> Use this file to discover all available pages before exploring further.

# Delete Agent

> Permanently delete an agent and all its versions

## Endpoint

```
DELETE /agents/{agent_id}
```

## Authentication

Requires JWT authentication via `Authorization: Bearer <token>` header.

## Description

Permanently deletes an agent, including all its versions, configuration, and associated triggers. This action is **irreversible**.

**What Gets Deleted:**

* Agent record
* All versions (v1, v2, v3, etc.)
* Version configurations (system prompts, tools, MCPs)
* Agent triggers (if any)
* Agent cache entries

**What Is NOT Deleted:**

* Agent runs (preserved for history)
* Threads created by this agent
* Messages generated by this agent

## Path Parameters

<ParamField path="agent_id" type="string" required>
  The unique identifier (UUID) of the agent to delete.
</ParamField>

## Restrictions

The following agents **cannot** be deleted:

1. **Default Agent**: Agents with `is_default: true` must first be unset as default
2. **Suna System Agent**: Agents with `metadata.is_suna_default: true` are protected

Attempting to delete protected agents returns `400 Bad Request`.

## Response

<ResponseField name="message" type="string">
  Success confirmation message
</ResponseField>

### Success Response

```json theme={null}
{
  "message": "Worker deleted successfully"
}
```

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.kortix.ai/agents/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python SDK theme={null}
  from kortix import Kortix

  client = Kortix(api_key="YOUR_API_KEY")

  client.agents.delete("550e8400-e29b-41d4-a716-446655440000")
  print("Agent deleted successfully")
  ```

  ```typescript TypeScript SDK theme={null}
  import { Kortix } from '@kortix/sdk';

  const client = new Kortix({ apiKey: 'YOUR_API_KEY' });

  await client.agents.delete('550e8400-e29b-41d4-a716-446655440000');
  console.log('Agent deleted successfully');
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  await axios.delete(
    'https://api.kortix.ai/agents/550e8400-e29b-41d4-a716-446655440000',
    {
      headers: {
        'Authorization': `Bearer ${process.env.KORTIX_API_KEY}`,
      },
    }
  );

  console.log('Agent deleted successfully');
  ```
</CodeGroup>

## Error Responses

<ResponseField name="404 Not Found" type="error">
  Agent does not exist or user does not have access

  ```json theme={null}
  {
    "detail": "Worker not found"
  }
  ```
</ResponseField>

<ResponseField name="403 Forbidden" type="error">
  User does not own this agent or lacks permission to delete

  ```json theme={null}
  {
    "detail": "Access denied"
  }
  ```
</ResponseField>

<ResponseField name="400 Bad Request" type="error">
  Attempting to delete a protected agent

  ```json theme={null}
  {
    "detail": "Cannot delete default agent"
  }
  ```

  Or:

  ```json theme={null}
  {
    "detail": "Cannot delete Suna default agent"
  }
  ```
</ResponseField>

<ResponseField name="401 Unauthorized" type="error">
  Missing or invalid authentication token

  ```json theme={null}
  {
    "detail": "Not authenticated"
  }
  ```
</ResponseField>

<ResponseField name="500 Internal Server Error" type="error">
  Server error during deletion

  ```json theme={null}
  {
    "detail": "Internal server error"
  }
  ```
</ResponseField>

## Safe Deletion Pattern

Before deleting an agent, ensure it's not the default:

<CodeGroup>
  ```python Python SDK theme={null}
  from kortix import Kortix

  client = Kortix(api_key="YOUR_API_KEY")

  # Get agent details
  agent = client.agents.get("550e8400-e29b-41d4-a716-446655440000")

  # Check if it's the default
  if agent.is_default:
      # Make another agent the default first
      other_agent_id = "660f9511-f3ac-52e5-b827-557766551111"
      client.agents.update(other_agent_id, is_default=True)
      print("Switched default agent")

  # Check if it's a system agent
  if agent.metadata.get('is_suna_default'):
      raise ValueError("Cannot delete system agent")

  # Safe to delete
  client.agents.delete(agent.agent_id)
  print(f"Deleted agent: {agent.name}")
  ```

  ```typescript TypeScript SDK theme={null}
  import { Kortix } from '@kortix/sdk';

  const client = new Kortix({ apiKey: 'YOUR_API_KEY' });

  const agentId = '550e8400-e29b-41d4-a716-446655440000';
  const agent = await client.agents.get(agentId);

  // Check if default
  if (agent.isDefault) {
    const otherAgentId = '660f9511-f3ac-52e5-b827-557766551111';
    await client.agents.update(otherAgentId, { isDefault: true });
    console.log('Switched default agent');
  }

  // Check if system agent
  if (agent.metadata?.is_suna_default) {
    throw new Error('Cannot delete system agent');
  }

  // Safe to delete
  await client.agents.delete(agentId);
  console.log(`Deleted agent: ${agent.name}`);
  ```
</CodeGroup>

## Cleanup Actions

When an agent is deleted, the following cleanup occurs automatically:

1. **Agent Record**: Removed from `agents` table
2. **Versions**: All version records deleted from `agent_versions` table
3. **Triggers**: Associated triggers deleted via trigger service
4. **Cache**: Agent configuration cache invalidated
5. **User Limits Cache**: Agent count cache invalidated to reflect new limit

## Trigger Cleanup

If the agent has configured triggers (e.g., scheduled runs, webhooks), they are automatically deleted:

```python theme={null}
# Example: Agent has 3 triggers configured
agent = client.agents.get(agent_id)
print(f"Agent has {len(agent.triggers)} triggers")  # Output: 3

# Delete agent - triggers are cleaned up automatically
client.agents.delete(agent_id)

# Triggers are now deleted and will not fire
```

## Recovering from Accidental Deletion

Agent deletion is **permanent** and cannot be undone. To minimize risk:

1. **Export Before Deleting**: Use the export endpoint to save configuration
2. **Verify Agent ID**: Double-check the agent ID before deletion
3. **Check Dependencies**: Ensure no active runs are using this agent

### Export Before Delete

```python theme={null}
# Export agent configuration before deleting
agent = client.agents.get(agent_id)
export_data = client.agents.export(agent_id)

# Save to file
import json
with open(f'agent_backup_{agent.name}.json', 'w') as f:
    json.dump(export_data, f, indent=2)

print(f"Backed up agent: {agent.name}")

# Now safe to delete
client.agents.delete(agent_id)
```

## Notes

* **Irreversible**: Deletion is permanent; consider exporting first
* **Default Protection**: Cannot delete default agent; unset default first
* **System Protection**: Suna and other system agents cannot be deleted
* **History Preserved**: Agent runs and messages remain in the database for audit purposes
* **Cache Invalidation**: Triggers automatic cache cleanup
* **Trigger Cleanup**: All associated triggers are deleted

## Related Endpoints

* [Get Agent](/api/agents/get) - View agent before deleting
* [Update Agent](/api/agents/update) - Unset default flag if needed
* [Export Agent](/api/agents/export) - Backup configuration before deletion
* [List Agents](/api/agents/list) - Find agents to delete