<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/img/logo.png"> <img alt="AgentFlow" src="assets/img/logo.png" width=31%> </picture> </p> <h3 align="center"> AgentFlow: In-the-Flow Agentic System Optimization </h3>  <p align="center"> <a href="https://arxiv.org/abs/2510.05592"><img src="https://img.shields.io/badge/arXiv-2510.05592-B31B1B.svg?logo=arxiv" alt="Arxiv"></a> <a href="https://huggingface.co/spaces/AgentFlow/agentflow"><img src="https://img.shields.io/badge/Gradio-Demo-F97316.svg?logo=gradio" alt="Gradio Demo"></a> <a href="https://huggingface.co/papers/2510.05592"><img src="https://img.shields.io/badge/Huggingface-Paper-FFD21E.svg?logo=huggingface" alt="Huggingface Paper"></a> <a href="https://huggingface.co/AgentFlow"><img src="https://img.shields.io/badge/Huggingface-Model-FFD21E.svg?logo=huggingface" alt="Huggingface Model"></a> <a href="https://agentflow.stanford.edu/"><img src="https://img.shields.io/badge/Website-AgentFlow-E5426E?logo=kashflow" alt="Website"></a> <a href="https://x.com/lupantech/status/1976016000345919803"><img src="https://img.shields.io/badge/Coverage-AgentFlow-2176BC.svg?logo=x" alt="X"></a> <a href="https://www.youtube.com/watch?v=kIQbCQIH1SI"><img src="https://img.shields.io/badge/YouTube-Tutorial-FF0000?logo=youtube" alt="Youtube"></a> <a href="https://deepwiki.com/lupantech/AgentFlow"><img src="https://img.shields.io/badge/DeepWiki-AgentFlow-6B4FBB?logo=readthedocs&logoColor=white" alt="DeepWiki"></a> <a href="https://join.slack.com/t/agentflow-co/shared_invite/zt-3f712xngl-LfxS4gmftAeKvcxR3nSkWQ"><img src="https://img.shields.io/badge/Slack-AgentFlow-D41544.svg?logo=slack" alt="Slack"></a> <a href="https://github.com/lupantech/AgentFlow/blob/main/assets/img/wechat_group.jpg"> <img src="https://img.shields.io/badge/Wechat-AgentFlow-07C160.svg?logo=wechat" alt="Wechat AgentFlow"> </a> </p>

📣 News

[2026.01.26] 🚀 Our paper has been accepted by ICLR 2026! See you in Rio de Janeiro!
[2025.10.26] 📚 Our project introduction has been featured on DeepWiki!
[2025.10.16] 🏆 Our paper has been accepted by NeurIPS 2025 Efficient Reasoning Workshop!
[2025.10.13] 📸 Excited to have a tutorial video for AgentFlow covered by Discover AI on YouTube!
[2025.10.10] 🚀 Our X post 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.

🌟 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 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

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

📺 YouTube Tutorial

Excited to have a tutorial video for AgentFlow covered by Discover AI on YouTube!

<div align="center"> <a href="https://www.youtube.com/watch?v=kIQbCQIH1SI"> <img src="https://img.youtube.com/vi/kIQbCQIH1SI/maxresdefault.jpg" alt="AgentFlow Tutorial" width="100%"> </a> </div>

🚀 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
- Installation
- Setup Environment Variables
⚡ Quick Start on AgentFlow Inference
💥 Quick Start on AgentFlow Flow-GRPO Training
🎯 AgentFlow Benchmark
🧩 Use Your Own Model in AgentFlow
🤝 Core Contributors
🎓 Advisors
🙏 Acknowledgements
🚀 Contributing

⚙️ Setup

Prerequisites

Python 3.11 (recommended)

Installation

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

Please check API Key Setup Guide for detailed instructions on how to obtain these keys.

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:

cd agentflow/agentflow
bash ./tools/test_all_tools.sh

Example output:

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:

python agentflow/scripts/test_llm_engine.py

Example output:

🚀 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):

python quick_start.py

Example output of python quick_start.py:

==> 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 for detailed testing instructions.

Dataset Preparation

We mix two datasets for training: NQ (Natural Questions) for agentic search and DeepMath-103K for mathematical reasoning.

# train data
python data/get_train_data.py
# validation data
python data/aime24_data.py

After that, data dir should be:

data/
├── train/

AgentFlow

Install / Use

README