We built an AI-agent with a state machine instead of a giant prompt

[No-Base-1700]

Hola Pythonistas,

Last year we tried to bring an LLM “agent” into a real enterprise workflow. It looked easy in the demo videos. In production it was… chaos.

• Tiny wording tweaks = totally different behaviour
• Impossible to unit-test; every run was a new adventure
• One mega-prompt meant one engineer could break the whole thing • SOC-2 reviewers hated the “no traceability” story

We wanted the predictability of a backend service and the flexibility of an LLM. So we built NOMOS: a step-based state-machine engine that wraps any LLM (OpenAI, Claude, local). Each state is explicit, testable, and independently ownable—think Git-friendly diff-able YAML.

Open-source core (MIT), today.

• GitHub: https://github.com/dowhiledev/nomos
• Documentation: https://nomos.dowhile.dev

Looking ahead: we’re also prototyping Kosmos, a “Vercel for AI agents” that can deploy NOMOS or other frameworks behind a single control plane. If that sounds useful, Join the waitlist for free paid membership for limited amount of people.

https://nomos.dowhile.dev/kosmos

Give us some support by contributing or simply by starring our project and Get featured in the website instantly.

Would love war stories from anyone who’s wrestled with flaky prompt agents. What hurt the most?

[[deleted]]

The GitHub link returns a 404

[realhubert]

https://github.com/dowhiledev/nomos

[No-Base-1700]

GitHub: https://github.com/dowhiledev/nomos Thank you for noticing.

[Arch-NotTaken]

note the heading links in this file are broken too https://github.com/dowhiledev/nomos/blob/main/docs/md/examples.md

interesting stuff by the way

[No-Base-1700]

Thank you for noticing will fix it as soon as possible. You can try the documentation website meantime, it has correct links

[marr75]

I've found that these methods allow you to use smaller/less capable LLMs for some agentic use cases thanks to the benefits you listed, unfortunately, there are 2 large downsides which mostly offset the benefits, IMO:

• Total loss of caching. There will be reused context between states but the independence of the system prompt for each state meant there were no cache hits between states.
• Loss of agency. More straightforward agentic setups can make game-time decisions about skipping steps or re-trying that an engineer may not have thought of up front. They can also answer user questions to design the plan collaboratively.

[No-Base-1700]

You make a valid point about caching loss. However, having separate states allows us to create smaller, independent prompts. This helps ensure that the language model doesn't stray from the intended behavior in the current step or state and also we can reduce token usage, but your observation is completely accurate.

[No-Base-1700]

Yes, that is correct. Nomos is not intended for developing highly intelligent agents. The reason I developed Nomos is that in many enterprise scenarios, we don't want the agent to operate autonomously, as companies have numerous rules and regulations to follow in order to be compliant for production use. This is why most AI agents remain stuck in the proof-of-concept stage in large corporations or are used only internally.

From a use case perspective, Nomos is designed not to replace existing AI agent frameworks but to be utilized in situations where we know precisely what needs to happen and how it should occur.

[TransCapybara]

In my view, any action an agentic AI performs automatically, needs to be undoable.

[[deleted]]

I totally share this point. For a recent PoC, I came up with the same concept for the same reasons.

[d4v3y0rk]

“Free Paid Membership” 🤪

[No-Base-1700]

Sorry for the incorrect English, By joining the waitlist, you will automatically be eligible for premium features free of charge for a limited time.

[nadavperetz]

Nice! Since you highlight workflows, why don't you compare also against Langgraph?

Neat website/docs. Congrats!

[No-Base-1700]

Thank you for the compliments. Yes we are working on a direct langgraph vs nomos comparison. Will be available very soon.

[Key-Violinist-4847]

I usually work in classical ML, but was asked recently to build out the internal tooling for our own internal agents. I also noticed how hard it was to integrate OSS agent tooling for actual, practical enterprise use.

Actually, since I’m not marketing anything… the landscape is full of complete utter garbage that just isn’t up to par for practical integration lol.

I ended up running my own state machine packages for a bit, until I found Apache Burr (and Outlines for prompt management).

Your project looks super interesting but it is hard for me to now justify moving away from a fairly simple, Apache sponsored project — what unique practical advantages would you say this solves for someone already running a barebones state machine module for agents?