Nano Agent

观看我们如何使用GPT-5和Claude Code与nano代理的视频这里。

什么是Nano Agent？ Nano Agent是一个用于实验的小规模工程代理的MCP服务器，支持多提供商的大语言模型（LLM）。

为什么需要Nano Agent？ 为了测试和比较云和本地LLM在性能、速度和成本方面的代理能力。

“这不再只是一个提示调用的问题。而是你的代理如何将多个工具串联起来，以实现真正的工程结果。”——来自我们的评估

<img src="images/nano-agent.png" alt="Nano Agent" style="max-width: 800px;">

🎬 实际操作演示

多模型评估流程 - 观看9个模型（GPT-5, Claude Opus, 本地GPT-OSS）在同一台M4 Max上并行运行： <img src="images/multi-model-eval-flow.gif" alt="多模型评估流程" style="max-width: 800px;">

模型对比：GPT-5 vs 本地模型 - 惊人的结果：GPT-OSS 20B/120B在设备上运行且成本为$0.00： <img src="images/model-comparison-gpt5-oss.gif" alt="模型对比 GPT-5 vs OSS" style="max-width: 800px;">

🔥 我们的测试关键发现

• 意外的赢家：当考虑到速度和成本时，GPT-5 Nano/Mini经常优于更大的模型
• 本地革命：GPT-OSS 20B/120B模型在M4 Max（128GB RAM）上完成真实的代理编码任务
• 成本现实检查：Claude Opus 4.1异常昂贵——性能不是一切
• 性能三角：性能 vs 速度 vs 成本——你并不总是需要最昂贵的模型

安装

快速安装（推荐）

• 安装 Astral UV
• 设置 Claude Code
• 设置 Ollama
• 获取你的OpenAI API密钥和Anthropic API密钥
• 设置dotenv
  • cp ./.env.sample ./.env 并填写变量
  • cp ./apps/nano_agent_mcp_server/.env.sample ./apps/nano_agent_mcp_server/.env 并填写变量
• 克隆仓库
  • git clone https://github.com/disler/nano-agent
• 全局安装 nano-agent 以便在Claude Code（任何mcp客户端）中使用
  • cd nano-agent/apps/nano_agent_mcp_server
  • ./scripts/install.sh
  • uv tool install -e .
• 将 .mcp.json.sample 复制为 .mcp.json 以使用 nano-agent
• 最终你应该得到一个如下所示的 .mcp.json 文件：

{
  "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代理。

Nano Agent交互

有三种方式可以与nano代理进行交互。

1. 通过CLI（uv run nano-cli run）
   • 适合理解代理的能力
2. 通过Claude Code或任何MCP客户端（.mcp.json 或等效配置）
   • 适合委派工作并在现场扩展计算
3. 通过高阶提示（HOP）和低阶提示（LOP）模式来测试和比较不同提供商和模型之间的模型。

通过CLI

记住，当你直接运行时，当前目录是你运行 uv run nano-cli run 的位置。

cd apps/nano_agent_mcp_server

# 测试工具（无需API）
uv run nano-cli test-tools

# 使用不同的模型运行（提供商会根据模型名称自动检测）
uv run nano-cli run "列出当前目录中的所有Python文件"  # gpt-5-mini（默认）
uv run nano-cli run "创建一个hello world脚本" --model gpt-5-nano
uv run nano-cli run "总结README.md" --model gpt-5

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

# 测试本地Ollama模型（需要Ollama服务）（确保先安装模型 `ollama pull gpt-oss:20b`）
uv run nano-cli run "列出文件" --model gpt-oss:20b --provider ollama
uv run nano-cli run "列出文件并计算总文件数和目录数" --model gpt-oss:120b --provider ollama

# 详细模式（显示令牌使用情况）
uv run nano-cli run "创建并编辑测试文件" --verbose

通过Claude Code

直接调用MCP服务器

mcp nano-agent: prompt_nano_agent "创建一个hello world脚本" --model gpt-5
mcp nano-agent: prompt_nano_agent "总结README.md" --model claude-opus-4-1-20250805 --provider anthropic
mcp nano-agent: prompt_nano_agent "读取README.md的前10行和后10行" --verbose
等等...

通过子代理调用MCP服务器

@agent-nano-agent-gpt-5-mini "创建一个hello world脚本"

@agent-nano-agent-gpt-5 "总结<文件名>"

@agent-nano-agent-claude-opus-4-1 "<插入代理提示>"

@agent-nano-agent-gpt-oss-20b "<插入代理提示>"

@agent-nano-agent-gpt-oss-120b "<插入代理提示>"

@agent-nano-agent-claude-sonnet-4 "<插入代理提示>"

@agent-nano-agent-claude-3-haiku "<插入代理提示>"

通过高阶提示（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对所有提供商进行公平比较，创建了一个真正的基准测试。

功能

• 🤖 多提供商支持：无缝切换OpenAI（GPT-5）、Anthropic（Claude）和Ollama（本地模型）
• 🔧 文件系统操作：自主地读取、写入、编辑和分析文件
• 🏗️ 嵌套代理架构：MCP服务器生成内部代理以执行任务
• 🎯 统一接口：所有提供商都使用相同的OpenAI SDK以保持一致性
• 📦 实验就绪：良好的测试、错误处理和令牌跟踪
• 🚀 易于集成：与Claude Desktop或作为CLI一起工作

Nano-Agent工具

随意添加/删除/改进工具。

Nano-Agent工具存储在 nano_agent_tools.py 中。

工具包括：

• read_file - 读取文件内容
• list_directory - 列出目录内容（默认为当前工作目录）
• write_file - 创建或覆盖文件
• get_file_info - 获取文件元数据（大小、日期、类型）
• edit_file - 通过替换精确文本匹配来编辑文件

项目结构

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    # Q&A测试基准结果
├── 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             # 项目logo/图表
├── 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 包管理器
• 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

服务器通过stdin/stdout使用MCP协议进行通信。

Nano Agent架构

嵌套代理层次结构

核心概念：这是一个具有两个不同代理层的嵌套代理系统。

┌─────────────────────────────────────────────────────────────┐
│ 外部代理（例如，Claude Code，任何MCP客户端）            │
│   • 通过MCP协议通信                                      │
│   • 只看到一个工具：prompt_nano_agent                     │
│   • 向nano-agent发送自然语言提示                         │
└