Long tasks fail through context growth, duplicate actions, and interruptions. Treat the plan as mutable data and execution as a finite state machine so a restart can continue from the last successful node.
Core concepts
Each plan item should have an id, prerequisites, input references, status, and retry count. The state machine should allow only declared transitions, such as pending -> running -> succeeded or running -> failed. Do not let a model change state through arbitrary strings.
from enum import StrEnum
class Status(StrEnum):
PENDING = 'pending'
RUNNING = 'running'
SUCCEEDED = 'succeeded'
FAILED = 'failed'
TRANSITIONS = {(Status.PENDING, Status.RUNNING), (Status.RUNNING, Status.SUCCEEDED), (Status.RUNNING, Status.FAILED)}
def transition(old: Status, new: Status) -> Status:
if (old, new) not in TRANSITIONS:
raise ValueError('invalid transition')
return new
Steps
- Draw the business flow as nodes and edges, marking parallel and serial work.
- Store input references for each node instead of copying large context, which lowers retry cost.
- Write
runningbefore execution, then commitsucceededand a result summary in one transaction. - On restart, scan
runningnodes and use idempotency rules to choose recovery, retry, or human handoff.
When to use it
It suits report generation, data synchronization, and multi-step approvals. A real-time chat normally does not need a complex state machine.
Common questions
Does the model still need to create the full plan? It may, but the server must validate node types, dependencies, and budget.
How do I aggregate parallel work? Track every child status and advance only when the required conditions are met.
Should failures be deleted? No. Keep the failure reason and the human resolution.
Official references
OpenAI Agents guide; OpenAI Evals.
Last checked: 2026-11-16. Use the linked official documentation for current behavior.
