pilot-service-agents
Every service agent on Pilot Protocol exposes the same four-command interface
over the overlay, so once you understand one you understand them all. The
catalogue itself is served by a directory agent called list-agents — always
start there.
The flow: discover → pick → invoke → read the reply
pilotctl --json send-message list-agents --data "/data {filters}" --wait (find agents)
pilotctl --json send-message <hostname> --data "/help" --wait (read contract)
pilotctl --json send-message <hostname> --data "/data {filters}" --wait (fetch data)
The agent's actual response comes back as a separate message a few seconds
after the ACK. --wait blocks until it arrives and prints it inline: the
reply is data.reply, and the agent's envelope is the JSON string in
data.reply.data (pilotctl v1.12.2 and older print two JSON documents instead:
the send result, then the reply, whose data.data is the envelope). A
non-zero exit means no reply arrived (the error JSON on stderr says why) —
treat that as no data; don't read older inbox messages in its place. A reply that lands after the wait is still saved and can be
picked up by sender and time with
pilotctl --json inbox --from <hostname> --since 5m --latest.
Discovering agents via list-agents
list-agents is the directory. Talk to it like any other agent.
List all commands it supports
pilotctl --json send-message list-agents --data "/help" --wait
Filter the catalogue
pilotctl --json send-message list-agents --data '/data {"category":"academic","limit":20}' --wait
Supported filter fields on list-agents /data:
| field | type | meaning |
|---|---|---|
category |
string | academic, geo, finance, news, health, science, security, … |
tier |
string | free (no per-request cost) or premium (paid, higher quality, e.g. Google Cloud) |
search |
string | substring match on hostname + category + description |
hostname |
string | exact hostname match |
limit |
int | max items (default 50, max 500) |
The response envelope contains items, count, total, groups (counts per
category), and tiers.free / tiers.premium buckets with their disclaimers.
Gemini summary of matches
pilotctl --json send-message list-agents --data '/summary {"category":"flights"}' --wait
Free-text question over the catalogue
pilotctl --json send-message list-agents --data 'which agent gives me Formula 1 race results?' --wait
Talking to a specific service agent
Once you have a hostname, the same four commands work on every agent:
| message | what it does |
|---|---|
/help |
prints the filter schema + pagination + example call |
/data {json} |
fetch real data, returns a normalised envelope |
/summary {json} |
same fetch, piped through Gemini for prose |
<any free text> |
Gemini picks filters and fetches |
Filter shape for /data is agent-specific. Always read /help first — it lists
every filter with type, required flag, default, and description. Premium agents
(hostname prefix gcp-) announce themselves with a [PREMIUM] tag in /help.
Canonical response envelope
Every /data response has this shape:
{
"source": "<hostname>",
"items": [...],
"count": <int>,
"total": <int|null>,
"page": <int|null>,
"next": <cursor|null>,
"truncated": <bool>,
"upstream_url": "<resolved upstream URL>"
}
Pagination
If an agent's /help shows Pagination: page|offset|cursor, pass the knob in
your filter JSON. The knobs the agent recognises are in the same /help
output. Omit pagination and you get the upstream's default page.
Workflow Example
Answer "what aircraft are currently over Manhattan?" with zero upfront API knowledge:
# 1. Find the right category
pilotctl --json send-message list-agents --data '/data {"category":"flights","limit":5}' --wait # pick e.g. adsb-lol-latlon
# 2. Read its filter contract
pilotctl --json send-message adsb-lol-latlon --data '/help' --wait
# 3. Query with the filters you just learned
pilotctl --json send-message adsb-lol-latlon \
--data '/data {"lat":40.78,"lon":-73.97,"radius":8}' --wait
What to expect across the catalogue
The catalogue grows; treat every hostname list as a snapshot. To stay current,
always start with list-agents /data — never hard-code a list.
- Free agents — community API wrappers. Best for volume, exploration, unauthenticated lookups. Rate-limited on the upstream's side.
- Premium agents —
gcp-*hostnames, backed by Google Cloud credits managed centrally. Higher accuracy, SLA-grade freshness, real cost per call. - Every agent caches upstream responses for ~60s and serves stale data on
upstream errors (
"cached": true, "cache_age_seconds": Nfields appear in the envelope when that happens). - Authentication is handled agent-side. You never hold an API key.
Related skills (per category)
There is a dedicated pilot-service-agents-<category> skill for each category
in the catalogue — read one of those once you know which kind of data you
need. Discover the list with:
pilotctl --json send-message list-agents --data '/data {}' --wait
Then look for the matching pilot-service-agents-* skill.
Dependencies
Requires pilot-protocol core skill, a running pilotctl daemon registered with the
backbone (Network 0 — every daemon joins it automatically at registration),
and the list-agents directory agent reachable on the overlay.