nano_agent_team_selfevolve

English (this page) | 中文文档

nano_agent_team_selfevolve is a secondary development branch based on nano_agent_team, focused on an unattended self-evolution workflow driven by a multi-agent team.

For full framework documentation (architecture, TUI/CLI details, tool system), refer to the upstream README.

---

Background

The self-evolution workflow enables the codebase to autonomously improve itself across rounds without human intervention. Each round runs a structured pipeline:

Phase 0 (Research) → Audit → Architect → Developer → Tester → Reviewer → Merge

A team of specialized agents collaborates on each round:

Agent	Role
Architect	Decides what to build based on research and audit findings
Developer	Implements the feature or integration
Tester	Writes and runs tests, checks quality gate
Auditor	Scans the codebase for dead code, gaps, and opportunities
Reviewer	Final code review and approval before merge

Supported LLM providers: Qwen, OpenAI, DeepSeek, Step, Moonshot, and any OpenAI-compatible endpoint.

---

This Run

Parameter	Value
Evolution rounds	5
Model	ltcraft/claude-opus-4-6
Run timestamp	20260311_225548
Session script	evolve_session.sh

evolve_session.sh orchestrates a complete automated session:

1. Clean — remove previous evolution artifacts
2. Evolve — run N rounds via evolve.sh
3. Record — capture screen recording via ffmpeg (macOS)
4. Debug — analyze results and test new features via Claude Code CLI
5. Document — write/update README.md and README_CN.md
6. Push — commit and push to GitHub

---

Evolution Results

All 5 rounds passed in this session.

Round	Timestamp	Type	Feature	Status
r1	2026-03-11 22:55	FEATURE	DataAnalysisTool	PASS
r2	2026-03-12 00:40	INTEGRATION	ArxivSearchTool wiring	PASS
r3	2026-03-12 01:44	FEATURE	CodeAnalysisTool	PASS
r4	2026-03-12 02:01	FEATURE	MarkdownExportTool	PASS
r5	2026-03-12 02:55	FEATURE	TokenUsageTracker	PASS

New capabilities added

r1 — DataAnalysisTool (backend/tools/data_analysis.py) Structured CSV/JSON data analysis with three operations: describe, query, and aggregate. Zero external dependencies (stdlib only). 38 unit tests, all passing.

r2 — ArxivSearchTool integration (backend/tools/arxiv_search.py) Wired an existing but unregistered tool into tool_registry.py, main.py, and agent_bridge.py. Refactored to inherit from BaseTool. 11 integration tests, all passing.

r3 — CodeAnalysisTool (backend/tools/code_analysis.py) AST-based Python code structure analysis using stdlib ast. Four operations: list_symbols, get_imports, get_structure, complexity_score. 15 unit tests, all passing.

r4 — MarkdownExportTool (backend/tools/markdown_export.py) Agent-callable tool to write structured markdown files with configurable headers and sections. 16 unit tests, all passing.

r5 — TokenUsageTracker (backend/tools/token_usage_tracker.py, src/core/middlewares/token_tracking.py) Singleton token/cost tracker + agent-callable query tool + StrategyMiddleware that intercepts LLM responses to accumulate usage stats per model and per session. 21 unit tests across 4 test classes, all passing.

Files modified across rounds

• backend/tools/ — 5 new tool files
• src/core/middlewares/token_tracking.py — new middleware
• backend/llm/tool_registry.py — updated each round
• main.py — updated each round
• src/tui/agent_bridge.py — updated each round
• tests/ — 6 new test files (101 tests total)
• docs/system_design.md — updated each round

---

Debug Results

Post-evolution analysis (evolve_session.sh Phase 3) examined each new tool and its wiring points.

Findings:

• All 5 tools are correctly registered in tool_registry.py and injected into both entry points (main.py and agent_bridge.py).
• Round 2 required a second iteration: the initial ArxivSearchTool implementation failed the BaseTool inheritance check; fixed in the same round by Developer2.
• Round 3 produced one non-blocking quality warning (false-positive self-match in CodeAnalysisTool); no action needed.
• No regressions detected across rounds.

Current feature availability:

Tool	Available in CLI	Available in TUI
DataAnalysisTool	Yes	Yes
ArxivSearchTool	Yes	Yes
CodeAnalysisTool	Yes	Yes
MarkdownExportTool	Yes	Yes
TokenUsageTracker	Yes	Yes

---

Quick Start

1. Install

git clone https://github.com/<your-org>/nano_agent_team_selfevolve.git
cd nano_agent_team_selfevolve
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Configure

Edit backend/llm_config.json to select a provider, then export the corresponding API key:

export OPENAI_API_KEY="your_key"
export DASHSCOPE_API_KEY="your_key"
# or other provider keys as needed

Or pass a key file:

python main.py --keys /path/to/keys.json

3. Run

Normal agent mode:

python main.py "Your mission"

Optional TUI:

python tui.py

4. Self-evolution mode

# Run 5 rounds with default model
bash evolve.sh 5

# Run 10 rounds with a specific model
bash evolve.sh 10 qwen/qwen-plus

# Stop after the current round completes
touch .evolution_stop

---

Project Structure

.
├── backend/
│   ├── llm/                   # Engine, providers, middleware chain, tool registry
│   └── tools/                 # Tool implementations (DataAnalysis, CodeAnalysis, etc.)
├── docs/
│   └── system_design.md       # Architecture reference
├── evolution_reports/         # Per-round markdown reports
├── src/
│   ├── core/
│   │   └── middlewares/       # StrategyMiddleware implementations
│   ├── prompts/               # Agent prompt protocols
│   └── tui/                   # Terminal UI and agent bridge
├── tests/                     # Unit and integration tests
├── evolve.sh                  # Round-based evolution loop
├── evolve_session.sh          # Full automated session (record + debug + doc + push)
├── evolution_history.jsonl    # Append-only round history
├── evolution_state.json       # Current evolution state snapshot
├── main.py                    # CLI entry point
└── tui.py                     # TUI entry point

---

License

MIT — see LICENSE.