🌌 Nexus: Custom Agent Framework

A High-Performance Architectural Blueprint for Production-Grade Autonomous Agents

"Designed from first principles to solve the gap between chat scripts and autonomous system reasoning."

Nexus (Custom Agent Framework) is a modular, production-ready framework for building high-autonomy AI agents. It moves beyond simple prompt-wrapping to provide a robust Self-Correction (Reflective) ReAct loop, multi-layered persistent memory, and a type-safe state machine for deterministic agentic behavior.

🔬 Engineering Logic · 🏗️ Architecture · 🚀 Quick Start · 🧪 Lab & Roadmap

---

📌 The Engineering Problem

Most AI agent implementations suffer from three critical "Brittleness Factors":

1. Memory Drift: Agents lose context over long tasks or hallucinate their own state history.
2. Logic Lock: When an LLM makes a mistake, the agent continues down the wrong path indefinitely.
3. State Opacity: It's often impossible to reconstruct why an agent made a specific tool choice.

Nexus solves these by externalizing the agent's internal state into a Pydantic-guarded machine, implementing a persistent SQLite memory layer, and introducing a Reflector Node that critiques the agent's progress every N iterations.

---

🔬 Engineering Logic

🔄 The Reflective ReAct Cycle

Nexus implements an enhanced Reasoning + Acting (ReAct) loop. Unlike standard loops, Nexus includes:

• Dynamic Scratchpad: A strictly managed text area where the agent's internal monologue and tool observations are curated.
• Autonomous Reflector: A background node that critiques the current execution trace and suggests "Adaptive Replanning" if the agent stalls.
• Constraint Parsing: A regex-based structured parser that forces the LLM to adhere to the Thought → Action → Observation sequence.

🧠 Multi-Layered Memory Hierarchy

Memory in Nexus is not just a chat history; it's a tiered architecture:

• Short-Term (Conversation): Sliding-window token-aware buffer for active context.
• Long-Term (Fact Storage): Persistent SQLite-backed key-value store for cross-session knowledge.
• Episodic (Experience): Complete session "Experience Replays" stored as traces, allowing the agent to "recall" past multi-step successes.
• Vector (Semantic - Placeholder): Structural support for ChromaDB/Pinecone semantic retrieval integration.

🛡️ State Sovereignty & Checkpointing

The StateManager treats every task as a stateful session:

• Pydantic Guarding: The AgentState ensures all history and status transitions are type-safe.
• Atomic Checkpoints: Save the entire agent universe mid-task.
• Crash Recovery: Restore from checkpoint_id.

🔌 Ecosystem Interoperability

Nexus is designed to be a bridge, not an island. Built-in adapters allow for:

• LangChain Bridge: Bi-directional tool conversion. Use Nexus tools in LangChain graphs or vice-versa.
• LlamaIndex Data-Loop: Integrate RAG-capable document stores into the autonomous ReAct cycle.
• Provider Agnostic: Switch between OpenAI, DeepSeek, and Anthropic with 0 logic changes.

---

🏗️ System Architecture

Internal Orchestration Map

┌──────────────────────────────────────────────────────────────────┐
│                          Core Interface                          │
│        ┌───────────────┐        ┌───────────────┐                │
│        │ Agent (Entry) │        │ State Manager │                │
│        └───────┬───────┘        └───────┬───────┘                │
└────────────────┼────────────────────────┼────────────────────────┘
                 ▼                        │
┌─────────────────────────────────────────┼────────────────────────┐
│                    Agent Executor       ▼                        │
│  ┌──────────────┐    ┌─────────────┐    ┌──────────────┐         │
│  │   Planner    │───▶│   Loop      │◀──▶│  Persistence │         │
│  └──────────────┘    │ (ReAct)     │    └──────────────┘         │
│           ▲          └──────┬──────┘                             │
│           │                 │                                    │
│           │                 ▼                                    │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐        │
│  │   Parser     │◀───│   Reflector  │    │ Tool Manager │        │
│  └──────────────┘    └──────────────┘    └──────┬───────┘        │
└─────────────────────────────────────────────────┼────────────────┘
                                                  ▼
