Pi Agent: Package Management
Última atualização: 2026-08-31
--- title: "Gerenciamento de Pacotes" description: "Aprenda o sistema de gerenciamento de pacotes do Pi Agent para instalar, criar, publicar e versionar pacotes de skills e ferramentas." order: 17 lang: pt-br
Pacotes são as "caixas de entrega" de skills e ferramentas — empacotados, instalação com um clique, compartilhamento em equipe.
1. O que são Pacotes Pi Agent
Um Package é uma unidade distribuível de skills, ferramentas, templates e configuração:
Package vs Extension vs Skill
├── Skill → Single capability (e.g., code_review)
├── Extension → Plugin (tools + skills + hooks)
└── Package → Distribution carrier (multiple extensions + skills + templates)
2. Comandos de Pacote
(1) Buscar
pi-agent pkg search code-review
pi-agent pkg search --category devops
pi-agent pkg search --author alice
(2) Instalar
pi-agent pkg install code-review-tools
pi-agent pkg install devops-toolkit@1.2.0
pi-agent pkg install git+https://github.com/user/my-pkg.git
(3) Gerenciar
pi-agent pkg list
pi-agent pkg info code-review-tools
pi-agent pkg update
pi-agent pkg update devops-toolkit
pi-agent pkg remove code-review-tools
3. Criando Pacotes
(1) Estrutura do Pacote
my-dev-tools/
├── pkg.yaml
├── tools/
│ ├── git_helper.py
│ └── docker_tool.py
├── skills/
│ ├── code_review.yaml
│ └── deploy.yaml
├── templates/
│ └── commit_msg.yaml
└── tests/
└── test_tools.py
(2) pkg.yaml
name: my-dev-tools
version: "1.0.0"
description: "Development toolset"
author: "Alice"
license: "MIT"
repository: "https://github.com/alice/my-dev-tools"
min_pi_agent_version: "0.8.0"
dependencies:
- git-tools>=1.0.0
tools:
- tools/git_helper.py
- tools/docker_tool.py
skills:
- skills/code_review.yaml
- skills/deploy.yaml
categories:
- development
- devops
tags:
- git
- docker
- code-review
4. Gerenciamento de Versão
(1) Versionamento Semântico
Major.Minor.Patch
1.0.0 -> 1.0.1 -> 1.1.0 -> 2.0.0
Major: mudanças de API incompatíveis
Minor: novos recursos compatíveis com versões anteriores
Patch: correções de bugs compatíveis com versões anteriores
(2) Restrições de Versão
dependencies:
- git-tools>=1.0.0 # 1.0.0 ou superior
- docker-tools~=2.1 # 2.1.x (compatível com 2.1)
- utils>=1.0,<2.0 # série 1.x
5. Publicando Pacotes
pi-agent pkg validate my-dev-tools
pi-agent pkg test my-dev-tools
pi-agent pkg build my-dev-tools
pi-agent pkg publish my-dev-tools
pi-agent pkg install my-dev-tools
6. Repositórios de Pacotes
(1) Repositório Oficial
pi-agent pkg search --repo official
(2) Repositórios de Terceiros
package_repos:
- name: official
url: "https://pkg.pi-agent.dev"
- name: company
url: "https://pkg.internal.company.com"
auth: token
❓ Perguntas Frequentes
P: Pacote vs extensão? R: Pacotes são carregadores de distribuição; extensões são plugins em tempo de execução. Um pacote pode conter múltiplas extensões. Pacotes focam em "distribuição e versionamento"; extensões em "carregamento de funcionalidades." P: Conflitos de dependências? R: Pi Agent usa um resolvedor de dependências similar ao pip. Se conflitos não puderem ser resolvidos automaticamente, ele solicita especificação manual de versão. P: Atualizações seguras? R: Atualizações Minor e Patch são compatíveis com versões anteriores. Atualizações Major precisam de revisão do CHANGELOG.
❓ Resumo
- Pacotes são unidades distribuíveis de skills, ferramentas, templates
- pkg.yaml define metadados com declarações de dependências
- Versionamento semântico; sintaxe de restrições similar ao pip
- Repositórios oficiais e privados suportados
- Workflow completo de busca, instalação, atualização, desinstalação e publicação
📝 Exercícios
- Básico (Dificuldade: ⭐): Busque e instale um pacote da comunidade, use sua skill.
- Intermediário (Dificuldade: ⭐⭐): Crie um pacote com 2 ferramentas e 1 skill, teste localmente.
- Avançado (Dificuldade: ⭐⭐⭐): Configure um repositório de pacotes privado, publique e instale pacotes de ferramentas internos.
