Scratch Coding Classes for Kids in Zilina

Chapter 184 — Connect AI Agents and Tools in a Flask Application

1. Introduction & Why Integrate Agents with Flask?

In preceding modules, we explored individual language model pipelines, memory systems, and basic REST API serving using Flask. However, building interactive, production-ready AI systems requires empowering models to interact dynamically with external tools—such as mathematical solvers, third-party web APIs, or Wikipedia fact retrievers.

Connecting LangChain Intelligent Agents with a Flask Web Framework creates a real-time bridge for serving interactive, reasoning-capable AI applications over HTTP endpoints.

  ┌─────────────────────────────────────────────────────────────┐
  │         Flask + LangChain Agent System Architecture         │
  ├─────────────────────────────────────────────────────────────┤
  │  Client Request (AJAX POST / JSON Payload)                  │
  │     • Route: `POST /agent_action` (Port 5100)               │
  │     • Payload: `{"question": "What is 14 times 3?"}`         │
  │                             │                               │
  │                             ▼                               │
  │  Flask Server Endpoint (`/agent_action`)                    │
  │     • Receives input query & invokes Agent Executor          │
  │                             │                               │
  │                             ▼                               │
  │  ReAct AI Agent (Qwen2 Base LLM)                            │
  │     • Analyzes query & reasons dynamically                  │
  │     • Selects appropriate tool from available Toolkit       │
  │                             │                               │
  │           ┌─────────────────┴─────────────────┐             │
  │           ▼                                   ▼             │
  │  Tool 1: `multiplier`                Tool 2: `get_weather`  │
  │  (Multiplies two integers)          (Fetches live API info) │
  │           │                                   │             │
  │           └─────────────────┬─────────────────┘             │
  │                             ▼                               │
  │  Observation Return & Final Thought Reasoning               │
  │                             │                               │
  │                             ▼                               │
  │  Clean JSON API Response (`jsonify(...)` + Status 200)      │
  └─────────────────────────────────────────────────────────────┘
    

Core Advantages of Agent-Driven Flask Applications:

• Dynamic Action Execution: Agents do not rely solely on static pre-trained weights; they use LLMs to perform actions and execute dynamic reasoning.
• Intelligent Tool Selection: Given a query, the agent evaluates its toolkit and selects the correct tool (e.g., choosing a calculator tool for math vs. a weather tool for climate queries).
• Extensible Infrastructure: Serving agents via Flask provides a real-time bridge that can be extended to web interfaces, voice systems, or Slack integrations.

2. The ReAct Agent Framework & Reasoning-Action Loop

To make autonomous decisions, the agent uses the ReAct (Reasoning + Acting) framework. The ReAct prompt structure instructs the model to iterate through an explicit reasoning loop before returning its final answer.

  ┌─────────────────────────────────────────────────────────────┐
  │                 The ReAct Reasoning-Action Loop             │
  ├─────────────────────────────────────────────────────────────┤
  │                                                             │
  │   User Question Input                                       │
  │        │                                                    │
  │        ▼                                                    │
  │   1. THOUGHT         ──► "I should think about what to do"  │
  │        │                                                    │
  │        ▼                                                    │
  │   2. ACTION          ──► Selects tool from tool list        │
  │        │                                                    │
  │        ▼                                                    │
  │   3. ACTION INPUT    ──► Passes arguments to selected tool  │
  │        │                                                    │
  │        ▼                                                    │
  │   4. OBSERVATION     ──► Captures execution result from tool│
  │        │                                                    │
  │        └───────► (Repeats Loop N Times Until Satisfied) ────┤
  │                                                             │
  │        ▼                                                    │
  │   5. FINAL THOUGHT   ──► "I now know the final answer"      │
  │        │                                                    │
  │        ▼                                                    │
  │   6. FINAL OUTPUT    ──► Returns final response to user     │
  │                                                             │
  └─────────────────────────────────────────────────────────────┘
    

