Pi Agent とは

はじめに

機能だけを見ると、Pi Agent は過小評価されがちです。ターミナルで動作し、ファイルを読み書きし、コマンドを実行し、セッションを保存し、モデルを切り替えることもできます。まるで別の Claude Code や Codex のように聞こえます。

しかし、Pi の真に興味深い点は、何を追加したかではなく、何を削減したかだと私は思います。AI プログラミングツールの最も核となる層、つまりモデル、コンテキスト、ツール、セッション、拡張機能を保持し、ユーザーのワークフローを事前に固定しないように最大限努めています。

したがって、私は Pi を次のように理解したいと考えています。

Pi Agent は「より完全な」AI プログラミング製品ではなく、より薄く、より透明性の高いコーディングエージェントハーネスです。

この判断は機能リストよりも重要です。なぜなら、Pi をどのように学ぶべきかを決定するからです。コマンドを覚えることから始めるのではなく、コーディングエージェントが実際にどのような層で構成されているかを理解することから始めるべきです。

まず Pi を適切な位置に置く

AI プログラミングツールは通常、モデル、ハーネス、エンジニアリング環境の3つの層に大まかに分けられます。しかし、この3つの層だけではまだ抽象的すぎます。Pi が本当に注目すべきは、中間層のハーネスがさらにどのようなモジュールに分割されているかです。

この図には3つの重要なポイントがあります。

第一に、Pi は単なる「チャット UI」ではありません。CLI、インタラクティブ TUI、print/JSON、RPC、SDK は単なる入り口であり、実際にタスクを引き受けるのは AgentSessionRuntime と AgentSession です。

第二に、Pi はモデルにリクエストを送信する前にリソースの読み込みを行います。ResourceLoader は AGENTS.md、CLAUDE.md、スキル、拡張機能、プロンプトテンプレートなどを整理し、SystemPrompt Builder に渡してモデルが実際に参照するコンテキストを構築します。

第三に、モデルがツールを呼び出す際、モデルが直接ファイルシステムを制御するわけではありません。AgentHarness と AgentLoop がツールの検証、実行、結果の受け取り、次のラウンドへの継続を担当します。Extensions、Tool Registry、SessionManager は、機能の拡張と状態の保存をサポートします。

したがって、Pi は中間層に位置しますが、この「中間」は単なる空虚な言葉ではありません。具体的には、どのコンテキストがモデルに入力されるか、どのツールが呼び出されるか、ツールの結果がどのようにセッションに戻るか、どの機能が拡張機能によって補完されるかを制御します。

これが、Pi を紹介する多くの記事が minimal、transparent、extensible を強調する理由です。これらはすべて同じことを言っています。Pi はエージェントのコア実行層を小さくし、ユーザーが見て変更できるようにしようとしています。

作業の流れ

Pi のリクエストは「モデルに一言尋ね、モデルが一言答える」というものではありません。より正確には、分岐を伴う一連のシーケンスです。

ここで最も重要なのは、ステップ4とステップ5の間の往復です。モデルはファイルシステムに直接触れることはなく、tool_call を提案するだけです。Pi はこの呼び出しを受け取り、ツール名とパラメータを検証し、存在する可能性のある拡張フックをトリガーし、実際の操作を実行し、tool_result をコンテキストに戻します。モデルは新しいコンテキストに基づいて次のステップを判断します。

これがコーディングエージェントと通常のチャットボットの違いです。チャットボットは主にテキスト内でタスクを完了しますが、コーディングエージェントはエンジニアリングシステムにアクセスする必要があるため、ツール、コンテキスト、状態を管理するためのハーネスが必要です。

Pi のデフォルトツールは非常に少ないです。

grep、find、ls のような読み取り専用ツールも有効化または制限できます。このツールセットは控えめに見えますが、コードの読み込み、コードの変更、テストの実行、エラーに基づく修正というプログラミングの閉ループをすでに形成しています。

この設計の背後にある問題は、「Pi がもっと多くのことをするかどうか」ではなく、「より多くのものがデフォルトでコアに含まれるべきかどうか」です。Pi の答えは明確です。必ずしもそうではありません。

なぜ多くの機能を急いで組み込まないのか

多くの AI プログラミング製品は、計画モード、TODO、サブエージェント、MCP、権限ポップアップ、バックグラウンドタスク、ブラウザツールなどを製品に組み込みます。これにより、すぐに使い始めることができますが、代償も伴います。モデルが実際にどのようなコンテキストを受け取ったのかを知るのが難しくなり、製品のワークフローを自分のワークフローに変更することも難しくなります。

