https://github.com/lucalullo/building-an-ai-agent
Hands-on notebook that builds an AI agent from scratch in plain Python - no LLM, no frameworks. Manual tool routing, regex-based parsing, and state memory to make agent internals fully transparent.
https://github.com/lucalullo/building-an-ai-agent
agent agent-skills agentic-ai python rule-based-system tool tools
Last synced: about 13 hours ago
JSON representation
Hands-on notebook that builds an AI agent from scratch in plain Python - no LLM, no frameworks. Manual tool routing, regex-based parsing, and state memory to make agent internals fully transparent.
- Host: GitHub
- URL: https://github.com/lucalullo/building-an-ai-agent
- Owner: lucalullo
- License: mit
- Created: 2026-07-04T15:36:59.000Z (1 day ago)
- Default Branch: main
- Last Pushed: 2026-07-04T15:50:07.000Z (1 day ago)
- Last Synced: 2026-07-04T17:12:10.686Z (1 day ago)
- Topics: agent, agent-skills, agentic-ai, python, rule-based-system, tool, tools
- Language: Jupyter Notebook
- Homepage:
- Size: 13.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Building an AI Agent (From Scratch, No LLM, No Frameworks)
A hands-on notebook that builds an AI agent from the ground up using **plain Python only** — no external LLM, no framework. Every piece (tool selection, argument parsing, execution, memory) is written by hand, to make the internals of an agent fully transparent.
Each version introduces one new concept. This README documents **Version 1**.
📓 **Notebook on Kaggle**: [Building an AI Agent](https://www.kaggle.com/code/lucalullo/building-an-ai-agent)
---
## How it works
```mermaid
graph TD
START(["User Request"]) --> Router["Router: score tools by synonym match"]
Router --> Parser["Parser: extract name / numbers via regex"]
Parser --> Execute["Run matched tool"]
Execute --> Memory["Log state in memory"]
Memory --> Output(["Return: request, action, arguments, result"])
```
1. **Tools** — 6 functions: `greeting`, `addition`, `subtraction`, `multiplication`, `division`, `power`.
2. **Router** — scores each tool by counting matching keywords/synonyms in the request (e.g. "plus", "+" → addition), with a priority tie-breaker so math intent beats a greeting in phrases like *"Hello, what is 2+3?"*.
3. **Parser** — regex-based extraction of names and numbers from the request text.
4. **Agent** — ties it all together into a single state object (`request`, `action`, `arguments`, `result`) and logs every call in a `memory` list.
```python
def agent(request):
state = {"request": request, "action": None, "arguments": {}, "result": None}
action = choose_tool(request)
state["action"] = action
tool_info = tools.get(action)
if not tool_info:
state["result"] = "Tool not found!"
else:
state["arguments"] = parser(action, request)
if arguments_are_valid(state["arguments"]):
state["result"] = tool_info["function"](**state["arguments"])
else:
state["result"] = "Invalid arguments"
memory.append(state)
return state
```
---
## Test Cases
| Input | Verifies | Output |
|---|---|---|
| `"What is 2 + 3?"` | Basic routing + math execution | `addition, result: 5` |
| `"Hello, what is 2 + 3?"` | Router prioritizes intent over greeting | `addition, result: 5` |
| `"Hello, my name is luca."` | Output formatting (`luca` → `Luca`) | `greeting, "Hello Luca, nice to meet you!"` |
---
## Run it
No dependencies beyond the Python standard library (`re`).
```bash
jupyter notebook building-an-ai-agent.ipynb
```
Or just open it directly on [Kaggle](https://www.kaggle.com/code/lucalullo/building-an-ai-agent).
---
## What's Next
Version 1 of an evolving architecture — future versions will add more tools, smarter parsing, richer memory, and eventually LLM-based routing.
---
**Author:** [Luca Lullo](https://github.com/lucalullo)
*Data Scientist | Machine Learning Applied*