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 编码技巧。