Pi Agent: Extension Basics
Last updated: 2026-08-31
Extensions take Pi Agent from "good enough" to "great" — use others' or publish your own.
1. What Are Extensions
Extensions are Pi Agent's plugin mechanism that can:
- Add new tools
- Add new skills
- Add new LLM providers
- Add new commands
- Modify Agent behavior
TEXT
📖 Display only
Extension Structure
├── manifest.yaml -> Metadata (name, version, dependencies)
├── tools/ -> Tool definitions
├── skills/ -> Skill definitions
├── providers/ -> Provider adapters
├── hooks/ -> Hook functions
└── templates/ -> Prompt templates
2. Installing Extensions
(1) From Official Repo
BASH
pi-agent ext install github-tools
pi-agent ext install database-query
(2) From Git Repo
BASH
pi-agent ext install git+https://github.com/user/pi-ext-custom.git
(3) From Local Directory
BASH
pi-agent ext install ./my_extension
(4) Managing Extensions
BASH
pi-agent ext list
pi-agent ext update github-tools
pi-agent ext remove github-tools
3. Creating Extensions
(1) Scaffold
BASH
pi-agent ext create my_extension
(2) manifest.yaml
YAML
name: my_extension
version: "1.0.0"
description: "My custom extension"
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) Define a Tool
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. Extension Lifecycle
(1) Hook Functions
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. Publishing Extensions
(1) Package
BASH
pi-agent ext package my_extension
# Generates my_extension-1.0.0.tar.gz
(2) Publish to Official Repo
BASH
pi-agent ext publish my_extension
(3) Publish to PyPI
BASH
cd my_extension
python -m build
twine upload dist/*
FAQ
Q Extension vs skill?
A A skill is a single capability unit (prompt + tool combo). An extension is a complete plugin package (multiple tools, skills, providers, hooks).
Q Extension dependencies?
A Declare in manifest.yaml's dependencies. Pi Agent auto-resolves and installs.
Q Security review for extensions?
A Official repo extensions are reviewed. Third-party extensions need your own risk assessment. Test in sandbox first.
Summary
- Extensions are Pi Agent's plugin mechanism for tools, skills, providers, commands
- Install with
pi-agent ext install, create withpi-agent ext create - manifest.yaml defines metadata; tools/ and skills/ hold functionality
- Hook functions handle lifecycle events
- Publish to official repo or PyPI
Exercises
- Basic (Difficulty: ⭐): Install an official extension and use its tool.
- Intermediate (Difficulty: ⭐⭐): Create a simple weather query extension with tool and skill.
- Advanced (Difficulty: ⭐⭐⭐): Create a full extension with tool, skill, hooks, and unit tests.
