Skip to main content

Architecture

1. Product Thinking​

At the current stage, the product goal of A2E is to turn an "AI conversational request" into a governable workflow execution process, while retaining sufficient engineering control during execution instead of returning only a one-off result.

To support this goal, the current implementation adopts a minimal closed loop:

  • Definition: use workflow as the execution blueprint to describe nodes, edges, and input/output constraints.
  • Execution: use run as a single execution instance that supports lifecycle operations such as create, cancel, and resume.
  • Observation: use event as the factual execution record to support incremental queries and state tracking.
  • Human intervention: use review as the review mechanism to pause at critical points, wait for a decision, and then continue execution.

At the interaction layer, A2E provides two parallel paths:

  • Web entry: for visual editing, runtime monitoring, and review handling.
  • MCP entry: for AI clients such as Codex / CLI, which access the same engine capabilities through tool calls.

This means A2E is neither "just a UI workflow tool" nor "just a collection of CLI automation scripts". It is an execution kernel that connects Web and AI collaboration endpoints through a unified semantic model (workflow / run / review / event). The current version is marked Experimental and focuses on validating architectural feasibility and the engineering closed loop.

2. Technical Architecture Overview​

The current implementation can be understood from two perspectives: component relationships and runtime execution flow.

2.1 Component Relationships​

Based on the current implementation, the main component responsibilities are:

  • Web
    • Provides workflow editing, runtime monitoring, review handling, settings, and the Codex interaction interface.
    • Uses HTTP and WebSocket to access the unified service capabilities exposed by the Server.
  • MCP Server
    • Exposes tool interfaces to Codex / CLI and other MCP clients through STDIO.
    • Does not manage workflow state directly. Instead, it calls A2E Server through loopback HTTP.
  • A2E Server
    • Handles services related to workflows, nodes, runs, reviews, events, and AI nodes.
    • Also manages Codex login, model queries, PTY sessions, and runtime directory management.
  • Codex CLI
    • Acts as the actual execution runtime for AI nodes, launched by the Server inside a controlled directory.
    • Writes structured outputs, logs, and artifact files back into the runtime directory.
  • SQLite + file system
    • SQLite stores structured state such as workflow / run / node_run / review / event.
    • The file system stores AI node definitions, runtime inputs/outputs, logs, artifacts, and failure clues.

The current version does not introduce a standalone queue or worker. Workflow scheduling, state progression, review coordination, and AI node control are all handled directly by the Server process.

2.2 Runtime Execution Flow​

This execution flow reflects the minimal closed loop of the current version: agent.codex handles automated execution, human.review provides human control, and the unified run / review / event semantics converge Web and MCP into the same execution kernel.

Overall, this architecture is aligned with the "minimal viable closed loop, recoverable, observable, runnable on a single machine" direction described in the Technical Selection Guide, while also reserving stable interface boundaries for future expansion such as richer policy governance and observability.

3. Workflow​

3.1 Lifecycle​

The lifecycle of workflow execution can be understood in five steps:

  1. Create: create one independent run after receiving an execution request.
  2. Start: the engine takes over the task and advances it according to node dependencies.
  3. Execute: process nodes one by one and generate intermediate artifacts and event records when necessary.
  4. Pause: pause and wait for a decision when a scenario requires human judgment.
  5. Finish: end in completed, failed, or canceled state according to the execution result, and produce summary information.

The core value of this lifecycle is to turn "AI automated execution" into an engineering process that is controllable, explainable, and replayable.

3.2 State Machine​

The state machine uses a unified semantic model. The main states are:

  • Queued
  • Running
  • Paused
  • Completed
  • Failed
  • Canceled

Typical transition logic:

  • Queued -> Running: the engine starts processing.
  • Running -> Paused: review or human takeover is triggered.
  • Paused -> Running: review passes and execution continues.
  • Running -> Completed: the flow ends as expected.
  • Running -> Failed: a critical node fails and is not recovered through takeover.
  • Any active state -> Canceled: the user or system actively terminates the flow.

State changes are recorded as events for observation, auditing, and troubleshooting.

3.3 Input/Output Contract​

Input/output contracts are used to ensure that the flow stays connected and results remain reusable. They work on two levels:

  • Pre-run validation: check whether flow inputs and node output declarations are complete, and stop obvious errors in advance.
  • Runtime validation: check whether node outputs match the contract after execution so bad data does not continue downstream.

Each node receives input from two sources:

  • Flow entry input
  • Upstream node outputs

Results are persisted both as structured data and as file artifacts so they can be inspected, replayed, and audited later.

4. AI Node​

4.1 Execution Model​

AI nodes are responsible for automated content generation and execution decisions. They are the main "production nodes" in the flow.

The current execution model has the following characteristics:

  • Asynchronous execution: nodes are driven by background tasks to avoid blocking the whole flow.
  • Configuration-driven: execution strategies are managed uniformly through node templates, including model, timeout, and permission scope.
  • Result collection: after execution ends, the system collects status, output, and artifacts into unified records.

4.2 Input/Output and Artifacts​

AI node data is represented in three forms:

  • Input: comes from flow context and upstream node results.
  • Output: structured results and consumable content used by downstream nodes.
  • Artifacts: execution logs, generated files, and failure clues as runtime evidence.

When the primary output is unavailable, the system includes a compatibility fallback mechanism so the flow remains observable and manageable whenever possible. All of this information is stored uniformly for both the Web UI and MCP tools.

4.3 Failure and Recovery​

The handling strategy for AI node failures is "close first, then recover":

  • Close: record failure reasons and contextual evidence so problems are not swallowed silently.
  • Take over: automatically enter review in high-uncertainty situations to prevent errors from spreading.
  • Recover: after review approval, the flow can continue without rerunning the entire workflow from scratch.

Debugging capability is also preserved so issues can be reproduced and fixes can be verified without breaking the main flow.

5. Review Node​

5.1 Active Review​

Active review is a human checkpoint explicitly configured at design time.

When the flow reaches such a node, the system automatically pauses and generates a review task. The reviewer then makes a decision based on the current context and determines whether execution should continue.

5.2 Passive Review​

Passive review is a fallback mechanism triggered dynamically during runtime.

When the system detects abnormal results, risk signals, or execution uncertainty, it automatically switches the flow into human decision mode to prioritize safety and control.

5.3 Interrupt and Resume​

Review nodes support a closed loop of interrupt -> decide -> resume:

  • Review approved: the flow resumes and continues downstream.
  • Review rejected: the flow enters failure closure.
  • Review canceled: the flow terminates and closes unfinished reviews to avoid hanging state.

This mechanism allows automated execution and human judgment to switch smoothly instead of being split into separate worlds.

6. Module Relationships and Data Flow​

The module relationship can be simplified as two entry points and one kernel:

  1. Web entry
    • For human users to configure flows, observe execution, and handle reviews.
  2. MCP entry
    • For AI clients to call the same capabilities through tools.
  3. Unified kernel
    • Both entries ultimately converge into the same execution kernel, which handles state progression, event recording, review coordination, and result persistence.
    • The current kernel mainly includes workflow management, run scheduling, review coordination, and AI node execution.

This ultimately forms a unified data semantic model: flow definitions, execution instances, node state, review records, and event traces.
That is also the key to A2E supporting both human-AI collaboration and consistency across multiple entry points.