Package com.tnsai.coordination.handoff

Class HandoffChain

java.lang.Object
com.tnsai.coordination.handoff.HandoffChain
public class HandoffChain extends Object
Chains multiple handoff steps into an A -> B -> C pipeline. Each step's output becomes the next step's payload via a freshly constructed HandoffContext — the receiver of step N+1 sees the output of step N, but no earlier output and none of any prior agent's reasoning.

This is the right shape for a known, fixed sequence of specialised executors (ingest → transform → emit-style pipelines), not for problem-solving among peer agents. The compression at each hop means information that was useful at step 1 is gone by step 3, so chains where a later step needs to revisit earlier decisions structurally cannot work here.

For novel problems where the right next agent is decided by the current state (not pre-baked), prefer the ROMA orchestrator-worker pattern at com.tnsai.coordination.roma. For inter-agent negotiation / debate / council use the dedicated topologies in those packages. HandoffChain is the wrong shape for any of those.

See this package's docs for the full when-to-use / when-not-to-use matrix.

  • Method Details

    • execute

      public List<HandoffResult> execute(Handoff handoff, HandoffContext initialContext)
      Executes the chain starting from the first agent. The first agent in the chain is the initial source; each subsequent agent receives a handoff from the previous one.
      Parameters:
      handoff - the handoff strategy to use
      initialContext - the starting context
      Returns:
      list of results (one per executed step, excluding the first agent which is source-only)

    • builder

      public static HandoffChain.Builder builder()