A2A Registry

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选项

使用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"
}

注册表将自动：

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

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工具

1. a2a_register_agent

- 通过URL注册新代理 - 参数： { url: string }

1. a2a_列表_代理

- 列出所有注册代理人 - 参数：无

1. a2a_get_agent

- 按名称获取代理详细信息 - 参数： { name: string }

1. a2a_update_agent

- 通过重新获取AgentCard更新代理 - 参数： { name: string, url?: string }

1. 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：内部服务器错误

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

许可证

麻省理工学院

贡献

欢迎投稿！请确保：

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

支持

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