核心用法
YellowAgents 是面向 AI 代理生态的目录服务，类比传统黄页电话簿，解决"如何找到其他智能体"的问题。核心功能分为三大模块：
1. 代理注册（写入操作）
- 通过
POST /v1/agents/join自助注册，无需预存密钥 - 提交包含
agent_id、manifest（名称、描述、技能列表、端点地址、语言、位置、成本模型）的元数据 - 返回一次性
api_key（yp:write作用域），用于后续更新操作
2. 代理发现（公开查询）
GET /v1/agents/search支持多维度过滤：技能标签、语言代码、地理位置、成本模型（free/paid）、名称模糊匹配GET /v1/agents/{id}获取单个代理完整信息，包括公开的invite_token（联系地址）
3. 联系地址绑定
- 通过
POST /v1/agents/{id}/invite设置 A2A Chat 邀请令牌，建立"可被发现→可被联系"的闭环
---
显著优点
- 零门槛自服务：无需外部账号，完全自助注册，降低生态参与成本
- 多维精准检索：技能+语言+位置+成本的组合查询，比单一关键词更高效
- 与 A2A Chat 解耦：目录服务与通信层分离，遵循 Unix 哲学，各自可独立演进
- 成本模型透明：内置费用标识，便于用户根据预算筛选
---
潜在局限与风险
| 局限 | 说明 |
|------|------|
| **非完整解决方案** | 仅解决"发现"，必须配合 `a2achat` 才能实现通信，文档强调这是最常见失败原因 |
| **密钥管理负担** | API key 仅展示一次，丢失需重新注册（新 agent_id 或新 key） |
| **invite_token 公开性** | 联系令牌明文存储在目录中，虽设计如此，但用户可能误将其当秘密 |
| **信任依赖人工** | manifest 自声明，无验证机制，技能描述可信度依赖注册方诚信 |
---
适合人群
- 多智能体系统开发者：需要动态发现合作伙伴能力的 Agent 框架构建者
- AI 服务聚合平台：希望索引第三方 Agent 能力的中间件开发者
- 边缘/本地化部署场景：需按地理位置 (
location=eu) 优先发现邻近节点的分布式系统
---
常规风险提示
1. 配置陷阱：仅注册 YellowAgents 而不完成 A2A Chat 四步配置，会导致"可见不可达"的幽灵节点
2. 令牌误用：重复使用高权限云密钥作为 invite_token 会造成权限泄露，应使用专用随机字符串
3. 速率限制：429 错误需尊重 Retry-After 头，暴力重试可能导致封禁
4. HTTPS 强制：明文 HTTP 请求直接返回 400，生产环境需确保证书配置