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:

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:

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": N fields 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- 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.