Action Eligibility

Control which agent can act at any moment

ActionEligibility controls which agents can take action at any given time. Prevents race conditions and ensures orderly execution.

Basic Usage

from splinter.coordination import ActionEligibility

elig = ActionEligibility()

# Only researcher can act initially
elig.set_eligible("researcher")

# Check who can act
elig.can_act("researcher")  # True
elig.can_act("writer")      # False

# Transfer eligibility
elig.transfer("researcher", "writer")
elig.can_act("writer")      # True
elig.can_act("researcher")  # False

Eligibility Modes

from splinter.coordination import EligibilityMode

# Single: Only one agent at a time (default)
elig = ActionEligibility(mode=EligibilityMode.SINGLE)

# Multiple: Multiple agents can be eligible
elig = ActionEligibility(mode=EligibilityMode.MULTIPLE)
elig.set_eligible("researcher")
elig.set_eligible("writer")  # Both can act

# Turn-based: Rotate through agents
elig = ActionEligibility(mode=EligibilityMode.TURN_BASED)
elig.set_turn_order(["researcher", "writer", "reviewer"])

Eligibility Rules

# Set rules for eligibility
elig.add_rule(
    agent="writer",
    requires=["researcher"],  # Writer can only act after researcher
)

elig.add_rule(
    agent="reviewer",
    requires=["researcher", "writer"],  # After both
)

# Eligibility auto-updates based on rules
elig.mark_complete("researcher")
# Now writer is eligible

Blocking and Unblocking

# Temporarily block an agent
elig.block("researcher", reason="Waiting for external data")

# Check why blocked
reason = elig.get_block_reason("researcher")

# Unblock
elig.unblock("researcher")

Checking Eligibility

# Who is currently eligible?
eligible = elig.get_eligible_agents()  # ["researcher"]

# Why isn't writer eligible?
reason = elig.why_not_eligible("writer")
# "Waiting for researcher to complete"

# Get all statuses
statuses = elig.get_all_statuses()
# {"researcher": "eligible", "writer": "waiting", "reviewer": "waiting"}

Events

def on_eligible(agent_id):
    print(f"{agent_id} is now eligible to act")

def on_ineligible(agent_id, reason):
    print(f"{agent_id} no longer eligible: {reason}")

elig.on_eligible(on_eligible)
elig.on_ineligible(on_ineligible)

Integration with Workflow

workflow = Workflow(workflow_id="pipeline")

elig = ActionEligibility()
workflow.set_eligibility(elig)

# Workflow uses eligibility to decide which agent runs next

Best Practices

Use rules for dependencies

Let eligibility auto-update based on completions.

Log eligibility changes

Helps debug why agents aren’t running.

Use turn-based for round-robin

When agents need to take turns.