Pilot Protocol

La pila de red para agentes de IA.
Direcciones. Puertos. Túneles. Cifrado. Confianza.

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

---

Internet fue construido para humanos. Los agentes de IA no tienen dirección, ni identidad, ni forma de ser alcanzados. Pilot Protocol es una red superpuesta que les da a los agentes lo que internet les dio a los dispositivos: una dirección permanente, canales cifrados autenticados y un modelo de confianza -- todo ello sobre UDP estándar.

Los agentes se registran en un servicio de rendezvous para el descubrimiento y la traversía de NAT. Los datos de la aplicación fluyen directamente entre pares por la ruta directa; cuando el hole-punching de NAT falla (por ejemplo, NAT simétrico), el beacon retransmite el tráfico, que sigue estando cifrado de extremo a extremo, como respaldo. No es una API. No es un framework. Es infraestructura.

---

El problema

Hoy en día, los agentes se comunican a través de APIs centralizadas. Cada mensaje pasa por una plataforma -- la plataforma ve todo el tráfico, controla el acceso y se convierte en un único punto de fallo.```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

El Protocolo Pilot saca a la plataforma de la ruta de datos. Un servicio ligero de **rendezvous** gestiona el descubrimiento y la travesía de NAT, pero una vez que los agentes se encuentran entre sí, se comunican directamente a través de túneles autenticados y cifrados:```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

---

Qué obtienen los agentes```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 vez que tenga un par de confianza, la mensajería de agente a agente utiliza el servicio de intercambio de datos en el puerto 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 mensajería de puerto sin procesar de nivel inferior:```bash

on the sender

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

on the receiver

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

Cada comando de la CLI admite `--json` para obtener una salida estructurada — consulta la [referencia de la CLI](https://pilotprotocol.network/docs/cli-reference) para conocer toda la superficie disponible.

<details>
<summary><strong>Ejemplo de salida 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\""}

---

Acceso programático (SDKs)

Una vez que el daemon está en ejecución, puedes interactuar con los agentes de forma programática a través del SDK en lugar de la CLI. Los tres SDKs se comunican con el daemon local de Pilot mediante su IPC de socket Unix y exponen toda la superficie del agente — handshake, trust, send, receive, stream y gateway — en el lenguaje de tu elección.

Lenguaje	Paquete	Inicio rápido
Node.js / TypeScript	pilotprotocol en npm	npm install pilotprotocol — consulta el README de sdk-node
Python	pilotprotocol en PyPI	pip install pilotprotocol — consulta el README de sdk-python
Swift / iOS / macOS	pilotprotocol en GitHub	Añádelo mediante Package.swift — consulta el README de sdk-swift

Un ejemplo mínimo de primera consulta en Node.js después de 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 el README de cada SDK para obtener la documentación completa de la API, ejemplos de streaming y configuración específica de la plataforma (simulador de iOS, extras de PyPI, etc.).

## Aspectos destacados

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