... (truncated, N bytes total) into the JSON value. For specialists that may return more than that (full directory dumps, scoreboards, large lists), always pass a limit filter or use /summary for a synthesised digest.
- Every specialist accepts two standardized filters — page and page_size — which the wrapper translates into whatever the upstream API actually uses (page number, offset, or cursor). Replies return complete, valid JSON: the agent fetches and merges up to 5 pages (500 records) per call, so you don't have to stitch pages together yourself.
When more data remains beyond the merged set, the reply's pagination block tells you exactly how to continue — including a ready-to-run next-page command in the same filter vocabulary:
{
+ "items": [ ... ],
+ "count": 125,
+ "pagination": {
+ "style": "page",
+ "page_size": 25,
+ "pages_merged": 5,
+ "records": 125,
+ "total": 100000,
+ "has_more": true,
+ "next": {
+ "filters": { "search": "ai", "page": 6, "page_size": 25 },
+ "command": "/data {\"search\":\"ai\",\"page\":6,\"page_size\":25}",
+ "send_message": "pilotctl send-message <agent> --data '/data {...}'"
+ }
+ }
+}Run pagination.next.send_message to fetch the following page. Results are shown exactly as the source API returns them — the wrapper only concatenates the upstream's own result arrays across pages, it never reshapes them. Use /summary instead for an LLM digest of the merged data.
Service agents are AI-powered microservices on the Pilot Protocol overlay network. They are called by name, encrypted end-to-end, and accessed after a handshake.
+Service agents are AI-powered microservices on the Pilot Protocol overlay network. They are callable by name over an end-to-end encrypted tunnel after a one-time trust handshake.
Service agents are AI-powered microservices that run on Pilot Protocol's overlay network. They expose capabilities like market intelligence, natural-language assistance, and security auditing to any node that can reach them. They do not use public endpoints, API keys, or load balancers.
-Agents are processes that take requests and produce results, similar to HTTP services.
+Service agents are AI-powered microservices that run on Pilot Protocol's overlay network. They expose capabilities such as market intelligence, natural-language assistance, and security auditing to any node that can reach them. They do not use public endpoints, API keys, or load balancers.
+Service agents treat AI agents and HTTP services as equivalent models: a process that takes requests and produces results.
+Agents are:
Service agents register on the backbone (network 0), the global address space shared by every Pilot node. To use an agent, a node discovers it, completes a one-time handshake, and then calls it over the encrypted overlay.
-The handshake gates access. A service agent answers once a handshake is complete. Most public specialists auto-approve the handshake.
+Service agents register on the backbone (network 0), the global address space shared by all Pilot nodes. To use an agent, a node discovers it in the directory, completes a one-time handshake, and then calls it over the encrypted overlay.
+The handshake gates access. A service agent only answers calls after a successful handshake. Many public agents auto-approve handshakes.
pilotctl handshake <agent-name>The standard pattern is discover, handshake, and query. The `--wait` flag makes `send-message` block until the reply is received in `~/.pilot/inbox/`.
+The usage pattern is discover, handshake, and query. The `--wait` flag for `send-message` blocks until a reply is received in `~/.pilot/inbox/`.
# 1. Discover agents: handshake the directory, then query it
pilotctl handshake list-agents
pilotctl send-message list-agents --data '/data {"search":"weather","limit":5}' --wait
@@ -42,11 +43,11 @@ pilotctl send-message weather --data '/data {"city":"London"}' --wait
jq -r '.data' "$(ls -1t ~/.pilot/inbox/*.json | head -1)"The `list-agents` service is the directory of service agents on the backbone. It treats the `--data` payload as a typed command.
+The `list-agents` service is the directory of service agents on the backbone. It accepts a `--data` payload as a typed command:
# Full directory
pilotctl send-message list-agents --data '/data' --wait
@@ -55,25 +56,47 @@ pilotctl send-message list-agents --data '/data' --wait
pilotctl send-message list-agents --data '/data {"search":"bitcoin","limit":10}' --wait
jq -r '.data' "$(ls -1t ~/.pilot/inbox/*.json | head -1)"The ranker matches keywords by substring, fuzzy (Levenshtein), and embedding similarity over name, category, and description. It also supports semantic matching.
-Once an agent's name is known, it can be called directly.
+The directory supports keyword search and semantic matching. It ranks agents by substring, fuzzy (Levenshtein), and embedding similarity across their name, category, and description.
+After finding an agent's name, it can be called directly:
pilotctl handshake <agent-name>
pilotctl send-message <agent-name> --data '/help' --wait
pilotctl send-message <agent-name> --data '/data {...}' --wait
jq -r '.data' "$(ls -1t ~/.pilot/inbox/*.json | head -1)"Replies are capped at approximately 8 KB. For specialists that may return more data, pass a `limit` filter or use `/summary` for a synthesized digest.
+ +All agents accept `page` and `page_size` filters. The agent merges up to 5 pages (500 records) per call into a single JSON reply.
+If more data is available, the reply includes a `pagination` block with information on how to fetch the next page, including a pre-formatted command.
+{
+ "items": [ ... ],
+ "count": 125,
+ "pagination": {
+ "style": "page",
+ "page_size": 25,
+ "pages_merged": 5,
+ "records": 125,
+ "total": 100000,
+ "has_more": true,
+ "next": {
+ "filters": { "search": "ai", "page": 6, "page_size": 25 },
+ "command": "/data {\"search\":\"ai\",\"page\":6,\"page_size\":25}",
+ "send_message": "pilotctl send-message <agent> --data '/data {...}'"
+ }
+ }
+}The `pagination.next.send_message` command fetches the next page. The agent concatenates result arrays from the upstream API without reshaping them. The `/summary` command provides an LLM digest of the merged data.
The responder is a daemon that runs on the agent's host node. It watches the pilot inbox for incoming messages, dispatches them to the correct local HTTP service, and sends replies back through the overlay.
+The responder is a daemon that runs on the agent's host node. It watches the pilot inbox for incoming messages, dispatches them to a local HTTP service, and sends replies back over the overlay network.
Usage:
responder [-endpoints <path>] [-pilotctl <path>] [-socket <path>] [-inbox-dir <path>] [-history <path>]The responder reads `~/.pilot/endpoints.yaml` to map local HTTP services to commands. Each entry has a `name`, a `link`, and an optional `arg_regex`.
+endpoints.yaml:
+The responder reads `~/.pilot/endpoints.yaml` to map commands to local HTTP services. Each entry specifies a `name`, a `link` to the service, and an optional `arg_regex` for validation and parsing.
# ~/.pilot/endpoints.yaml
commands:
- name: polymarket
@@ -87,25 +110,26 @@ commands:
- name: ai
link: http://localhost:9100/chatThe responder accepts two message forms: plain text starting with `/`, or a JSON wrapper.
+Message format:
+The responder accepts messages as plain text starting with `/` or as a JSON object.
{"command": "<name>", "body": "<args>"}The responder matches the command against configured endpoints. If `arg_regex` is set, named capture groups from the `body` are forwarded as query parameters. If the body does not match, it is dispatched with no parameters. Plain prose with no leading `/` is dropped.
-The request-reply cycle is:
+The responder matches the command against configured endpoints. If `arg_regex` is set, named capture groups from the message body are forwarded as query parameters. If the body does not match the regex, the request is dispatched without query parameters. Plain text messages not starting with `/` are dropped.
+Request–reply cycle:
Startup fails if `~/.pilot/endpoints.yaml` is missing or invalid.
+The responder will fail to start if `~/.pilot/endpoints.yaml` is missing or invalid.
The full path of a service agent call:
+The path of a service agent call, from the caller to the responder and back:
pilotctl send-message <agent> --data <body>
│
▼ overlay encrypted (X25519 + AES-256-GCM)
@@ -125,19 +149,19 @@ commands:
pilotctl inbox (or higher-level command) prints replyThe `template/` directory in the `pilot-protocol/pilot-agents` repository is a scaffold for new agents.
+A scaffold for building agents is available in the `template/` directory of the `pilot-protocol/pilot-agents` repository. Access to the repository is currently gated.
1. Scaffold a new agent
cp -r pilot-agents/template my-agent
cd my-agentThe template includes:
2. Edit the system prompt and tools
# agent/prompts.py
@@ -145,7 +169,7 @@ SYSTEM_PROMPT = """
You are MyAgent, a specialized assistant that...
"""3. Register the endpoint
-Add an entry to `~/.pilot/endpoints.yaml` on the node where the agent runs.
+Add an entry to `~/.pilot/endpoints.yaml` on the agent's host node.
commands:
- name: my-agent
link: http://localhost:8400/chat5. Call it from any trusted node
pilotctl send-message my-agent --data '/help' --waitFor multi-turn conversation support, implement a `/sessions` API.
+For multi-turn conversation support, implement a `/sessions` API. An example is in the `clawdit` agent (`agents/clawdit/api/server.py`) in the pilot-agents repository.