Nano Agent

🚀 Nano Agent

Nano Agent 是一個用於實驗性、小規模工程代理的 MCP 服務器，支持多供應商的大語言模型（LLM）。它旨在測試和比較雲服務和本地大語言模型在性能、速度和成本方面的代理能力。

🚀 快速開始

你可以觀看我們如何使用 GPT - 5 和 Claude Code 搭配 Nano 代理的視頻：點擊觀看。

✨ 主要特性

• 🤖 多供應商支持：可在 OpenAI（GPT - 5）、Anthropic（Claude）和 Ollama（本地模型）之間無縫切換。
• 🔧 文件系統操作：能夠自主讀取、寫入、編輯和分析文件。
• 🏗️ 嵌套代理架構：MCP 服務器會生成內部代理來執行任務。
• 🎯 統一接口：所有供應商都使用相同的 OpenAI SDK，保證一致性。
• 📦 實驗就緒：具備完善的測試、錯誤處理和令牌跟蹤功能。
• 🚀 易於集成：可與 Claude Desktop 配合使用，也可作為命令行界面（CLI）使用。

📦 安裝指南

快速安裝（推薦）

1. 安裝 Astral UV
2. 配置 Claude Code
3. 配置 Ollama
4. 獲取你的 OpenAI API 密鑰和 Anthropic API 密鑰
5. 配置 dotenv：
   • cp ./.env.sample ./.env 並填寫變量
   • cp ./apps/nano_agent_mcp_server/.env.sample ./apps/nano_agent_mcp_server/.env 並填寫變量
6. 克隆倉庫：
   • git clone https://github.com/disler/nano - agent
7. 全局安裝 nano - agent，以便 Claude Code（任何 MCP 客戶端）可以使用：
   • cd nano - agent/apps/nano_agent_mcp_server
   • ./scripts/install.sh
   • uv tool install -e .
8. 將 .mcp.json.sample 複製為 .mcp.json 以使用 nano - agent：

{
  "mcpServers": {
    "nano - agent": {
      "command": "nano - agent",
      "args": []
    }
  }
}

你也可以不全局安裝 nano - agent，直接在該目錄下運行：

{
  "mcpServers": {
    "nano - agent": {
      "command": "uv",
      "args": ["--directory", "apps/nano_agent_mcp_server", "run", "nano - agent"]
    }
  }
}

