Skip to main content
O Pi Agent é o agente de codificação em terminal distribuído pela IplanRio para as secretarias municipais. O binário do Pi é neutro: quem define skills, agentes, comandos e integrações é o pacote instalado junto com ele. Esse desenho existe para que cada público municipal receba só o que precisa. Uma equipe de desenvolvimento da SMS instala o pacote de engenharia; uma equipe de dados da SME poderá instalar um pacote analítico no futuro, sem reinstalar nem reconfigurar o agente.

​
Por Que Pacotes

Um pacote Pi entrega, em um único artefato versionado:
  • Skills: doutrina de trabalho carregada sob demanda pelo agente
  • Agentes: perfis especializados com modelo e permissões próprias
  • Comandos: atalhos de prompt em pt-BR, como /planejar e /revisar
  • Extensões: ferramentas adicionais registradas no agente em tempo de execução
  • Configuração recomendada: provedores, modelos habilitados e padrões de sessão
O Pi sozinho não traz MCP, diagnósticos de código nem subagentes. Essas capacidades chegam pelas extensões do pacote, e por isso a escolha do pacote define a experiência.
A IplanRio mantém o catálogo de pacotes, o instalador e as configurações recomendadas. Cada instalação fica isolada em ~/.pi/agent e não interfere em outras ferramentas de IA já instaladas na máquina.

​
Solicitar Acesso

O acesso aos modelos usa a mesma Virtual Key do Bifrost, o proxy centralizado de IA da IplanRio.
  1. Acesse o canal #peça-permissão no Discord da IplanRio
  2. Envie nome completo, email institucional, área ou secretaria e justificativa de uso
  3. Aguarde a aprovação da equipe de IA
  4. Receba a Virtual Key por email
Quem já usa o OpenCode deve pedir à equipe de IA que confirme se a Virtual Key também autoriza os modelos do dev-vpop. Não presuma que uma chave antiga possui o catálogo novo.
A Virtual Key é pessoal e intransferível. Nunca coloque a chave em repositório, ticket, print ou canal público.

​
Pré-requisitos

Confirme o Node antes de começar:
No Windows, instale o Node pelo site oficial. No WSL, instale o Node dentro da distribuição Linux, não no Windows host.

​
Instalação

O instalador recebe o nome do pacote como primeiro argumento. O ecossistema de Pi Agents da IplanRio foi desenhado para hospedar múltiplos pacotes temáticos na mesma infraestrutura centralizada.
Saída esperada ao final:
Omita --virtual-key para reaproveitar a credencial já gravada. Sem credencial existente, o instalador pede a chave em modo oculto no terminal.
A disponibilidade pública do instalador depende do provisionamento de acesso pela equipe de IA. Este é o comando suportado: solicite acesso no Discord antes de executá-lo.

​
O que o instalador faz

  1. Baixa o catálogo global da IplanRio (https://storage.googleapis.com/iplanrio-pi/manifests/catalog.json), valida o schema e resolve o pacote solicitado
  2. Confere o SHA-256 do próprio instalador, das configurações e dos metadados do pacote
  3. Instala o Pi na versão fixada com --ignore-scripts
  4. Grava credencial, settings.json e mcp.json em ~/.pi/agent com permissão restrita
  5. Instala o pacote e roda um diagnóstico determinístico
Um settings.json já existente é preservado: o instalador faz merge das chaves gerenciadas e cria backup com timestamp antes de sobrescrever.

​
Simular antes de aplicar

​
Biblioteca de Pacotes da IplanRio

O catálogo central de pacotes da Prefeitura do Rio organiza as capacidades por perfil de time e stack técnica. Novos pacotes são publicados com versionamento semântico imutável e distribuídos automaticamente pelo mesmo ecossistema: Para instalar qualquer pacote do catálogo, basta passar o nome dele no comando de instalação:

​
Verificação

Abra o agente e rode o diagnóstico:
O comando é determinístico e não consome cota de modelo. Ele confere Node, versão do Pi, diretório do agente, credencial, settings.json, pacote instalado, mcp.json, modelos registrados, sessões e isolamento em relação a outras ferramentas. Para checar a versão do Pi fora do agente:

​
Atualizações

Pacotes gerenciados pela IplanRio se atualizam sozinhos. A cada início de sessão o agente consulta o catálogo, no máximo uma vez a cada 24 horas, e instala a versão nova quando existe.
Reinicie o Pi para ativar a versão baixada. Para forçar uma verificação imediata ou ver o estado atual, use o comando de atualização do pacote dentro do agente. Atualizar o Pi em si, ou aplicar novas configurações recomendadas, exige reexecutar o instalador. A credencial existente é preservada.

​
Desinstalação

1

Remover o pacote da configuração

Liste a fonte instalada e remova o pacote pelo Pi:
2

Remover o Pi

3

Remover credencial e configuração

Isso apaga credencial, configurações e o registro do pacote gerenciado. Faça backup antes se quiser preservar ajustes locais.
No Windows, o diretório equivalente é %USERPROFILE%\.pi\agent.

​
Troubleshooting

Node >=22.19 e obrigatorio: instale o Node 22 ou superior. No WSL, instale dentro da distribuição Linux com nvm install 22. Pi foi instalado, mas o comando pi nao esta disponivel no PATH atual: o diretório global do npm não está no PATH. Rode npm prefix -g, adicione o subdiretório bin ao PATH e abra um novo terminal. Pacote 'x' nao encontrado no canal 'stable': o nome do pacote não existe no catálogo. Confira a tabela do catálogo acima. Checksum SHA-256 invalido: o download foi corrompido ou interceptado. Repita a instalação em rede confiável e, se persistir, avise no Discord da IplanRio sem executar o arquivo. Virtual Key obrigatoria: passe --virtual-key ou rode o instalador sem --yes para digitar a chave de forma oculta. Doctor: configuracao Pi incompleta ou invalida: rode /vpop:doctor --json dentro do agente para ver qual verificação falhou e leve a saída ao canal de suporte.

dev-vpop v1

Skills, agentes, modelos, MCP e política de custo do pacote de desenvolvimento

OpenCode

Alternativa em terminal já em uso nas secretarias, com a mesma Virtual Key