Agent Workloops: Building a Persistent State Management System for Agent Workflows

Agent Workloops is an open-source agent workflow framework whose core goal is to solve the state recovery problem for multi-step AI agent tasks after a single session is interrupted. It supports full workflow lifecycle management such as plan approval, execution leasing, and result review by defining persistent work loop patterns and deterministic state transition mechanisms. Keywords: Agent Workloops, AI Agent, Workflow, Persistence, Codex, State Management, TypeScript, Zod, Workflow Orchestration.

In AI agent development practice, traditional implementations often assume tasks can be completed in a single session, but real-world complex tasks require continuous work for hours or even days. When a session is terminated due to network interruptions, resource constraints, or human intervention, saving the state of unfinished tasks and resuming from breakpoints becomes a key pain point. The Agent Workloops project is designed to address this issue, providing portable persistent work loop patterns to ensure AI agent work transcends the lifecycle of a single session.

Core Features of WorkLoop

WorkLoop is the core abstraction of the framework, representing a persistent work unit with a clear lifecycle, different from simple task queues:

• State Persistence: State can be serialized and stored, supporting interruption and recovery at any time;
• Deterministic Transition: State transitions follow predefined rules, and the same input produces the same output;
• Sliced Execution: Complex tasks are decomposed into WorkLoopSlices (atomic operation units).

WorkLoopSlice Design

Each slice includes:

• Execution context (input parameters, dependencies, preconditions);
• Execution strategy (calling underlying agent runtime like Codex);
• Result contract (output format and success criteria);
• Retry strategy (failure rollback and retry logic). The sliced design allows tasks to be executed, verified, and rolled back independently.

Layered Architecture

• Core Layer: Defines the common contracts for WorkLoop and WorkLoopSlice, implements pure functions for state selection and transition, provides result adjudication interfaces, and does not depend on specific tracking/review systems or agent runtimes to ensure portability;
• Optional Hosting Layer: Provides advanced features such as plan submission and approval, client token execution leasing, completion archiving, and review UI, which users can enable as needed.

Key Components

• WorkLoop Selector: Selects the next executable slice from the persistent state, considering dependencies, preconditions, retry counts, etc.;
• Adjudication Engine: Converts slice results and review evidence into controller decisions (configurable rules or AI-driven);
• Codex Launcher: Encapsulates Codex execution, supports bounded prompts and result contracts, maps slices to Codex instructions, and returns the state;
• AI Quality Loop Adapter: A dependency-free interface that maps slice context to AI review requests and converts review results into review evidence.

Scenario 1: Long-term Code Refactoring

Decompose large codebase refactoring tasks into multiple slices, each responsible for a module or refactoring pattern; state is persisted after slice execution; session interruptions can be resumed from the last completed slice; results can be manually reviewed before continuing.

Scenario 2: Sensitive Operation Approval

The agent generates an operation plan and submits it as a WorkLoop; enters a waiting-for-approval state and notifies the responsible person; obtains an execution lease (limited time to complete) after approval; automatically archives the operation upon completion for auditing.

Scenario 3: Multi-agent Collaboration

Define a project-level WorkLoop containing subtasks; each agent is responsible for assigned slices; coordinate via shared persistent state; the adjudication engine handles conflicts and dependencies.

State Contract Design

Use Zod schema to define TypeScript types for safety:

• LoopState (current state of the work loop: active/completed slices, global variables, etc.);
• SliceState (slice execution state: input, output, retry count, error information, etc.);
• Policy (slice selection, retry, timeout strategy);
• Decision (adjudication result: continue, retry, skip, terminate, etc.).

Codex Integration

Simplify integration via the Codex Launcher component, encapsulating API complexity while retaining flexibility.

Extensibility

The framework explicitly does not include: specific tool adapters (Linear/Jira, etc.), peer review engines, private orchestration strategies; business logic is implemented by the host system to adapt to complex organizational environments.

Feedback Loop Design

• Codebases using the framework should feed back common, safe, and general workflows to the core framework;
• Avoid accumulating project-specific prompts, warnings, and workarounds downstream;
• Feed back general improvements to the upstream via contribution mechanisms.

Host System Integration

Need to implement adapters:

• Tracker adapter (maps WorkLoop state to project management tools);
• Review engine (implements peer review according to organizational policies);
• Notification routing (configures approval and state change notification channels);
• Deployment strategy (defines private deployment and access control).

Agent Workloops represents an important evolution in AI agent development models: agents are no longer viewed as one-time session tools, but as work units for long-term management and coordination. Through WorkLoop and Slice abstractions, it provides a foundation for the reliability, auditability, and collaboration of AI agents. The layered architecture and extensible design support use as a lightweight library or an enterprise-level platform. As AI agents are deeply applied in various fields, the demand for persistent workflow management will grow, and this framework deserves attention from developers and platform builders.