AgentFlow

AgentFlow is a multi-utility AI chatbot built using LangGraph and Streamlit, designed around modular and stateful agent workflows.

The system combines Retrieval-Augmented Generation (RAG), dynamic tool calling, Model Context Protocol (MCP) integration, Human-in-the-Loop (HITL) capabilities, persistent conversation state, and observability into a single AI assistant.

The chatbot uses an open-source Large Language Model hosted through the Hugging Face Inference API. The LLM is accessed remotely using a Hugging Face API token rather than being executed locally.

For document retrieval, the project uses an open-source Hugging Face sentence-transformer embedding model together with FAISS for vector similarity search.

🚀 Features

1. Modular Stateful Agent

The chatbot is implemented using LangGraph's StateGraph.

The agent separates the reasoning and execution process into different components:

LLM reasoning
Tool selection
Tool execution
Conditional routing
State management
Human approval
Persistent checkpointing

The main workflow is:

START
  ↓
chat_node
  ↓
tools_condition
  ├──→ tools → chat_node
  │
  └──→ END

This allows the agent to iteratively reason, invoke tools when required, process tool results, and generate a final response.

2. Human-in-the-Loop (HITL)

AgentFlow supports Human-in-the-Loop workflows using LangGraph's interrupt and resume capabilities.

For actions that require human approval, the workflow can pause before execution.

The user can then:

Review the proposed action
Approve the action
Reject the action
Modify the input before continuing

The workflow can then resume from the point where it was interrupted.

The general flow is:

LLM
 ↓
Proposed Action
 ↓
HITL Interrupt
 ↓
Human Review
 ├── Approve → Continue
 └── Reject  → Stop / Modify

This provides better control over potentially sensitive or important agent actions.

3. Retrieval-Augmented Generation (RAG)

AgentFlow allows users to upload PDF documents and ask questions about their contents.

The RAG pipeline is:

PDF
 ↓
PyPDFLoader
 ↓
Text Chunking
 ↓
Hugging Face Embeddings
 ↓
FAISS
 ↓
Similarity Search
 ↓
Relevant Context
 ↓
Hugging Face LLM
 ↓
Final Answer

RAG Process

The user uploads a PDF.
PyPDFLoader extracts the document text.
RecursiveCharacterTextSplitter divides the text into smaller chunks.
Each chunk is converted into an embedding using a Hugging Face sentence-transformer model.
The embeddings are stored in a FAISS vector index.
When the user asks a question, the query is converted into an embedding.
FAISS performs similarity search.
The most relevant chunks are retrieved.
The retrieved context is provided to the LLM.
The LLM generates a grounded response.

Example embedding model:

sentence-transformers/all-MiniLM-L6-v2

4. Per-Thread Document Retrieval

Each conversation thread can maintain its own document retriever.

For example:

Thread A
 └── research_paper.pdf
      └── FAISS Retriever

Thread B
 └── company_report.pdf
      └── FAISS Retriever

This helps prevent documents uploaded in one conversation from being used unintentionally in another conversation.

Each thread is identified using a unique thread_id.

5. Dynamic Tool Calling

AgentFlow supports multiple tools that the LLM can select dynamically based on the user's request.

Example tools include:

Calculator
DuckDuckGo web search
Stock price retrieval
PDF RAG retrieval
Custom MCP tools

Instead of manually implementing routing logic such as:

if user_wants_calculation:
    call_calculator()

elif user_wants_stock:
    call_stock_api()

elif user_wants_document:
    call_rag()

the LLM receives the available tool definitions and determines when a tool is required.

LangGraph then routes the tool call to the appropriate execution node.

For example:

User
 ↓
"What is 125 × 42?"
 ↓
LLM
 ↓
Calculator Tool
 ↓
5250
 ↓
LLM
 ↓
Final Answer

6. Model Context Protocol (MCP)

AgentFlow integrates Model Context Protocol (MCP) to provide a standardized interface for connecting the agent with external tools.

The project contains both an MCP client and a custom MCP server.

The general architecture is:

LangGraph Agent
       ↓
   MCP Client
       ↓
   MCP Server
       ↓
   Custom / External Tools

The MCP client can discover available tools exposed by an MCP server and make them available to the agent.

This makes the architecture easier to extend because additional tools can be added through MCP without tightly coupling their implementation to the core agent.

7. Open-Source Hugging Face LLM

AgentFlow uses an open-source instruction-tuned LLM from Hugging Face.

