Pi Agent: Extension Basics
最終更新：2026-08-31
--- title: "拡張機能の基本" description: "Pi Agentの拡張メカニズムを学び、拡張のアーキテクチャ、ライフサイクル、開発フローを理解します。" order: 14 lang: ja
拡張機能はPi Agentを「そこそこ」から「すごい」へ変える——他人のものを使うもよし、自分で公開するもよし。
1. 拡張機能とは
拡張機能はPi Agentのプラグインメカニズムで、以下が可能です：
- 新しいツールの追加
- 新しいスキルの追加
- 新しいLLMプロバイダーの追加
- 新しいコマンドの追加
- Agentの動作の変更
TEXT
📖 参照専用
拡張機能の構造
├── manifest.yaml -> メタデータ（名前、バージョン、依存関係）
├── tools/ -> ツール定義
├── skills/ -> スキル定義
├── providers/ -> プロバイダーアダプター
├── hooks/ -> フック関数
└── templates/ -> プロンプトテンプレート
2. 拡張機能のインストール
(1) 公式リポジトリから
BASH
pi-agent ext install github-tools
pi-agent ext install database-query
(2) Gitリポジトリから
BASH
pi-agent ext install git+https://github.com/user/pi-ext-custom.git
(3) ローカルディレクトリから
BASH
pi-agent ext install ./my_extension
(4) 拡張機能の管理
BASH
pi-agent ext list
pi-agent ext update github-tools
pi-agent ext remove github-tools
3. 拡張機能の作成
(1) スキャフォールド
BASH
pi-agent ext create my_extension
(2) manifest.yaml
YAML
name: my_extension
version: "1.0.0"
description: "私のカスタム拡張機能"
author: "Alice"
min_pi_agent_version: "0.8.0"
dependencies:
- requests>=2.28.0
tools:
- tools/my_tool.py
skills:
- skills/my_skill.yaml
entry_point: hooks.py
(3) ツールの定義
PYTHON
# tools/my_tool.py
from pi_agent import tool
@tool(
name="weather_query",
description="Query weather for a city",
parameters={
"city": {"type": "string", "description": "City name"},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius"}
}
)
def weather_query(city: str, unit: str = "celsius") -> dict:
import requests
resp = requests.get(f"https://wttr.in/{city}?format=j1")
data = resp.json()
temp = data["current_condition"][0]["temp_C"]
if unit == "fahrenheit":
temp = int(temp) * 9 // 5 + 32
return {"city": city, "temperature": temp, "unit": unit}
4. 拡張機能のライフサイクル
(1) フック関数
PYTHON
# hooks.py
from pi_agent import ExtensionHook
class MyExtension(ExtensionHook):
def on_load(self, agent):
print(f"Loaded my_extension for {agent.name}")
def on_tool_call(self, agent, tool_name, params):
print(f"Tool called: {tool_name}")
def on_tool_result(self, agent, tool_name, result):
print(f"Tool result: {tool_name}")
def on_error(self, agent, error):
print(f"Error: {error}")
def on_unload(self, agent):
print("my_extension unloaded")
5. 拡張機能の公開
(1) パッケージ化
BASH
pi-agent ext package my_extension
# my_extension-1.0.0.tar.gz を生成
(2) 公式リポジトリに公開
BASH
pi-agent ext publish my_extension
(3) PyPIに公開
BASH
cd my_extension
python -m build
twine upload dist/*
❓ よくある質問
Q 拡張機能とスキルの違いは？
A スキルは単一の能力単位（プロンプト＋ツールの組み合わせ）です。拡張機能は完全なプラグインパッケージ（複数のツール、スキル、プロバイダー、フック）です。
Q 拡張機能の依存関係は？
A manifest.yamlのdependenciesで宣言します。Pi Agentが自動的に解決・インストールします。
Q 拡張機能のセキュリティレビューは？
A 公式リポジトリの拡張機能はレビュー済みです。サードパーティの拡張機能は自己責任で評価してください。まずサンドボックスでテストしましょう。
📖 まとめ
- 拡張機能はPi Agentのプラグインメカニズムで、ツール、スキル、プロバイダー、コマンドを追加
pi-agent ext installでインストール、pi-agent ext createで作成- manifest.yamlがメタデータを定義；tools/ と skills/ に機能を格納
- フック関数でライフサイクルイベントを処理
- 公式リポジトリまたはPyPIに公開可能
📝 練習問題
- 基礎（難易度：⭐）: 公式拡張機能をインストールし、そのツールを使用してください。
- 中級（難易度：⭐⭐）: ツールとスキルを含むシンプルな天気照会拡張機能を作成してください。
- 上級（難易度：⭐⭐⭐）: ツール、スキル、フック、ユニットテストを含む完全な拡張機能を作成してください。
