pguso/ai-agents-from-scratch を読む: フレームワークの前に ReAct と function calling を手で書く
Demystify AI agents by building them yourself. Local LLMs, no black boxes, real understanding of function calling, memory, and ReAct patterns.
ひと目でわかる
- これは何？
- ローカル LLM と node-llama-cpp だけでエージェントを組み立てる JavaScript チュートリアル。11 段階の学習順序と、フレームワークを使う前に何を理解しておくべきかを見る。
- 誰に向いている？
- フレームワークの抽象化に納得がいかず、function calling やメモリ、ReAct ループが実際に何をしているのかを自分の手で確かめたい開発者には向いている。逆に、すぐ動くエージェントを業務に組み込みたい場合や、モデルのダウンロードと 8GB 以上のメモリを用意できない環境では遠回りになる。
- 商用利用できる？
- できます。MIT は寛容なライセンスで、著作権表示とライセンス表示を残せば、使用・改変・販売が可能です。
- 今もメンテナンスされている？
- されています。最後のコミットは 53 日前です。
- 何の言語で書かれている？
- 主に JavaScript です（GitHub の言語統計による）。
回答はプロジェクトの GitHub データ（最終同期：2026年9月15日）と当サイトの分析に基づくもので、法的助言ではありません。
オープンソース詳細解説
この教材が埋めようとしている溝
エージェントフレームワークは、ツール定義、会話履歴、ループ制御をまとめて隠す。便利だが、ツール呼び出しが失敗したときに何が起きているのか、モデルがなぜそのツールを選んだのかが分からなくなる。このリポジトリはその逆を行く。README は目的を「Learn to build AI agents locally without frameworks」と述べ、フレームワークを使う前に内部で何が起きているかを理解することを狙いとして掲げている。対象読者は JavaScript を書ける開発者で、Python 版が別リポジトリとして用意されている点からも、言語ごとに読者を分けていることが分かる。学習の単位は 11 個のディレクトリで、intro から aot-agent、error-handling まで順に並ぶ。各ディレクトリにはコード本体に加えて CODE.md と CONCEPT.md が置かれ、実装の説明と概念の説明が分離されている。README の推奨ワークフローでは、GitHub 側を「running, modifying, and studying the code」に、companion website を「mental models, explanations, and progression」に使うと役割を切っている。サイトはリポジトリの代替ではないと明記されている。
依存は node-llama-cpp とローカルモデルだけ
仕組みの中心にあるのは node-llama-cpp で、Node.js プロセス内から GGUF 形式のモデルを読み込んで推論する。前提として README が挙げるのは Node.js 18 以上、メモリ 8GB 以上（16GB 推奨）、そしてモデルファイルを ./models/ に置くこと。モデルの入手方法は DOWNLOAD.md に分離されている。クラウド API を呼ばないため、トークン課金もネットワーク往復も発生しない代わりに、推論速度と扱えるモデルサイズは手元のハードウェアで決まる。ここは設計上の割り切りとして率直に書いておく。8GB という下限は、量子化された小さめのモデルを動かすための線であって、快適に回るという意味ではない。README はバッチ処理の章で GPU バッチ処理とシーケンスに触れているが、CPU のみの環境でどこまで実用的かについては記述が見当たらない。なお 2 章の openai-intro だけはホスト型モデルを呼ぶ例で、ここでネットワーク遅延、コストと制御のトレードオフ、データプライバシー、ベンダー依存という論点が導入される。ローカル推論を主軸に置きながら、あえてホスト型を 1 章挟んで比較させる構成は意図的だと読める。
学習パスは 11 段階で、7 章目に段差がある
順序そのものが設計になっている。1 章の intro はモデルのロードとプロンプト応答サイクルだけを扱う。3 章の translation でシステムプロンプトによる役割の固定と出力形式の制御を学び、4 章の think で推論の限界と外部ツールが必要になる境界に触れる。5 章の batch は並列実行とコンテキストシーケンス、6 章の coding はストリーミングとトークン予算の管理で、ここまではエージェントではなく LLM の使い方の話である。7 章の simple-agent でようやく function calling が入り、README はこの章を「This is where text generation becomes agency!」と位置づけている。ツールの定義、パラメータの JSON Schema、モデルがいつツールを使うと判断するかが主題になる。8 章で永続メモリ、9 章で ReAct の Reason → Act → Observe ループと自己修正、10 章で Atom of Thought による原子操作への分解と依存関係の解決、11 章でエラー分類とタイムアウト、リトライが入る。9 章について README は「This is the foundation of modern agent frameworks!」と書いており、ここが山場だと分かる。逆に言えば、7 章より前で止めると得られるのは LLM 入門であってエージェントの理解ではない。
動かし方: npm install と node コマンド
手順は短い。リポジトリを取得したあと、まず npm install を実行する。次に DOWNLOAD.md の指示に従ってモデルをダウンロードし、./models/ ディレクトリに配置する。実行はディレクトリごとのエントリポイントを node で直接叩く形で、README が例として挙げているのは node intro/intro.js、node simple-agent/simple-agent.js、node react-agent/react-agent.js の 3 つである。設定ファイルや環境変数の類は README には現れない。モデルの切り替えがどう行われるかは本文からは確認できないので、そこは各ディレクトリの CODE.md を読む必要がある。openai-intro の章だけはホスト型モデルを呼ぶため、ローカルモデルとは別の準備が要るはずだが、README の抜粋にはその手順が含まれていない。API キーの扱いについてはこの材料からは判断できない。バッチの章で触れられている GPU バッチ処理も、対応するバックエンドやフラグの指定方法までは README に書かれていない。
エラー処理の章が示す、教材としての踏み込み方
11 章の error-handling は、このリポジトリの性格がはっきり出る章だ。README はここで「Typed error taxonomy (validation, LLM, tools, workflow) with stable codes」を学ぶと説明している。つまり検証、LLM、ツール、ワークフローの 4 分類にエラーを分け、それぞれに安定したコードを振る。加えてタイムアウトとリトライが扱われる。LLM は確率的に出力するので、ツール呼び出しの引数がスキーマに合わないことが普通に起きる。その失敗をどの層のエラーとして扱い、どこで再試行するかを決めるのは、フレームワークが内部でやっていることの一つである。ここを自分で書いた経験があると、後でフレームワークのリトライ設定を読んだときに何を調整しているのかが分かる。ただし README の抜粋は「Timeouts, retries wi」で途切れており、リトライ回数の上限やバックオフの方式までは確認できない。この章の具体的な実装は error-handling/ 配下のコードと CODE.md を見ないと判断できない。
向かないケースと、代わりに取れる道
最初に断っておくと、これは製品ではなく教材である。すぐ動くエージェントが必要なら、LangChain.js のようなフレームワークを使うほうが速い。違いは抽象化の位置にある。フレームワークはツール呼び出しのループ、メモリの永続化、エラー時の再試行をライブラリ側の責務として提供し、利用者は設定とツールの実装に集中する。このリポジトリはその逆で、ループもメモリもエラー分類も自分で書き、なぜその形になるのかを先に体験する。どちらが優れているという話ではない。判断の分かれ目は、既にフレームワークで動くものを運用していて、その挙動が理解できない場面に遭遇したことがあるかどうかだ。あるなら 9 章と 11 章は直接役に立つ。ないなら、フレームワークのドキュメントを読むほうが短時間で目的に着く。もう一つの制約は実行環境で、クラウド上のノートブックやメモリの少ない CI では、モデルのダウンロードとロードの時点でつまずく。README が前提に挙げる 8GB という数字を満たせない場合、この教材は読むだけのものになる。
MIT ライセンスと、更新を追うコスト
ライセンスは MIT で、コードを自分のプロジェクトに取り込むことも、改変して配布することもできる。ただし教材として書かれたコードをそのまま本番に置く前提は置かないほうがよい。ここで扱われるモデルの重みは別ライセンスであり、MIT が及ぶ範囲ではない。どのモデルを ./models/ に置くかによって条件が変わるので、モデル側のライセンスは各自で確認する必要がある。これは法的助言ではなく、確認すべき対象の指摘である。更新については、リポジトリはアーカイブされておらず、最終 push は 2026-07-24 時点で記録されている。リリースは取得できておらず、バージョン番号で追う形にはなっていない。node-llama-cpp は活発に動く依存なので、時間が経てば API の差異が生じうる。教材の性質上、コードは特定の時点の書き方を写したものになる。手元で動かすときは package.json が固定しているバージョンを確認し、README のコマンドと実際のエントリポイントのパスが一致しているかを最初に見ておくとよい。
編集部の結論
フレームワークの抽象化に納得がいかず、function calling やメモリ、ReAct ループが実際に何をしているのかを自分の手で確かめたい開発者には向いている。逆に、すぐ動くエージェントを業務に組み込みたい場合や、モデルのダウンロードと 8GB 以上のメモリを用意できない環境では遠回りになる。着手前に DOWNLOAD.md でモデルの入手方法とサイズを確認し、node intro/intro.js が手元で通るかどうかを最初に確かめてほしい。そこが通らなければ以降の 10 章はすべて同じ前提の上に乗っているので、読むだけでは得られるものが少ない。
コミュニティノート