Pi のアプローチは逆です。コアを非常に小さく保ち、ワークフローを外部に配置します。

これは「機能が足りない」のではなく、製品のトレードオフです。コアはエージェントループのみを管理し、具体的なワークフローはユーザーとチーム自身が組み合わせることに任せます。

例えば、Pi にはデフォルトで DeepSearch が組み込まれていません。しかし、これは深度検索ができないという意味ではありません。Pi の考え方に沿ったより良い方法は、deep_search ツールを登録する拡張機能を作成し、Tavily、Exa、Brave Search、または社内検索を接続し、必要に応じてモデルに呼び出させることです。

これは「検索ボタン」を製品にハードコーディングするのとは異なります。前者はエージェントの機能を拡張しているのに対し、後者は製品がワークフローを決定しています。

重要な点：自分のワークフローを拡張する方法

Pi を単に「試す」だけでなく、実際に活用するには、自分のワークフローを拡張することが重要です。

ここで混同しやすいのは、Pi には「プラグイン」という拡張方法しかないわけではないということです。むしろ、プロジェクトルール、タスクメソッド、実際のツール、共有可能なパッケージという4つの層の入り口が提供されています。まず、自分が何を定着させたいのかを判断する必要があります。

私の理解では、Skill は作業マニュアル、Extension は実行可能なプラグイン、Package は配布コンテナです。

例えば、現在のこのブログのワークフローは次のように分解できます。

これは単に「プラグインをインストールする」と言うよりも正確です。なぜなら、多くのワークフローはコードを書く必要がなく、良いルールやスキルがあれば十分だからです。しかし、エージェントに外部検索、データベース検索、CI の呼び出し、危険なコマンドのインターセプトなどの新しい機能を追加したい場合は、Extension を書くべきです。

Extension：真のプラグイン層

Pi の Extension は TypeScript モジュールです。いくつかの種類のことができます。

Extension はグローバルに配置することも、プロジェクト内に配置することもできます。

~/.pi/agent/extensions/      # グローバル拡張機能、すべてのプロジェクトで利用可能
.pi/extensions/              # プロジェクト拡張機能、現在のプロジェクトでのみ利用可能

一時的な拡張機能をテストするには、次のようにします。

pi -e ./my-extension.ts

自動検出ディレクトリに配置した後、Pi で次のように使用できます。

/reload

extensions、skills、prompts、context files を再読み込みします。

これが Pi の最も価値のある点だと私は思います。単に「モデルにコードを書いてもらう」だけでなく、モデルのために制御可能な作業環境を設計しているのです。Extension はモデルが呼び出せる機能を決定し、hooks はどの動作をインターセプトするかを決定し、commands は自分のワークフローがどのようにトリガーされるかを決定します。

Skill：すべてをプラグインとして書かない

ある機能が主に「どうやるか」であり、「実際の API を呼び出す」または「プログラムを実行する」ではない場合、それは Skill として書くのに適しています。

Skill の構造は通常次のとおりです。

my-skill/
  SKILL.md
  scripts/
  templates/
  references/

Pi は起動時に完全なスキルをすべてコンテキストに詰め込むことはありません。まずスキルの名前と説明を読み込み、タスクが一致したときにモデルに完全な SKILL.md を読み込ませます。これは段階的開示と呼ばれます。利点は、複雑な方法論を保存できる一方で、毎回コンテキストを汚染する必要がないことです。

例えば、「良い記事を書く」「公式アカウントに公開する」「ブラウザ QA を行う」などは、より Skill に近いものです。それらの価値は主に手順、判断基準、参考資料にあり、LLM が呼び出し可能なツールを登録する必要があるとは限りません。

Package：自分のワークフローをパッケージ化する

安定した機能セットができた場合は、それを Pi Package として作成することを検討できます。

Package には次のものが含まれます。

インストール方法は次のとおりです。

pi install npm:@scope/my-pi-package
pi install git:github.com/user/repo@v1
pi install ./relative/path/to/package
pi list
pi remove npm:@scope/my-pi-package
pi update --extensions

デフォルトのインストールは個人設定に書き込まれます。チームプロジェクトで共有したい場合は、プロジェクトレベルの設定を使用し、パッケージを .pi/settings.json に記録できます。これにより、他の人がプロジェクトに入って Pi を起動したときに、不足しているパッケージが自動的に補完されます。

