English · 简体中文

Nova

A minimal, readable, from-scratch AI agent framework.

Keywords: AI Agent · 智能体 · LLM · 大模型 · Tool Calling · Function Calling · RAG · Multi-Agent · 多智能体 · ReAct · 向量检索 · Memory · 记忆 · Planning · 规划 · Python · Qwen 通义千问 · DeepSeek · Ollama

Nova implements the core mechanisms behind modern AI agents — the reasoning loop, tool calling, memory, planning and multi-agent orchestration — directly on top of the OpenAI-compatible protocol, with no heavyweight framework dependencies. The entire core is a few hundred lines of plain Python, written so you can read and understand every part.

Why Nova?

• Learn the internals. Every mechanism — the ReAct loop, function calling, a vector store — is implemented in ~50–100 lines you can actually read.
• Provider-agnostic. Works with OpenAI, Aliyun Bailian (Qwen), DeepSeek, Moonshot and any other OpenAI-compatible endpoint.
• Zero magic. No LangChain, no CrewAI. Nova shows you what an agent framework does, not just how to call one.

Features

• LLM abstraction — a small provider interface plus an OpenAI-compatible adapter, a local Ollama adapter, and a deterministic mock for offline tests.
• Tool system — a @tool decorator that infers JSON Schema from type hints, plus a registry and builtin tools (calculator, file I/O, web search, ...).
• Memory — a sliding-window conversation buffer (short-term), a dependency-free vector store with feature-hashing embeddings (long-term RAG), and LLM-based summarization for long conversations.
• ReAct agent — the classic Reason + Act loop with tool calling and an iteration budget.
• Plan-and-execute — structured planning (via forced tool output) followed by step execution and synthesis.
• Multi-agent team — a supervisor that delegates to specialists using the same tool-calling mechanism.
• Streaming — token-level streaming and event-level agent traces.
• Async — arun / achat for concurrent, non-blocking agent runs.
• Structured output — JSON mode (response_format) for parsing model output.
• HTTP server — expose the agent over REST with FastAPI (nova.server).
• CLI, examples and tests — runnable demos and a hermetic test suite.

Installation

git clone https://github.com/escape9th/nova-agent.git
cd nova-agent
pip install -e ".[dev]"

Quick start

# 1. configure your provider (copy and edit)
cp .env.example .env

# 2. run a one-shot task
nova run "27 * 43 等于多少？"

# 3. or start an interactive session
nova chat

from nova.llm.openai_compat import OpenAICompatLLM
from nova.agents.react import ReActAgent
from nova.tools.registry import ToolRegistry
from nova.tools.builtin import calculator, get_datetime

agent = ReActAgent(
    llm=OpenAICompatLLM(),
    tools=ToolRegistry([calculator, get_datetime]),
)

result = agent.run("(12 + 3) * 5 是多少？")
print(result.answer)

Architecture

                    ┌─────────────────────────────┐
                    │          CLI / API          │
                    └──────────────┬──────────────┘
                                   │
   ┌───────────────────────────────┼───────────────────────────────┐
   │                               │                               │
┌──▼────────────┐       ┌──────────▼──────────┐       ┌────────────▼──┐
│  ReActAgent   │       │ PlanAndExecuteAgent │       │     Team      │
│  reason+act   │       │   plan + execute    │       │  supervisor   │
└──┬────────────┘       └──────────┬──────────┘       └────────────┬──┘
   │           agents              │                              │
   └───────────────────────────────┼──────────────────────────────┘
                                   │
       ┌───────────────────────────┼───────────────────────────┐
       │                           │                           │
  ┌────▼─────┐              ┌──────▼──────┐             ┌───────▼──────┐
  │  Tools   │              │   Memory    │             │      LLM     │
  │ registry │              │ buffer/vec  │             │ OpenAI-compat│
  └──────────┘              └─────────────┘             └──────────────┘

See docs/ARCHITECTURE.md for a component-by-component walkthrough.

Examples

Example	What it shows
examples/01_chat.py	Basic chat via the LLM layer
examples/02_tools.py	Registering and calling tools
examples/03_react.py	The ReAct tool-using loop
examples/04_memory.py	Vector store / RAG retrieval
examples/05_planner.py	Plan-and-execute
examples/06_team.py	Multi-agent supervision
examples/07_streaming.py	Token streaming
examples/08_ollama.py	Local model via Ollama

Running tests

pytest

The suite is fully hermetic — it drives a MockLLM with scripted responses, so it needs no API key and no network.

Security note

Builtin tools (file I/O, URL fetching) run with the caller's privileges. Nova keeps them intentionally plain so the trust boundary is visible; sandbox them before exposing an agent to untrusted input.

License

MIT