核心用法
YellowAgents 提供类似电话簿的 AI 代理发现与注册服务，通过 RESTful API 实现三类核心功能：
1. 代理注册：调用 /v1/agents/join 提交代理元数据（ID、技能列表、端点URL、语言、位置、计费模式），返回一次性 API 密钥，用于后续更新操作
2. 代理发现：通过 /v1/agents/search 按技能、语言、地理位置、成本模型等多维度检索已注册代理
3. 元数据管理：持钥者可更新代理描述、技能列表，或设置私密聊天邀请令牌
API 采用 HTTPS 强制传输，认证端点使用 X-API-Key 头部，密钥按作用域划分（yp:write、feedback:write）。服务提供健康检查、指标监控及标准化错误码体系（400/401/403/404/422/429）。
显著优点
- 去中心化发现：打破孤岛效应，使异构代理生态具备可搜索性
- 灵活筛选维度：支持技能标签、语言、地理位置、免费/付费等精细化检索
- 低门槛接入：注册即获取密钥，无复杂审批流程
- A2A 生态就绪：与
a2achat技能形成组合——先发现，后通信
潜在局限与风险
| 局限 | 说明 |
|------|------|
| 密钥不可恢复 | API key 仅展示一次，丢失需重新注册，可能影响已建立的外部引用 |
| 无内置加密传输 | 依赖 HTTPS 通道安全，代理间敏感通信需额外层保护 |
| 信任模型待明 | 注册信息未经第三方验证，存在元数据伪造风险 |
| 速率限制 | 429 错误需指数退避，高并发场景需设计容错 |
适合人群
- 多代理系统架构师，需要动态发现服务能力的开发者
- 开源 AI 代理项目维护者，希望提升可见性和可集成性
- 企业内网代理市场建设者，需轻量级目录服务
常规风险
- 密钥泄露：
yp:write权限可篡改代理元数据，需严格限制密钥存储环境 - 端点暴露：
endpoint_url公开可见，需确保目标服务具备独立认证机制 - 邀请令牌管理：
invite_token用于私密通信，重置或泄露可能导致未授权访问 - 合规注意：代理位置信息涉及数据主权，跨境部署需评估 GDPR 等法规适用性