DEV Community

Cover image for Atomic Stateful Agent — From Architecture Idea to Working Code
nghiach
nghiach

Posted on • Edited on

Atomic Stateful Agent — From Architecture Idea to Working Code

#ai #agents

In a previous article, I introduced the idea of the Atomic Stateful Agent (ASA) — an architecture for building AI agents that can operate safely inside real enterprise workflows.

This repo, atomic-stateful-agent, is the practical implementation of that idea.

It’s not about making agents “talk better”.
It’s about making agents behave safely around real system state.

GitHub: https://github.com/chnghia/atomic-stateful-agent

🚨 The Problem with Chat-Centric Agents

Most agent systems today look like this:

User message → LLM → tool call → system update
Enter fullscreen mode Exit fullscreen mode

This works well for demos.
But in real systems (ERP, CRM, tickets, finance records…):

  • The LLM might misunderstand intent
  • A half-complete instruction can still trigger a write
  • Conversation history becomes your “state” (unstructured, fragile)

That’s risky.

Enterprises don’t run on chat history.
They run on entities, workflows, and transactions.

💡 What Is an Atomic Stateful Agent?

An Atomic Stateful Agent (ASA) is a system where:

  • Workflow logic is modeled as a state machine
  • Business objects are treated as entities
  • Changes happen through a draft → commit process
  • LLM reasoning is controlled, not in charge

Think of it like this:

LLM = reasoning layer
ASA = transactional control layer

The LLM can suggest.
The system decides.

🧩 AIU + ASA: Two Layers, Two Responsibilities

This repo combines two ideas:

🧠 AIU — Atomic Inference Unit

(from my earlier article)

AIU is about atomic reasoning.

An AIU:

  • Has clear structured input
  • Produces structured output
  • Solves one focused inference task
  • Is stateless
  • Does not control workflows or databases

In this repo, AIUs are built using the JIL stack:

Jinja → Instructor → LiteLLM

They live mainly in:

core/      # inference abstractions
schemas/   # structured IO contracts
prompts/   # Jinja templates
Enter fullscreen mode Exit fullscreen mode

So:

AIU = safe, structured thinking

🔄 ASA — Atomic Stateful Agent

(the workflow/state layer)

ASA is about atomic state control.

It handles:

  • Workflow steps
  • State transitions
  • Draft data
  • Commit/cancel logic
  • Interaction with external systems

This layer is implemented through:

nodes/     # workflow nodes
state.py   # AgentState
graph.py   # LangGraph state machine
Enter fullscreen mode Exit fullscreen mode

So:

AIUs think
ASA decides what can happen

This separation is the core design principle.

🔑 Core ASA Patterns in This Repo

1️⃣ Sticky Routing (Intent Lock)

Once a workflow starts, the agent stays in that intent.

Example state:

{
  "active_intent": "daily_log",
  "active_draft": {...},
  "record_id": None
}
Enter fullscreen mode Exit fullscreen mode

The agent doesn’t jump to other tasks just because the user changes wording.

2️⃣ Draft → Commit Protocol

The agent never writes to the real system immediately.

Instead:

User input
   ↓
Create draft state
   ↓
Refine over multiple turns
   ↓
User confirms
   ↓
Commit → persist
Enter fullscreen mode Exit fullscreen mode

During conversation, the user edits a draft object, not production data.

3️⃣ Recall & Hydrate

When editing existing data:

  1. Load record from DB
  2. Hydrate it into draft state
  3. Let the user edit
  4. Commit or cancel

This is not chat memory.
It’s structured state restoration.

📦 Project Structure 

src/
├── core/        # AIU foundation (inference layer)
├── schemas/     # structured IO for AIUs
├── prompts/     # Jinja templates (AIU prompts)
├── nodes/       # ASA workflow nodes
├── state.py     # AgentState model
├── mock_db.py   # in-memory DB
└── graph.py     # LangGraph builder

main.py          # CLI entry point
Enter fullscreen mode Exit fullscreen mode

Key idea:

  • Prompts do not define the system
  • State logic lives in code
  • LLM reasoning is modular (AIUs)
  • Workflow control is deterministic (ASA)

▶️ Running the Agent 

pip install -e .
cp .env.example .env
# add LLM key

python main.py
Enter fullscreen mode Exit fullscreen mode

You get an interactive console, but the behavior is state-driven — not just free chat.

🧪 Example — Creating a Record 

You: Log task: Review PR for auth feature
Agent: Draft created

You: Change priority to high
Agent: Draft updated

You: Done
Agent: Task saved successfully!
Enter fullscreen mode Exit fullscreen mode

Notice:

  • The task was not saved immediately
  • Only after confirmation does it become real

🔁 Editing an Existing Record 

You: Edit the PR review task
Agent: Record found. Hydrating draft…

You: Change title to "Review PR plan"
Agent: Draft updated

You: Save
Agent: Task updated!
Enter fullscreen mode Exit fullscreen mode

This is structured state editing, not memory guessing.

🏗 Why This Matters

If your agent:

  • Updates tickets
  • Modifies contracts
  • Handles finance data
  • Talks to ERP/CRM

Then prompt engineering is not enough.

You need:

  • State machines
  • Entity models
  • Transaction-like control

That’s what ASA provides.

🔄 Architecture → Implementation

My previous article explained the architecture and mindset.

This repo shows:

“Here’s how to actually build it.”

Together:

AIU → Atomic reasoning
ASA → Atomic state control

🧠 Final Thought

The future of enterprise agents is not:

“Smarter chat”

It’s:

Controlled AI operating on structured state

Start thinking less about longer prompts,
and more about state, entities, and workflows.

Top comments (0)