AgentFlow Python Orchestration for Agent Graphs

AgentFlow's graph model for multi-agent work

AgentFlow addresses a specific coordination problem: expressing several coding-agent invocations as a program rather than manually passing prompts and results between terminal sessions. It is aimed at engineers building code review pipelines, iterative implementations, dependency audits, fanout research jobs, and other workflows where a later agent needs the output of an earlier agent. The graph is authored in Python with typed actor nodes, explicit task identifiers, prompts, tools, and edge operators.

The core abstraction is a `Graph`, created with a name and scheduling limits such as `concurrency` or `max_iterations`. Nodes represent agents or fanout and merge operations. The operator `>>` expresses dependencies. A downstream prompt can reference an upstream node through templating such as `{{ nodes.plan.output }}`. This makes data flow explicit in the source file rather than hiding it in shell scripts or prose instructions.

AgentFlow supports Codex, Claude, Kimi, and Pi targets. That breadth matters when a pipeline assigns planning to one agent family, implementation to another, and review to a third. It does not mean that every agent has identical capabilities or permissions. Each node can specify tools such as `read_only` or `read_write`, and the repository describes separate profiles and actor documentation for those choices.

Fanout, merge, and failure-based iteration

The main advantage over a sequence of individual CLI commands is that AgentFlow represents two common coordination patterns directly: expanding one task into many tasks and reducing many results back into one result. `fanout(node, source)` accepts an integer for identical copies, a list for one copy per item, or a dictionary for a Cartesian product. In the documented review example, one scan node feeds a review fanout over `api.py`, `auth.py`, and `db.py`, then a summary node consumes the fanout results.

The reduction side uses `merge`. The README documents batch reduction with `merge(node, source, size=N)` and grouped reduction with `merge(node, source, by=["field"])`. The exact merge prompt is still written as a template, so the graph defines both scheduling and the output contract. That is more controllable than assuming a generic aggregator will know what constitutes a useful final answer.

AgentFlow also models retry-like cycles through `on_failure`. In the iterative implementation example, a writer creates a Python email validator, a reviewer emits `LGTM` when it accepts the result, and `review.on_failure >> write` sends rejected work back to the writer. `success_criteria=[{"kind": "output_contains", "value": "LGTM"}]` makes the stop condition machine-readable. `max_iterations=5` provides a bounded failure path. This is useful for review loops, but it is not a general guarantee that an agent will converge. A graph can still consume its iteration budget while producing an unsatisfactory result.

Pi providers and shared inference services

Pi gives AgentFlow a route to external and local model providers. The README lists Anthropic, OpenAI, Groq, Cerebras, xAI, DeepSeek, Gemini, OpenRouter, and Bedrock, as well as local endpoints such as LMStudio and Ollama through OpenAI-compatible or Anthropic-compatible protocols. A Pi node receives a provider model identifier in the graph, for example `anthropic/claude-sonnet-4-6:high` or `lmstudio/qwen/qwen3.6-27b`. The documentation also describes one-off `ProviderConfig` values that cause AgentFlow to materialize a scoped `models.json` for the run.

For graph execution, AgentFlow can attach a SkyPilot inference service. `InferenceSetup` specifies the GPU selector, model, and engine, such as `engine="sglang"`. According to the README, AgentFlow launches one shared service before scheduling nodes and injects the resolved OpenAI-compatible provider into Pi nodes that do not already define one. The CLI can also launch a vLLM or SGLang endpoint independently and print a `base_url` and `api_key` for use in a structured provider configuration.

This is a meaningful difference from a local agent runner. AgentFlow is not limited to choosing among installed coding CLIs, but it also introduces cloud provisioning, GPU selection, provider configuration, and service lifecycle concerns. The documented Spot behavior is another decision point: Spot is enabled by default, and the README documents `--no-spot` when that policy is unsuitable.

Install AgentFlow and run a first graph