現在你可以按照下面的 [Nano Agent 交互部分](#nano - agent - interaction) 來測試 Nano 代理。

💻 使用示例

基礎用法

通過命令行界面（CLI）

請記住，直接運行時，當前目錄是你運行 uv run nano - cli run 的目錄。

cd apps/nano_agent_mcp_server

# 無 API 情況下測試工具
uv run nano - cli test - tools

# 使用不同模型運行（根據模型名稱自動檢測供應商）
uv run nano - cli run "List all Python files in the current directory"  # gpt - 5 - mini（默認）
uv run nano - cli run "Create a hello world script in python" --model gpt - 5 - nano
uv run nano - cli run "Summarize the README.md" --model gpt - 5

# 測試 Anthropic 模型（需要 ANTHROPIC_API_KEY）
uv run nano - cli run "Hello" --model claude - 3 - haiku - 20240307 --provider anthropic
uv run nano - cli run "Hello" --model claude - sonnet - 4 - 20250514 --provider anthropic
uv run nano - cli run "Hello" --model claude - opus - 4 - 20250514 --provider anthropic
uv run nano - cli run "Hello" --model claude - opus - 4 - 1 - 20250805 --provider anthropic

# 測試本地 Ollama 模型（需要 ollama 服務）（確保先使用 `ollama pull gpt - oss:20b` 安裝模型）
uv run nano - cli run "List files" --model gpt - oss:20b --provider ollama
uv run nano - cli run "List files and count the total number of files and directories" --model gpt - oss:120b --provider ollama

# 詳細模式（顯示令牌使用情況）
uv run nano - cli run "Create and edit a test file" --verbose

通過 Claude Code

直接調用 MCP 服務器

mcp nano - agent: prompt_nano_agent "Create a hello world script in python" --model gpt - 5
mcp nano - agent: prompt_nano_agent "Summarize the README.md" --model claude - opus - 4 - 1 - 20250805 --provider anthropic
mcp nano - agent: prompt_nano_agent "Read the first 10 lines and last 10 lines of the README.md" --verbose

通過子代理調用 MCP 服務器

@agent - nano - agent - gpt - 5 - mini "Create a hello world script in python"

@agent - nano - agent - gpt - 5 "Summarize the <file name>"

@agent - nano - agent - claude - opus - 4 - 1 "<insert agentic prompt here>"

@agent - nano - agent - gpt - oss - 20b "<insert agentic prompt here>"

@agent - nano - agent - gpt - oss - 120b "<insert agentic prompt here>"

@agent - nano - agent - claude - sonnet - 4 "<insert agentic prompt here>"

@agent - nano - agent - claude - 3 - haiku "<insert agentic prompt here>"

通過高階提示（HOP）和低階提示（LOP）模式

在 Claude Code 中調用：

/perf:hop_evaluate_nano_agents .claude/commands/perf/lop_eval_1__dummy_test.md

/perf:hop_evaluate_nano_agents .claude/commands/perf/lop_eval_2__basic_read_test.md

/perf:hop_evaluate_nano_agents .claude/commands/perf/lop_eval_3__file_operations_test.md

/perf:hop_evaluate_nano_agents .claude/commands/perf/lop_eval_4__code_analysis_test.md

/perf:hop_evaluate_nano_agents .claude/commands/perf/lop_eval_5__complex_engineering_test.md

高級用法

理解 HOP/LOP：工作原理

HOP/LOP 模式 能夠對多個模型進行系統的並行評估：

• HOP（高階提示）：作為協調器，讀取測試文件，並行委託給代理，並對結果進行評分。
• LOP（低階提示）：包含單個測試定義，如提示、預期輸出和評分標準。
• 執行流程：HOP → 讀取 LOP → 同時調用 9 個代理 → 收集結果 → 生成比較表。

示例：當你運行 /perf:hop_evaluate_nano_agents lop_eval_3__file_operations_test.md 時：

1. HOP 從 LOP 文件中讀取測試規範。
2. 提取提示和要測試的代理列表。
3. 並行執行所有代理（GPT - 5、Claude、本地模型）。
4. 每個代理通過 nano - agent MCP 服務器獨立運行。
5. 根據性能、速度和成本對結果進行評分。
6. 輸出顯示排名比較，可能會有令人驚訝的結果（例如，Claude - 3 - haiku 通常勝過昂貴的模型）。

這種架構通過對所有供應商使用相同的 OpenAI 代理 SDK，確保了公平比較，創建了真正的同類對比基準。

🔧 技術細節

項目結構

nano - agent/
├── apps/                           # ⚠️ 所有應用代碼存於此
│   └── nano_agent_mcp_server/     # 主 MCP 服務器應用
│       ├── src/                    # 源代碼
│       │   └── nano_agent/         # 主包
│       │       ├── modules/        # 核心模塊
│       │       │   ├── constants.py         # 模型/供應商常量和默認值
│       │       │   ├── data_types.py        # Pydantic 模型和類型定義
│       │       │   ├── files.py             # 文件系統操作
│       │       │   ├── nano_agent.py        # 主代理執行邏輯
│       │       │   ├── nano_agent_tools.py  # 內部代理工具實現
│       │       │   ├── provider_config.py   # 多供應商配置
│       │       │   ├── token_tracking.py    # 令牌使用和成本跟蹤
│       │       │   └── typing_fix.py        # 類型兼容性修復
│       │       ├── __main__.py     # MCP 服務器入口點
│       │       └── cli.py          # CLI 接口（nano - cli）
│       ├── tests/                  # 測試套件
│       │   ├── nano_agent/         # 單元測試
│       │   └── isolated/           # 供應商集成測試
│       ├── scripts/                # 安裝和實用腳本
│       ├── pyproject.toml          # 項目配置和依賴項
│       ├── uv.lock                 # 鎖定的依賴項版本
│       └── .env.sample             # 環境變量模板
├── .claude/                        # Claude Code 配置
│   ├── agents/                     # 子代理配置（9 個模型）
│   │   ├── nano - agent - gpt - 5 - nano.md         # OpenAI GPT - 5 Nano
│   │   ├── nano - agent - gpt - 5 - mini.md         # OpenAI GPT - 5 Mini（默認）
│   │   ├── nano - agent - gpt - 5.md              # OpenAI GPT - 5
│   │   ├── nano - agent - claude - opus - 4 - 1.md    # Claude Opus 4.1
│   │   ├── nano - agent - claude - opus - 4.md      # Claude Opus 4
│   │   ├── nano - agent - claude - sonnet - 4.md    # Claude Sonnet 4
│   │   ├── nano - agent - claude - 3 - haiku.md     # Claude 3 Haiku
│   │   ├── nano - agent - gpt - oss - 20b.md        # Ollama 20B 模型
│   │   ├── nano - agent - gpt - oss - 120b.md       # Ollama 120B 模型
│   │   └── hello - world.md                   # 簡單問候代理
│   ├── commands/                   # Claude Code 命令
│   │   ├── perf/                   # 性能評估命令
│   │   │   ├── hop_evaluate_nano_agents.md  # 高階提示協調器
│   │   │   ├── lop_eval_1__dummy_test.md    # 簡單問答測試
│   │   │   ├── lop_eval_2__basic_read_test.md   # 文件讀取測試
│   │   │   ├── lop_eval_3__file_operations_test.md  # 複雜 I/O 測試
│   │   │   ├── lop_eval_4__code_analysis_test.md    # 代碼理解
│   │   │   └── lop_eval_5__complex_engineering_test.md  # 完整項目測試
│   │   ├── convert_paths_absolute.md   # 轉換為絕對路徑
│   │   ├── convert_paths_relative.md   # 轉換為相對路徑
│   │   ├── create_worktree.md          # Git 工作樹管理
│   │   ├── plan.md                     # 規劃模板
│   │   ├── prime.md                    # 代碼庫理解
│   │   └── build.md                    # 構建命令
│   ├── hooks/                      # 開發鉤子
│   ├── settings.json               # 便攜式設置（相對路徑）
│   └── settings.local.json         # 本地設置（絕對路徑）
├── eval_results_1_dummy_test.md    # 問答測試基準結果
├── eval_results_2_basic_read_test.md   # 文件讀取基準結果
├── eval_results_3_file_operations_test.md  # I/O 基準結果
├── eval_results_4_code_analysis_test.md    # 代碼分析基準結果
├── eval_results_5_complex_engineering_test.md  # 項目創建基準結果
├── images/                         # 文檔圖片
│   └── nano - agent.png             # 項目標誌/圖表
├── app_docs/                       # 特定於應用的文檔
├── ai_docs/                        # AI/LLM 文檔和指南
│   ├── python_uv_mcp_server_cookbook.md    # MCP 服務器開發指南
│   ├── openai_agent_sdk_*.md      # OpenAI SDK 文檔
│   ├── anthropic_openai_compat.md # Anthropic 兼容性指南
│   ├── ollama_openai_compat.md    # Ollama 兼容性指南
│   └── new_openai_gpt_models.md   # GPT - 5 模型規範
└── specs/                          # 技術規範

開發指南

前提條件

• Python 3.12+（需要正確的類型支持）
• [uv](https://github.com/astral - sh/uv) 包管理器
• OpenAI API 密鑰（用於 GPT - 5 模型測試）

開發設置

cd apps/nano_agent_mcp_server
uv sync --extra test  # 包含測試依賴項

Claude Code 鉤子配置

如果你使用 Claude Code 來處理這個代碼庫，項目中包含了用於增強開發體驗的鉤子。鉤子默認使用相對路徑以保證可移植性。

要為你的本地環境激活使用絕對路徑的鉤子： 在 .claude/settings.local.json 中將相對路徑轉換為絕對路徑，在 Claude Code 中運行以下命令： 此命令會更新所有鉤子路徑以使用你機器的絕對路徑，同時會自動在 .claude/settings.json.backup 創建備份。 /convert_paths_absolute.md

注意：鉤子是可選的，但提供了一些有用的功能，如：

• 工具使用前後的通知
• 會話跟蹤
• 用於調試的事件日誌

對於生產使用，請參閱上面的 安裝部分。

UV 依賴管理

使用 UV 和可選依賴項時：

• uv sync - 僅安裝主要依賴項（mcp, typer, rich）
• uv sync --extra test - 安裝主要 + 測試依賴項（包括 pytest, openai 等）
• uv sync --all - extras - 安裝主要 + 所有可選依賴項組
• uv pip list - 顯示虛擬環境中所有已安裝的包

重要提示：需要運行測試時，始終使用 --extra test，因為單獨使用 uv sync 會移除測試依賴項。

配置

1. 複製環境模板：

cp .env.sample .env

2. 添加你的 OpenAI API 密鑰：

echo "OPENAI_API_KEY = sk - your - key - here" > .env

運行服務器

cd apps/nano_agent_mcp_server
uv run nano - agent --help

服務器通過標準輸入/輸出使用 MCP 協議進行通信。

Nano Agent 架構

嵌套代理層次結構

關鍵概念：這是一個具有兩個不同代理層的嵌套代理系統。

┌─────────────────────────────────────────────────────────────┐
│ 外部代理（例如，Claude Code，任何 MCP 客戶端）            │
│   • 通過 MCP 協議通信                          │
│   • 可見一個工具：prompt_nano_agent                       │
│   • 向 nano - agent 發送自然語言提示           │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ MCP 協議
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ NANO - AGENT MCP 服務器（apps/nano_agent_mcp_server）         │
│   • 暴露一個 MCP 工具：prompt_nano_agent             │
│   • 接收來自外部代理的提示                      │
│   • 生成內部 OpenAI 代理來處理請求         │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ 創建並管理
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ 內部代理（具有函數調用功能的 OpenAI GPT）             │
│   • 每次調用 prompt_nano_agent 時都會重新創建          │
│   • 有自己的工具（外部代理不可見）：        │
│     - read_file: 讀取文件內容                        │
│     - list_directory: 列出目錄內容              │
│     - write_file: 創建/覆蓋文件                   │
│     - get_file_info: 獲取文件元數據                     │
│   • 運行自主循環（最多 20 輪）                    │
│   • 將最終結果返回給 MCP 服務器 → 外部代理       │
└─────────────────────────────────────────────────────────────┘

驗證和測試

單元測試（實際 API 調用）

# 運行所有集成測試
uv run pytest tests/ - v

# 測試特定功能
uv run pytest tests/nano_agent/modules/test_nano_agent.py::TestExecuteNanoAgent - v

# 快速驗證
uv run pytest - k "test_execute_nano_agent_success" - v

CLI 驗證

# 驗證工具是否正常工作（無需 API）
uv run nano - cli test - tools

# 快速代理測試
export OPENAI_API_KEY = sk - your - key
uv run nano - cli run "What is 2+2?"  # 使用默認模型

多供應商支持

Nano 代理通過使用 OpenAI SDK 的統一接口支持多個大語言模型供應商。所有供應商都通過與 OpenAI 兼容的端點訪問，提供一致的 API。

可用供應商和模型

你可以根據需要添加/刪除供應商和模型。

OpenAI（默認）

• 模型：gpt - 5, gpt - 5 - mini（默認）, gpt - 5 - nano, gpt - 4o
• 要求：OPENAI_API_KEY 環境變量
• 特殊功能：
  • GPT - 5 模型使用 max_completion_tokens 而不是 max_tokens
  • GPT - 5 模型僅支持 temperature = 1
  • 擴展上下文窗口（400K 令牌）

Anthropic

• 模型：claude - opus - 4 - 1 - 20250805, claude - opus - 4 - 20250514, claude - sonnet - 4 - 20250514, claude - 3 - haiku - 20240307
• 要求：ANTHROPIC_API_KEY 環境變量
• 實現：使用 Anthropic 的與 OpenAI 兼容的端點
• 基礎 URL：https://api.anthropic.com/v1/

Ollama（本地模型）

• 模型：gpt - oss:20b, gpt - oss:120b 或任何你本地拉取的模型
• 要求：本地運行的 Ollama 服務
• 實現：使用 Ollama 的與 OpenAI 兼容的 API
• 基礎 URL：http://localhost:11434/v1

使用不同供應商

# OpenAI（默認）
uv run nano - cli run "Create a hello world script"

# 使用特定的 OpenAI 模型
uv run nano - cli run "Analyze this code" --model gpt - 5 --provider openai

# Anthropic
uv run nano - cli run "Write a test file" --model claude - 3 - haiku - 20240307 --provider anthropic

# Ollama（本地）
uv run nano - cli run "List files" --model gpt - oss:20b --provider ollama

多模型評估系統

Nano 代理包含一個複雜的多層評估系統，用於比較不同供應商和模型的大語言模型性能。通過使用相同的執行環境（OpenAI 代理 SDK），無論底層供應商如何，都能為基準測試創造公平的競爭環境。

HOP/LOP 模式

評估系統的核心創新是 HOP/LOP（高階提示 / 低階提示） 模式，它創建了一個用於並行模型測試的分層協調系統：

┌─────────────────────────────────────────────────────────────┐
│ 1. 高階提示（HOP）                                │
│   文件：.claude/commands/perf/hop_evaluate_nano_agents.md  │
│   • 協調整個評估過程                  │
│   • 接受測試用例文件作為 $ARGUMENTS                   │
│   • 格式化和評分結果                              │
│   • 生成性能比較表                 │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ 讀取並執行
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. 低階提示（LOP）                                 │
│   文件：.claude/commands/perf/lop_eval_*.md               │
│   • 定義測試用例（要評估的提示）               │
│   • 列出要測試的代理（@agent - nano - agent - *）             │
│   • 指定預期輸出                             │
│   • 提供評分標準                               │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ @agent 引用
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. Claude Code 子代理                                   │
│   文件：.claude/agents/nano - agent - *.md                    │
│   • 單個代理配置                        │
│   • 每個指定模型 + 供應商組合            │
│   • 按模型家族顏色編碼：                          │
│     - 綠色：GPT - 5 系列（nano, mini, standard）          │
│     - 藍色：GPT - OSS 系列（20b, 120b）                    │
│     - 紫色：Claude 4 Opus 模型                        │
│     - 橙色：Claude 4 Sonnet 和 Claude 3 Haiku            │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ 調用 MCP 服務器
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. Nano - Agent MCP 服務器                                    │
│   函數：prompt_nano_agent(prompt, model, provider)     │
│   • 為每個請求創建獨立的代理實例            │
│   • 對所有供應商使用 OpenAI 代理 SDK               │
│   • 確保一致的執行環境               │
│   • 返回帶有指標的結構化結果                │
└─────────────────────────────────────────────────────────────┘

為何採用此架構

1. 公平比較：所有模型使用相同的 OpenAI 代理 SDK，消除了實現差異。
2. 並行執行：代理同時運行，減少了時間變化。
3. 結構化指標：對所有供應商一致跟蹤時間、令牌和成本。
4. 可擴展性：易於添加新模型、供應商或測試用例。
5. 可視化層次結構：顏色編碼的代理使結果在 Claude Code 中易於查看。
6. 可重複性：相同的提示和執行環境確保了一致的基準測試。

📄 許可證

本項目採用 MIT 許可證。

掌握 AI 編碼

為代理工程做好準備

學習基於 [AI 編碼原則](https://agenticengineer.com/principled - ai - coding?y = nanoagent) 進行 AI 編碼。

關注 IndyDevDan YouTube 頻道 以獲取更多 AI 編碼技巧。