lhh737/LangChain-ReAct-Agent: a ReAct agent with RAG, tools and a Streamlit front end

What lhh737/LangChain-ReAct-Agent is for

The repository targets a narrow, familiar problem: a chat assistant that has to answer questions from a private document set and, on some turns, produce a longer written report instead of a short reply. The README frames the demo around a robot vacuum, with knowledge documents in data/ and a prompt set that switches between ordinary Q&A and report generation. The audience is a Python developer who already knows what an agent loop is and wants a working skeleton to read, not a library to depend on. Everything is MIT licensed, so the code can be copied into a private project without a licence negotiation. The trade-off is that the project ships no package, no release artefact and no versioned API. There are no releases listed, so the main branch is the only distribution channel, and any upgrade is a git pull plus a diff review.

The ReAct loop and where retrieval and tools plug in

The architecture diagram in the README shows a Thought, Action, Observation cycle wrapped by middleware, with three downstream dependencies: Chroma for vector search, a tool set (weather, user data, external data retrieval, report context filling) and a prompt layer that swaps templates at runtime. The agent decides per turn whether to answer from the model, hit the knowledge base, or call a tool. Retrieval itself is split in two: rag/vector_store.py owns the Chroma collection, document loading and MD5-based file deduplication, while rag/rag_service.py performs the lookup and hands the retrieved chunks to the LLM for summarisation. That separation matters because it means the summarisation prompt (prompts/rag_summarize.txt) can be edited without touching the vector store. The prompt switching lives in agent/tools/middleware.py, which the README describes as choosing between the main_prompt.txt and report_prompt.txt system prompts based on runtime context. Configuration is YAML-driven across four files in config/, covering the chat model name, embedding model name, Chroma persistence path, chunk size, retrieval Top-K and supported file types. The design is conventional LangGraph wiring, and the value here is the wiring being visible in one place rather than the approach being novel.

Installing LangChain ReAct Agent and running a first query

The README requires Python 3.10 or newer and a DashScope API key from the Alibaba Cloud Bailian console. Clone the repository first, then install the pinned dependency set from requirements.txt, which fixes langchain 0.3.7, langchain-core 0.3.18, langgraph 0.2.50, langchain-chroma 0.1.4, chromadb 0.5.15, streamlit 1.40.1 and dashscope 1.20.14.

git clone https://github.com/lhh737/LangChain-ReAct-Agent.git
cd LangChain-ReAct-Agent
pip install -r requirements.txt

The API key is read from the environment. The README shows an export for Linux and macOS and a set command for Windows CMD, and .env.example carries the same variable name with a placeholder value.

export DASHSCOPE_API_KEY="your-api-key"

Before the first chat you have to build the vector store once, because the app assumes a populated Chroma collection. The README gives this one-liner, which loads the documents under data/ into the store.

python -c "from rag.vector_store import VectorStoreService; VectorStoreService().load_document()"

Then start the UI. Streamlit serves it on port 8501 and the README says the browser opens at http://localhost:8501.

streamlit run app.py

The README suggests three verification questions: one that should be answered from the knowledge base, one troubleshooting question, and one that should trigger report generation with tool calls. If the first returns a generic answer rather than document content, the vector store is the first thing to check.

Knowledge base loading, deduplication and the DashScope dependency

Two constraints shape how usable this is outside the demo. The first is the model provider. Every LLM and embedding call goes through DashScope, using ChatTongyi for chat and DashScopeEmbedding for vectors, so there is no local-model path and no provider abstraction in the configuration. If your data cannot leave your network, or if you do not have an Alibaba Cloud account, the project does not run as written. The second is the ingestion pipeline. Documents are split with RecursiveCharacterTextSplitter and deduplicated by MD5, which means re-running the load step will not duplicate unchanged files, but it also means an edited document with the same path is treated as a new file rather than an update in place. The README does not describe a delete or reindex path for stale chunks, so a corrected document can leave the old version retrievable until the collection is cleared. Supported file types are configured rather than hardcoded, and the README lists txt and pdf as the mixed-loading formats. Chunk size and Top-K are both in config/chroma.yml, which is where you would tune retrieval quality, but the README does not state defaults for either.

Where the middleware prompt switch can surprise you

The dynamic prompt switching is the most opinionated part of the design and also the least documented. The README says the middleware selects between the ordinary Q&A prompt and the report prompt based on runtime context, and the project structure confirms both templates live as text files under prompts/. What the README does not specify is the rule that triggers the switch. That matters operationally: if you change the wording of a user request, you may move it across the boundary and get a long report where you expected a short answer, or the reverse. There is no documented way to force a mode from the client. The agent timeout is configured in config/agent.yml, and the external data path is set there too, so a tool that reads outside data will fail silently or slowly if that path is wrong. Tool monitoring is listed as a middleware responsibility, which suggests execution is observable, but the README does not describe what is logged or where the log is written. Treat the middleware as something to read in the source before you rely on it.

How this compares to LangChain's own agent constructors

The search terms around this project are mostly about LangChain's built-in agent APIs, so the honest comparison is with those. LangChain exposes create_react_agent and a newer create_agent entry point, and the framework documentation covers prompt templates, streaming and structured output for them directly. Using the library gives you a maintained surface, changelog and upstream fixes. This repository instead hands you a complete application: a Streamlit interface, a Chroma ingestion step, YAML configuration and a middleware layer, all assembled around the same ReAct idea. The difference in approach is scope, not capability. If you want to understand how the loop, retrieval and prompt switching fit together end to end, reading an assembled app is faster than reading framework docs. If you want a dependency you can upgrade on a schedule, the framework constructors are the safer base, and the pinned versions here (langchain 0.3.7, langgraph 0.2.50) will drift from current releases over time.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-05-10. That is roughly four months before today, which is recent enough that the code has not obviously been abandoned, but there are no tagged releases, so there is no changelog to read before pulling. Upgrades are therefore manual: compare requirements.txt against your environment, check config/ YAML keys for renames, and re-read agent/tools/middleware.py if you depend on the prompt switch. The dependency pins are tight, which reduces surprise on a fresh install and increases friction when you want a newer LangChain. The MIT licence permits commercial use, modification and redistribution, and the only obligation is preserving the copyright notice and licence text. That is a statement about the licence terms, not legal advice for your situation. One practical note: the DashScope API key is a recurring cost outside the licence, and nothing in the repository manages or meters it.

Editorial conclusion

Adopt this repository if you want a readable, MIT-licensed walkthrough of a ReAct loop with retrieval, tool calls and a streaming UI, and you are willing to supply your own DashScope key and knowledge documents. Skip it if you need a supported library, a pinned upgrade path or a deployment story, because the README documents none of those. Before building on it, verify that DASHSCOPE_API_KEY is set in your shell, that data/ holds the documents you want indexed, and that the Chroma collection is populated by running the VectorStoreService load step once.

Frequently asked questions

Official sources

1. Issues
2. lhh737/LangChain-ReAct-Agent on GitHub
3. License: MIT
4. README