The model is not executed locally.

Instead, the application accesses the model through the Hugging Face Inference API using a Hugging Face API token.

Example model:

meta-llama/Llama-3.1-8B-Instruct

Other compatible open-source instruction-tuned models can also be used depending on Hugging Face provider availability and tool-calling support.

The architecture is:

User
 ↓
Streamlit
 ↓
LangGraph
 ↓
LangChain Hugging Face Integration
 ↓
Hugging Face Inference API
 ↓
Open-Source LLM
 ↓
Response

This allows the project to use an open-source LLM without requiring the model weights to be downloaded and executed on the local machine.

8. Hugging Face Embeddings

For document retrieval, AgentFlow uses an open-source sentence-transformer model from Hugging Face.

Example:

sentence-transformers/all-MiniLM-L6-v2

The embedding model converts text into numerical vectors.

For example:

"Machine learning is a subset of AI"
                ↓
        Embedding Model
                ↓
     [0.12, -0.31, 0.82, ...]

These vectors are stored and searched using FAISS.

Note: The LLM is accessed remotely through the Hugging Face Inference API. The embedding model is used within the application environment for document vectorization.

9. Persistent Conversation State

AgentFlow uses SQLite checkpointing through LangGraph's SqliteSaver.

Each conversation is associated with a unique thread_id.

The state flow is:

User
 ↓
thread_id
 ↓
LangGraph
 ↓
Agent State
 ↓
SqliteSaver
 ↓
SQLite Database

This allows conversations to be:

Paused
Resumed
Revisited
Continued across sessions

The SQLite database stores LangGraph checkpoints so that previous conversation state can be restored.

The database file is:

chatbot.db

10. LangSmith Observability

AgentFlow integrates LangSmith for tracing and observability.

LangSmith can be used to inspect:

LLM calls
Tool calls
LangGraph execution
Execution latency
Errors
Agent traces
Retrieval behavior
Intermediate execution steps

A typical execution can be visualized as:

User Request
     ↓
LangGraph
     ↓
LLM Call
     ↓
Tool Call
     ↓
Tool Result
     ↓
LLM Call
     ↓
Final Response

This helps identify problems such as:

Incorrect tool selection
Poor retrieval
Unexpected model responses
Tool failures
Excessive LLM calls
Slow execution

LangSmith can also be used to evaluate and improve agent behavior over time.

🏗️ Architecture

                         ┌─────────────────────┐
                         │  Streamlit Frontend │
                         │                     │
                         │  Chat UI            │
                         │  PDF Upload         │
                         │  Thread Management  │
                         │  HITL Interaction   │
                         └──────────┬──────────┘
                                    │
                                    ▼
                         ┌─────────────────────┐
                         │   LangGraph Agent   │
                         │                     │
                         │   StateGraph        │
                         │   Chat Node         │
                         │   Tool Node         │
                         │   Conditional       │
                         │   Routing            │
                         │   HITL               │
                         └──────────┬──────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                  │
                 ▼                  ▼                  ▼
          ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
          │     RAG     │    │    Tools    │    │     MCP     │
          │             │    │             │    │             │
          │ PDF         │    │ Calculator  │    │ MCP Client  │
          │ Embeddings  │    │ Web Search  │    │ MCP Server  │
          │ FAISS       │    │ Stock API   │    │ Custom Tools│
          └──────┬──────┘    └─────────────┘    └─────────────┘
                 │
                 ▼
          ┌─────────────┐
          │ Hugging Face│
          │ Embeddings  │
          └─────────────┘

                         │
                         ▼
               ┌─────────────────────┐
               │ Hugging Face        │
               │ Inference API       │
               │                     │
               │ Open-Source LLM     │
               └─────────────────────┘

                         │
                         ▼
               ┌─────────────────────┐
               │      SQLite         │
               │    Checkpointing    │
               └─────────────────────┘

                         │
                         ▼
               ┌─────────────────────┐
               │     LangSmith       │
               │ Tracing & Evaluation│
               └─────────────────────┘

🔄 LangGraph Execution Flow

The core LangGraph workflow is:

START
  │
  ▼
chat_node
  │
  ▼
tools_condition
  │
  ├────────────── No tool required ──────────────→ END
  │
  └────────────── Tool required
                         │
                         ▼
                       tools
                         │
                         ▼
                     chat_node
                         │
                         ▼
                  tools_condition
                         │
                    ...repeat...

