Agent Protocol 之 A2X 注册中心使用指南注册、查询与 3 种搜索方法一文讲透【免费下载链接】agent-protocolopenJiuwen agent-protocol提供agent通信协议实现包括MCP、A2A协议的C SDK项目地址: https://gitcode.com/openJiuwen/agent-protocolopenJiuwen/agent-protocol开源项目中的A2X RegistryA2X 注册中心是面向智能体的服务发现注册中心它统一管理 Agent、MCP 工具与 Skill 的注册、注销、查询与生命周期并内置A2X 智能搜索让你的智能体从海量服务中快速、准确地找到所需能力。本文用最短路径带你完成部署并讲透服务注册、查询和 3 种搜索方法的适用场景。一、为什么需要 A2X 注册中心当智能体互联网上的服务数量从几十个膨胀到上万个时一个核心问题浮出水面如何让智能体高效找到所需能力现有方案各有痛点MCP 全量注入把所有工具塞进上下文容易上下文溢出还会触发Lost in the Middle效应纯向量检索不理解跨术语的语义意图命中率有限查询改写方向不确定效果不稳定。A2X 的解法是由 LLM 从服务描述中自动构建层次化能力目录分类树搜索时沿领域 → 子领域 → 具体能力 → 服务逐层递归导航查找成本接近O(log N)兼顾召回与精度且分类树无需人工维护。在公开的 ToolRet 基准1839 服务 / 1714 查询上实测方法Hit RateRecall单次查询 TokenA2X92.59%89.19%~7k向量检索 (top-5)69.08%61.81%0MCP 全量仅名称描述86.00%83.67%~67k完整数据与更多数据集对比见 AgentRegistry/README.md。二、快速安装与启动3 步跑起你的注册中心 1. 克隆仓库并安装依赖要求 Python ≥ 3.10git clone -b develop https://gitcode.com/openJiuwen/agent-protocol cd agent-protocol/AgentRegistry pip install -e .[full] 默认安装即可使用A2X 搜索、Traditional 搜索与分类树构建这些是纯 LLM 工作流只有向量检索需要[vector]附加依赖。[full] 全量功能。2. 配置 LLM API KeyA2X 搜索与建树必需默认位置~/.a2x_registry/llm_apikey.json可参照仓库内的模板文件 llm_apikey.example.json 编写格式为 OpenAI 兼容 API支持多 provider 轮询故障转移。若仅做 CRUD 或向量检索可跳过此步。全部环境变量见 docs/environment.md。3. 启动服务a2x-registry # 后端启动于 http://127.0.0.1:8000交互文档在 /docs如果想同时启动网页 UI只需一条命令python ui/launcher.pylauncher 会按ui/frontend/dist/是否存在自动选择直接托管静态文件或启动 Vite 开发服务器实现细节见 docs/frontend_design.md。三、服务注册4 种方式一次讲清 ✍️A2X 注册中心支持 4 种注册对象覆盖绝大多数智能体服务形态类型说明关键参数generic通用服务namedescriptiona2aURL通过 URL 自动拉取 A2A Agent Cardagent_card_urla2a内联直接提供 Agent Card 内容agent_cardskillSkill 文件夹 / ZIP 上传file或本地目录以注册一个 A2A Agent 为例通过 URL 自动拉取 Agent Cardcurl -X POST http://localhost:8000/api/datasets/my_dataset/services/a2a \ -H Content-Type: application/json \ -d {agent_card_url: https://agent.example.com/.well-known/agent.json}不想走 API也可以直接在database/{数据集名}/user_config.json中声明要注册的服务下次启动时后端自动加载模板见 user_config.example.json。注册模块的字段校验、Agent Card 抓取与描述生成逻辑详见 docs/register_design.md。四、服务查询与生命周期管理 注册只是开始注册中心提供全生命周期管理浏览服务GET /api/datasets/{ds}/services支持分页与 brief / detail 两种字段粒度精确查询按service_id查询单个服务skill 类型直接返回 ZIP字段级更新PUT部分覆盖无需整卡重写状态声明支持online / busy / offline状态标记注销服务一条DELETE请求即可下线。两个可选但很实用的进阶能力能力用途设计文档静态 API Key 鉴权admin / provider / user 三档角色 数据集作用域默认关闭docs/auth_design.md心跳保活客户端定期心跳维持服务存活停跳自动清理默认关闭docs/heartbeat_design.md全量接口请求/响应格式见 docs/backend_api.md。五、3 种搜索方法对比选对方法事半功倍 调用POST /api/search通过method参数切换搜索方法方法原理依赖适用场景a2x_*分类树 LLM 递归导航两阶段检索需 LLM Key高精度、省 Token推荐默认vectorChromaDB 向量相似度检索需[vector]依赖毫秒级响应、无 LLM 成本traditionalMCP 全量上下文一次性注入需 LLM Key小服务池、基线对比其中 A2X 方法又细分 3 种搜索模式见 docs/search_design.md模式策略适用场景a2x_get_all选所有可能相关的分类与服务高召回场景a2x_get_important只选确实需要的服务同功能去重平衡精度与召回推荐a2x_get_one只返回最匹配的一个服务高精度单一目标同步搜索一条命令搞定curl -X POST http://localhost:8000/api/search \ -H Content-Type: application/json \ -d {query: 帮我预订航班, method: a2x_get_all, dataset: my_dataset}需要实时看到 LLM 沿分类树导航的过程A2X 搜索还支持 WebSocket 流式接口/api/search/ws实时推送每一步分类选择是前端树形动画的数据源。算法细节见 docs/a2x_design.md。六、网页 UI可视化对比 3 种方法的效果 ✨通过python ui/launcher.py启动后浏览器打开即可使用无需任何额外配置搜索模式输入查询交互对比 A2X / 向量 / 传统全量 3 种方法的结果D3.js 实时动画展示分类树导航过程直观理解LLM 是如何一步步逼近目标服务的管理员模式数据集管理、服务注册/注销含 Skill 文件夹上传、服务查询、分类树构建、Embedding 模型配置一站完成。前端入口源码ui/launcher.pyReact D3.js 组件位于 ui/frontend/src/ 对应的ui/frontend目录。七、进阶能力速览 能力一句话说明参考数据集隔离多业务线各自独立命名空间Embedding 模型可按数据集切换docs/backend_api.md预订锁reservationAgent Team 场景下多智能体协调的短时互斥锁docs/register_design.md分布式同步多注册中心 gossip 复制 失活驱逐默认关闭README_forDistributed.mdAgent Team 客户端 SDKPython SDK心跳自动续期、Token 登录等client/README.md精简部署面向 Agent Team 的轻量安装模式README_forAgentTeam.md八、参考文档与源码索引 资料说明AgentRegistry/README.md注册中心总 README评测数据、快速开始docs/architecture_overview.md整体架构模块布局、数据流、安装模式docs/backend_api.md后端全量 HTTP API 说明docs/search_design.mdA2X 两阶段递归检索算法docs/build_design.md分类树自动构建设计docs/environment.md全部环境变量与默认值小结A2X 注册中心把智能体服务发现这件复杂的事拆成了三步——注册4 种方式一个 curl 搞定、查询全生命周期管理、搜索3 种方法按需选择。配合 O(log N) 的 A2X 导航搜索和可视化 UI它是组织级 Agent 网关与互联网级 Agent DNS 的现成底座。克隆仓库10 分钟跑起来试试吧【免费下载链接】agent-protocolopenJiuwen agent-protocol提供agent通信协议实现包括MCP、A2A协议的C SDK项目地址: https://gitcode.com/openJiuwen/agent-protocol创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
