English 中文 العربية 日本語 Português

Pi Agent: Extension Basics

Última atualização: 2026-08-31

--- title: "Fundamentos de Extensoes" description: "Aprenda o mecanismo de extensoes do Pi Agent, entenda a arquitetura de extensoes, ciclo de vida, fluxo de desenvolvimento e publicacao." order: 14 lang: pt-br

Extensões levam o Pi Agent de "bom o bastante" para "excelente" — use as de outros ou publique as suas.

1. O que são Extensões

Extensões são o mecanismo de plugin do Pi Agent que podem:

TEXT 📖 Somente leitura 
Extension Structure
├── manifest.yaml    -> Metadata (name, version, dependencies)
├── tools/          -> Tool definitions
├── skills/         -> Skill definitions
├── providers/      -> Provider adapters
├── hooks/          -> Hook functions
└── templates/      -> Prompt templates

2. Instalando Extensões

(1) Do Repositório Oficial

BASH 
pi-agent ext install github-tools
pi-agent ext install database-query

(2) De Repositório Git

BASH 
pi-agent ext install git+https://github.com/user/pi-ext-custom.git

(3) De Diretório Local

BASH 
pi-agent ext install ./my_extension

(4) Gerenciando Extensões

BASH 
pi-agent ext list
pi-agent ext update github-tools
pi-agent ext remove github-tools

3. Criando Extensões

(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) Definir uma Ferramenta

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. Ciclo de Vida de Extensão

(1) Funções Hook

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. Publicando Extensões

(1) Empacotar

BASH 
pi-agent ext package my_extension
# Generates my_extension-1.0.0.tar.gz

(2) Publicar no Repositório Oficial

BASH 
pi-agent ext publish my_extension

(3) Publicar no PyPI

BASH 
cd my_extension
python -m build
twine upload dist/*

❓ Perguntas Frequentes

P: Extensão vs skill? R: Uma skill é uma unidade de capacidade única (combo de prompt + ferramenta). Uma extensão é um pacote de plugin completo (múltiplas ferramentas, skills, provedores, hooks). P: Dependências de extensão? R: Declare em dependencies do manifest.yaml. Pi Agent resolve e instala automaticamente. P: Revisão de segurança para extensões? R: Extensões do repositório oficial são revisadas. Extensões de terceiros precisam de sua própria avaliação de risco. Teste em sandbox primeiro.

❓ Resumo

📝 Exercícios

  1. Básico (Dificuldade: ⭐): Instale uma extensão oficial e use sua ferramenta.
  2. Intermediário (Dificuldade: ⭐⭐): Crie uma extensão simples de consulta de clima com ferramenta e skill.
  3. Avançado (Dificuldade: ⭐⭐⭐): Crie uma extensão completa com ferramenta, skill, hooks e testes unitários.
Web-Tutorial.com

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

100%