`chat_node`

The LLM receives:

System instructions
Conversation history
Current user request
Available tool definitions

It determines whether it can answer directly or needs additional information from a tool.

`tools_condition`

LangGraph checks whether the LLM response contains a tool call.

If a tool call exists:

chat_node → tools

Otherwise:

chat_node → END

`tools`

The selected tool is executed and the result is added back to the graph state.

The LLM then receives the tool result and can decide whether another tool is required or whether it can generate the final answer.

🧠 RAG Example

Suppose the user uploads a research paper and asks:

"What methodology is used in this paper?"

The workflow is:

User
 ↓
Streamlit
 ↓
LangGraph
 ↓
Hugging Face LLM
 ↓
LLM selects RAG tool
 ↓
RAG Tool
 ↓
FAISS Similarity Search
 ↓
Top-K Relevant Chunks
 ↓
Context
 ↓
Hugging Face LLM
 ↓
Final Answer

This allows the LLM to generate an answer using information retrieved from the uploaded document instead of relying only on its pretrained knowledge.

🛠️ Available Tools

Tool	Purpose
Calculator	Performs basic arithmetic operations
DuckDuckGo Search	Searches the web for relevant information
Stock Price	Retrieves stock information through an external API
RAG Tool	Retrieves relevant information from uploaded PDFs
MCP Tools	Provides additional custom/external capabilities

📁 Project Structure

AgentFlow/
│
├── README.md
├── agent.py
├── app.py
├── chatbot.db
├── config.py
├── llm.py
├── mcp_client.py
├── mcp_server.py
├── rag.py
├── requirements.txt
├── state.py
└── tools.py

File Responsibilities

File	Responsibility
`app.py`	Streamlit frontend and user interaction
`agent.py`	LangGraph agent and workflow
`state.py`	Defines the agent state
`llm.py`	Hugging Face LLM configuration
`rag.py`	PDF processing, embeddings, FAISS indexing and retrieval
`tools.py`	Pre-built and custom agent tools
`mcp_client.py`	MCP client and dynamic MCP tool integration
`mcp_server.py`	Custom MCP server and tool definitions
`config.py`	Application configuration and environment variables
`requirements.txt`	Python dependencies
`chatbot.db`	SQLite checkpoint database generated at runtime
`README.md`	Project documentation

⚙️ Requirements

Python 3.10+
Hugging Face account
Hugging Face API token
LangSmith account/API key
API key for any external service used by the tools
Internet connection for Hugging Face Inference API and web/API tools

Important: You must provide your own API keys/tokens. The repository does not provide API credentials.

🔑 Environment Variables

Create a .env file in the project root.

Example:

HUGGINGFACEHUB_API_TOKEN=your_huggingface_token

LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your_langsmith_api_key
LANGCHAIN_PROJECT=AgentFlow

ALPHA_VANTAGE_API_KEY=your_alpha_vantage_api_key

Replace the placeholder values with your own credentials.

Hugging Face Token

Required for accessing the Hugging Face-hosted LLM through the Inference API.

HUGGINGFACEHUB_API_TOKEN=your_huggingface_token

LangSmith API Key

Required if you want to enable LangSmith tracing and observability.

LANGCHAIN_API_KEY=your_langsmith_api_key

External API Keys

Tools such as stock-price retrieval may require an external API key.

For example:

ALPHA_VANTAGE_API_KEY=your_alpha_vantage_api_key

📦 Installation

1. Clone the Repository

git clone https://github.com/Pheonix-1002/AgentFlow.git
cd AgentFlow

2. Create a Virtual Environment

Windows

python -m venv venv
venv\Scripts\activate

Linux / macOS

python3 -m venv venv
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure API Keys

Create a .env file:

HUGGINGFACEHUB_API_TOKEN=your_huggingface_token

LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your_langsmith_api_key
LANGCHAIN_PROJECT=AgentFlow

ALPHA_VANTAGE_API_KEY=your_alpha_vantage_api_key

Use your own keys for all services.

5. Run the Application

streamlit run app.py

Streamlit will provide a local URL, usually:

http://localhost:8501

💡 Usage

1. Chat Normally

Ask general questions through the Streamlit chat interface.

The agent determines whether it can answer directly or needs a tool.

2. Upload a PDF

Upload a PDF through the application.

The document goes through:

PDF
 ↓
Text Extraction
 ↓
