Content
# MCPF Agent-to-Agent Registry (A2A)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://expressjs.com/)
[](https://www.postgresql.org/)
[](https://mcpf.dev)
[](https://developers.google.com/assistant/app-actions)
**Delegation Control for AI Agents** - Registry for managing which agents can delegate tasks to which other agents, with policy enforcement and audit logging.
## 🌟 What is A2A Registry?
The Agent-to-Agent (A2A) Registry manages delegation relationships between AI agents:
```
Agent A (fraud-detector)
↓ wants to delegate to
Agent B (risk-analyzer)
↓ check registry
A2A Policy: ALLOWED (with constraints)
↓ enforce policy
Delegation proceeds with audit log
```
**Based on Google's A2A Protocol and MCPF specifications**
## Features
- **🔐 Delegation Policies** - Define who can delegate to whom
- **📋 Policy Registry** - Persistent storage of delegation rules
- **✅ Real-time Authorization** - Check delegation permissions
- **🔍 Audit Logging** - Complete delegation history
- **⚡ Policy Constraints** - Time limits, scope restrictions, conditions
- **🔄 Revocation** - Instant policy revocation
- **🗄️ PostgreSQL Backend** - Production-ready database
- **🚀 REST API** - Simple HTTP/JSON interface
## 🚀 Quick Start
### Using Docker (Recommended)
```bash
# Clone repository
git clone https://github.com/MCPTrustFramework/MCPF-a2a-registry.git
cd MCPF-a2a-registry
# Start service
docker-compose up -d
# Verify running
curl http://localhost:4003/health
# {"status":"ok"}
# Check delegation policy
curl 'http://localhost:4003/a2a/check?from=did:web:agent1.example&to=did:web:agent2.example'
```
### Manual Installation
```bash
# Install dependencies
cd src
npm install
# Set up database
createdb mcpf_a2a
psql mcpf_a2a < db.sql
# Configure
cp .env.example .env
# Edit .env
# Run
npm start
```
## 📖 API Reference
### Core Endpoints
#### Check Delegation Permission
```http
GET /a2a/check?from={fromDID}&to={toDID}&action={action}
```
**Example:**
```bash
curl 'http://localhost:4003/a2a/check?from=did:web:fraud-detector.bank.example&to=did:web:risk-analyzer.bank.example&action=analyze'
```
**Response:**
```json
{
"allowed": true,
"policy": {
"id": "pol_123",
"fromAgent": "did:web:fraud-detector.bank.example",
"toAgent": "did:web:risk-analyzer.bank.example",
"allowedActions": ["analyze", "query"],
"constraints": {
"maxDuration": 3600,
"scope": ["transaction-data"],
"requiresApproval": false
},
"status": "active",
"issuedBy": "did:web:bank.example",
"validFrom": "2025-01-01T00:00:00Z",
"validUntil": "2026-01-01T00:00:00Z"
}
}
```
#### List All Policies
```http
GET /a2a/policies?page=1&limit=50
```
**Response:**
```json
{
"page": 1,
"limit": 50,
"total": 15,
"items": [
{
"id": "pol_123",
"fromAgent": "did:web:fraud-detector.bank.example",
"toAgent": "did:web:risk-analyzer.bank.example",
"allowedActions": ["analyze", "query"],
"constraints": {...},
"status": "active",
"createdAt": "2025-01-01T00:00:00Z"
}
]
}
```
#### Get Policies for Agent
```http
GET /a2a/policies/from/:did
GET /a2a/policies/to/:did
```
**Example:**
```bash
# Get all policies where agent can delegate FROM
curl http://localhost:4003/a2a/policies/from/did:web:fraud-detector.bank.example
# Get all policies where others can delegate TO this agent
curl http://localhost:4003/a2a/policies/to/did:web:risk-analyzer.bank.example
```
#### Register Delegation Policy
```http
POST /a2a/policies
Content-Type: application/json
{
"fromAgent": "did:web:fraud-detector.bank.example",
"toAgent": "did:web:risk-analyzer.bank.example",
"allowedActions": ["analyze", "query", "report"],
"constraints": {
"maxDuration": 3600,
"scope": ["transaction-data"],
"requiresApproval": false,
"maxConcurrent": 5
},
"issuedBy": "did:web:bank.example",
"validFrom": "2025-01-01T00:00:00Z",
"validUntil": "2026-01-01T00:00:00Z"
}
```
#### Revoke Policy
```http
POST /a2a/revoke
Content-Type: application/json
{
"policyId": "pol_123",
"reason": "Agent credentials compromised"
}
```
#### Audit Log
```http
GET /a2a/audit?from={fromDID}&to={toDID}&action={action}&startDate={date}&endDate={date}
```
**Example:**
```bash
curl 'http://localhost:4003/a2a/audit?from=did:web:fraud-detector.bank.example&startDate=2025-01-01'
```
**Response:**
```json
{
"entries": [
{
"id": "audit_456",
"timestamp": "2025-01-15T10:30:00Z",
"fromAgent": "did:web:fraud-detector.bank.example",
"toAgent": "did:web:risk-analyzer.bank.example",
"action": "analyze",
"result": "allowed",
"policyId": "pol_123",
"metadata": {
"requestId": "req_789",
"duration": 245
}
}
]
}
```
## 🏗️ Architecture
```
┌─────────────────────────────────────┐
│ HTTP API (Express.js) │
│ /a2a/check, /a2a/policies │
└──────────────┬──────────────────────┘
│
┌──────────────┴──────────────────────┐
│ A2A Authorization Engine │
│ • Policy matching │
│ • Constraint validation │
│ • Audit logging │
└──────────────┬──────────────────────┘
│
┌──────────────┴──────────────────────┐
│ PostgreSQL Database │
│ • a2a_policies table │
│ • a2a_audit_log table │
│ • Indexes on DIDs, actions │
└─────────────────────────────────────┘
```
## 📊 Database Schema
### a2a_policies Table
```sql
CREATE TABLE a2a_policies (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
from_agent TEXT NOT NULL, -- Delegating agent DID
to_agent TEXT NOT NULL, -- Receiving agent DID
allowed_actions JSONB NOT NULL, -- Array of allowed actions
constraints JSONB NOT NULL DEFAULT '{}', -- Policy constraints
status TEXT NOT NULL DEFAULT 'active', -- active|revoked
issued_by TEXT NOT NULL, -- Policy issuer DID
valid_from TIMESTAMPTZ NOT NULL,
valid_until TIMESTAMPTZ,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
revoked_at TIMESTAMPTZ,
revocation_reason TEXT,
UNIQUE(from_agent, to_agent)
);
```
### a2a_audit_log Table
```sql
CREATE TABLE a2a_audit_log (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
timestamp TIMESTAMPTZ NOT NULL DEFAULT now(),
from_agent TEXT NOT NULL,
to_agent TEXT NOT NULL,
action TEXT NOT NULL,
result TEXT NOT NULL, -- allowed|denied
policy_id UUID,
metadata JSONB NOT NULL DEFAULT '{}',
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
```
### Indexes
```sql
CREATE INDEX idx_a2a_policies_from ON a2a_policies (from_agent);
CREATE INDEX idx_a2a_policies_to ON a2a_policies (to_agent);
CREATE INDEX idx_a2a_policies_status ON a2a_policies (status);
CREATE INDEX idx_a2a_audit_timestamp ON a2a_audit_log (timestamp DESC);
CREATE INDEX idx_a2a_audit_from ON a2a_audit_log (from_agent);
CREATE INDEX idx_a2a_audit_to ON a2a_audit_log (to_agent);
```
## 🔐 Policy Constraints
Policies support various constraints:
```json
{
"constraints": {
"maxDuration": 3600, // Max delegation duration (seconds)
"scope": ["data-type-1"], // Data/resource scope
"requiresApproval": false, // Human approval required
"maxConcurrent": 5, // Max concurrent delegations
"allowedDays": ["Mon","Tue"], // Day restrictions
"allowedHours": [9, 17], // Hour restrictions (9 AM - 5 PM)
"ipWhitelist": ["192.168.1.0/24"],// IP restrictions
"conditions": { // Custom conditions
"minimumRiskScore": 0.7,
"requiresEncryption": true
}
}
}
```
## 🐳 Docker Deployment
### docker-compose.yml
```yaml
version: '3.8'
services:
a2a-registry:
build: .
ports:
- "4003:4003"
environment:
- DATABASE_URL=postgresql://postgres:password@db:5432/mcpf_a2a
- PORT=4003
depends_on:
- db
restart: unless-stopped
db:
image: postgres:16-alpine
environment:
- POSTGRES_DB=mcpf_a2a
- POSTGRES_PASSWORD=password
volumes:
- postgres_data:/var/lib/postgresql/data
restart: unless-stopped
volumes:
postgres_data:
```
## 📝 Examples
### Example 1: Banking Fraud Detection
```bash
# Register policy: fraud-detector can delegate to risk-analyzer
curl -X POST http://localhost:4003/a2a/policies \
-H 'Content-Type: application/json' \
-d '{
"fromAgent": "did:web:fraud-detector.bank.example",
"toAgent": "did:web:risk-analyzer.bank.example",
"allowedActions": ["analyze", "query", "report"],
"constraints": {
"maxDuration": 3600,
"scope": ["transaction-data"],
"requiresApproval": false,
"maxConcurrent": 5
},
"issuedBy": "did:web:bank.example",
"validFrom": "2025-01-01T00:00:00Z",
"validUntil": "2026-01-01T00:00:00Z"
}'
# Check if delegation is allowed
curl 'http://localhost:4003/a2a/check?from=did:web:fraud-detector.bank.example&to=did:web:risk-analyzer.bank.example&action=analyze'
```
### Example 2: Healthcare Diagnostic Chain
```bash
# Register policy: primary-diagnostics can delegate to specialist-ai
curl -X POST http://localhost:4003/a2a/policies \
-H 'Content-Type: application/json' \
-d '{
"fromAgent": "did:web:primary-diagnostics.hospital.example",
"toAgent": "did:web:radiology-specialist.hospital.example",
"allowedActions": ["analyze-xray", "analyze-ct", "generate-report"],
"constraints": {
"maxDuration": 1800,
"scope": ["radiology-images"],
"requiresApproval": true,
"allowedDays": ["Mon","Tue","Wed","Thu","Fri"]
},
"issuedBy": "did:web:hospital.example",
"validFrom": "2025-01-01T00:00:00Z",
"validUntil": "2025-12-31T23:59:59Z"
}'
```
### Example 3: Customer Service Escalation
```bash
# Register policy: chatbot can escalate to supervisor-ai
curl -X POST http://localhost:4003/a2a/policies \
-H 'Content-Type: application/json' \
-d '{
"fromAgent": "did:web:chatbot-l1.company.example",
"toAgent": "did:web:supervisor-ai.company.example",
"allowedActions": ["escalate", "review", "approve"],
"constraints": {
"maxDuration": 600,
"scope": ["customer-support"],
"requiresApproval": false,
"conditions": {
"minimumSeverity": "medium",
"customerTier": ["premium", "enterprise"]
}
},
"issuedBy": "did:web:company.example",
"validFrom": "2025-01-01T00:00:00Z"
}'
```
## 🧪 Testing
```bash
# Run tests
npm test
# With coverage
npm run test:coverage
# Integration tests
npm run test:integration
```
## 📈 Performance
Benchmarks on standard hardware (4 CPU, 8GB RAM):
| Operation | Performance | Notes |
|-----------|-------------|-------|
| Check delegation | ~8ms | Indexed query |
| List policies | ~15ms | Paginated |
| Register policy | ~20ms | Insert + validation |
| Audit log entry | ~5ms | Async write |
| Throughput | ~3000 req/s | Check operations |
## 🔗 Integration with MCPF
### With MCPF-did-vc
```javascript
import { VCVerifier } from 'mcpf-did-vc';
import { A2ARegistry } from 'mcpf-a2a-registry';
const a2a = new A2ARegistry('http://localhost:4003');
const verifier = new VCVerifier();
// Before delegation, verify both agents
const fromAgentValid = await verifier.verifyAgent(fromDID);
const toAgentValid = await verifier.verifyAgent(toDID);
if (fromAgentValid && toAgentValid) {
// Check delegation permission
const result = await a2a.check(fromDID, toDID, 'analyze');
if (result.allowed) {
// Proceed with delegation
await delegateTask(fromDID, toDID, taskData);
}
}
```
### With MCPF-ans
```javascript
import { ANSClient } from 'mcpf-ans';
import { A2ARegistry } from 'mcpf-a2a-registry';
// Resolve agent names
const ans = new ANSClient('https://ans.example.com');
const fromAgent = await ans.resolve('fraud-detector.risk.bank.example.agent');
const toAgent = await ans.resolve('risk-analyzer.analytics.bank.example.agent');
// Check delegation
const a2a = new A2ARegistry('http://localhost:4003');
const result = await a2a.check(fromAgent.card.did, toAgent.card.did, 'analyze');
```
### With Google A2A Protocol
The MCPF A2A Registry implements Google's A2A protocol concepts:
```javascript
// Google A2A style delegation
{
"agent": "did:web:fraud-detector.bank.example",
"delegateTo": "did:web:risk-analyzer.bank.example",
"task": {
"type": "analyze",
"data": {...}
},
"authorization": {
"registry": "https://a2a-registry.example.com",
"policyId": "pol_123"
}
}
```
## 🤝 Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## 📝 License
MIT License - see [LICENSE](LICENSE)
## 📞 Contact
- **Website:** https://mcpf.dev
- **GitHub:** https://github.com/MCPTrustFramework/MCPF-a2a-registry
- **Issues:** https://github.com/MCPTrustFramework/MCPF-a2a-registry/issues
- **Discussions:** https://github.com/MCPTrustFramework/MCPF-a2a-registry/discussions
## 🙏 Acknowledgments
Based on:
- **Google A2A Protocol** - Agent-to-agent delegation concepts
- **MCPF Specification** - Trust framework integration
## 🔗 Related Projects
- [MCPF-specification](https://github.com/MCPTrustFramework/MCPF-specification) - SSOT
- [MCPF-did-vc](https://github.com/MCPTrustFramework/MCPF-did-vc) - DID/VC infrastructure
- [MCPF-ans](https://github.com/MCPTrustFramework/MCPF-ans) - Agent Name Service
- [MCPF-registry](https://github.com/MCPTrustFramework/MCPF-registry) - MCP Trust Registry
---
**Version:** 1.0.0-alpha
**Last Updated:** December 31, 2025
**Status:** Production-ready
