Completion Signals

Agents must explicitly declare when they’re done

Require agents to explicitly declare when a step is complete.

Why?

Without explicit signals:

• Hard to know if agent finished or crashed
• Can’t verify output was produced
• No suggested next agent

Usage

from splinter.coordination import CompletionTracker

tracker = CompletionTracker(require_explicit=True)

# Agent declares completion
tracker.declare_complete(
    agent_id="researcher",
    step=0,
    success=True,
    output_summary="Found 5 relevant articles",
    next_agent="writer",  # Suggest who should run next
)

Check Completion

# Check if step is complete
if tracker.is_complete("researcher", 0):
    print("Step 0 complete!")

# Get completion details
signal = tracker.get_completion("researcher", 0)
print(f"Success: {signal.success}")
print(f"Output: {signal.output_summary}")
print(f"Next: {signal.next_agent}")

Require Completion

# Require that completion was declared before proceeding
tracker.require_completion("researcher", 0)

# If not declared, raises CompletionNotDeclaredError

Completion Signal Properties

signal = tracker.get_completion("researcher", 0)

print(signal.agent_id)        # "researcher"
print(signal.step)            # 0
print(signal.success)         # True/False
print(signal.output_summary)  # "Found 5 relevant..."
print(signal.next_agent)      # "writer"
print(signal.timestamp)       # When completed
print(signal.metadata)        # Additional data

List All Completions

all_completions = tracker.get_all_completions()

for signal in all_completions:
    print(f"Step {signal.step}: {signal.agent_id} - {signal.success}")

Callbacks

def on_completion(signal):
    print(f"{signal.agent_id} completed step {signal.step}")
    if signal.next_agent:
        print(f"  Suggested next: {signal.next_agent}")

tracker = CompletionTracker(
    require_explicit=True,
    on_completion=on_completion,
)

Error Handling

from splinter.coordination.execution import CompletionNotDeclaredError

try:
    tracker.require_completion("researcher", 0)
except CompletionNotDeclaredError as e:
    print(f"Agent '{e.agent_id}' did not declare completion for step {e.step}")