Pilot Protocol

La pile réseau pour les agents IA.
Adresses. Ports. Tunnels. Chiffrement. Confiance.

Docs  ·  Spécification du protocole  ·  Livre blanc  ·  Brouillon IETF  ·  Compétences d'agent  ·  Polo (tableau de bord en direct)

---

Internet a été conçu pour les humains. Les agents IA n'ont ni adresse, ni identité, ni moyen d'être joints. Pilot Protocol est un réseau superposé qui donne aux agents ce qu'Internet a donné aux appareils : une adresse permanente, des canaux chiffrés authentifiés et un modèle de confiance -- le tout bâti au-dessus d'UDP standard.

Les agents s'enregistrent auprès d'un service de rendez-vous pour la découverte et la traversée de NAT. Les données applicatives circulent directement entre pairs sur le chemin direct ; lorsque le perçage de trou NAT échoue (par exemple avec un NAT symétrique), le beacon relaie le trafic toujours chiffré de bout en bout comme solution de repli. Ce n'est pas une API. Ce n'est pas un framework. C'est une infrastructure.

---

Le problème

Aujourd'hui, les agents communiquent via des API centralisées. Chaque message passe par une plateforme -- la plateforme voit tout le trafic, contrôle l'accès et devient un point de défaillance unique.```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

Le protocole Pilot retire la plateforme du chemin des données. Un service léger de **rendez-vous** gère la découverte et la traversée NAT, mais une fois que les agents se trouvent, ils communiquent directement via des tunnels authentifiés et chiffrés :```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

Ce que les agents obtiennent```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

Une fois que vous disposez d'un pair de confiance, la messagerie agent-à-agent utilise le service d'échange de données sur le port 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>

Pour la messagerie brute de port de bas niveau :```bash

on the sender

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

on the receiver

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

Chaque commande CLI prend en charge `--json` pour une sortie structurée — consultez la [référence CLI](https://pilotprotocol.network/docs/cli-reference) pour l'ensemble des fonctionnalités disponibles.

<details>
<summary><strong>Exemple de sortie 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\""}

---

Accès programmatique (SDK)

Une fois le daemon en cours d'exécution, vous pouvez interagir avec les agents par programmation via le SDK au lieu de la CLI. Les trois SDK communiquent avec le daemon Pilot local via son IPC par socket Unix et exposent toute la surface de l'agent — handshake, trust, send, receive, stream et gateway — dans le langage de votre choix.

Langage	Paquet	Démarrage rapide
Node.js / TypeScript	pilotprotocol sur npm	npm install pilotprotocol — voir sdk-node README
Python	pilotprotocol sur PyPI	pip install pilotprotocol — voir sdk-python README
Swift / iOS / macOS	pilotprotocol sur GitHub	Ajouter via Package.swift — voir sdk-swift README

Un exemple minimal de première requête Node.js aprè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());

Consultez le README de chaque SDK pour la documentation complète de l'API, des exemples de streaming et une configuration spécifique à chaque plateforme (simulateur iOS, extras PyPI, etc.).

## Points forts

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

**Adressage**
- Adresses virtuelles 48 bits (`N:NNNN.HHHH.LLLL`)
- Ports 16 bits avec attributions bien connues
- Découverte basée sur le nom d'hôte