Hey everyone, my name is AbdulRahman Elzahaby (@egyjs), a software engineer from Egypt who’s recently fallen down the rabbit hole of LLMs. Like so many of us, you’ll find me in the thick of automation, bots, and making AI work for fast-tracking features and workflows.
As I started diving into complex, multi-agent workflow automation, I experimented with… everything. I fiddled with n8n, played with OpenClaw, tinkered with Hermes Agent, andspent what felt like ages manually chaining together Python scripts with LangChain and LangGraph. Every tool showed promise, but my work became increasingly complex and every single workflow somehow felt... Unfinished.
The way the industry seems to approach building these kinds of agents revealed a massive, structural gap in tool design.
On one hand, we have intuitive, visual workflow tools like n8n. The drag-and-drop interface is great for a bird’s eye view of higher-level logic. But when you need more advanced concepts, like complex looping with conditional logic, custom state reduction, or a system that integrates properly with code review and versioning, these low-code boxes quickly hit limitations.
On the other hand, we have powerful code-first frameworks like LangGraph. They provide incredible flexibility and raw execution power, but as soon as you start to build even a simple three-agent triage workflow, the boilerplate code starts to pile up. You have to write custom state schemas (TypedDict), initialize every node function individually, define custom logic for how to route between agents, set up the graph checkpointer, and grapple with environment and dependency management.
What seemed missing was a sweet spot - a seamless bridge between the design intuition of visual workflows and the production-ready execution power of code-based frameworks. I wanted a tool that allowed me to simply design a workflow, and then run it efficiently without getting tangled in repetitive boilerplate code. Ultimately, I concluded that what we truly needed was a neutral, portable way to describe a workflow – one that’s separate from the execution environment.
Since such a tool didn’t exist, I decided to build it myself. I’m happy to introduce OpenAgentFlow (.oaf) to the open-source community!
So, what exactly is OpenAgentFlow?
In short, OpenAgentFlow acts for AI agent workflows like OpenAPI does for REST APIs.
We’ve created a human-readable specification language (.oaf) that describes stateful, multi-agent communication flows and state machines. Instead of writing extensive framework-specific Python code to define your agent system, you write a clean, concise .oaf specification that captures the essence of your workflow.
Consider this example – an entire production-ready Customer Support Triage workflow in just 40 lines of .oaf text:
workflow "Support Ticket Triage" {
config {
max_iterations: 3
timeout_seconds: 45
}
state {
ticket_text: string
user_tier: string
category: string
urgency: string
suggested_reply: string
}
agent Classifier {
instructions: """
Analyze the incoming support ticket.
Categorize into: 'Billing', 'Technical Bug', or 'Feature Request'.
Assess urgency level: 'Low', 'Medium', or 'Critical'.
"""
model: "gemini-2.0-flash"
temperature: 0.1
inputs: [ticket_text, user_tier]
outputs: [category, urgency]
}
agent Responder {
instructions: """
Draft a helpful response based on category and urgency.
If urgency is 'Critical', note that high-priority alert has been dispatched.
"""
model: "gemini-2.0-flash"
temperature: 0.6
inputs: [ticket_text, user_tier, category, urgency]
outputs: [suggested_reply]
}
flow {
start -> Classifier
Classifier -> Responder
Responder -> end
}
}
This single 40-line file replaces what would typically be over 250 lines of Python boilerplate code.
How does it work internally? (The AST -> IR -> Target)
OpenAgentFlow is not just another wrapper. It’s a full compiler pipeline implemented from scratch with zero core dependencies, written in JavaScript/Node.js.
[ Your .oaf Specification File ]
-> (1. Lexer & Recursive-Descent Parser) ->
[ Abstract Syntax Tree (AST) ]
-> (2. Semantic Validator: 3-Phase Graph Topology Checking) ->
[ Validated Intermediate Representation (IR JSON) ]
-> (3. Target Adapter Code Generator) ->
[ Executable App (e.g., LangGraph Python, AutoGen, CrewAI) ]
1. Rigorous 3-Phase Semantic Validation
Before even touching an LLM API (which can be costly), OpenAgentFlow performs rigorous validation of your specification:
-
Symbol Resolution: Verifies that every agent and state variable referenced in your
flow {}block is declared within the workflow. - Reference Validation: Ensures all agent inputs are defined in
state {}and that output types match declared states. - Topology and Reachability Checks: At compile-time, it detects common issues like infinite cycles without termination, unreachable nodes, or broken graph edges, preventing runtime errors.
2. A Standardized Intermediate Representation (IR)
After parsing and validation, the compiler transforms your .oaf specification into a clean, standardized JSON Intermediate Representation (docs/api/ir-schema.md). This IR serves as a universal blueprint that isolates your workflow logic from the specifics of any execution framework.
3. Framework Agnosticism through Target Adapters
Currently, our primary execution target is LangGraph (Python). When you use the command oaf run your_workflow.oaf, the OpenAgentFlow compiler converts the IR into a self-contained LangGraph application that runs against your configured LLM providers (OpenAI, Gemini, Anthropic).
The beauty of this approach is that your .oaf files are forward and backward compatible. If a groundbreaking new agent execution framework emerges next year that surpasses LangGraph, you won’t need to rewrite your existing .oaf workflow files. We’ll simply develop a new target adapter (like adapters/autogen/ or adapters/crewai/) that translates the same IR JSON into that new framework.
Give it a Spin in Just 1 min
You can try out OpenAgentFlow right now using Node.js and Python on your machine:
# 1. Install CLI globally
npm install -g openagentflow
# 2. Clone starter template & install dependencies
git clone https://github.com/OpenAgentFlow/openagentflow-starter.git
cd openagentflow-starter
npm install
npm run setup # creates Python venv + prompts for API keys
# 3. Run the triage workflow
npm run triage
We’ve also developed a comprehensive VS Code Extension (simply search for OpenAgentFlow Support in the Marketplace) to provide instant syntax highlighting and grammar checking as you write your .oaf specifications.
What’s Next & How You Can Get Involved
OpenAgentFlow is open-source under the MIT License. The project boasts an extensive test suite with over 163 native checks and zero core dependencies.
I’m actively looking for passionate builders and contributors who share this vision for simplifying agent workflow development:
Adapter Developers: We have open RFCs and scaffolding to start building target adapters for Microsoft AutoGen and CrewAI.
Language Designers: Let’s refine advanced .oaf syntax features like conditional when clauses and more complex routing logic.
Workflow Creators: Share your .oaf` topologies and useful starter templates with the community!
If you’re as tired of juggling Python boilerplate and being tied to a specific framework as I am, head over to the GitHub repository, give it a star if you like what you see, and let me know your feedback and suggestions!
- GitHub Repository: https://github.com/OpenAgentFlow/OpenAgentFlow
- VS Code Marketplace: OpenAgentFlow Support
- Let's connect on X/Twitter: @egyjs
