使用说明

A2A注册表

一种模型上下文协议（MCP）服务器，为实现A2A（代理到代理）协议的代理提供统一的注册表。注册表公开了用于注册、查询和管理代理元数据的REST API和MCP工具。

特性

双重API访问：在单个HTTP服务器上运行的REST API和MCP服务器
智能代理注册：使用智能路由从URL自动获取AgentCard
多个存储后端：JSON文件或SQLite数据库
并发访问：基于SSE的MCP传输允许同时使用多个客户端
完整的CRUD操作：创建、读取、更新和删除代理
符合A2A协议：使用来自的标准AgentCard模型 @a2a-js/sdk

安装

npm install
npm run build

用法

基本用法

# Start with default settings (JSON store, port 3000)
npm start

# Or run directly
node dist/index.js

配置选项

# Use SQLite storage
node dist/index.js --store=sqlite --file=./agents.db

# Custom port
node dist/index.js --port=4000

# Custom JSON file location
node dist/index.js --store=json --file=./my-agents.json

# Combine options
node dist/index.js --store=sqlite --file=./agents.db --port=4000

CLI选项

标志	值	描述	默认值
`--store`	`json`, `sqlite`	存储后端	`json`
`--file`	path	数据库或JSON文件路径	`a2a-registry.json` 或 `a2a-registry.db`
`--port`	number	HTTP服务器端口	`3000`
`--help`	-	显示帮助消息	-

使用PM2

# Start with PM2
pm2 start ecosystem.config.cjs

# View logs
pm2 logs a2a-registry

# Stop
pm2 stop a2a-registry

# Restart
pm2 restart a2a-registry

API终点

REST API

所有REST端点都位于 /agents:

列出所有代理

GET /agents

按名称获取代理

GET /agents/:name

注册新代理

POST /agents
Content-Type: application/json

{
  "url": "https://example.com"
}

注册表将自动：

使用智能路由确定AgentCard URL
从URL获取代理卡
验证代理卡结构
使用代理的名称作为主键进行存储

URL路由示例：

https://example.com → 胎儿来自 https://example.com/.well-known/agent-card.json
https://example.com/my-agent → 胎儿来自 https://example.com/my-agent/.well-known/agent-card.json
https://cdn.example.com/agent.json → 直接获取（URL以结尾 .json)

更新代理

PUT /agents/:name
Content-Type: application/json

{
  "url": "https://new-url.com"  # Optional, re-fetches from existing URL if omitted
}

删除代理

DELETE /agents/:name

MCP服务器

MCP服务器可在 /mcp 使用SSE（服务器发送事件）传输。

配置示例

{
  "mcpServers": {
    "a2a-registry": {
      "type": "http",
      "url": "http://localhost:3005/mcp"
    }
  }
}

可用的MCP工具

a2a_register_agent
- 通过URL注册新代理
- 参数： { url: string }
a2a_列表_代理
- 列出所有注册代理人
- 参数：无
a2a_get_agent
- 按名称获取代理详细信息
- 参数： { name: string }
a2a_update_agent
- 通过重新获取AgentCard更新代理
- 参数： { name: string, url?: string }
a2a_delete_agent
- 从注册表中删除代理
- 参数： { name: string }

建筑

┌─────────────────────────────────────────┐
│     REST API        │     MCP Server    │
│   (HTTP Routes)     │   (MCP Tools)     │
├─────────────────────┴───────────────────┤
│          AgentService                   │
│  (Business Logic & Validation)          │
├─────────────────────────────────────────┤
│          Store Interface                │
│     (Storage Abstraction)               │
├─────────────────────────────────────────┤
│   JsonFileStore  │  SqliteStore         │
│   (Implementations)                     │
└─────────────────────────────────────────┘

关键设计原则

服务层模式：AgentService封装了所有业务逻辑
无代码重复：REST和MCP API是调用AgentService的瘦适配器
智能注册：自动发现和获取代理卡
可插拔存储：易于添加新的存储后端
并发访问：MCP的无状态SSE运输

代理卡结构

注册表使用A2A协议中的标准AgentCard模型。必填字段包括：

name：代理名称（用作主键）
description：代理目的和能力
url：主要A2A端点URL
version：代理版本
capabilities：支持的A2A协议功能
defaultInputModes：支持的输入MIME类型
defaultOutputModes：支持的输出MIME类型
skills：代理的独特能力

请参阅 A2A协议规范了解完整细节。

发展

项目结构

a2a-registry/
├── src/
│   ├── index.ts              # Main entry point
│   ├── types/                # TypeScript type definitions
│   ├── store/                # Storage implementations
│   │   ├── JsonFileStore.ts
│   │   └── SqliteStore.ts
│   ├── services/             # Business logic
│   │   └── AgentService.ts
│   ├── api/                  # REST API
│   │   └── restApi.ts
│   ├── mcp/                  # MCP server
│   │   └── mcpServer.ts
│   └── utils/                # Utilities
│       └── validation.ts
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
└── ecosystem.config.cjs      # PM2 configuration

构建

npm run build

开发模式（带自动重新加载）

npm run dev

清洁建筑

npm run clean
npm run build

错误处理

注册表提供清晰、可操作的错误消息：

404：未找到代理
409：代理已存在（请改用更新）
400：URL无效、获取失败或验证错误
500：内部服务器错误

所有错误都包含有用的消息，以指导下一步。

许可证

麻省理工学院

贡献

欢迎投稿！请确保：

代码遵循现有的架构模式
所有业务逻辑都在AgentService中
API是瘦适配器
测试通过，构建成功

支持

对于问题或疑问，请在GitHub上打开问题。