Noureddine RAMDI / AgentFlow: orchestrating AI coding agents with programmatic dependency graphs

Created Sat, 23 May 2026 20:41:14 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
1032 Words
github-stars python ai-agents agent-orchestration graph-dsl remote-execution concurrency

shouc/agentflow

AgentFlow turns AI coding agent orchestration into a graph programming model — using Python operators instead of YAML configs to define complex workflows involving parallelism, iteration, and remote execution. It addresses a key challenge in AI development: managing multiple coding agents working concurrently with dependencies and evolving outputs.

orchestrating ai coding agents with programmatic dependency graphs

AgentFlow is a Python framework designed to orchestrate AI coding agents like Codex, Claude, Kimi, and Pi through programmatic dependency graphs. Unlike simple linear chains of agent calls, it models your AI workflows as directed acyclic graphs (DAGs), where each node represents an AI agent task and edges define dependencies.

The graph DSL is embedded in Python using the >> operator to declare edges between nodes. This lets you express complex fanout and merge patterns naturally. For example, a single node can fan out to hundreds of parallel worker agents, each processing a slice of data, and their outputs can be merged downstream. Iterative cycles are supported with stop conditions, enabling refinement loops until success criteria are met.

Remote execution is a first-class feature: you can run your agent pipelines remotely on AWS EC2, ECS, or any SSH-accessible host without additional configuration. This lets you scale out workloads easily.

Communication between nodes uses Jinja2 templating to dynamically reference outputs from upstream tasks. A shared scratchboard memory provides lightweight, in-memory state sharing across agents during execution. Additionally, AgentFlow supports agent evolution: past run traces can be used to tune or spawn improved agents.

Under the hood, AgentFlow integrates with multiple AI models: Codex, Claude, Kimi, and Pi (a multi-model routing provider). It also includes a CLI for running, validating, inspecting, and evolving pipelines. Notably, AgentFlow installs skills that let you invoke it directly from Codex or Claude Code.

technical strengths and design tradeoffs in agentflow’s graph-based orchestration

What distinguishes AgentFlow is its graph-centric approach to AI agent orchestration, embedding the workflow definition directly into Python code with minimal ceremony. Using the >> operator for dependency edges feels intuitive and expressive, avoiding the verbosity and complexity of YAML or JSON-based pipeline definitions.

The support for parallel fanout to hundreds of workers via Cartesian products is well-suited for scaling tasks like code review, testing, or multi-part code generation. The merge pattern ensures results converge correctly downstream.

Iterative cycles with configurable stop conditions enable retry or refinement loops, a common pattern in AI workflows where initial outputs may need improvement.

Remote execution capabilities stand out: zero configuration for EC2, ECS, or SSH lets you distribute workloads to the cloud or other hosts easily, a feature often missing or complicated in other orchestration tools.

Shared scratchboard memory is a lightweight mechanism for nodes to share transient state without relying on external databases or caches, improving runtime efficiency.

The tradeoff is a dependency on Python and some complexity in understanding the graph DSL and execution model. While the DSL is elegant, it may have a learning curve for those unfamiliar with Python operator overloading or graph programming.

The codebase quality appears solid, with a clean API and CLI integration that improve developer experience. However, the documentation could be more extensive in covering advanced use cases and failure handling under remote execution.

quick start with agentflow

To install or upgrade AgentFlow, you can run the provided installer script:

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

This command installs AgentFlow, adds it to your PATH, and installs the skill for Codex and Claude Code.

Alternatively, you can manually set up a Python virtual environment and install the package with development dependencies:

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

Here’s a minimal example of defining and running a pipeline programmatically:

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 the pipeline from the CLI and save the output summary:

agentflow run pipeline.py --output summary

You can also invoke AgentFlow directly from Codex using the installed skill, for example:

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

AgentFlow is a practical and thoughtfully designed Python framework for orchestrating AI coding agents at scale using graph-based workflows. Its programmatic DSL embedded in Python makes defining complex fanout, merge, and iterative cycles natural and expressive.

The built-in remote execution support on EC2/ECS/SSH and multi-model integration with Codex, Claude, Kimi, and Pi provide flexibility for cloud scaling and heterogeneous AI agent setups.

That said, the learning curve for the graph DSL and Python dependency mean it’s best suited for developers comfortable with Python and graph programming concepts. The framework shines when scaling multi-agent coding workflows that require parallelism, iteration, and remote distribution.

In production environments, expect to invest time in mastering the execution model, failure handling, and tuning agent evolution features. The CLI and Codex skill integration improve developer experience notably.

Overall, AgentFlow is worth exploring for teams building sophisticated AI coding pipelines beyond simple linear chains. It offers a solid foundation that balances flexibility, scalability, and developer ergonomics, with some tradeoffs in complexity and documentation scope.

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