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 mirrors OpenAI Agents SDK handoffs and the orchestrator-workers delegation workflow.

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.