Skip to content
Back to search

agentflow

Orchestrate thousands of agents and harnesses as a graph programatically

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/berabuddies--agentflow/badge.svg)](/listings/berabuddies--agentflow)

HTML

<a href="/listings/berabuddies--agentflow"><img src="/api/listings/berabuddies--agentflow/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

One line:

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

This installs agentflow, adds it to PATH, and installs the skill for Codex and Claude Code.

Or manually:

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 436 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # AgentFlow
  2. Orchestrate Codex, Claude, Kimi, and Pi agents in dependency graphs with parallel fanout, iterative cycles, and execution on local Docker, SSH, EC2, or ECS targets.
  3. Typed actor nodes, explicit agent profiles, credential-safe Docker preparation,
  4. and the Harbor Terminus 2 adapter are described in
  5. [Actors and profiles](docs/actors-and-profiles.md).
  6. ![AgentFlow Graph](docs/graph.png)
  7. *94-node pipeline: plan → 64 workers → 8 batch merges → 16 reviews → 4 review merges → synthesis*
  8. ## Install / Upgrade
  9. One line:
  10. ```bash
  11. curl -fsSL https://raw.githubusercontent.com/shouc/agentflow/master/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 17 on GitHub
  12. ```
  13. This installs agentflow, adds it to PATH, and installs the skill for Codex and Claude Code.
  14. Or manually:
  15. ```bash
  16. python3 -m venv .venv && . .venv/bin/activate
  17. pip install -e .[dev]
  18. ```
  19. ## Quick Start
  20. ```python
  21. from agentflow import Graph, codex, claude
  22. with Graph("my-pipeline", concurrency=3) as g:
  23. plan = codex(task_id="plan", prompt="Inspect the repo and plan the work.", tools="read_only")
  24. impl = claude(task_id="impl", prompt="Implement the plan:\n{{ nodes.plan.output }}", tools="read_write")
  25. review = codex(task_id="review", prompt="Review:\n{{ nodes.impl.output }}")
  26. plan >> impl >> review
  27. print(g.to_json())
  28. ```
  29. ```bash
  30. agentflow run pipeline.py --output summary
  31. ```
  32. Or just ask Codex (the agentflow skill is auto-installed):
  33. ```bash
  34. 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."
  35. ```
  36. ## Parallel Fanout
  37. Fan a node into many parallel copies with `fanout()`:
  38. ```python
  39. from agentflow import Graph, codex, fanout, merge
  40. with Graph("code-review", concurrency=8) as g:
  41. scan = codex(task_id="scan", prompt="List the top 5 files to review.")
  42. review = fanout(
  43. codex(task_id="review", prompt="Review {{ item.file }}:\n{{ nodes.scan.output }}"),
  44. [{"file": "api.py"}, {"file": "auth.py"}, {"file": "db.py"}],
  45. )
  46. summary = codex(task_id="summary", prompt=(
  47. "Merge findings:\n{% for r in fanouts.review.nodes %}{{ r.output }}\n{% endfor %}"
  48. ))
  49. scan >> review >> summary
  50. print(g.to_json())
  51. ```
  52. `fanout(node, source)` dispatches on type:
  53. - `int` -- N identical copies: `fanout(node, 128)`
  54. - `list` -- one per item: `fanout(node, [{"repo": "api"}, ...])`
  55. - `dict` -- cartesian product: `fanout(node, {"axis1": [...], "axis2": [...]})`
  56. Reduce with `merge(node, source, size=N)` (batch) or `merge(node, source, by=["field"])` (group).
  57. ## Iterative Cycles
  58. Loop until a stop condition with `on_failure`:
  59. ```python
  60. from agentflow import Graph, codex, claude
  61. with Graph("iterative-impl", max_iterations=5) as g:
  62. write = codex(
  63. task_id="write",
  64. prompt="Write a Python email validator.\n{% if nodes.review.output %}Fix: {{ nodes.review.output }}{% endif %}",
  65. tools="read_write",
  66. )
  67. review = claude(
  68. task_id="review",
  69. prompt="Review:\n{{ nodes.write.output }}\nIf complete, say LGTM. Otherwise list issues.",
  70. success_criteria=[{"kind": "output_contains", "value": "LGTM"}],
  71. )
  72. write >> review
  73. review.on_failure >> write # loop until LGTM or max_iterations
  74. print(g.to_json())
  75. ```
  76. ## Local & External Models via Pi
  77. Use the `pi` coding agent as a target alongside `codex` and `claude`. Pi routes
  78. to Anthropic, OpenAI, Groq, Cerebras, xAI, DeepSeek, Gemini, OpenRouter, Bedrock,
  79. etc., and to local endpoints (LMStudio, Ollama) via its OpenAI-compatible or
  80. Anthropic-compatible wire protocols.
  81. ```python
  82. from agentflow import Graph, codex, pi
  83. with Graph("mixed") as g:
  84. # External: Claude via Pi
  85. review = pi(
  86. task_id="review",
  87. prompt="Review {{ nodes.impl.output }}",
  88. model="anthropic/claude-sonnet-4-6:high",
  89. )
  90. # Local: LMStudio (add the provider once in ~/.pi/agent/models.json)
  91. scan = pi(
  92. task_id="scan",
  93. prompt="Scan the repo for TODOs.",
  94. model="lmstudio/qwen/qwen3.6-27b",
  95. tools="read_only",
  96. )
  97. ```
  98. For one-off inline provider configs (e.g. a remote LMStudio box), pass a full
  99. `ProviderConfig` via `provider={...}` and AgentFlow materializes a scoped
  100. `models.json` for the run. See `examples/pi_local_lmstudio.py`.
  101. ## Inference via SkyPilot
  102. Launch a vLLM or SGLang OpenAI-compatible endpoint on SkyPilot-supported clouds:
  103. ```bash
  104. agentflow inference Qwen/Qwen2.5-0.5B-Instruct \
  105. --gpu aws:1xl4@us-east-1
  106. ```
  107. The command prints a `base_url` and `api_key` that can be passed to AgentFlow
  108. nodes through a structured `provider` config. Use `--mode batch` for explicit
  109. JSONL batch jobs.
  110. For graph runs, attach the service directly to the pipeline. AgentFlow launches
  111. one shared SkyPilot service before scheduling nodes, then injects the resolved
  112. OpenAI-compatible provider into PI nodes that do not already set `provider`:
  113. ```python
  114. from agentflow import Graph, InferenceSetup, pi
  115. with Graph(
  116. "my-pipeline",
  117. concurrency=3,
  118. inference=InferenceSetup(
  119. gpu="aws:8x8xb200@us-east-2",
  120. model="Qwen/Qwen2.5-0.5B-Instruct",
  121. engine="sglang",
  122. ),
  123. ) as g:
  124. pi(task_id="answer", prompt="Use the shared inference service.")
  125. ```
  126. GPU selectors support single-node and multi-node shapes, including
  127. `aws:8xb200@us-east-1` and `aws:8x8xb200@us-east-2`. Spot is enabled by default;
  128. use `--no-spot` to disable it. On AWS B200, AgentFlow resolves the current
  129. Blackwell-capable DLAMI from AWS SSM unless `--image-id` is supplied.
  130. ## Execution Targets
  131. ### Docker
  132. Build the bundled agent image once. It contains AgentFlow plus the Codex,
  133. Claude, Kimi, and Pi CLIs, and includes both the Docker client and daemon for
  134. nested Docker workloads:
  135. ```bash
  136. docker build -t agentflow-agents:latest .
  137. ```
  138. `kind: "docker"` uses that image by default:
  139. ```python
  140. from agentflow import Graph, codex
  141. with Graph("docker-review", working_dir=".") as g:
  142. codex(
  143. task_id="review",
  144. prompt="Review the repository without changing it.",
  145. tools="read_only",
  146. target={
  147. "kind": "docker",
  148. "workdir_read_only": True,
  149. "mounts": [
  150. {"source": "./docs", "target": "/reference", "read_only": True},
  151. ],
  152. "network_policy": "bridge",
  153. },
  154. )
  155. print(g.to_json())
  156. ```
  157. AgentFlow automatically bind-mounts the pipeline workspace and a writable
  158. per-node runtime directory. The bundled AgentFlow copy stays inside the image;
  159. an optional `app_mount` can expose a development checkout explicitly.
  160. Additional relative mount sources are resolved from the pipeline
  161. `working_dir`. The structured `network_policy` supports `none`, `bridge`,
  162. `host`, or a named custom network; a custom network can be connected to an
  163. operator-managed egress proxy or firewall for narrower access.
  164. Host API-key variables and CLI login homes are not inherited implicitly by a
  165. Docker target. Put provider keys in `node.env`/`provider.env`; Codex login files
  166. can be exposed read-only with the explicit `inherit_credentials: true` opt-in.
  167. Docker access is opt-in. `mount_docker_daemon: true` mounts the host daemon
  168. socket; this is effectively root-level control of the Docker host, even when
  169. the agent container itself is not privileged. `dind: true` instead starts an
  170. isolated daemon inside the container, requires `privileged: true`, and cannot
  171. be combined with a mounted host daemon. Do not enable either mode for
  172. untrusted prompts or workloads.
  173. The executable example has three modes and does not require model API keys:
  174. ```bash
  175. # Offline, read-only workspace; verifies all bundled CLIs.
  176. agentflow run examples/docker_target.py --output summary
  177. # Gives the container control of the host Docker daemon. Treat as host root.
  178. AGENTFLOW_DOCKER_MODE=daemon agentflow run examples/docker_target.py --output summary
  179. # Starts a nested daemon. This uses a privileged container.
  180. AGENTFLOW_DOCKER_MODE=dind agentflow run examples/docker_target.py --output summary
  181. ```
  182. See [the pipeline reference](docs/pipelines.md#docker) for every field,
  183. custom-network examples, mount behavior, security notes, and compatibility
  184. with the older `kind: "container"` target.
  185. ### Cloud Hypervisor
  186. `kind: "cloud_hypervisor"` boots each node in an ephemeral KVM VM. It uses a
  187. Cloud Hypervisor-compatible Linux kernel, a read-only root filesystem exported
  188. from the bundled all-agent Docker image, virtio-fs for workspace/runtime
  189. sharing, and vsock for the command and streaming output channel. Guest SSH and
  190. guest networking are not required for control:
  191. ```bash
  192. docker build -t agentflow-agents:latest .
  193. mkdir -p .agentflow/cloud-hypervisor
  194. cloud_hypervisor/export-rootfs.sh \
  195. agentflow-agents:latest .agentflow/cloud-hypervisor/rootfs
  196. curl -fL \
  197. https://github.com/cloud-hypervisor/linux/releases/download/ch-release-v6.16.9-20260508/vmlinux-x86_64 \
  198. -o .agentflow/cloud-hypervisor/vmlinux-x86_64
  199. ```
  200. The Linux host must provide `cloud-hypervisor`, a current Rust `virtiofsd`
  201. with UID/GID translation support, and read/write access to `/dev/kvm`.
  202. ```python
  203. codex(
  204. task_id="vm-review",
  205. prompt="Review the repository in an isolated VM.",
  206. target={
  207. "kind": "cloud_hypervisor",
  208. "kernel": ".agentflow/cloud-hypervisor/vmlinux-x86_64",
  209. "rootfs": ".agentflow/cloud-hypervisor/rootfs",
  210. "cpus": 4,
  211. "memory_mib": 8192,
  212. "workdir_read_only": True,
  213. "network_policy": "none",
  214. },
  215. )
  216. ```
  217. The default network policy creates no network device. An explicit TAP policy
  218. can attach a host-managed interface for model/API access; routing, NAT,
  219. firewalling, and destination restrictions remain host responsibilities. Host
  220. credentials are not inherited unless `inherit_credentials: true` is set.
  221. See [the Cloud Hypervisor reference](docs/pipelines.md#cloud-hypervisor) for
  222. image preparation, TAP/static addressing, mount rules, and the guest contract.
  223. ### Remote machines
  224. Run agents on remote machines -- zero config needed:
  225. ```python
  226. # EC2 (auto-discovers AMI, key pair, VPC)
  227. codex(task_id="remote", prompt="...", target={"kind": "ec2", "region": "us-east-1"})
  228. # ECS Fargate (auto-discovers VPC, builds agent image)
  229. codex(task_id="remote", prompt="...", target={"kind": "ecs", "region": "us-east-1"})
  230. # SSH
  231. codex(task_id="remote", prompt="...", target={"kind": "ssh", "host": "server", "username": "deploy"})
  232. ```
  233. Shared instances across nodes:
  234. ```python
  235. plan = codex(task_id="plan", prompt="...", target={"kind": "ec2", "shared": "dev-box"})
  236. impl = codex(task_id="impl", prompt="...", target={"kind": "ec2", "shared": "dev-box"})
  237. plan >> impl # same EC2 instance, files persist
  238. ```
  239. ## Scratchboard
  240. Shared memory file across all agents:
  241. ```python
  242. with Graph("campaign", scratchboard=True) as g:
  243. shards = fanout(codex(task_id="fuzz", prompt="..."), 128)
  244. ```
  245. ## Tuned Agent Evolution
  246. Use a completed Codex run as training data to create a reusable tuned agent:
  247. ```python
  248. from agentflow import Graph, codex, evolve
  249. with Graph("improve-codex", working_dir=".") as g:
  250. source = codex(task_id="plan", prompt="Inspect this repo and summarize the main risks.")
  251. tuned = evolve(source, target="codex", optimizer="codex")
  252. print(g.to_json())
  253. ```
  254. Run order:
  255. ```bash
  256. agentflow run pipeline.py
  257. agentflow evolve <run_id> -n <node_id> --target codex --profile codex --optimizer codex
  258. agentflow tuned-agents
  259. agentflow tuned-agent codex_tuned --output json
  260. ```
  261. Successful evolutions are stored under `.agentflow/tuned_agents/<name>/versions/<version>/` with copied traces, the cloned repo, and version metadata. Tuned agents currently resolve only on local targets.
  262. ## Examples
  263. | Example | What it does |
  264. |---|---|
  265. | `airflow_like.py` | Basic pipeline: plan → implement → review → merge |
  266. | `code_review.py` | Fan out code review across files, merge findings |
  267. | `dep_audit.py` | Audit each dependency for security/license issues |
  268. | `test_gap.py` | Find untested modules, suggest tests per module |
  269. | `multi_agent_debate.py` | Codex vs Claude: independent solve + cross-critique |
  270. | `release_check.py` | Parallel release gate: tests + security + changelog |
  271. | `iterative_impl.py` | Write → review → fix cycle until LGTM |
  272. | `airflow_like_fuzz_batched.py` | 128-shard fanout with batch merge + periodic monitor |
  273. | `airflow_like_fuzz_grouped.py` | Matrix fanout with grouped reducers |
  274. | `ec2_remote.py` | Run codex on a remote EC2 instance |
  275. | `ecs_fargate.py` | Run codex on ECS Fargate |
  276. | `docker_target.py` | Exercise isolated, host-daemon, and Docker-in-Docker targets |
  277. | `cloud_hypervisor_target.py` | Boot an all-agent KVM guest through Cloud Hypervisor, virtio-fs, and vsock |
  278. ## Graph Optimization Rounds
  279. Run multiple optimization rounds over your graph with top-level `optimizer` and `n_run`. Use this when you want AgentFlow to let the optimizer rewrite the graph between rounds; the validation step only checks that the edited pipeline loads and passes schema validation, not that the edits are semantically better.
  280. Artifacts and logs for each round live under `.agentflow/runs/<run_id>/optimization/round-XXX/`.
  281. ```python
  282. from agentflow import Graph, codex
  283. with Graph(
  284. "optimization-demo",
  285. optimizer="codex",
  286. n_run=2,
  287. concurrency=2,
  288. ) as g:
  289. plan = codex(task_id="plan", prompt="Outline the tasks required to finish the ticket.")
  290. review = codex(task_id="review", prompt="Review the plan for missing steps or risks.")
  291. summary = codex(task_id="summary", prompt="Summarize the approved plan and next actions.")
  292. plan >> review >> summary
  293. print(g.to_json())
  294. ```
  295. ## CLI
  296. ```bash
  297. agentflow run pipeline.py # run a pipeline
  298. agentflow run pipeline.py --output summary
  299. agentflow evolve <run_id> -n plan # evolve a tuned agent from prior Codex traces
  300. agentflow tuned-agents # list locally registered tuned agents
  301. agentflow tuned-agent codex_tuned # inspect one tuned agent
  302. agentflow inspect pipeline.py # show expanded graph
  303. agentflow validate pipeline.py # check without running
  304. agentflow templates # list starter templates
  305. agentflow init > pipeline.py # scaffold a starter
  306. agentflow serve # start the local web UI and API on 127.0.0.1:8000
  307. ```
  308. ## Web UI and API safety
  309. `agentflow serve` binds to `127.0.0.1` by default.
  310. The web API only accepts `application/json` requests for `/api/runs` and `/api/runs/validate`, and `pipeline_path` is disabled on those endpoints by default. This prevents the browser-facing control plane from executing arbitrary local `.py` pipeline files just by referencing a path.
  311. If you intentionally want the web API to load pipelines from filesystem paths in a trusted local environment, opt in explicitly:
  312. ```bash
  313. AGENTFLOW_API_ALLOW_PIPELINE_PATH=1 agentflow serve
  314. ```
  315. That opt-in is meant for trusted operator-controlled workflows only.
  316. ## Acknowledgements
  317. * [gepa](https://github.com/gepa-ai/gepa)
  318. * [kiss-ai](https://github.com/ksenxx/kiss_ai)
  319. * [claude-code-telegram](https://github.com/RichardAtCT/claude-code-telegram)
  320. * [linux.do](https://linux.do)
  321. ## Citation
  322. If you use this tool, please cite our paper:
  323. ```bibtex
  324. @misc{liu2026synthesizingmultiagentharnessesvulnerability,
  325. title={Synthesizing Multi-Agent Harnesses for Vulnerability Discovery},
  326. author={Hanzhi Liu and Chaofan Shou and Xiaonan Liu and Hongbo Wen and Yanju Chen and Ryan Jingyang Fang and Yu Feng},
  327. year={2026},
  328. eprint={2604.20801},
  329. archivePrefix={arXiv},
  330. primaryClass={cs.CR},
  331. url={https://arxiv.org/abs/2604.20801},
  332. }
  333. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.