NOOA - The New-Generation Python Framework for Building LLM Agents

By the Frontier staff, HowiPrompt

> TL;DR - NOOA (pronounced "no-ah") is an open-source Python library that lets developers assemble large-language-model (LLM) agents entirely in native Python, without the heavyweight orchestration layers many other frameworks require. It embraces the Model Context Protocol (MCP) to hook agents up to tools, data stores, and external services, and it ships with a small but growing ecosystem of ready-made components. If you want to prototype a reasoning-rich chatbot, a data-driven automation script, or a research-assistant that can call APIs on-the-fly, NOOA may be the most lightweight entry point yet.

---

1. What it is & why it matters

1.1 The problem NOOA solves

LLM agents have exploded in popularity because they can reason, plan, and act beyond a simple prompt-completion cycle. However, most production-grade frameworks (e.g., LangChain, LlamaIndex, CrewAI) introduce a stack of abstractions, configuration files, and external services that can be a barrier for:

• Python-first developers who want to stay inside a single language/runtime.
• Researchers and hobbyists who need a fast, reproducible prototype without spinning up a separate orchestration server.
• Teams bound by security policies that disallow outbound network calls during code generation (e.g., in air-gapped environments).

NOOA addresses these pain points by:

1.2 Why it's hot right now

• MCP adoption - The Model Context Protocol has become the de-facto standard for describing tool-to-LLM contracts. NOOA ships with native MCP adapters, meaning you can plug in any MCP-compliant service (e.g., a vector store, a spreadsheet API) without writing boilerplate.
• Zero-runtime overhead - The library runs entirely on the client device; there's no hidden cloud component that could leak data. This aligns with the growing demand for on-premise AI solutions.
• Community momentum - Since the "NOOA: Building LLM Agents in Native Python" video went viral (see the YouTube links below), the repository has seen a steady influx of pull requests, third-party tool adapters, and community-run tutorials.
• Open-source transparency - The codebase is hosted on GitHub under an MIT license, making it easy for security teams to audit.

If you're already using Xray-core panels like 3x-ui for proxy management (see the official docs), you'll appreciate NOOA's similarly "no-frills, all-Python" philosophy: focus on the core problem, not on a sprawling UI.

---

2. What's new / key features (detailed breakdown)

> Note: The feature list reflects the current stable release (as of the latest official tag). For the most up-to-date list, always double-check the repository's CHANGELOG.md or the official documentation site.

---

3. Installation -- every OS

NOOA is pure Python and therefore works on any platform that supports Python 3.9+. Below are step-by-step instructions for the three major OS families. The commands assume you have administrative (or sudo) rights where required.

3.1 Windows

1. Install Python (if not already present)

   # Download the latest installer from https://www.python.org/downloads/windows/
   # During install, tick "Add Python to PATH"

1. Upgrade pip

   python -m pip install --upgrade pip

1. Create a virtual environment (recommended)

   python -m venv nooa-env
   .\nooa-env\Scripts\Activate.ps1   # PowerShell
   # or
   .\nooa-env\Scripts\activate.bat   # Command Prompt

1. Install NOOA

   pip install nooa

1. Optional: Install extra toolkits (e.g., faiss-cpu for vector search)

   pip install faiss-cpu

3.2 macOS

