Pilot Protocol

Lo stack di rete per gli agenti AI.
Indirizzi. Porte. Tunnel. Crittografia. Fiducia.

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

---

Internet è stato costruito per gli esseri umani. Gli agenti AI non hanno un indirizzo, un'identità, né un modo per essere raggiunti. Pilot Protocol è una rete overlay che dà agli agenti ciò che Internet ha dato ai dispositivi: un indirizzo permanente, canali cifrati autenticati e un modello di fiducia -- il tutto stratificato sopra UDP standard.

Gli agenti si registrano presso un servizio di rendezvous per la scoperta e il NAT traversal. I dati applicativi fluiscono direttamente tra i peer sul percorso diretto; quando l'hole-punching NAT fallisce (ad es. NAT simmetrico), il beacon inoltra il traffico, comunque cifrato end-to-end, come fallback. Non è un'API. Non è un framework. È infrastruttura.

---

Il problema

Oggi gli agenti comunicano attraverso API centralizzate. Ogni messaggio passa attraverso una piattaforma -- la piattaforma vede tutto il traffico, controlla l'accesso e diventa un singolo punto di guasto.```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

Il Pilot Protocol rimuove la piattaforma dal percorso dei dati. Un leggero servizio di **rendezvous** gestisce la scoperta e il NAT traversal, ma una volta che gli agenti si trovano tra loro, comunicano direttamente tramite tunnel autenticati e cifrati:```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

Cosa ottengono gli agenti```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

Una volta che hai un peer attendibile, la messaggistica da agente ad agente utilizza il servizio di scambio dati sulla 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>

Per la messaggistica raw di porte di livello inferiore:```bash

on the sender

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

on the receiver

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

Ogni comando CLI supporta `--json` per l'output strutturato — consulta il [riferimento CLI](https://pilotprotocol.network/docs/cli-reference) per l'intera superficie di utilizzo.

<details>
<summary><strong>Esempio di output 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\""}

---

Accesso programmatico (SDK)

Una volta che il daemon è in esecuzione, puoi interagire con gli agenti in modo programmatico tramite l'SDK invece della CLI. Tutti e tre gli SDK comunicano con il daemon locale Pilot attraverso il suo IPC su socket Unix ed espongono l'intera superficie dell'agente — handshake, trust, send, receive, stream e gateway — nella lingua che preferisci.

Linguaggio	Pacchetto	Avvio rapido
Node.js / TypeScript	pilotprotocol su npm	npm install pilotprotocol — vedi sdk-node README
Python	pilotprotocol su PyPI	pip install pilotprotocol — vedi sdk-python README
Swift / iOS / macOS	pilotprotocol su GitHub	Aggiungi tramite Package.swift — vedi sdk-swift README

Un esempio minimale di prima query in Node.js dopo 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());

Consulta il README di ciascun SDK per la documentazione completa delle API, esempi di streaming e configurazione specifica per piattaforma (simulatore iOS, extra PyPI, ecc.).

## In evidenza

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

**Indirizzamento**
- Indirizzi virtuali a 48 bit (`N:NNNN.HHHH.LLLL`)
- Porte a 16 bit con assegnazioni well-known
- Discovery basata su hostname