Pilot Protocol

A pilha de rede para agentes de IA.
Endereços. Portas. Túneis. Encriptação. Confiança.

Docs  ·  Wire Spec  ·  Whitepaper  ·  IETF Draft  ·  Agent Skills  ·  Polo (Live Dashboard)

---

A internet foi construída para humanos. Os agentes de IA não têm endereço, nem identidade, nem forma de serem alcançados. O Pilot Protocol é uma rede overlay que dá aos agentes o que a internet deu aos dispositivos: um endereço permanente, canais encriptados e autenticados, e um modelo de confiança -- tudo em camadas sobre UDP padrão.

Os agentes registam-se num serviço de rendezvous para descoberta e NAT traversal. Os dados da aplicação fluem diretamente entre pares no caminho direto; quando o NAT hole-punching falha (por exemplo, NAT simétrico), o beacon retransmite o tráfego ainda encriptado ponta-a-ponta como fallback. Não é uma API. Não é uma framework. É infraestrutura.

---

O problema

Hoje, os agentes comunicam através de APIs centralizadas. Cada mensagem passa por uma plataforma -- a plataforma vê todo o tráfego, controla o acesso e torna-se um ponto único de falha.```mermaid graph LR A1[Agent A] -->|HTTP API| P[Platform / Cloud] A2[Agent B] -->|HTTP API| P A3[Agent C] -->|HTTP API| P style P fill:#f66,stroke:#333,color:#fff style A1 fill:#4a9,stroke:#333,color:#fff style A2 fill:#4a9,stroke:#333,color:#fff style A3 fill:#4a9,stroke:#333,color:#fff

O Pilot Protocol tira a plataforma do caminho dos dados. Um serviço leve de **rendezvous** lida com a descoberta e a travessia de NAT, mas, uma vez que os agentes se encontram, eles conversam diretamente por túneis autenticados e criptografados:```mermaid
graph LR
    A1[Agent A<br/><small>0:0000.0000.0001</small>] <-->|Encrypted UDP Tunnel| A2[Agent B<br/><small>0:0000.0000.0002</small>]
    A1 <-->|Encrypted UDP Tunnel| A3[Agent C<br/><small>0:0000.0000.0003</small>]
    A2 <-->|Encrypted UDP Tunnel| A3
    A1 -.->|discovery| RV[Rendezvous]
    A2 -.->|discovery| RV
    A3 -.->|discovery| RV
    style A1 fill:#4a9,stroke:#333,color:#fff
    style A2 fill:#4a9,stroke:#333,color:#fff
    style A3 fill:#4a9,stroke:#333,color:#fff
    style RV fill:#888,stroke:#333,color:#fff

O que os agentes recebem```bash

pilotctl info # show your address, hostname, peer count pilotctl set-hostname my-agent # claim a name other agents can resolve pilotctl find agent-alpha # resolve a public demo peer pilotctl ping agent-alpha # round-trip over the encrypted tunnel pilotctl bench agent-alpha # 1 MB echo benchmark

Assim que você tiver um peer confiável, a mensagem agente-a-agente usa o serviço de troca de dados na porta 1001:```bash
# Send a structured message (waits for reply by default)
pilotctl send-message other-agent --data "hello"

# Read messages delivered to your inbox
pilotctl inbox

# Read a specific message
pilotctl inbox read <id>

Para mensagens de porta bruta de nível inferior:```bash

on the sender

pilotctl send other-agent 1000 --data "hello"

on the receiver

pilotctl recv 1000 --count 5 --timeout 30s

Todo comando CLI suporta `--json` para saída estruturada — consulte a [referência da CLI](https://pilotprotocol.network/docs/cli-reference) para a superfície completa.

<details>
<summary><strong>Exemplo de saída JSON</strong></summary>```json
$ pilotctl --json info
{"status":"ok","data":{"address":"0:0000.0000.0005","node_id":5,"hostname":"my-agent","peers":3,"connections":1,"uptime_secs":3600}}

$ pilotctl --json find other-agent
{"status":"ok","data":{"hostname":"other-agent","address":"0:0000.0000.0003"}}

$ pilotctl --json recv 1000 --count 1
{"status":"ok","data":{"messages":[{"seq":0,"port":1000,"data":"hello","bytes":5}]}}

$ pilotctl --json find nonexistent
{"status":"error","code":"not_found","message":"cannot find \"nonexistent\" — hostname not found or no mutual trust","hint":"establish trust first: pilotctl handshake nonexistent \"reason\""}

---

Acesso programático (SDKs)

Depois que o daemon estiver em execução, você pode interagir com os agentes programaticamente através do SDK em vez da CLI. Todos os três SDKs se comunicam com o daemon local do Pilot através do seu IPC de socket Unix e expõem toda a superfície do agente — handshake, trust, send, receive, stream e gateway — na linguagem de sua escolha.

Linguagem	Pacote	Início rápido
Node.js / TypeScript	pilotprotocol no npm	npm install pilotprotocol — consulte o README do sdk-node
Python	pilotprotocol no PyPI	pip install pilotprotocol — consulte o README do sdk-python
Swift / iOS / macOS	pilotprotocol no GitHub	Adicione via Package.swift — consulte o README do sdk-swift

Um exemplo mínimo de primeira consulta em Node.js após daemon start:```js import { createPilot, createAgent } from 'pilotprotocol';

const pilot = await createPilot(); const conn = await pilot.handshake('agent-alpha', 'hello'); await conn.trust();

// Send a message await conn.send(3000, Buffer.from('ping'));

// Receive on any port const msgs = await conn.recv(3000, { count: 1, timeout: 10 }); console.log('Received:', msgs[0].data.toString());

Consulte o README de cada SDK para obter a documentação completa da API, exemplos de streaming e configuração específica da plataforma (simulador iOS, extras do PyPI, etc.).

## Destaques

<table>
<tr>
<td width="50%" valign="top">

**Endereçamento**
- Endereços virtuais de 48 bits (`N:NNNN.HHHH.LLLL`)
- Portas de 16 bits com atribuições bem conhecidas
- Descoberta baseada em hostname