pguso/ai-agents-from-scratch

Demystify AI agents by building them yourself. Local LLMs, no black boxes, real understanding of function calling, memory, and ReAct patterns.

このプロジェクトは何ですか？

pguso/ai-agents-from-scratch は、人気のあるエージェントフレームワークを一切使わずに、AIエージェントをゼロから構築する方法を教える実践的なチュートリアルリポジトリです。代わりに、node-llama-cppというライブラリを介して、自分のコンピュータ上で動作するローカル言語モデル（LLM）を使用します。

核となる考え方は「作って学ぶ」です。生のLLM呼び出しから始めて、能力（ツール、メモリ、推論パターン）を徐々に追加し、現代のエージェントフレームワークが行うことを再現します。これにより、なぜそれらのフレームワークがそのような設計選択をするのかを理解できます。

何を学べますか？

READMEによると、以下を理解できます：

LLMが基本的なレベルでどのように機能するか
エージェントが実際に何であるか（LLM + ツール + パターン）
異なるエージェントアーキテクチャがどのように機能するか
フレームワークが特定の設計選択をする理由

中核となる定義

READMEはAIエージェントの簡単な式を示しています：

AIエージェント = LLM + システムプロンプト + ツール + メモリ + 推論パターン

LLM = 「脳」（言語モデル）
システムプロンプト = 「アイデンティティ」（動作を形作る指示）
ツール = 「手」（モデルが呼び出せる関数）
メモリ = 「状態」（永続的な情報）
推論パターン = 「戦略」（ステップバイステップで考える方法）

学習パス（15の例、順番に）

各例は前の例に基づいています。READMEは次のようにリストしています：

イントロ — ローカルLLMをロードして実行；基本的なプロンプト/レスポンスサイクル。
OpenAIイントロ （オプション） — GPT-4などのホスト型LLMを呼び出す；温度、トークン使用量、コストと制御、データプライバシーについて学ぶ。
翻訳 — システムプロンプトを使用してエージェントの動作を特化し、出力形式を制御する。
考える — 論理的推論のためにLLMを設定；純粋なLLM推論の限界と外部ツールをいつ使用するかを学ぶ。
バッチ — パフォーマンスのために複数のリクエストを並列処理する。
コーディング — リアルタイムでトークンごとにレスポンスをストリーミング；トークン予算を管理する。
シンプルエージェント — 大きなステップ：関数呼び出し。LLMに使用するか決定できるツールを提供します。READMEはこれを「テキスト生成がエージェンシーになるところ」と呼んでいます。
メモリ付きシンプルエージェント — セッションをまたいで事実と好みを永続化；長期メモリ管理。
ReActエージェント — 推論 → 行動 → 観察ループ：自己修正を伴う反復的な問題解決。READMEはこれを「現代のエージェントフレームワークの基盤」と呼んでいます。
AoTエージェント（思考の原子） — タスクを依存関係を持つ原子的な計画ステップに分解し、構造化JSONとして出力し、決定的に実行します。
エラーハンドリング — LLM + ツールシステムを回復力のあるものにする：型付きエラー、タイムアウト、バックオフ付きリトライ、優雅なフォールバック。
思考の木 — 複数の候補となる次のアクションを生成し、ブランチをランク付けして剪定（ビームサーチ）、勝者パスを検証。
思考のグラフ — 推論をDAG（有向非巡回グラフ）としてモデル化：並列ソース抽出 → マージルール → 最終ドラフト。生成前に競合を解決。
思考の連鎖 — リスクの高い決定を明示的で監査可能な推論フェーズに分割（例：ポリシー適用前に事実のみの抽出）。
ツールルーティング（埋め込み） — ツールの説明の埋め込みを事前計算し、ユーザーメッセージを類似度でスコアリングし、トップkツールのみをモデルに渡してコンテキストを節約。

例の構造

各例のフォルダには3つのファイルが含まれています：

<name>.js — 動作するコード
CODE.md — ステップバイステップのコード説明（行ごとの分解）
CONCEPT.md — 高レベルの概念、アーキテクチャパターン、実際のアプリケーション、簡単な図

READMEは完全な理解のために両方のファイルを読むことを推奨しています。

実行要件

Node.js 18+
少なくとも8GBのRAM（16GB推奨）
モデルをダウンロードして./models/フォルダに配置（詳細はDOWNLOAD.md）

npm installでインストールし、次のように例を実行します：

node intro/intro.js
node simple-agent/simple-agent.js
node react-agent/react-agent.js

コンパニオンウェブサイト

https://agentsfromscratch.comに対応するサイトがあります。これはリポジトリの代替ではなく、なぜ各例が存在するかを説明し、学習パスを視覚化する概念的なコンパニオンです。推奨されるワークフロー：コードの実行と研究にはGitHubを使用し、メンタルモデルと説明にはウェブサイトを使用します。READMEは次のように述べています：「サイトを地図と考え、このリポジトリを地形と考えてください。」

ヘルパーユーティリティ

PromptDebugger（helper/prompt-debugger.js）があり、LLMが正確に何を見ているか（システムプロンプト、関数定義、会話履歴、コンテキスト状態）を表示します。デバッグに役立ちます。

参照される追加リソース

node-llama-cpp — ローカル推論に使用されるライブラリ
Hugging Face — GGUFモデルのモデルハブ
GGUF形式 — ローカル推論用の量子化モデル

ライセンスと貢献

READMEはこれを教育リソースと述べています：「学習のために必要に応じて使用および変更してください。」貢献を歓迎します：ドキュメントの改善、新しい例のパターン、バグ修正、または構築したものの共有。

著者

このリポジトリはpguso（Patric Gutersohn）によるもので、AIワークフロー、コンテキストエンジニアリング、RAG、ローカル/本番LLMプロジェクトのフリーランス/契約作業を提供しています（連絡先：pguso@gmx.de）。

結論： フレームワークを使用する前にAIエージェントの内部で何が起こっているかを本当に理解したいなら、このリポジトリは、自分のマシン上で、一度に1つの能力ずつ、自分で構築する手順を案内します。