Chunking
 ↓
Embeddings
 ↓
FAISS

You can then ask questions about the uploaded document.

3. Use Tools

Example:

Calculate 1234 * 567

The agent can select the calculator tool.

Another example:

Search the web for the latest developments in generative AI.

The agent can select the web-search tool.

For documents:

According to my uploaded PDF, what is the proposed methodology?

The agent can use the RAG tool.

4. Human Approval

For actions configured for HITL, the graph pauses and waits for human approval before continuing.

5. Resume Conversations

Previous conversation threads can be selected and resumed.

SQLite checkpointing restores the saved LangGraph state.

6. Monitor Agent Execution

With LangSmith enabled, you can inspect:

LLM Calls
Tool Calls
Graph Execution
Latency
Errors
Retrieval
Agent Traces

🔬 Example Multi-Step Workflow

A complex request may require multiple steps.

For example:

User
 ↓
"Find information about a company and calculate
its percentage change."
 ↓
LangGraph
 ↓
Hugging Face LLM
 ↓
Web / Stock Tool
 ↓
Tool Result
 ↓
Calculator
 ↓
Tool Result
 ↓
Hugging Face LLM
 ↓
Final Response

This demonstrates the iterative nature of the LangGraph agent.

The LLM can select a tool, receive its output, reason over the result, and request another tool if necessary.

🎯 Design Goals

AgentFlow is designed around several principles.

Modularity

Different capabilities such as RAG, search, calculation, and MCP tools are separated into reusable modules.

Stateful Execution

LangGraph maintains the state of the conversation and workflow.

Dynamic Tool Selection

The LLM determines when a tool is required instead of relying entirely on manually written routing logic.

Grounded Generation

RAG provides relevant document context to improve answers over user-provided knowledge sources.

Persistent State

SQLite checkpointing allows conversations to be resumed later.

Extensibility

MCP provides a standardized mechanism for connecting additional tools and services.

Human Control

HITL allows humans to review and approve selected actions.

Observability

LangSmith provides visibility into LLM calls, tools, graph execution and agent behavior.

🚀 Future Improvements

Potential improvements include:

Persistent FAISS indexes
Multiple document support per thread
Hybrid keyword + vector retrieval
Reranking retrieved chunks
Metadata filtering
Streaming LLM responses
Additional MCP servers
More advanced HITL workflows
Automated RAG evaluation
Retrieval quality metrics
Tool-call accuracy evaluation
Authentication and multi-user support
Production deployment
Better error handling and retry mechanisms
Conversation summarization for long-running threads

👨‍💻 Author

Pheonix-1002

Name		Name	Last commit message	Last commit date
README.md		README.md
agent.py		agent.py
app.py		app.py
chatbot.db		chatbot.db
config.py		config.py
llm.py		llm.py
mcp_client.py		mcp_client.py
mcp_server.py		mcp_server.py
rag.py		rag.py
requirements.txt		requirements.txt
state.py		state.py
tools.py		tools.py

Latest commit

History

Folders and files

Repository files navigation

AgentFlow

🚀 Features

1. Modular Stateful Agent

2. Human-in-the-Loop (HITL)

3. Retrieval-Augmented Generation (RAG)

RAG Process

4. Per-Thread Document Retrieval

5. Dynamic Tool Calling

6. Model Context Protocol (MCP)

7. Open-Source Hugging Face LLM

8. Hugging Face Embeddings

9. Persistent Conversation State

10. LangSmith Observability

🏗️ Architecture

🔄 LangGraph Execution Flow

chat_node

tools_condition

tools

🧠 RAG Example

🛠️ Available Tools

📁 Project Structure

File Responsibilities

⚙️ Requirements

🔑 Environment Variables

Hugging Face Token

LangSmith API Key

External API Keys

📦 Installation

1. Clone the Repository

2. Create a Virtual Environment

Windows

Linux / macOS

3. Install Dependencies

4. Configure API Keys

5. Run the Application

💡 Usage

1. Chat Normally

2. Upload a PDF

3. Use Tools

4. Human Approval

5. Resume Conversations

6. Monitor Agent Execution

🔬 Example Multi-Step Workflow

🎯 Design Goals

Modularity

Stateful Execution

Dynamic Tool Selection

Grounded Generation

Persistent State

Extensibility

Human Control

Observability

🚀 Future Improvements

👨‍💻 Author

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`chat_node`

`tools_condition`

`tools`