Runtime

Handoffs

techrevati.runtime.handoffs

Handoffs — delegation between agents.

A Handoff records the intent of one agent (the source) to pass control to another (the target), with a structured reason and caller-provided context payload. The source session finalizes its worker as COMPLETED; a new worker is created in the registry under the target role so downstream code can pick it up by worker_id.

The caller resolves the handoff by opening a new session for the target role. This module does not run the target agent — it just records and routes.

The pattern records delegation between sessions without running the target agent directly.

Handoff dataclass 

Handoff(
    source_role,
    target_role,
    phase,
    reason,
    context=dict(),
    project_id=None,
    target_worker_id="",
    created_at=(lambda: datetime.now(UTC).isoformat())(),
)

Immutable record of an agent-to-agent delegation.

Created by OrchestrationSession.handoff_to / AsyncOrchestrationSession.handoff_to. Use target_worker_id to look up the freshly-registered worker from the same AgentRegistry the source session was using.