Agent Framework + DevTools

A lightweight framework for building AI agents where every decision is visible, debuggeable, and reproducible. The Chrome DevTools, but for AI agents.

Task: "Research quantum computing and write a report"

[think]      I need to search the web for recent information
[tool_call]  web_search("quantum computing 2026 advances")
[tool_result] - IBM announces 1000+ qubit processor...
[think]      Found relevant results. Let me read the top article.
[tool_call]  http_request("https://...")
[tool_result] Article content...
[think]      I have enough information. Generating report.
[answer]     # Quantum Computing Report...

Every step is traced, persisted in SQLite, and inspectable via the Trace Explorer UI.

Quick Start

1. Install

git clone https://github.com/OriginalKazdov/agent-framework.git
cd agent-framework
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # Add your ANTHROPIC_API_KEY

2. Run an agent

import src.tools.builtin
from src.agents.core import Agent

agent = Agent()
result = agent.run("What is sqrt(144) + 2^8? Use the calculator.")
print(result.answer)  # "268"

for step in result.steps:
    print(f"[{step.step_type.value}] {step.content}")

3. Create your own tool

from src.tools.registry import tool

@tool(name="greet", description="Greet someone by name")
def greet(name: str) -> str:
    return f"Hello, {name}!"

# The agent can now use this tool automatically

Architecture

User Task
    |
    v
+------------------+
| Query Analyzer   |  "Is this simple or complex?"
+--------+---------+
         |
    +----+----+
    |         |
    v         v
+-------+ +----------+
| Agent | | Planning  |    Direct: think -> act -> observe (ReAct)
| (ReAct| | Agent     |    Planning: plan -> execute each step
+---+---+ +----+-----+
    |          |
    +----+-----+
         |
         v
+------------------+
| Tool Registry    |  @tool decorator, auto JSON Schema
+------------------+
| calculator       |
| web_search       |
| read_file        |
| http_request     |
| save_memory      |
| recall_memory    |
| ... your tools   |
+--------+---------+
         |
         v
+------------------+
| Trace Store      |  SQLite - every step persisted
+------------------+
         |
         v
+------------------+
| Trace Explorer   |  Web UI - inspect every decision
+------------------+

Two Agent Modes

Direct (ReAct)

Think -> Act -> Observe loop. Best for simple tasks.

agent = Agent()
result = agent.run("What's 25 * 47?")

Planning

Plan first, then execute each step. Best for complex tasks.

agent = PlanningAgent()
result = agent.run("Research topic X and write a report")
# Agent creates plan -> executes step by step -> summarizes

Built-in Tools

Tool	Description
calculator	Safe math evaluation (sqrt, log, trig, etc.)
web_search	Search the web via DuckDuckGo
read_file	Read local files
write_file	Write files
list_files	List directory contents
http_request	Make HTTP requests (GET/POST)
save_memory	Persist a fact for later
recall_memory	Retrieve a saved fact
search_memory	Search through saved facts
list_memories	List all saved facts

Trace Explorer

Start the API and web UI:

# Backend
uvicorn src.api:app --port 8000 --reload

# Frontend
cd frontend && npm install && npm run dev

• Run Agent tab: Execute agents and see traces in real-time
• Trace Explorer tab: Browse past runs, inspect every step

API Endpoints

Method	Endpoint	Description
POST	/run	Run an agent (direct or planning mode)
GET	/traces	List past traces
GET	/traces/{id}	Full trace detail
GET	/traces/{id}/export	Export trace as JSON
DELETE	/traces/{id}	Delete a trace
POST	/memory	Save a fact
GET	/memory	List saved facts
GET	/memory/search?q=	Search memory
GET	/health	Health check

Examples

# Research agent
python examples/research_agent.py "AI agents in 2026"

# Code explainer
python examples/code_explainer.py ../adaptive-rag/src/rag.py

Project Structure

agent-framework/
├── src/
│   ├── api.py              # FastAPI endpoints
│   ├── config.py           # Settings
│   ├── models.py           # AgentStep, AgentResult, ToolDefinition
│   ├── agents/
│   │   ├── core.py         # Agent (ReAct loop)
│   │   └── planner.py      # PlanningAgent (plan-and-execute)
│   ├── tools/
│   │   ├── registry.py     # @tool decorator + ToolRegistry
│   │   ├── builtin.py      # Built-in tools (calc, search, files, http)
│   │   └── memory_tools.py # Memory tools (save, recall, search)
│   ├── trace/
│   │   └── store.py        # TraceStore (SQLite persistence)
│   └── memory/
│       └── store.py        # WorkingMemory + LongTermMemory
├── tests/                  # 69 tests, all run offline
├── frontend/               # Trace Explorer (React + Tailwind)
├── examples/               # Research agent, code explainer
├── docker-compose.yml      # Full stack deployment
├── SCOPE.md               # Project scope and phases
└── LEARNINGS.md           # Learning resources

Run Tests

pytest tests/ -v  # All 69 tests run offline, no API keys needed