ただし、ここでも非常に注意が必要です。Package、Extension、Skill はすべてエージェントの動作に影響を与える可能性があります。サードパーティのパッケージはブラウザプラグインのような低権限の装飾ではなく、コードを実行したり、モデルにコマンドを実行させたりする可能性があります。インストールする前にソースコードを確認する必要があります。

したがって、私は Pi の拡張機能を次の順序で学習します。

1. まず AGENTS.md を使用してプロジェクトルールを明確に記述します。
2. 次に、繰り返しのメソッドを Skill にします。
3. 実際のツール機能が必要な場合は、Extension を記述します。
4. 複数のプロジェクトで再利用する場合は、最後に Package にします。

このように学習する方が安定しています。いきなりプラグインを書くのではなく、まずワークフローを「ルール、メソッド、ツール、配布」の4つのカテゴリに分解し、次に各カテゴリを Pi のどの層に配置するかを決定します。

ソースコードから何が見えるか

Pi のソースコードを見たとき、各関数を追うことよりも、いくつかのファイルがそれぞれどの設計層を表しているかを見るのが最も役立ちました。

これらを合わせると、Pi の心臓部がほぼ完成します。まずコンテキストとツールを組み立て、次にリクエストをモデルに渡します。モデルがツールを呼び出す必要がある場合、Pi がツールを実行します。結果が返されると、ループが続行されます。

したがって、Pi の「極めてシンプル」は空虚な言葉ではありません。ソースコードの構造自体もこの考えを表現しています。エージェントループ、ハーネス、コーディングツール、リソースローダー、拡張システムを分離し、各層が比較的明確です。

Pi の境界

Pi は非常に自由度が高いですが、自由度が高いからといって安全であるとは限りません。

Pi パッケージと拡張機能はコードを実行できます。スキルもモデルにスクリプトの実行を指示する可能性があります。bash は実際のシステムにアクセスできます。公式ドキュメントとセキュリティ分析は、サードパーティのパッケージ、拡張機能、スキルは自分でレビューする必要があることを警告しています。

私は Pi の境界を3つの点として理解しています。

1. サンドボックスではない：これを自然な隔離環境として扱わないでください。危険なプロジェクトはコンテナ、一時ディレクトリ、またはクリーンなワークツリーに配置するのが最善です。
2. 権限を判断しない：Pi の核となる哲学は、多くのポップアップでリスクを管理することではなく、ツール、コンテキスト、拡張機能を自分で制御することです。
3. エンジニアリングの境界を理解している人に適している：エージェントにコマンドを実行させるタイミング、読み取り専用ツールのみを与えるタイミング、git チェックポイントを最初に作成するタイミングを知る必要があります。

これも Pi と、より製品化されたエージェントとの違いです。製品化されたツールは、より多くのセキュリティとインタラクションの詳細をパッケージ化してくれますが、Pi はより直接的な制御権を与え、同時に多くの責任をユーザーに返します。

Pi をどのように学ぶべきか

Pi を学ぶ際、「どのようなコマンドがあるか」から始めることはお勧めしません。コマンドはすぐに調べられますが、本当に学ぶべきは次の質問です。

Claude Code や Codex を使用したことがある場合は、Pi を「分解して見る」機会として捉えることができます。同じようにモデルにコードを書かせるのに、なぜあるツールはブラックボックス製品のように見え、あるツールは改造可能なランタイムのように見えるのでしょうか？

この質問は、「Pi が特定のツールを置き換えられるか」という質問よりも問う価値があります。

最後に

Pi Agent の最も価値のある点は、AI プログラミングツールの中間層を公開していることです。

それは私たちに、コーディングエージェントの能力はモデルだけでなく、ハーネスの設計からも生まれることを思い出させます。モデルは思考を担当し、ハーネスはモデルが実際のエンジニアリング環境で行動できるようにします。コンテキストがどのように入力され、ツールがどのように出力され、結果がどのように戻され、拡張機能がどのように挿入されるか、これらの詳細がエージェントの信頼性、透明性、制御可能性を共同で決定します。

したがって、私は Pi を単に「Claude Code の代替品」とは見なしません。むしろ、開発者が研究し、改造するのに適したエージェントランタイムのようなものです。これを使って直接コードを書くこともできますし、自分のエージェントワークフローを設計する方法を学ぶこともできます。

次の実践編では、この考え方に沿って続けます。通常のチュートリアルではなく、Pi Extension を使用して deep_search ツールを作成し、外部検索機能をエージェントループに接続する方法を見ていきます。

参考文献