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

agent_id · string · required

The unique identifier (UUID) of the agent to delete.

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

message · string

Success confirmation message

Success Response

{
  "message": "Worker deleted successfully"
}

Examples

cURL

curl -X DELETE https://api.kortix.ai/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Responses

404 Not Found · error

Agent does not exist or user does not have access

{
  "detail": "Worker not found"
}

403 Forbidden · error

User does not own this agent or lacks permission to delete

{
  "detail": "Access denied"
}

400 Bad Request · error

Attempting to delete a protected agent

{
  "detail": "Cannot delete default agent"
}

Or:

{
  "detail": "Cannot delete Suna default agent"
}

401 Unauthorized · error

Missing or invalid authentication token

{
  "detail": "Not authenticated"
}

500 Internal Server Error · error

Server error during deletion

{
  "detail": "Internal server error"
}

Safe Deletion Pattern

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

Python SDK

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}")

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:

# 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

# 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 - View agent before deleting
• Update Agent - Unset default flag if needed
• Export Agent - Backup configuration before deletion
• List Agents - Find agents to delete