Stage-by-Stage Breakdown:

1. Question: The user query received by the Flask endpoint.
2. Thought: The agent's internal reasoning process evaluating how to address the request.
3. Action: The specific tool name selected by the agent from its available toolkit.
4. Action Input: The input arguments extracted from the prompt and passed to the tool.
5. Observation: The execution output returned by the tool back to the agent.
6. Iteration: This loop (Thought → Action → Action Input → Observation) repeats N times until the agent is confident.
7. Final Thought & Output: The agent declares "I now know the final answer" and outputs the final result to the user.

3. Building Custom Tools (multiplier & get_weather)

The agent's capabilities depend on the tools provided in its toolkit. In this implementation, two custom tools are created using LangChain's @tool decorator:

  ┌─────────────────────────────────────────────────────────────┐
  │                    Agent Toolkit Definition                 │
  ├───────────────────────────────┬─────────────────────────────┤
  │ Tool 1: `multiplier`          │ Tool 2: `get_weather`       │
  ├───────────────────────────────┼─────────────────────────────┤
  │ • Takes two integers: `A, B`. │ • Accepts city name string. │
  │ • Performs math: `a * b`.     │ • Hits live weather URL.    │
  │ • Returns cast string `str()`.│ • Uses `format=3` summary.  │
  │ • Solves arithmetic queries.  │ • Checks HTTP Status 200.   │
  └───────────────────────────────┴─────────────────────────────┘
    

Tool 1: Arithmetic Multiplier Tool (multiplier):

• Functionality: Takes two integer arguments (a and b), calculates their product (a * b), and returns the result cast as a string (str(a * b)) for text processing.

Tool 2: Live Weather API Tool (get_weather):

• Functionality: Accepts a city name parameter (e.g., "Lahore"), constructs a web API URL using format=3 for a concise weather summary, verifies an HTTP 200 OK response status code, and returns current weather conditions.

4. Agent Creation (create_react_agent) & Flask Endpoint (/agent_action)

The underlying language model uses the open-source Qwen model running locally via HuggingFace pipelines and tokenizers. The agent executor is compiled using create_react_agent and wrapped inside a Flask web application.

# =====================================================================
# LangChain ReAct Agent with Flask Web Service (Topic 184)
# =====================================================================

import os
import requests
import threading
import time
from flask import Flask, request, jsonify
from flask_cors import CORS

from langchain_core.tools import tool
from langchain.agents import create_react_agent, AgentExecutor
from langchain_core.prompts import PromptTemplate
from langchain_community.llms import HuggingFacePipeline
from transformers import AutoTokenizer, AutoModelForCausalLM, pipeline

# 1. Instantiate Open-Source Base LLM (Qwen Model)
model_id = "Qwen/Qwen2-0.5B-Instruct"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id)

hf_pipe = pipeline("text-generation", model=model, tokenizer=tokenizer, max_new_tokens=256)
llm = HuggingFacePipeline(pipeline=hf_pipe)

# 2. Define Tool 1: Multiplier Tool
@tool
def multiplier(a: int, b: int) -> str:
    """Multiplies two integers a and b together and returns the product as a string."""
    return str(a * b)

# 3. Define Tool 2: Weather API Tool
@tool
def get_weather(city: str) -> str:
    """Fetches live weather summary for a specified city name."""
    url = f"https://wttr.in/{city}?format=3"
    response = requests.get(url, timeout=10)
    if response.status_code == 200:
        return response.text.strip()
    else:
        return "Error: Unable to fetch weather data."

# Toolkit Array
tools = [multiplier, get_weather]

# 4. Construct ReAct Prompt Template
react_template = """Answer the following questions as best as you can. You have access to the following tools:

{tools}

Use the following format:

Question: the input question you must answer
Thought: you should always think about what to do
Action: the action to take, should be one of [{tool_names}]
Action Input: the input to the action
Observation: the result of the action
... (this Thought/Action/Action Input/Observation can repeat N times)
Thought: I now know the final answer
Final Answer: the final answer to the original input question

Begin!

Question: {input}
Thought:{agent_scratchpad}"""