┌───────────────────────────┐         ┌────────────────────────────┐
│      Memory Manager       │         │       LLM Providers        │
│ ┌─────────┐   ┌─────────┐ │         │ ┌─────────┐    ┌─────────┐ │
│ │ Short   │   │ Long    │ │         │ │ OpenAI  │    │ Anthropic│ │
│ └─────────┘   └─────────┘ │         │ └─────────┘    └─────────┘ │
│ ┌─────────┐   ┌─────────┐ │         └────────────────────────────┘
│ │ Episodic│   │ Vector  │ │
│ └─────────┘   └─────────┘ │
└───────────────────────────┘

Module Breakdown

Namespace	Responsibility
core/executor	The heart of the machine. Manages the iteration limit and state transitions.
core/reflector	Intelligence guardian. Critiques the execution trace every 3-5 steps.
memory/episodic	Records "Experience Traces" — allows agents to learn from past trajectories.
state/persistence	Handles the physical serialization of state to SQLite or files.
tools/executor	Safe sub-process/function execution with 0-risk validation.
observability/logger	Structured JSON logging for integration with Datadog/ELK.

---

🚀 Quick Start

1. Installation

git clone https://github.com/Ismail-2001/Custom-Agent-Framework-Design.git
cd Custom-Agent-Framework-Design
pip install -r requirements.txt

2. Configure Environment

cp .env.example .env
# Open .env and add your keys:
# DEEPSEEK_API_KEY=sk-...
# OPENAI_API_KEY=sk-...

3. Initialize the Agent

import asyncio
from core.agent import Agent
from llm.openai_provider import OpenAIProvider
from memory.manager import MemoryManager

async def run_lab():
    # 1. Setup Intelligence
    llm = OpenAIProvider(model="gpt-4o")
    memory = MemoryManager()
    
    # 2. Instantiate Agent
    agent = Agent(llm=llm, memory=memory)
    
    # 3. Execute with Persistence
    result = await agent.run(
        "Generate a report on AI trends and save the checkpoint.",
        pattern="react",
        use_planning=True
    )
    
    # 4. Access Trace
    print(f"Final Outcome: {result['output']}")
    print(f"History Size: {len(result['state']['history'])}")

asyncio.run(run_lab())

---

🧪 The Lab & Roadmap

✅ Phase 1-7: Full Framework & Ecosystem Sync (Completed)

• State Machine Core: Deterministic status management (Pending → Running → Completed).
• Episodic Replay: SQLite storage of full task sequences.
• Self-Reflection Loop: Autonomous critique node that monitors execution quality.
• Adaptive Replanning: Logic to adjust strategy when progress stalls.
• LangChain/LlamaIndex Adapters: Native bi-directional tool & memory bridges.
• Tool Guardrail System: JSON Schema validation for all agent actions.
• Structured Trace Logger: Time-stamped, categorized event logging.

🔨 Phase 8: Scaling & Advanced Autonomy (Next)

• Multi-Agent Handover: Logic for one agent to delegate to another.
• OTEL Integration: Full OpenTelemetry support for cloud-native tracing.
• Distributed Memory: Redis-backed memory for cluster deployments.
• Human-in-the-loop (HITL): Tool calls that wait for human approval via state suspension.

---

🧪 Testing Protocol

Nexus includes a high-coverage test suite built for framework integrity:

# Run Core System Tests
pytest tests/test_core.py

# Run Memory Persistence Tests
pytest tests/test_memory.py

# Run State Recovery Integration Tests
pytest tests/test_state.py

---

Built for systems engineers. Perfected for AI autonomy.

If this framework helped you understand agent architecture, star ⭐ the repo.

Built with ❤️ by Ismail Sajid