1. Install Homebrew (if you don't have it)

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

1. Install Python 3 (Homebrew version is fine)

   brew install python@3.11   # or latest stable

1. Create a virtual environment

   python3 -m venv nooa-env
   source nooa-env/bin/activate

1. Install NOOA

   pip install --upgrade pip
   pip install nooa

1. Optional vector store

   pip install faiss-cpu   # works on Intel Macs
   # For Apple Silicon, you may need:
   pip install faiss-gpu   # or use chromadb which ships wheels for M1/M2

3.3 Linux (Ubuntu/Debian-based)

1. System dependencies (only needed for optional C extensions)

   sudo apt-get update
   sudo apt-get install -y python3-pip python3-venv build-essential libssl-dev

1. Create a virtual environment

   python3 -m venv nooa-env
   source nooa-env/bin/activate

1. Upgrade pip & install NOOA

   pip install --upgrade pip
   pip install nooa

1. Optional: Install GPU-accelerated FAISS (if you have CUDA)

   pip install faiss-gpu

> Tip: If you encounter "permission denied" errors on any platform, prepend the pip install command with --user (or use a virtual environment as shown above).

---

4. First run / quick start (a few clicks)

Below is the minimum code you need to spin up a functional NOOA agent that can answer natural-language questions using OpenAI's gpt-4o-mini. The steps assume you have an OpenAI API key stored in the environment variable OPENAI_API_KEY.

# quick_start.py
import os
from nooa import Agent, OpenAIChatTool, MemorySQLite

# 1️⃣ Define the LLM tool (MCP-compatible)
chat = OpenAIChatTool(
    model="gpt-4o-mini",
    api_key=os.getenv("OPENAI_API_KEY"),
    temperature=0.2,
)

# 2️⃣ Set up a persistent memory store (optional but recommended)
memory = MemorySQLite(db_path="agent_memory.db")

# 3️⃣ Build the agent - we give it the chat tool and memory
assistant = Agent(
    name="QuickBot",
    tools=[chat],
    memory=memory,
    description="Answers factual questions using the OpenAI API.",
)

# 4️⃣ Run a single query (the Agent's `run` method returns a string)
if __name__ == "__main__":
    user_query = "What is the capital of Mongolia?"
    answer = assistant.run(user_query)
    print(f"🧠 Answer: {answer}")

Running it

python quick_start.py

You should see something like:

🧠 Answer: Ulaanbaatar

That's it - no YAML, no external config files, and no Docker containers. The whole pipeline (LLM -> memory -> response) lives in a single Python script.

---

5. Examples (several varied, concrete, with snippets)

Below are three realistic use-cases that showcase NOOA's flexibility. Each example includes a short code excerpt and a brief explanation of the MCP flow.

5.1 A Weather-Bot that calls a public API

# weather_bot.py
import os
import requests
from nooa import Agent, OpenAIChatTool, HttpTool, MemoryInMemory

# 1️⃣ HTTP GET tool (MCP-compatible)
class WeatherAPI(HttpTool):
    def __init__(self):
        super().__init__(base_url="https://api.open-meteo.com/v1/forecast")

    def get_weather(self, lat: float, lon: float, days: int = 1):
        params = {
            "latitude": lat,
            "longitude": lon,
            "daily": "temperature_2m_max,temperature_2m_min",
            "timezone": "auto",
        }
        return self.get("/", params=params)

# 2️⃣ LLM tool
chat = OpenAIChatTool(
    model="gpt-4o-mini",
    api_key=os.getenv("OPENAI_API_KEY"),
    temperature=0.0,
)

# 3️⃣ Agent composition
weather_tool = WeatherAPI()
assistant = Agent(
    name="WeatherBot",
    tools=[chat, weather_tool],
    memory=MemoryInMemory(),
    description="Provides short weather forecasts for any city.",
)

# 4️⃣ Prompt engineering (via a system message)
assistant.system_prompt = """
You are a helpful assistant. When a user asks for the weather in a city,
first resolve the city name to latitude/longitude using any public service,
then call the `WeatherAPI.get_weather` tool with those coordinates.
Return a concise, human-readable forecast.
"""

if __name__ == "__main__":
    print(assistant.run("Will it rain in Seattle tomorrow?"))

What happens under the MCP hood?

1. The user query is sent to the OpenAIChatTool.
2. The LLM decides to invoke WeatherAPI.get_weather (MCP tool_call).
3. NOOA routes the call to the WeatherAPI Python class, which performs a real HTTP request.
4. The result is fed back to the LLM, which synthesizes the final answer.

5.2 A Document-Summarizer with vector retrieval

# doc_summarizer.py
import os
from nooa import Agent, OpenAIChatTool, MemoryFAISS, VectorRetriever

# 1️⃣ Load documents (pretend we have a list of strings)
docs = [
    "The quick brown fox jumps over the lazy dog.",
    "Artificial intelligence is transforming many industries...",
    # ... many more
]

# 2️⃣ Build a FAISS index (MCP-compatible memory)
vector_mem = MemoryFAISS(dim=1536)   # 1536 = dimension of OpenAI embeddings
for i, txt in enumerate(docs):
    vector_mem.add_document(id=str(i), text=txt)

retriever = VectorRetriever(memory=vector_mem)

# 3️⃣ LLM tool (same as before)
chat = OpenAIChatTool(
    model="gpt-4o-mini",
    api_key=os.getenv("OPENAI_API_KEY"),
    temperature=0.1,
)

# 4️⃣ Agent that first retrieves relevant chunks, then asks the LLM to summarize
summarizer = Agent(
    name="Summarizer",
    tools=[chat, retriever],
    memory=None,   # we rely on the vector store only
    description="Summarizes a set of documents relevant to a user query.",
)

summarizer.system_prompt = """
You receive a user question. Use the `retriever.search(query, k=3)` tool
to fetch the three most relevant document snippets. Then, using those snippets,
produce a concise 2-sentence summary that directly answers the question.
"""

if __name__ == "__main__":
    print(summarizer.run("What are the main challenges of AI adoption?"))

Key take-aways

• The vector store (MemoryFAISS) implements the MCP Memory contract, exposing add_document and search.
• The VectorRetriever is a thin MCP tool that calls memory.search.
• The LLM never sees the full corpus--only the top-k snippets, keeping token usage low.

5.3 A "Planner + Executor" pair for file-system automation

# file_automation.py
import os
from nooa import Agent, OpenAIChatTool, Tool, MemoryInMemory

# 1️⃣ Simple file-system tool
class FileOps(Tool):
    name = "FileOps"
    description = "Read, write, list, or delete files on the local machine."

    def list_dir(self, path: str = "."):
        return os.listdir(path)

    def read_file(self, path: str):
        with open(path, "r", encoding="utf-8") as f:
            return f.read()

    def write_file(self, path: str, content: str):
        with open(path, "w", encoding="utf-8") as f:
            f.write(content)
        return f"Written {len(content)} bytes to {path}"

# 2️⃣ LLM tool
chat = OpenAIChatTool(
    model="gpt-4o-mini",
    api_key=os.getenv("OPENAI_API_KEY"),
    temperature=0.0,
)

# 3️⃣ Planner agent (decides what to do)
planner = Agent(
    name="Planner",
    tools=[chat],
    memory=MemoryInMemory(),
    description="Creates a step-by-step plan for a user request.",
)
planner.system_prompt = """
You are a planner. When given a high-level goal, output a short numbered list
of actions that can be performed using the `FileOps` tool. Do not execute anything.
"""

# 4️⃣ Executor agent (actually runs the plan)
executor = Agent(
    name="Executor",
    tools=[chat, FileOps()],
    memory=None,
    description="Executes a list of FileOps actions generated by the Planner.",
)
executor.system_prompt = """
You receive a list of numbered actions that use the FileOps tool.
Execute them in order and return a short report of what happened.
"""

# 5️⃣ Orchestrator - glue them together
def orchestrate(goal: str):
    plan = planner.run(goal)
    print("🗒️ Plan:\n", plan)
    # Extract numbered steps (naïve split)
    steps = [line.strip() for line in plan.splitlines() if line.strip().startswith(str(len(plan)))]
    # Feed the whole plan to the executor (the LLM will parse the steps)
    result = executor.run(plan)
    return result

if __name__ == "__main__":
    print(orchestrate("Create a folder called 'reports', write a README inside, and list its contents."))

What you see here

• Two agents (Planner and Executor) communicate via plain text, but under the hood each call obeys the MCP tool_call contract.
• The FileOps tool is sandboxable - you can attach a safety guard that rejects paths outside a whitelist, demonstrating NOOA's built-in safety hooks.

---

6. Benefits & best use-cases

Best-fit use-cases

1. Research assistants - Pull papers from arXiv, embed them, and answer questions.
2. Internal automation bots - File handling, ticket triage, or inventory checks.
3. Education tools - Interactive tutoring agents that can call a math-solver tool.
4. Rapid PoC for LLM-augmented products - Build a demo in a single Jupyter notebook.

---

7. Alternatives & how it compares

Key differentiators for NOOA

• MCP as a first-class contract - while LangChain can talk to MCP services, NOOA treats MCP as the core API, eliminating translation layers.
• Zero-dependency UI - NOOA has no built-in web UI; you stay in code. This is a pro for developers who dislike "admin panels" (think 3x-ui).
• Modular memory back-ends - you can switch from SQLite to Redis with a single import line.

If you need a full-stack UI, a graphical workflow editor, or deep integrations with LangChain's extensive tool ecosystem, LangChain may still be the better fit. For pure-Python, low-overhead agents that need to be MCP-ready, NOOA shines.

---

8. Tips, performance & troubleshooting (FAQ)

Performance tuning nuggets

1. Batch embeddings - When populating a vector store, batch calls to the embedding model (most providers support up to 2048 tokens per request).
2. Cache LLM responses - For static knowledge (e.g., FAQs), store the output in memory and reuse it.
3. Limit k in vector retrieval - Smaller k reduces token usage without sacrificing relevance if your index is well-curated.
4. Use async tools - NOOA's Tool base class can be subclassed with async def methods; the agent will automatically await them, allowing concurrent API calls.

---

9. What the community says

• "The simplicity is refreshing." - A senior data-engineer on the NOOA Discord server notes that "I built a complete ticket-triage bot in under an hour, no YAML, no extra services."
• "MCP makes integration painless." - A security analyst on Reddit highlights that "