Nano Agent

🚀 Nano Agent

Nano Agentは、複数のプロバイダの大規模言語モデル（LLM）をサポートする、実験的な小規模エンジニアリングエージェント用のMCPサーバーです。クラウドとローカルのLLMのエージェント機能を、パフォーマンス、速度、コストの面でテストおよび比較することができます。

こちらで、nano - agentsを使ったGPT - 5とClaude Codeの使用例をご覧いただけます。

概要：多プロバイダのLLMをサポートする実験用小規模エンジニアリングエージェント向けMCPサーバー。 目的：クラウドとローカルのLLMのエージェント機能を、パフォーマンス、速度、コストの面でテスト・比較する。

"もはや単一のプロンプト呼び出しではなく、エージェントが複数のツールを連鎖させて、実際のエンジニアリング成果を達成する能力が重要です。" - 評価より

🎬 動作を見る

マルチモデル評価フロー

同じM4 Max上で9つのモデル（GPT - 5、Claude Opus、Local GPT - OSS）が並列で実行される様子をご覧ください。

モデル比較：GPT - 5 vs ローカルモデル

驚くべき結果！GPT - OSS 20B/120Bがコスト$0.00でデバイス上で実行されます。

🔥 テストからの重要な発見

• 意外な勝者：速度とコストを考慮すると、GPT - 5 Nano/Miniが大規模モデルを上回ることが多い。
• ローカル革命：GPT - OSS 20B/120BモデルがM4 Max（128GB RAM）上で実際のエージェントコーディングタスクを完了する。
• コストの現実：Claude Opus 4.1は非常に高価で、パフォーマンスだけがすべてではない。
• トレードオフの三角関係：パフォーマンス vs 速度 vs コスト - 常に高価なモデルが必要なわけではない。

📦 インストール

クイックインストール（推奨）

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": []
    }
  }
}

9. nano - agent をグローバルにインストールせずに、このディレクトリで実行してテストすることもできます。

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

