blog.dopana

Back

5 min
ja
ai/
cli/
developer tools/
typescript

Pi Agent Harness 探訪: 拡張可能なターミナル AI エージェント

earendil-works による Pi Agent Harness の解説。モジュール構造、ツリー型セッション管理、TypeScript 拡張機能で柔軟にカスタム可能な AI エージェント。

現在の AI コーディングアシスタントの多くは、ブラックボックス化されたモノリシックな構造を持っています。決められたワークフローや UI、計画モードに従う必要があり、独自のツール追加や処理のカスタマイズを行いたい場合、ベンダーのアップデートを待つか複雑なラッパースクリプトを書くしかありませんでした。

Pi (@earendil-works/pi) は「エージェントを自分のワークフローに適応させる」という理念のもと開発されたオープンソースの AI Agent Harness です。

[!NOTE] Pi は earendil-works（Mario Zechner / badlogic 氏が主導）によって開発されている Agent Harness プロジェクトです。コア機能をモジュール化し、ユーザーが自由にカスタマイズできる柔軟性を提供します。

1. 10歳でもわかる例え（ELI5）#

ボンネットが溶接されていてエンジン交換もカスタマイズもできない市販車をイメージしてください。

Pi Agent Harness は「モジュール式のレーシングシャーシ」のようなものです：

  • エンジンの自由な載せ替え: Claude、GPT-4o、Gemini、DeepSeek、さらには llama.cpp によるローカル LLM まで簡単に切り替えられます。
  • カスタムコックピット: TypeScript エクステンションで独自のターミナル UI や質問フォームを追加可能。
  • スキルの追加: プロジェクト特有の作業手順を Skills や Prompt Templates として定義できます。
  • タイムトラベル機能: セッション履歴はすべてツリー構造（Tree-structured Session）で保存されるため、試行錯誤の途中で過去の分岐に戻って別のアプローチを試すことができます。

2. 4つの層からなるモジュール設計#

Pi は4つの独立した npm パッケージで構成されており、CLI として利用するだけでなく、自分のアプリに組み込むことも可能です：

┌─────────────────────────────────────────────────────────┐
│        @earendil-works/pi-coding-agent (CLI)             │
├─────────────────────────────────────────────────────────┤
│        @earendil-works/pi-tui (Terminal UI)             │
├─────────────────────────────────────────────────────────┤
│        @earendil-works/pi-agent-core (Agent Engine)     │
├─────────────────────────────────────────────────────────┤
│        @earendil-works/pi-ai (Unified Provider API)    │
└─────────────────────────────────────────────────────────┘
text
パッケージ役割
@earendil-works/pi-ai30 以上の LLM プロバイダー（Anthropic、OpenAI、Google、DeepSeek、Bedrock、llama.cpp など）を統一インターフェースで包む API 層。
@earendil-works/pi-agent-coreツール呼び出し（read, write, edit, bash）、履歴管理、エージェントループ、コンテキスト圧縮を担うコアランタイム。
@earendil-works/pi-tui差分レンダリング（Differential Rendering）に対応した高パフォーマンスなターミナル UI ライブラリ。
@earendil-works/pi-coding-agentターミナル上で対話的に利用できるメインの CLI Harness。

3. Pi の主な特徴と強み#

TypeScript による自己拡張機能#

デフォルトでは read, write, edit, bash の 4 つの基本ツールが用意されていますが、Pi 内省コードを書き換えることなく拡張できます：

  • Skills (/skill:name): Markdown や TypeScript で記述するタスク自動化手順。
  • Extensions: カスタムツール、ステータスライン、UI オーバーレイを追加する TypeScript モジュール。
  • Prompt Templates: /template-name で呼び出せるプロンプトマクロ。
  • Pi Packages: テーマやスキル、拡張機能を npm/git 経由で共有可能。

ツリー構造セッション管理 (/tree)#

単一の直線的なログではなく、各ノードが id と parentId を持つ JSONL 形式のツリー構造で履歴を保存します。

対話モード中に /tree を実行すると、過去の分岐ポイントへジャンプしたり、過去のプロンプトから別の分岐を作成したりできます。

[!TIP] /tree 画面で Ctrl+O を押すと、全履歴・ツール非表示・ユーザー発言のみ・ブックマーク指定などのフィルター切り替えが可能です。

豊富なプロバイダー & ローカル LLM サポート#

API キーおよび各種サブスクリプションログインに対応：

  • クラウドサービス: Anthropic Claude, OpenAI, Google Gemini, DeepSeek, Groq, OpenRouter など。
  • ローカルモデル: /llama コマンドで llama.cpp サーバーと連携し、GGUF モデルをダウンロード・実行できます。

安全なサンドボックス環境#

デフォルトでは実行ユーザーの権限で動作しますが、必要に応じてコンテナ分離が可能です：

  1. Gondolin Micro-VM: ホスト上で pi を動かしつつ、bash ツールのみを軽量 Linux VM 内で実行。
  2. Docker Container: pi プロセス全体を Docker コンテナで隔離。
  3. OpenShell: 細かなポリシー権限管理を適用。

4. クイックスタート#

インストール#

npm を使用したグローバルインストール：

Terminal
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
bash

または公式スクリプトを利用：

Terminal
curl -fsSL https://pi.dev/install.sh | sh
bash

起動とモデル選択#

API キーを設定して起動します：

Terminal
export ANTHROPIC_API_KEY=sk-ant-...
pi
bash

対話モードでよく使うコマンド：

  • /model: 使用する LLM モデルの切り替え（Ctrl+L でも可）
  • /login: プロバイダーのアカウント認証
  • /tree: セッションツリーの表示
  • /compact: コンテキストの圧縮
  • /reload: 設定、拡張機能、スキルの再読み込み

5. Pi と OpenCode、Claude Code、Codex の比較#

項目Pi Agent (@earendil-works/pi)Claude CodeOpenAI CodexOpenCode
設計思想Unopinionated Harness (自己拡張可能な基盘)Opinionated Assistant (Claude 最適化)Dedicated Assistant (OpenAI 最適化)モジュール型オープンソース枠組み
LLM プロバイダー30+ プロバイダー (Anthropic, OpenAI, Gemini, DeepSeek, llama.cpp)Anthropic エコシステム限定OpenAI エコシステム限定マルチプロバイダー (API Key/OpenRouter)
セッション管理Tree Session (/tree): ツリー型履歴、分岐と巻き戻し直線的な履歴 (Linear history)直線的な履歴 (Linear history)標準セッション / セッション単位
拡張性TS Extensions, Skills, Prompt Templates, Pi Packages限定的なフック / Sub-agent基本的な Custom Instructions / Toolsプラグイン構造 & スケジューラー
Terminal UI差分描画対応高機能 TUI (pi-tui)カスタムターミナル UI基本的な CLIターミナル CLI
組み込み・SDK4モード (CLI, Print/JSON, RPC, 組み込み SDK)スタンドアロン CLICLI / APICLI / Framework
サンドボックスGondolin Micro-VM, Docker, OpenShellホスト / Docker コンテナホストDocker / Local

6. OSS セッションデータの共有#

Pi では、オープンソース開発中のセッションログを badlogic/pi-share-hf を使って Hugging Face に共有することを推奨しています。実際の開発ワークフローデータは、今後のオープン LLM や評価基盤の向上に役立ちます。

参考文献#

Exploring Pi Agent Harness: Extensible Terminal AI Agent

Khám phá Pi Agent Harness: AI Coding Agent Mở Rộng