📦 Pilot Service Agents — Pilot 服务 代理s
v1.0.0Discover and 查询 the pilot-服务-代理s cata记录ue — ~370 always-on data 代理s reachable over Pilot Protocol that wrap real-world APIs (Google Maps, Open...
详细分析 ▾
运行时依赖
安装命令
点击复制技能文档
pilot-service-agents Pilot Protocol 上的每个服务代理都通过 overlay 暴露统一的四条命令接口,弄懂一个就全懂了。目录由名为 list-agents 的目录代理提供——永远从它开始。
流程:discover → pick → invoke → read inbox
pilotctl send-message list-agents --data "/data {filters}" # 发现代理
pilotctl send-message --data "/help" # 读合约
pilotctl send-message --data "/data {filters}" # 取数据
pilotctl inbox # 读响应
send-message 立即返回 ACK;真实响应几秒后以 inbox 消息形式返回。 通过 list-agents 发现代理 list-agents 就是目录,像普通代理一样跟它对话。 列出它支持的全部命令
pilotctl --json send-message list-agents --data "/help"
pilotctl --json inbox
过滤目录
pilotctl --json send-message list-agents --data '/data {"category":"academic","limit":20}'
pilotctl --json inbox
list-agents /data 支持的过滤字段:
- category: string academic, geo, finance, news, health, science, security, …
- tier: string free(无计费)或 premium(付费、更高质量,如 Google Cloud)
- search: string hostname + category + description 的子串匹配
- hostname: string 精确匹配 hostname
- limit: int 最大返回条数(默认 50,上限 500)
响应信封包含 items、count、total、groups(各分类计数)及 tiers.free / tiers.premium 桶及其免责声明。
Gemini 摘要匹配
pilotctl --json send-message list-agents --data '/summary {"category":"flights"}'
pilotctl --json inbox
对目录的自由文本提问
pilotctl --json send-message list-agents --data 'which agent gives me Formula 1 race results?'
pilotctl --json inbox
与具体服务代理对话 拿到 hostname 后,四条命令通用于所有代理:
| 消息 | 作用 |
|---|---|
| /help | 打印过滤 schema、分页、示例调用 |
| /data {json} | 取真实数据,返回标准化信封 |
| /summary {json} | 同上,但经 Gemini 转为散文 |
| <任意自由文本> | Gemini 自动选过滤条件并抓取 |
标准响应信封 每条 /data 响应都长这样:
{
"source": "",
"items": [...],
"count": ,
"total": ,
"page": ,
"next": ,
"truncated": ,
"upstream_url": "<解析后的上游 URL>"
}
分页 若代理 /help 显示 Pagination: page|offset|cursor,在过滤 JSON 中传入对应旋钮即可;不指定则使用上游默认页。
工作流示例 零 API 知识回答“现在曼哈顿上空有哪些飞机?”
# 1. 找分类 pilotctl --json send-message list-agents --data '{"category":"flights","limit":5}' sleep 5 pilotctl --json inbox # 选 adsb-lol-latlon# 2. 读过滤合约 pilotctl --json send-message adsb-lol-latlon --data '/help' sleep 5 pilotctl --json inbox
# 3. 用刚学的过滤条件查询 pilotctl --json send-message adsb-lol-latlon \ --data '/data {"lat":40.78,"lon":-73.97,"radius":8}' sleep 5 pilotctl --json inbox
目录须知 目录持续增长,hostname 列表只是快照。要最新数据,永远从 list-agents /data 开始——切勿硬编码列表。
- Free 代理:社区 API 封装,适合大量调用、探索、无需鉴权的查询;受上游限流。
- Premium 代理:gcp- 主机,由中央管理的 Google Cloud 额度支撑;更高准确度、SLA 级新鲜度,每次调用真实计费。
所有代理将上游响应缓存约 60 秒,上游出错时返回陈旧数据(信封内出现 "cached": true, "cache_age_seconds": N)。 鉴权由代理端完成,你无需持有 API key。
相关技能(按分类) 每个分类都有专属 skill:pilot-service-agents-,确定数据类型后去读对应 skill。 用以下命令发现列表:
pilotctl --json send-message list-agents --data '/data {}'
然后找匹配的 pilot-service-agents- skill。 依赖
需安装 pilot-protocol core skill,运行已加入网络 9 的 pilotctl 守护进程(pilotctl --json network join 9),且 list-agents 目录代理在 overlay 可达。