ローカルの Ollama モデルに「ファイルを読んで」「コマンドを実行して」と頼んだら、自分で考えて動いてくれる。そんな仕組みを作りました。
何ができるようになったか
helix-agent v0.4.0 で、ローカル LLM が 自律的にツールを使いながら推論する ReAct エージェント になりました。
タスク: 「pyproject.toml を読んで、プロジェクトの概要を教えて」
Step 1: 「ファイルを読む必要がある」 → read_file 実行
Step 2: ファイル内容を分析 → 「v0.4.0, 依存: fastmcp + httpx」と回答
2ステップで完了
LLM が自分で「何をすべきか」を考え、ツールを呼び出し、結果を見て次の行動を決めます。
従来との違い
従来: ユーザー → Claude Code → helix-agent → LLM「回答」→ 終わり
今回: ユーザー → Claude Code → helix-agent → LLM → ツール → 観察 → 再推論 → 回答
考えて、動いて、結果を見て、また考える。これがエージェントです。
使えるツール（7種類）
| ツール | できること |
|---|---|
| read_file | ファイルを読む |
| write_file | ファイルに書き込む |
| list_files | ディレクトリ内のファイル一覧 |
| search_in_file | ファイル内を正規表現で検索 |
| run_command | シェルコマンド実行（git, python, uv, ollama のみ） |
| calculate | 数式を計算 |
| search_memory | Qdrant で過去の知識を検索 |
セキュリティ: PathGuard
エージェントにファイル操作を任せても安全です。
- ディレクトリ許可リスト — 指定フォルダ以外アクセス不可
- 機密ファイルブロック — .env、credentials、SSH 鍵は自動ブロック
- パストラバーサル防止 — ../../ 攻撃を検知・遮断
- コマンド制限 — git, python, uv, ollama 以外は実行不可
なぜネイティブ Function Calling ではなく ReAct か
Ollama のネイティブ tools API は Llama 3.1 など一部モデルのみ対応。Qwen3.5 ではバグも報告されています。
helix-agent は プロンプトベースの ReAct + JSON 出力 を採用。全 Ollama モデルで同じように動きます。
セットアップ（2分）
# 1. Ollama でモデルを用意
ollama pull gemma3
# 2. クローンとインストール
git clone https://github.com/tsunamayo7/helix-agent.git
cd helix-agent && uv sync
~/.claude/settings.json に追加:
{
"mcpServers": {
"helix-agent": {
"command": "uv",
"args": ["run", "--directory", "/path/to/helix-agent", "python", "server.py"]
}
}
}
Claude Code を再起動すれば使えます。144 テスト通過、MIT ライセンス。