Distributed Saga Workflow Specification for Agentic Microservices

Role: Principal Distributed Systems Architect with 15+ years of experience in microservices orchestration and fault-tolerant agent execution.

Context

• Target Orchestration Engine: {{orchestration_engine}}
• Sequential Agent Workflow Steps: {{primary_agent_steps}}
• Shared State Store: {{state_store}}
• High-Risk Failure Modes: {{failure_modes}}
• Retry and Backoff Policy: {{retry_policy}}
• Ops Notification Channel: {{notification_channel}}

Task

Author a production-ready Distributed Saga Workflow Specification that defines the deterministic orchestration sequence, forward transaction contracts, compensating actions for failures, and state persistence rules across {{primary_agent_steps}} using {{orchestration_engine}}.

Method

1. Analyze {{primary_agent_steps}} and map each step to an explicit atomic transaction boundary.
2. Define the payload structure and state delta committed to {{state_store}} at each transition step.
3. Identify failure triggers per step based on {{failure_modes}} and categorize them into retryable vs fatal errors.
4. Apply {{retry_policy}} to transient failures, defining jitter, maximum attempts, and timeout budgets.
5. Design compensating rollback actions for each completed step in reverse order when a non-retryable failure occurs.
6. Specify idempotency mechanisms (e.g., deduplication keys, token checking) for both forward and compensating tasks.
7. Establish dead-letter queue (DLQ) ingestion and alerting workflows routed to {{notification_channel}}.

Constraints

• MUST define explicit backward compensating logic for every forward-executing agent task.
• MUST NOT leave state transitions uncommitted between step boundaries in {{state_store}}.
• Every transaction boundary MUST specify maximum timeout durations and retry ceilings.
• Specifications must avoid vague pseudo-code; use structured schema definitions.

Output format

1. Workflow Topology Overview (Mermaid sequence diagram and state machine definition, max 30 lines)
2. Step-by-Step Step Contract Table (Step ID, Agent Role, Forward Action, Idempotency Key, Timeout)
3. Compensation Matrix (Failure Trigger, Rollback Action, Target Microservice, Invariant Validation)
4. State Persistence & Telemetry Specification (JSON schema for {{state_store}} state object, DLQ routing to {{notification_channel}})

Self-review

• Verify every forward step has a corresponding, executable compensating step.
• Confirm all variables from context ({{orchestration_engine}}, {{state_store}}, etc.) are mapped into the specification.
• Check that the idempotency mechanism prevents double-spend or duplicate mutation during retries.