Actors

An Actor represents a user role in your system. It's the "who" in the Screenplay Pattern: the character whose story you're helping to complete.

What Makes a Good Actor?

Actors should represent distinct user roles with different needs:

# E-commerce example
et create actor --id "shopper" --name "Shopper" \
  --description "A customer browsing and purchasing products"

et create actor --id "seller" --name "Seller" \
  --description "A merchant managing inventory and fulfilling orders"

et create actor --id "support_agent" --name "Support Agent" \
  --description "Customer service representative resolving issues"

Actor Fields

Field	Required	Description
id	Yes	Unique identifier (letters, numbers, underscores, hyphens)
name	Yes	Human-readable name
description	Yes	Brief description of the actor's role and needs
goals	No	List of goal IDs this actor wants to achieve
tags	No	Labels for filtering and organisation
meta	No	Custom key-value metadata

Creating Actors

et create actor \
  --id "customer" \
  --name "Customer" \
  --description "End user of the application seeking to accomplish tasks efficiently"

With goals reference:

et create actor \
  --id "admin" \
  --name "Administrator" \
  --description "System administrator managing users and configuration" \
  --goals "manage_users,configure_system"

Tags and Metadata

Use tags to categorize and filter actors. Use metadata to store additional information like login hints or test credentials references.

# Create actor with tags
et create actor \
  --id "premium_customer" \
  --name "Premium Customer" \
  --description "Paying customer with full access" \
  --tags "external,paying"

# Create actor with metadata
et create actor \
  --id "test_admin" \
  --name "Test Administrator" \
  --description "Admin account for testing" \
  --tags "internal,test" \
  --meta "login_hint=admin@test.example.com" \
  --meta "environment=staging"

Filtering by Tags

# List only internal actors
et list actors --tag internal

# List external or paying actors
et list actors --tag "external,paying"

Updating Tags

# Add tags to existing actor
et update actor admin --add-tags "verified"

# Remove tags
et update actor admin --remove-tags "unverified"

# Replace all tags
et update actor admin --tags "internal,active"

Listing Actors

# Table format (default)
et list actors

# JSON format
et list actors --format json

Viewing Actor Details

et show actor customer

Output:

ID:          customer
Name:        Customer
Description: End user of the application seeking to accomplish tasks efficiently
Goals:       checkout, get_support
Tags:        external, verified
Metadata:    login_hint=test@example.com
Created:     2024-01-15T10:30:00.000Z
Updated:     2024-01-15T10:30:00.000Z

Updating Actors

et update actor customer --description "Updated description"
et update actor customer --goals "checkout,browse,get_support"

# Update tags and metadata
et update actor customer --add-tags "premium" --meta "tier=gold"

Removing Actors

# Will warn if actor is referenced by goals, interactions, or journeys
et remove actor old_actor

# Force removal despite references
et remove actor old_actor --force

Best Practices

Do: Create Distinct Roles

et create actor --id "free_user" --name "Free User" \
  --description "User on free tier with limited features"

et create actor --id "premium_user" --name "Premium User" \
  --description "Paying customer with full feature access"

Don't: Create Actors for Internal Roles

# AVOID - these aren't users of your product
et create actor --id "developer" --description "Team member writing code"
et create actor --id "qa" --description "Tester verifying features"

Exception: Tools for Developers

If your product is for developers (like Epilogue Tracker itself), then developers are valid actors:

# Valid for et - developers ARE the users
et create actor --id "team_member" --name "Team Member" \
  --description "A human defining and reviewing user-centric work"

et create actor --id "agent" --name "Agent" \
  --description "An AI agent using et to manage work items autonomously"

Next Steps

• Goals: What your actors want to achieve
• Interactions: How you help them get there