これで、以下の [Nano Agent Interactionセクション](#nano - agent - interaction) に従って、nanoエージェントをテストできます。

💻 Nano Agent Interaction

Nanoエージェントとのやり取り方法は3つあります。

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
etc...

サブエージェントを通じて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>"

Higher Order Prompt (HOP) と Lower Order Prompt (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 (Higher Order Prompt)：テストファイルを読み取り、エージェントに並列でタスクを委任し、結果を採点するオーケストレーターです。
• LOP (Lower Order Prompt)：プロンプト、期待される出力、採点基準を含む個々のテスト定義です。
• 実行フロー：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 Agent SDKを使用することで、公平な比較を保証し、真のリンゴ同士のベンチマークを作成します。

✨ 主な機能

• 🤖 多プロバイダサポート：OpenAI（GPT - 5）、Anthropic（Claude）、Ollama（ローカルモデル）間をシームレスに切り替えることができます。
• 🔧 ファイルシステム操作：ファイルの読み取り、書き込み、編集、分析を自動的に行うことができます。
• 🏗️ ネストされたエージェントアーキテクチャ：MCPサーバーが内部エージェントを生成してタスクを実行します。
• 🎯 統一インターフェース：すべてのプロバイダが一貫性を保つために同じOpenAI SDKを使用します。
• 📦 実験準備完了：適切なテスト、エラーハンドリング、トークン追跡が行われます。
• 🚀 簡単な統合：Claude Desktopで使用できるか、CLIとして動作します。

Nano - Agent Tools

必要に応じて、ツールの追加、削除、改善を自由に行ってください。

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  # Higher Order Promptオーケストレーター
│   │   │   ├── lop_eval_1__dummy_test.md    # シンプルなQ&Aテスト
│   │   │   ├── 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             # プロジェクトロゴ/ダイアグラム
├── 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プロトコルを使用してstdin/stdoutを介して通信します。

ナノエージェントアーキテクチャ

ネストされたエージェント階層

キーコンセプト：これは2つの異なるエージェントレイヤーを持つネストされたエージェントシステムです。

┌─────────────────────────────────────────────────────────────┐
│ OUTER AGENT (e.g., Claude Code, any MCP client)            │
│   • Communicates via MCP protocol                          │
│   • Sees ONE tool: prompt_nano_agent                       │
│   • Sends natural language prompts to nano - agent         │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ MCP Protocol
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ NANO - AGENT MCP SERVER (apps/nano_agent_mcp_server)         │
│   • Exposes SINGLE MCP tool: prompt_nano_agent             │
│   • Receives prompts from outer agent                      │
│   • Spawns internal OpenAI agent to handle request         │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ Creates & Manages
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ INNER AGENT (OpenAI GPT with function calling)             │
│   • Created fresh for each prompt_nano_agent call          │
│   • Has its OWN tools (not visible to outer agent):        │
│     - read_file: Read file contents                        │
│     - list_directory: List directory contents              │
│     - write_file: Create/overwrite files                   │
│     - get_file_info: Get file metadata                     │
│   • Runs autonomous loop (max 20 turns)                    │
│   • Returns final result to MCP server → outer agent       │
└─────────────────────────────────────────────────────────────┘

検証とテスト

単体テスト（実際の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?"  # DEFAULT_MODELを使用する

多プロバイダサポート

ナノエージェントは、OpenAI SDKを使用した統一インターフェースを通じて、複数のLLMプロバイダをサポートしています。すべてのプロバイダは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モデルは温度=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

異なるプロバイダの使用

CLIでの使用

# 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

マルチモデル評価システム

ナノエージェントには、異なるプロバイダとモデル間のLLMパフォーマンスを比較するための高度な多層評価システムが含まれています。これにより、基盤となるプロバイダに関係なく、同じ実行環境（OpenAI Agent SDK）を使用して、公平なベンチマークを行うことができます。

"個々のベンチマークを信用しないでください。すべてのモデルの内部を調べて、真の価値がどこにあるかを見極める必要があります。" - エンジニアリングはトレードオフの世界です。

🎯 核心：HOP/LOPパターン

評価システムの核心的な革新は、HOP/LOP (Higher Order Prompt / Lower Order Prompt) パターンです。これは、並列モデルテストのための階層的なオーケストレーションシステムを作成します。

┌─────────────────────────────────────────────────────────────┐
│ 1. HIGHER ORDER PROMPT (HOP)                                │
│   File: .claude/commands/perf/hop_evaluate_nano_agents.md  │
│   • Orchestrates entire evaluation process                  │
│   • Accepts test case files as $ARGUMENTS                   │
│   • Formats and grades results                              │
│   • Generates performance comparison tables                 │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ Reads & Executes
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. LOWER ORDER PROMPT (LOP)                                 │
│   Files: .claude/commands/perf/lop_eval_*.md               │
│   • Defines test cases (prompts to evaluate)               │
│   • Lists agents to test (@agent - nano - agent - *)             │
│   • Specifies expected outputs                             │
│   • Provides grading rubrics                               │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ @agent References
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. CLAUDE CODE SUB - AGENTS                                   │
│   Files: .claude/agents/nano - agent - *.md                    │
│   • Individual agent configurations                        │
│   • Each specifies model + provider combination            │
│   • Color - coded by model family:                          │
│     - green: GPT - 5 series (nano, mini, standard)          │
│     - blue: GPT - OSS series (20b, 120b)                    │
│     - purple: Claude 4 Opus models                        │
│     - orange: Claude 4 Sonnet & Claude 3 Haiku            │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ Calls MCP Server
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. NANO - AGENT MCP SERVER                                    │
│   Function: prompt_nano_agent(prompt, model, provider)     │
│   • Creates isolated agent instance per request            │
│   • Uses OpenAI Agent SDK for ALL providers               │
│   • Ensures consistent execution environment               │
│   • Returns structured results with metrics                │
└─────────────────────────────────────────────────────────────┘

このアーキテクチャの理由

1. 公平な比較：すべてのモデルが同じOpenAI Agent SDKを使用するため、実装の違いを排除します。
2. 並列実行：エージェントが同時に実行されるため、時間的なばらつきを減らします。
3. 構造化されたメトリクス：すべてのプロバイダで一貫した時間、トークン、コストの追跡が行われます。
4. 拡張性：新しいモデル、プロバイダ、またはテストケースを簡単に追加できます。
5. 視覚的な階層：色分けされたエージェントにより、Claude Codeで結果を簡単に確認できます。
6. 再現性：同じプロンプトと実行環境により、一貫したベンチマークが保証されます。

📄 ライセンス

MIT

AIコーディングの習得

そしてエージェントエンジニアリングに備える

[AIコーディングの原則](https://agenticengineer.com/principled - ai - coding?y=nanoagent) を基に、AIを使ったコーディングを学びましょう。

IndyDevDanのYouTubeチャンネル をフォローして、さらなるAIコーディングのヒントやテクニックを学びましょう。