# AgentFlow **Repository Path**: computerhong/AgentFlow ## Basic Information - **Project Name**: AgentFlow - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-27 - **Last Updated**: 2026-07-27 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README

AgentFlow

AgentFlow: In-the-Flow Agentic System Optimization

Arxiv Gradio Demo Huggingface Paper Huggingface Model Website X Youtube DeepWiki Slack Wechat AgentFlow

## πŸ“£ News - **[2026.01.26]** πŸš€ Our paper has been accepted by [**ICLR 2026**](https://iclr.cc/Conferences/2026)! See you in Rio de Janeiro! - **[2025.10.26]** πŸ“š Our project introduction has been featured on **[DeepWiki](https://deepwiki.com/lupantech/AgentFlow)**! - **[2025.10.16]** πŸ† Our paper has been accepted by [**NeurIPS 2025 Efficient Reasoning Workshop**](https://efficient-reasoning.github.io/)! - **[2025.10.13]** πŸ“Έ Excited to have a tutorial video for AgentFlow covered by Discover AI on **[YouTube](https://www.youtube.com/watch?v=kIQbCQIH1SI)**! - **[2025.10.10]** πŸš€ Our X [post](https://x.com/lupantech/status/1976016000345919803) received **1K+ likes**! Feel free to check out the post and join the discussion! πŸ’¬ - **[2025.10.08]** πŸ”₯ We are honored to be featured as πŸ€— HuggingFace **[Daily Paper #2](https://huggingface.co/papers/2510.05592)**. ## 🌟 Why AgentFlow? AgentFlow is a **trainable, tool-integrated agentic framework** designed to overcome the **scalability** and **generalization limits** of today’s tool-augmented reasoning approaches. Unlike prevailing approaches such as [Search-R1](https://github.com/PeterGriffinJin/Search-R1) which train a **single LLM** to interleave reasoning steps with tool calls, **AgentFlow** introduces a **modular agentic system** with four specialized modules: 🧭 **Planner**, πŸ›  **Executor**, βœ… **Verifier**, and ✍️ **Generator**. ![framework_overall](assets/img/framework.png) For effective planning and tool use, the framework directly **optimizes planner agent within the system** in an **online fashion** using **Flow-based Group Refined Policy Optimization (Flow-GRPO)**, achieving superior performance across diverse domains with improved tool-calling reliability and long-horizon reasoning capabilities. ![flow_grpo](assets/img/flow_grpo.png) ## πŸ“Ί YouTube Tutorial Excited to have a tutorial video for AgentFlow covered by [Discover AI](https://www.youtube.com/@code4AI) on YouTube!
AgentFlow Tutorial
## πŸš€ Key Features - 🧩 **Modular Agentic System** – Four specialized agent modules (**Planner**, **Executor**, **Verifier**, **Generator**) that coordinate via evolving memory and integrated tools across multiple turns. - πŸ”— **Multi-Tool Integration** – Seamlessly connect with diverse tool ecosystems, including `base_generator`, `python_coder`, `google_search`, `wikipedia_search`, `web_search`, and more. - 🎯 **Flow-GRPO Algorithm** – Enables **in-the-flow agent optimization** for **long-horizon reasoning tasks** with sparse rewards. - πŸ“ˆ **Proven Results** – **AgentFlow (7B Backbone)** beats top baselines on 10 benchmarks, with **+14.9% search**, **+14.0% agentic**, **+14.5% math**, **+4.1% science**, even outperforming ~200B-parameter **GPT-4o**. --- ## πŸ“‘ Table of Contents - [βš™οΈ Setup](#️-setup) - [Installation](#installation) - [Setup Environment Variables](#setup-environment-variables) - [⚑ Quick Start on AgentFlow Inference](#-quick-start-on-agentflow-inference) - [πŸ’₯ Quick Start on AgentFlow Flow-GRPO Training](#-quick-start-on-agentflow-flow-grpo-training) - [(Optional) Test Your Environment](#optional-test-your-environment) - [Dataset Preparation](#dataset-preparation) - [Flow-GRPO Training](#flow-grpo-training) - [🎯 AgentFlow Benchmark](#-agentflow-benchmark) - [🧩 Use Your Own Model in AgentFlow](#-use-your-own-model-in-agentflow) - [🀝 Core Contributors](#-core-contributors) - [πŸŽ“ Advisors](#-advisors) - [πŸ™ Acknowledgements](#-acknowledgements) - [πŸš€ Contributing](#-contributing) ## βš™οΈ Setup ### Prerequisites - **Python 3.11** (recommended) ### Installation ```bash bash setup.sh source .venv/bin/activate # (Optional) Install `parallel` for running benchmark experiments in parallel: sudo apt-get update sudo apt-get install parallel ``` ### Setup Environment Variables Copy the `.env.template` file from `agentflow/.env.template` and rename it to `.env`, then place it in the `agentflow/` folder. Update the following variables with your own API keys: - `OPENAI_API_KEY` (for judging reasponse) - `GOOGLE_API_KEY` (for Google Search tool) - `DASHSCOPE_API_KEY` ([optional] for calling Qwen-2.5-7B-Instruct as engine for agents and tools) - `TOGETHER_API_KEY` ([optional] alternative for calling Qwen-2.5-7B-Instruct as engine for agents and tools - recommended for international users) - More ways: serve Qwen2.5-7B-instruct model with vLLM (details refer to [`serve_vllm_local.md`](assets/doc/serve_vllm_local.md)). Please check [API Key Setup Guide](assets/doc/api_key.md) for detailed instructions on how to obtain these keys. ```bash cp agentflow/.env.template agentflow/.env # Then edit agentflow/.env with your API keys ``` ## πŸ” Check Before You Run (Recommended) Before running inference or training, we recommend verifying that your API keys and environment are properly configured. ### πŸ› οΈ Test Tools Run the following command to test all integrated tools: ```bash cd agentflow/agentflow bash ./tools/test_all_tools.sh ``` Example output: ```text Testing all tools... βœ… base_generator passed βœ… google_search passed βœ… python_coder passed βœ… wikipedia_search passed ... βœ… All tests passed ``` ### 🧠 Test LLM Engines Verify that your LLM engines (OpenAI, DashScope, Gemini, etc.) are correctly initialized and responding: ```bash python agentflow/scripts/test_llm_engine.py ``` Example output: ```text πŸš€ Starting fault-tolerant test for 11 engines... βœ… Passed: 4 β€’ gpt-4o β†’ ChatOpenAI β€’ dashscope-qwen2.5-3b-instruct β†’ ChatDashScope β€’ gemini-1.5-flash β†’ ChatGemini β€’ deepseek-chat β†’ ChatDeepseek ... πŸŽ‰ All engines initialized successfully! ``` ## ⚑ Quick Start on AgentFlow Inference AgentFlow provides a modular agentic system with **four specialized modules** (planner, executor, verifier, generator) that coordinate through **evolving memory** and a **toolkit** over **multiple turns** to solve complex reasoning tasks. To quickly experience the system in action, run the command below (don’t forget to set up your API key): ```bash python quick_start.py ``` Example output of `python quick_start.py`: ```text ==> Initializing agentflow... ==> Setting up tools... ==> 🎯 Reasoning Steps from AgentFlow (Deep Thinking...) ==> πŸ” Step 0: Query Analysis ==> 🎯 Step 1: Action Prediction (Google_Search_Tool) ==> πŸ› οΈ Step 1: Command Execution (Google_Search_Tool) ... **Answer:** The capital of France is Paris. ==> βœ… Query Solved! **Process Summary:** 1. **Query Analysis:** Identified as a factual question about the capital of France. 2. **Tool Selection:** Used Google Search for accurate information. 3. **Execution:** Confirmed Paris as the capital. 4. **Verification:** Cross-referenced sources for reliability. **Answer:** The capital of France is Paris. ``` ## πŸ’₯ Quick Start on AgentFlow Flow-GRPO Training For effective planning and tool use, the framework directly **optimizes the planner agent within the system in an online fashion using Flow-GRPO**. Below is a quick start for training. ### (Optional) Test Your Environment Before diving in, we recommend verifying that AgentFlow's tools, LLM engines, and network configuration are properly set up. See [test_env.md](assets/doc/test_env.md) for detailed testing instructions. ### Dataset Preparation We mix two datasets for training: [NQ (Natural Questions)](https://huggingface.co/datasets/RUC-NLPIR/FlashRAG_datasets) for agentic search and [DeepMath-103K](https://huggingface.co/datasets/zwhe99/DeepMath-103K) for mathematical reasoning. ```bash # train data python data/get_train_data.py # validation data python data/aime24_data.py ``` After that, data dir should be: ``` data/ β”œβ”€β”€ train/ β”‚ └── combined_train.parquet (182,190 samples) β”œβ”€β”€ val/ β”‚ └── aime24.parquet (30 samples) β”œβ”€β”€ aime24_data.py └── get_train_data.py ``` ### Flow-GRPO Training Start agentflow training using Flow-GRPO with tmux: ```bash # Create tmux session and start agentflow service (Window 0) tmux new-session -s agentflow bash train/serve_with_logs.sh # Create new window (Ctrl+B then C) and start training (Window 1) bash train/train_with_logs.sh ``` **Configuration:** All training hyperparameters are in [`train/config.yaml`](train/config.yaml) (model settings, tools, RL parameters, resources, etc.) **Logging:** We provide a comprehensive logging to monitor training. See [logs.md](assets/doc/logs.md) for more details. ## 🎯 AgentFlow Benchmark Serve the trained planner model with VLLM (here we deploy our [7B Flow-GRPO planner model](https://huggingface.co/AgentFlow/agentflow-planner-7b)): ```bash bash scripts/serve_vllm.sh ``` Run inference on specific benchmark tasks: ```bash cd test # Run Bamboogle benchmark bash bamboogle/run.sh ``` After running, each task folder (e.g., `test/bamboogle/`) will contain: - `data/`: Contains the evaluation dataset (e.g., `data.json`). - `logs/`: Contains detailed execution logs for each problem index (organized by model label). - `results/`: Contains the model's generated answers (`output_i.json`) and final evaluation scores (`finalscore_*.log`). You can find more benchmarking details in [benchmark.md](assets/doc/benchmark.md). ## 🧩 Use Your Own Model in AgentFlow AgentFlow supports different LLM engines for each agent module. See [llm_engine.md](assets/doc/llm_engine.md) for supported models and [`factory.py`](agentflow/agentflow/engine/factory.py) for the corresponding `model_string` configuration: **Planner Agent:** - Modify the `llm_engine_name` parameter in the corresponding `run.sh` script (e.g., `test/bamboogle/run.sh`) **Other Agents (Executor, Verifier, Generator):** - By default, these agents use a fixed LLM engine (Qwen-2.5-7B-Instruct via DashScope) - To use your own model, modify `self.llm_engine_fixed` in [`agentflow/agentflow/models/planner.py:19`](agentflow/agentflow/models/planner.py#L19): ```python self.llm_engine_fixed = create_llm_engine(model_string="your-engine", is_multimodal=False, temperature=temperature) ``` and - Modify the `llm_engine_name` parameter in the Executor instantiation from [`agentflow/agentflow/solver.py:232`](agentflow/agentflow/solver.py#L232): ```python # Instantiate Executor executor = Executor( # llm_engine_name=llm_engine_name, llm_engine_name="dashscope", root_cache_dir=root_cache_dir, verbose=verbose, # base_url=base_url, temperature=temperature ) ``` - For detailed information on supported engines and `model_string` formats, see [`llm_engine.md`](assets/doc/llm_engine.md) ## πŸ† Experiments ### πŸ“Š Main Results **AgentFlow (Qwen-2.5-7B-Instruct Backbone)** outperforms top baselines on 10 benchmarks: - **+14.9%** on search - **+14.0%** on agentic reasoning - **+14.5%** on math - **+4.1%** on science πŸ’‘ Even surpasses larger proprietary models like **GPT-4o (~200B)**. ![main_table1](assets/img/maintable1.png) ![main_table2](assets/img/maintable2.png) ### πŸ” In-Depth Analysis - Improved planning and decision-making - Enhanced tool-calling reliability - Positive scaling trends with model size & reasoning turns Explore more in our [paper](https://arxiv.org/abs/2510.05592) or [project page](https://agentflow.stanford.edu/). ![tool_call](assets/img/tool_call.png) --- ## 🀝 Core Contributors
Zhuofeng Li
Zhuofeng Li 		Haoxiang Zhang
Haoxiang Zhang 		Pan Lu
Pan Lu
## πŸŽ“ Advisors
James Zou
James Zou 		Yejin Choi
Yejin Choi 		Yu Zhang
Yu Zhang
## πŸ™ Acknowledgements We thank the following open-source projects: - [verl](https://github.com/volcengine/verl) for the excellent RL framework design. - [vLLM ](https://github.com/vllm-project/vllm) for fast LLM inference support. - [Verl-Tool](https://github.com/TIGER-AI-Lab/verl-tool) and [agent-lightning](https://github.com/microsoft/agent-lightning) for their early-stage exploration in agentic RL Training. We thank [Lambda](https://lambda.ai/careers) for GPU support! ## πŸš€ Contributing We are truly looking forward to open-source contributions to AgentFlow! If you’re interested in contributing, collaborating, or reporting issues, please feel free to open an issue or submit a pull request (PR). You can also reach us at [zhuofengli12345@gmail.com](mailto:zhuofengli12345@gmail.com), [isaacpfino@gmail.com](mailto:isaacpfino@gmail.com), [lupantech@gmail.com](mailto:lupantech@gmail.com) or join our Slack community: [AgentFlow](https://join.slack.com/t/agentflow-co/shared_invite/zt-3f712xngl-LfxS4gmftAeKvcxR3nSkWQ). We are also looking forward to your feedback and suggestions! ## πŸ“š Citation ```bibtex @inproceedings{li2026flow, title = {In-the-Flow Agentic System Optimization for Effective Planning and Tool Use}, author = {Li, Zhuofeng and Zhang, Haoxiang and Han, Seungju and Liu, Sheng and Xie, Jianwen and Zhang, Yu and Choi, Yejin and Zou, James and Lu, Pan}, booktitle = {International Conference on Learning Representations (ICLR)}, year = {2026} } ``` ## ⭐ Star History [![Star History Chart](https://api.star-history.com/svg?repos=lupantech/AgentFlow&type=Date)](https://star-history.com/#lupantech/AgentFlow&Date)

↑ Back to Top ↑