[FEATURE] Code-first durable Workflow orchestration

[gautamsirdeshmukh]

SDK Language

TypeScript

Problem Statement

Strands can coordinate agents with Graph and Swarm, and SessionManager can restore their orchestration state after completed or interrupted nodes. Those primitives are intentionally agent-oriented: they route message inputs through declared nodes or model-selected handoffs and persist multi-agent execution state.

Applications that need to coordinate agents with ordinary code, external systems, retries, human approvals, and process restarts still need a separate durable process layer. A Graph node can block on a tool or suspend through an interrupt, but an in-flight node may rerun after a crash, and Graph does not provide an operation history that checkpoints arbitrary typed side effects for deterministic replay.

This gap appears in long-running SDLC automation, security remediation, incident response, plan/delegate/synthesize systems with runtime-generated tasks, and multi-day approval processes. Each application currently has to define its own run identity, step persistence, callback protocol, replay behavior, and Agent adapter.

Proposed Solution

Add an experimental, code-first durable Workflow primitive for TypeScript. A workflow definition would use ordinary TypeScript control flow over JSON-serializable application values and expose:

• step(id, operation) for checkpointed side-effect boundaries;
• parallel(id, operations) and independently checkpointed steps composed with Promise.all;
• callback(id, payload), signal(runId, callbackId, value), and resume(runId) for externally resolved suspension;
• stable run IDs, persisted operation history, deterministic replay, retries, timeouts, and explicit cross-run cache keys;
• progress streaming, cancellation, state inspection, and optional thread state;
• composition with existing Agent, Graph, and Swarm invocations;
• a checkpointed-Agent adapter that can resume inside one logical Agent invocation without rerunning tool work covered by a persisted checkpoint.

Graph and Swarm remain the preferred primitives for fixed agent topologies and model-directed handoffs. Workflow owns the longer-lived application process around them rather than replacing either primitive.

The first implementation should use the unified Storage API and start experimental. It should define a portable Strands contract without requiring an external workflow service, while leaving room for future AWS Durable Execution, Temporal, or other runtime adapters.

Use Case

1. A CI/CD process designs and implements a change, runs review and tests concurrently, loops through rework, waits for approval, deploys, and later receives an integration-health verdict. The process must resume on another worker without repeating completed stages.
2. A planner returns a runtime-generated typed list of work packages. Specialists execute them in parallel, a critic identifies gaps, and only missing work is repeated after partial failure.
3. A security finding acquires an isolated workspace, runs a checkpointed coding agent, performs independent reviews, waits for severity-dependent approval, deploys a canary, and closes the ticket after production verification.

Alternatives Solutions

• Extend Graph: Graph already supports conditional edges, cycles, parallelism, interrupts, and session persistence. Adding arbitrary typed values, dynamic language-level control flow, operation replay, and external callbacks would mix durable activity semantics into an agent-topology primitive and make its existing use case harder to understand.
• Implement Workflow as MultiAgent: This would reuse one nominal interface, but require application values, callbacks, and side effects to masquerade as agent messages, node results, and multi-agent state.
• Require an external durable engine: Mature engines provide schedulers and operational tooling, but every Strands application would still need to independently define the Agent adapter, event model, callback protocol, and local-development story.

Additional Context

• Discussion Distributed, durable execution for Swarm and Graph multi-agent patterns? #1037 covers distributed and durable execution for Graph and Swarm.
• [FEATURE] Support snapshot session management for multi-agent (Graph/Swarm) #3662 covers snapshot session management for Graph and Swarm.
• [FEATURE] Tool-level suspend/resume for external async callbacks (e.g., Lambda Durable Functions ctx.callback) #2243 covers tool-level suspension for external callbacks.
• The minimum behavioral comparison target is the LangGraph Functional API: code-first entrypoints, durable tasks, replay, human input, retries, caching, progress, and state inspection.
• V1 is not a distributed scheduler, durable timer service, cross-process lock manager, or exactly-once side-effect system. External effects still require idempotency across the crash window before a checkpoint is persisted.