Delete Agent

​

Endpoint

DELETE /agents/{agent_id}

​

Authentication

​

Description

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

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

​

Path Parameters

​

Restrictions

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

​

Response

​

Success Response

{
  "message": "Worker deleted successfully"
}

​

Examples

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

​

Error Responses

{
  "detail": "Worker not found"
}

{
  "detail": "Access denied"
}

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

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

{
  "detail": "Not authenticated"
}

{
  "detail": "Internal server error"
}

​

Safe Deletion Pattern

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

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

# 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

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