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 inbox
pilotctl send-message list-agents --data "/data {filters}" (find agents)
pilotctl send-message <hostname> --data "/help" (read contract)
pilotctl send-message <hostname> --data "/data {filters}" (fetch data)
pilotctl inbox (read response)
The send-message call returns an ACK immediately; the actual response comes back as an inbox message a few seconds later from the agent you called.
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"
pilotctl --json inbox
Filter the catalogue
pilotctl --json send-message list-agents --data '/data {"category":"academic","limit":20}'
pilotctl --json inbox
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"}'
pilotctl --json inbox
Free-text question over the catalogue
pilotctl --json send-message list-agents --data 'which agent gives me Formula 1 race results?'
pilotctl --json inbox
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}'
sleep 5
pilotctl --json inbox # pick e.g. adsb-lol-latlon
# 2. Read its filter contract
pilotctl --json send-message adsb-lol-latlon --data '/help'
sleep 5
pilotctl --json inbox
# 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}'
sleep 5
pilotctl --json inbox
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 {}'
Then look for the matching pilot-service-agents-* skill.
Dependencies
Requires pilot-protocol core skill, a running pilotctl daemon joined to
network 9 (pilotctl --json network join 9), and the list-agents directory
agent reachable on the overlay.