prompt = PromptTemplate.from_template(react_template)

# 5. Create ReAct Agent and Agent Executor
agent = create_react_agent(llm=llm, tools=tools, prompt=prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True, handle_parsing_errors=True)
print("Agent is ready!")

# 6. Initialize Flask Web Server Layer
app = Flask(__name__)
CORS(app)

@app.route('/agent_action', methods=['POST'])
def agent_action():
    """POST endpoint receiving user queries and executing Agent actions."""
    try:
        data = request.json
        user_query = data.get("question", "")

        # Invoke Agent Executor
        result = agent_executor.invoke({"input": user_query})

        return jsonify({
            "status": "success",
            "question": user_query,
            "output": result.get("output", "")
        }), 200

    except Exception as e:
        return jsonify({
            "status": "error",
            "message": str(e)
        }), 500

# 7. Run Flask Application in Background Daemon Thread on Port 5100
def run_flask():
    app.run(host="0.0.0.0", port=5100, use_reloader=False)

server_thread = threading.Thread(target=run_flask, daemon=True)
server_thread.start()
time.sleep(3)
print("Flask Agent Application is active on port 5100.")
    

5. Testing & Execution Trace (Math vs. Weather Queries)

To verify that the agent selects tools dynamically, we test two distinct queries against the /agent_action endpoint on port 5100.

  ┌─────────────────────────────────────────────────────────────┐
  │                 Dynamic Tool Selection Traces               │
  ├───────────────────────────────┬─────────────────────────────┤
  │ Math Query Trace              │ Weather Query Trace         │
  ├───────────────────────────────┼─────────────────────────────┤
  │ Query: "What is 14 times 3?"  │ Query: "Weather of Lahore?" │
  │ Thought: Needs calculation.   │ Thought: Needs climate data.│
  │ Action: `multiplier`          │ Action: `get_weather`       │
  │ Action Input: `14, 3`         │ Action Input: `Lahore`      │
  │ Observation: `42`             │ Observation: `Sunny 32-40°C`│
  │ Final Answer: `42`            │ Final Answer: `Sunny 32-40°`│
  └───────────────────────────────┴─────────────────────────────┘
    

Execution Test 1: Mathematical Calculation

• Input Question: "What is 14 times 3?"
• Agent Reasoning Trace:
  1. Thought: Recognizes that this is a mathematical problem.
  2. Action: Dynamically selects the multiplier tool.
  3. Action Input: 14, 3.
  4. Observation: 42 (correct calculation).
  5. Final Answer: 42.

Execution Test 2: Live Weather Information

• Input Question: "What is the weather of Lahore?"
• Agent Reasoning Trace:
  1. Thought: Recognizes a request for live location weather.
  2. Action: Dynamically selects the get_weather tool.
  3. Action Input: "Lahore".
  4. Observation: "The current weather in Lahore is sunny with temperature ranging from 32 to 40°C".
  5. Final Answer: "The current weather in Lahore is sunny with temperature ranging from 32 to 40°C".

6. Summary Comparison Matrix

Aspect / Component	Technical Role	Implementation Parameter	Practical Benefit
Base LLM	Open-source language model.	Qwen2 0.5B Instruct.	Free, self-hosted reasoning engine.
Tool 1 (multiplier)	Arithmetic multiplication.	Takes integer inputs A, B.	Solves math queries precisely.
Tool 2 (get_weather)	Live weather API scraper.	URL call with format=3.	Pulls up-to-date climate data.
Agent Framework	ReAct reasoning loop.	create_react_agent.	Enables step-by-step thinking.
Agent Executor	Manages action loop.	AgentExecutor.	Handles tool execution & parsing.
Flask Route	RESTful web endpoint.	POST /agent_action (Port 5100).	Exposes agent service over HTTP.