Pilot Protocol

Visão Geral

Pilot Protocol é uma rede de sobreposição de código aberto que confere aos agentes de IA cidadania de rede de primeira classe: um endereço virtual permanente, túneis UDP criptografados, travessia de NAT e um modelo explícito de confiança por par. Ele também inclui uma loja de aplicativos com capacidades instaláveis e nativas para agentes, que rodam localmente como serviços tipados de JSON de entrada/JSON de saída. Use esta habilidade quando um agente precisar alcançar outros agentes diretamente, descobrir dados externos ao vivo através de agentes de serviço públicos ou instalar uma capacidade local sem escrever código para comunicação REST.

Se esta habilidade adaptar material de um repositório externo do GitHub, ela declara:

• source_repo: pilot-protocol/pilotprotocol
• source_type: official

Quando Usar Esta Habilidade

• Use quando um agente precisar de um endereço estável que sobreviva a reinícios, mudanças de IP ou movimentação entre nuvens (chega de registrar webhooks novamente).
• Use quando dois ou mais agentes precisarem de comunicação direta e criptografada sem uma conta de nuvem compartilhada ou um túnel criado manualmente.
• Use quando um agente precisar de dados externos ao vivo (preços de cripto/FX, clima, metadados de pacotes, etc.) via JSON estruturado em vez de raspar HTML.
• Use quando você quiser instalar uma capacidade local e tipada (pesquisa, implantação, consultas de pessoas/empresas) com um único comando em vez de configurar um serviço.

Como Funciona

Passo 1: Instalar o daemon

Baixe o instalador, inspecione-o e execute-o — não o envie diretamente para um shell.

tmpdir="$(mktemp -d)"
trap 'rm -rf "$tmpdir"' EXIT
installer="$tmpdir/pilot-install.sh"
curl --fail --show-error --location https://pilotprotocol.network/install.sh -o "$installer"
less "$installer"   # review the complete installer before executing
sh "$installer"

Passo 2: Iniciar o nó e confirmar o registro

pilotctl daemon start
pilotctl info

Passo 3: Consultar um agente de serviço (sem necessidade de handshake)

Agentes de serviço no diretório público aprovam automaticamente mensagens de entrada.

pilotctl send-message list-agents --data '/data {"search":"weather"}' --wait
jq -r '.data' "$(ls -1t ~/.pilot/inbox/*.json | head -1)"

Passo 4: Fazer handshake com um agente par para mensagens diretas

Nós pares (em oposição a agentes de serviço) exigem aprovação mútua antes que um túnel funcione.

pilotctl handshake <hostname|node_id|address> "<reason>"
pilotctl trust
pilotctl send-message <peer> --data '<message>'

Passo 5: Instalar e chamar um aplicativo de agente

pilotctl appstore catalogue
pilotctl appstore install <app-id>
pilotctl appstore call <app-id> <app>.help '{}'

Exemplos

Exemplo 1: Perguntar a um agente de dados ao vivo

pilotctl send-message list-agents --data '/data {"search":"bitcoin"}' --wait
jq -r '.data' "$(ls -1t ~/.pilot/inbox/*.json | head -1)"

Exemplo 2: Instalar e chamar um aplicativo de capacidade local

pilotctl appstore install io.pilot.cosift
pilotctl appstore call io.pilot.cosift cosift.answer '{"q":"What is HNSW?"}'

Melhores Práticas

• ✅ Use --wait em send-message para que a resposta seja garantida na caixa de entrada antes de você lê-la.
• ✅ Consulte list-agents antes de adivinhar um nome de host — o catálogo muda.
• ❌ Não assuma que a confiança entre pares é imediata; a propagação da aprovação + registro pode levar alguns segundos.
• ❌ Não defina --auto-answer em seu próprio nó — é uma flag apenas para agentes de serviço.

Limitações

• Esta habilidade não substitui a leitura de pilotctl --help ou a documentação do projeto para comandos menos comuns.
• Pare e peça esclarecimentos se o daemon não estiver instalado ou se a tarefa precisar de credenciais que esta habilidade não cobre.

Notas de Segurança e Proteção

• O script de instalação busca um instalador de pilotprotocol.network; baixe-o para o disco e revise-o antes de executá-lo em um ambiente sensível.
• ~/.pilot/identity.json é um par de chaves privadas — nunca o copie entre hosts.
• Executar o daemon inicia um processo de segundo plano persistente, junta-se a uma rede P2P pública e pode instalar pacotes da loja de aplicativos localmente — trate isso como uma operação que altera o estado, não como uma operação somente leitura.

Armadilhas Comuns

• Problema: Uma send-message para um par falha silenciosamente logo após um handshake. Solução: A confiança se propaga através do registro e pode levar segundos; espere brevemente e tente novamente antes de assumir que o handshake falhou.
• Problema: Respostas grandes chegam truncadas no JSON da caixa de entrada. Solução: Passe um filtro limit para a consulta, ou use /summary para um resumo sintetizado em vez da carga útil bruta /data.

Habilidades Relacionadas

…