Noureddine RAMDI / AgentFlow: orchestrating AI coding agents with graph-based parallelism and remote execution

Created Mon, 04 May 2026 10:23:02 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
1024 Words
github-stars python ai-agents orchestration parallelism codex cli

shouc/agentflow

AgentFlow tackles a real problem in AI development: managing complex workflows involving multiple coding agents running concurrently and interacting in sophisticated ways. Unlike simple agent chaining, it structures AI agents as nodes in a programmatic dependency graph, enabling parallel execution, iterative refinement, and remote deployment. The result is a practical framework for scaling AI coding tasks using graph orchestration under the hood.

orchestrating ai coding agents with programmatic dependency graphs

AgentFlow is a Python library that lets you build AI agent pipelines as directed graphs. Each node represents an AI coding agent task, and dependencies between nodes define execution order and data flow. This graph-based DSL is embedded in Python, using context managers and the >> operator to declare dependencies clearly and concisely.

The system supports parallel fanout patterns where a node can dispatch multiple agents over lists, dictionaries, or integer ranges, then merge their outputs downstream. This pattern is essential for scaling tasks like code review or testing across many files or components.

AgentFlow also supports iterative cycles with on_failure loops, allowing agents to retry or refine their output until a condition is met. Remote execution is built-in, letting you run agents over SSH, EC2, or ECS, which is crucial for distributing workload and leveraging cloud resources.

Communication between nodes uses Jinja2 templating, enabling nodes to reference outputs of upstream agents dynamically. A shared memory feature called “scratchboard” offers a lightweight way for agents to share state during execution. Additionally, the framework supports agent evolution, where data from completed runs can be used to tune or spawn improved agents.

Under the hood, AgentFlow integrates with various AI models: Codex, Claude, Kimi, or any model accessible via the Pi interface. It even hooks directly into Codex CLI as a skill, which means you can describe your pipeline in natural language and have the system generate and run it automatically.

parallel fanout and remote execution powering scalable multi-agent workflows

What distinguishes AgentFlow is its focus on parallel fanout and merge patterns at scale. The README highlights a 94-node pipeline example with planning, 64 worker agents, batch merges, review agents, and synthesis steps, illustrating its capability to orchestrate hundreds of AI agents efficiently.

The graph DSL’s use of Python context managers and operator overloading (using >>) leads to readable, maintainable code that still expresses complex dependency chains. The choice of Jinja2 for templating between nodes is pragmatic, leveraging a well-understood syntax for dynamic content injection.

Remote execution over SSH or cloud services like EC2 and ECS is integrated rather than bolted-on, which simplifies scaling workloads beyond a local machine. This is key when dispatching dozens or hundreds of agents in parallel.

The codebase is surprisingly clean for a project coordinating so many moving parts, and the modular skill system enables swapping or adding AI models without rewriting core logic. However, the tradeoff is complexity: managing large graphs and debugging distributed execution requires careful thought and tooling.

AgentFlow’s integration with Codex CLI as an auto-installed skill enhances developer experience by allowing pipeline generation from natural language prompts. This reduces friction and enables quick experimentation.

quick start with agentflow

Installing AgentFlow is straightforward. You can run this one-liner to install and set up the CLI skill for Codex and Claude Code:

curl -fsSL https://raw.githubusercontent.com/shouc/agentflow/master/install.sh | bash

Alternatively, for development or manual setup:

python3 -m venv .venv && . .venv/bin/activate
pip install -e .[dev]

Here’s a minimal example pipeline script in Python, lifted directly from the README:

from agentflow import Graph, codex, claude

with Graph("my-pipeline", concurrency=3) as g:
    plan = codex(task_id="plan", prompt="Inspect the repo and plan the work.", tools="read_only")
    impl = claude(task_id="impl", prompt="Implement the plan:\n{{ nodes.plan.output }}", tools="read_write")
    review = codex(task_id="review", prompt="Review:\n{{ nodes.impl.output }}")
    plan >> impl >> review

print(g.to_json())

To run this pipeline and get a summary output:

agentflow run pipeline.py --output summary

You can also ask Codex directly to generate and run pipelines using natural language, thanks to the auto-installed skill:

codex "Use agentflow to fan out 10 codex agents, each telling a unique joke, then merge their outputs and pick the funniest one. Write the pipeline and run it."

verdict: who agentflow is for and what to expect

AgentFlow is a solid choice if you’re building AI workflows that require scaling across many agents and complex dependency management. Its graph-based DSL and parallel fanout patterns handle large multi-agent scenarios better than simple chaining frameworks.

The remote execution support and integration with multiple AI models add flexibility for real-world deployments where local resources aren’t enough. The ability to evolve agents from past runs suggests a path toward more adaptive workflows.

That said, the learning curve is not trivial. Designing, debugging, and maintaining large graphs with many nodes and remote execution demands discipline and tooling. The dependency on specific AI models might limit flexibility if you want to plug in radically different agents.

If your use case involves orchestrating dozens or hundreds of AI coding agents with iterative refinement and remote execution, AgentFlow is worth exploring. Its clean Python DSL, templating system, and Codex CLI integration make it accessible while offering powerful features under the hood. For smaller or simpler multi-agent needs, lighter frameworks might suffice.

Overall, AgentFlow offers a thoughtful balance of expressive power, scalability, and developer experience for orchestrating AI coding agents in production-like workflows.

→ GitHub Repo: shouc/agentflow ⭐ 1,176 · Python