The README provides a one-line installer that installs the `agentflow` command, adds it to `PATH`, and installs the AgentFlow skill for Codex and Claude Code:

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

That command is convenient, but it executes a remote shell script directly. A source-based installation is also documented for development environments. The following commands create a virtual environment, activate it, and install the package in editable mode with its development dependencies:

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

The first run can serialize a small dependency chain and print its JSON representation:

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())

Save that as `pipeline.py`, then invoke the documented CLI. It should execute the graph and print a summary according to the `--output summary` option:

agentflow run pipeline.py --output summary

Before using a real agent node, install the corresponding agent CLI and complete its login or provider setup. AgentFlow orchestrates those tools, but the repository does not claim that a single package installation supplies every external agent account or model credential.

Docker, SSH, EC2, and ECS execution boundaries

AgentFlow separates graph definition from execution targets. The bundled Dockerfile builds an image containing AgentFlow and the Codex, Claude, Kimi, and Pi CLIs, with Docker client and daemon support for nested workloads. The documented build command is:

docker build -t agentflow-agents:latest .

A Docker node can use that image by default with `kind: "docker"`. The graph configuration can set `workdir_read_only`, mount repository paths, and choose a `network_policy` of `none`, `bridge`, `host`, or a named custom network. AgentFlow bind-mounts the pipeline workspace and creates a writable per-node runtime directory. The documentation specifically states that host API-key variables and CLI login homes are not inherited implicitly by a Docker target. Keys must be supplied through `node.env` or `provider.env`, while Codex login material has separate handling described in the Docker section.

The repository also lists examples for EC2, ECS Fargate, cloud hypervisors, and SSH-related execution, and the README describes SkyPilot-managed inference. These are distinct operational models. A Docker image can make a run repeatable, but it does not remove the need for credentials, network policy, provider access, and container maintenance. A custom network may be connected to an operator-managed egress proxy or firewall, which makes the runtime boundary more controllable but adds infrastructure configuration.

AgentFlow's local and remote options are therefore not interchangeable. A graph that works with a host-installed CLI may fail in Docker because the target does not inherit host login homes or environment variables. The first deployment decision is the execution boundary, not merely the graph syntax.

Maintenance, licensing, and practical limitations

The repository is not archived, and the last push was on 2026-09-13. The repository has no GitHub releases, so there is no release-based upgrade history documented here. The `pyproject.toml` currently identifies the project as version `0.1.0`, requires Python `>=3.10`, and defines the `agentflow` console entry point. Optional dependency groups include `terminus`, `dev`, and `sky`, which means some advertised integrations are not part of the base dependency set.

The Dockerfile pins specific agent CLI versions, including Codex `0.148.0`, Claude Code `2.1.236`, Kimi CLI `1.49.0`, and Pi `0.84.2`. Those pins make image construction more reproducible, but they also create an upgrade path. Operators need to decide when to refresh the image, update Python dependencies, and check whether agent CLI behavior or authentication has changed. The presence of a `Makefile` with `test` and `smoke` targets provides documented project-level checks, but it does not establish production readiness or compatibility with every external provider.

The project uses the MIT license. That permits use and modification under the license's conditions, but users remain responsible for reviewing the license text and complying with external agent CLI, provider, model, and infrastructure terms. The main functional limitation is scope. AgentFlow does not make agents reliable by itself. Prompt quality, stop criteria, credentials, target isolation, iteration limits, and result validation remain pipeline design responsibilities.

Editorial conclusion

Adopt AgentFlow when the work is genuinely multi-step, needs parallel agent fanout or retry cycles, and can provide the required CLI credentials and execution environment. Do not choose it for a single local prompt or when the graph must be understood without Python. Verify first that the target agent CLIs, provider credentials, Docker setup, and any SkyPilot or Harbor integration match the intended deployment.

Frequently asked questions

Official sources

1. agentenv/agentflow on GitHub
2. Issues
3. License: MIT
4. README