Implementing ARAL-INTEROP Profile

ℹ️

Information

ARAL-INTEROP is the complete profile with all 7 layers. It adds 26 protocol requirements to ARAL-ORCH’s 94, enabling interoperability between different ARAL implementations.

This guide covers implementing the protocol layer for agent-to-agent communication and interoperability.

---

ARAL-INTEROP Overview

ARAL-CORE (68 req)
    ↓ adds Layer 6
ARAL-ORCH (68 + 26 = 94 req)
    ↓ adds Layer 7
ARAL-INTEROP (68 + 26 + 26 = 120 req) ✅ Complete Standard

---

Layer 7: Protocol Requirements

envelope ✅ Message Format (PRO-001 to PRO-004)

• PRO-001: ARAL Message structure (header, body, signature)
• PRO-002: Message versioning support
• PRO-003: Content negotiation (JSON, MessagePack, Protobuf)
• PRO-004: Compression support (gzip, deflate)

magnifying-glass ✅ Agent Discovery (PRO-005 to PRO-008)

• PRO-005: Service discovery mechanism
• PRO-006: Agent registration/deregistration
• PRO-007: Capability advertisement
• PRO-008: Health check protocol

handshake ✅ Connection Handshake (PRO-009 to PRO-012)

• PRO-009: Initial connection establishment
• PRO-010: Protocol version negotiation
• PRO-011: Capability exchange
• PRO-012: Connection keep-alive

lock ✅ Authentication (PRO-013 to PRO-017)

• PRO-013: mTLS mutual authentication
• PRO-014: JWT token validation
• PRO-015: OAuth 2.0 integration
• PRO-016: API key authentication
• PRO-017: Session management

shield ✅ Authorization (PRO-018 to PRO-020)

• PRO-018: RBAC for agent actions
• PRO-019: Scope-based permissions
• PRO-020: Delegation of authority

alert ✅ Error Handling (PRO-021 to PRO-023)

• PRO-021: Error response format
• PRO-022: Retry-After headers
• PRO-023: Circuit breaker pattern

network-wired ✅ Interoperability (PRO-024 to PRO-026)

• PRO-024: Protocol version support
• PRO-025: Backwards compatibility
• PRO-026: Cross-implementation testing

---

Protocol Architecture

---

Core Implementation

Message Format

interface ARALMessage {
  header: {
    version: string;        // "1.0"
    messageId: string;      // UUID
    timestamp: number;
    sender: string;         // Agent ID
    recipient: string;      // Agent ID
    contentType: string;    // "application/json"
    compression?: string;   // "gzip"
  };
  body: {
    type: 'request' | 'response' | 'notification';
    action?: string;
    parameters?: Record<string, any>;
    result?: any;
    error?: {
      code: string;
      message: string;
      details?: any;
    };
  };
  signature: {
    algorithm: string;      // "SHA256"
    value: string;          // Base64 encoded
    certificate?: string;   // mTLS certificate
  };
}

Agent Discovery

interface AgentInfo {
  id: string;
  name: string;
  endpoint: string;        // gRPC or HTTP/2 URL
  capabilities: string[];  // Available actions
  version: string;         // Protocol version
  healthStatus: 'healthy' | 'unhealthy' | 'unknown';
  lastHeartbeat: number;
}

---

Complete Implementation

protocol.ts

import crypto from 'crypto';

class ProtocolHandler {
  private agentId: string;
  private version: string = '1.0';
  private privateKey: crypto.KeyObject;
  private certificates: Map<string, any> = new Map();

  constructor(agentId: string, privateKeyPath: string) {
    this.agentId = agentId;
    // Load private key for signing
    this.privateKey = crypto.createPrivateKey({
      key: require('fs').readFileSync(privateKeyPath),
      format: 'pem'
    });
  }

  // Create message
  createMessage(
    recipient: string,
    type: 'request' | 'response',
    action?: string,
    data?: any
  ): ARALMessage {
    const message: ARALMessage = {
      header: {
        version: this.version,
        messageId: crypto.randomUUID(),
        timestamp: Date.now(),
        sender: this.agentId,
        recipient,
        contentType: 'application/json'
      },
      body: {
        type,
        action,
        parameters: data
      },
      signature: {
        algorithm: 'SHA256',
        value: ''
      }
    };

    // Sign message
    message.signature.value = this.signMessage(message);
    return message;
  }

  // Sign message
  private signMessage(message: ARALMessage): string {
    const bodyString = JSON.stringify(message.body);
    const signature = crypto.sign('sha256', Buffer.from(bodyString), this.privateKey);
    return signature.toString('base64');
  }

  // Verify message
  verifyMessage(message: ARALMessage, senderPublicKey: string): boolean {
    const bodyString = JSON.stringify(message.body);
    const signature = Buffer.from(message.signature.value, 'base64');

    return crypto.verify(
      'sha256',
      Buffer.from(bodyString),
      senderPublicKey,
      signature
    );
  }

  // Service discovery
  async discoverAgent(agentId: string): Promise<AgentInfo> {
    // Query service registry
    const response = await fetch(`http://registry:8500/agent/${agentId}`);
    const data = await response.json();

    return {
      id: data.id,
      name: data.name,
      endpoint: data.endpoint,
      capabilities: data.capabilities,
      version: data.version,
      healthStatus: 'healthy',
      lastHeartbeat: Date.now()
    };
  }

  // Register agent
  async registerAgent(info: AgentInfo): Promise<void> {
    await fetch('http://registry:8500/register', {
      method: 'POST',
      body: JSON.stringify(info)
    });
  }

  // Health check
  async healthCheck(endpoint: string): Promise<boolean> {
    try {
      const response = await fetch(`${endpoint}/health`, { timeout: 5000 });
      return response.ok;
    } catch {
      return false;
    }
  }

  // Send message to another agent
  async sendMessage(message: ARALMessage, endpoint: string): Promise<ARALMessage> {
    const response = await fetch(`${endpoint}/messages`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Agent-ID': this.agentId,
        'X-Message-ID': message.header.messageId
      },
      body: JSON.stringify(message)
    });

    if (!response.ok) {
      throw new Error(`Protocol error: ${response.status}`);
    }

    return response.json();
  }
}

protocol.py

import json
import uuid
import hashlib
import base64
from datetime import datetime
from typing import Dict, Optional
import aiohttp

class ProtocolHandler:
    def __init__(self, agent_id: str):
        self.agent_id = agent_id
        self.version = '1.0'

    def create_message(
        self,
        recipient: str,
        msg_type: str,
        action: str = None,
        data: dict = None
    ) -> dict:
        message = {
            'header': {
                'version': self.version,
                'messageId': str(uuid.uuid4()),
                'timestamp': int(datetime.now().timestamp() * 1000),
                'sender': self.agent_id,
                'recipient': recipient,
                'contentType': 'application/json'
            },
            'body': {
                'type': msg_type,
                'action': action,
                'parameters': data
            },
            'signature': {
                'algorithm': 'SHA256',
                'value': ''
            }
        }

        # Sign message
        message['signature']['value'] = self._sign_message(message)
        return message

    def _sign_message(self, message: dict) -> str:
        body_str = json.dumps(message['body'])
        hash_obj = hashlib.sha256(body_str.encode())
        return base64.b64encode(hash_obj.digest()).decode()

    def verify_message(self, message: dict, sender_key: str) -> bool:
        body_str = json.dumps(message['body'])
        hash_obj = hashlib.sha256(body_str.encode())
        expected = base64.b64encode(hash_obj.digest()).decode()
        return expected == message['signature']['value']

    async def discover_agent(self, agent_id: str) -> dict:
        async with aiohttp.ClientSession() as session:
            async with session.get(f'http://registry:8500/agent/{agent_id}') as resp:
                return await resp.json()

    async def register_agent(self, info: dict) -> None:
        async with aiohttp.ClientSession() as session:
            await session.post('http://registry:8500/register', json=info)

    async def health_check(self, endpoint: str) -> bool:
        try:
            async with aiohttp.ClientSession() as session:
                async with session.get(
                    f'{endpoint}/health',
                    timeout=aiohttp.ClientTimeout(total=5)
                ) as resp:
                    return resp.status == 200
        except:
            return False

    async def send_message(self, message: dict, endpoint: str) -> dict:
        async with aiohttp.ClientSession() as session:
            async with session.post(
                f'{endpoint}/messages',
                json=message,
                headers={
                    'X-Agent-ID': self.agent_id,
                    'X-Message-ID': message['header']['messageId']
                }
            ) as resp:
                if resp.status != 200:
                    raise Exception(f"Protocol error: {resp.status}")
                return await resp.json()

---

MTLS Configuration

mtls-config.yaml

tls:
  enabled: true

  # Server certificate
  server:
    cert: /certs/agent.crt
    key: /certs/agent.key

  # Client authentication
  client:
    ca: /certs/ca.crt
    verify: true

  # TLS settings
  minVersion: "1.2"
  cipherSuites:
    - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

---

Testing ARAL-INTEROP

Interoperability Test Suite

describe('ARAL-INTEROP Compliance', () => {
  it('should communicate with different ARAL implementations', async () => {
    // Agent A (TypeScript + OpenAI)
    // Agent B (Python + Anthropic)
    // Agent C (Rust + local LLM)

    const messageAtoB = protocolA.createMessage('agent-b', 'request', 'get_weather', {
      city: 'Paris'
    });

    const response = await protocolA.sendMessage(messageAtoB, agentBEndpoint);

    expect(response.body.type).toBe('response');
    expect(response.body.result).toBeDefined();
  });

  it('should verify message signatures', async () => {
    const message = protocolHandler.createMessage('peer', 'request', 'test');
    const isValid = protocolHandler.verifyMessage(message, publicKey);
    expect(isValid).toBe(true);
  });

  it('should discover agents dynamically', async () => {
    const agent = await protocolHandler.discoverAgent('technical-support');
    expect(agent.capabilities).toContain('diagnose');
    expect(agent.healthStatus).toBe('healthy');
  });
});

---

Certification Requirements

To achieve ARAL-INTEROP Conformance:

✅ Implement all L1-L6 requirements (ARAL-ORCH = 94 reqs) ✅ Implement all L7 requirements (26 reqs) ✅ Pass interoperability tests with other implementations ✅ Support message signing and verification ✅ Implement mTLS or OAuth2 authentication ✅ Support service discovery and health checks

aral-test --profile interop --config ./agent-config.json

# Expected output:
# ✅ L1-L6: All ARAL-ORCH requirements passed
# ✅ L7: All protocol requirements passed
# ✅ Interoperability: Cross-implementation tests passed
#
# Result: 120/120 requirements met
# Status: ARAL-INTEROP Conformant ✅

---

Badge & Recognition

Once certified, display your badge:

[![ARAL-INTEROP Conformant](https://img.shields.io/badge/ARAL-INTEROP%20Conformant-success)](https://aral.dev/conformance/interop)

Your agent is now a fully compliant, interoperable ARAL system! 🎉

---

Next Steps

layer-group Protocol Layer

Deep technical details of Layer 7

shield-check Coming Soon

Production deployment patterns

sitemap Multi-Agent Example

See interoperability in action

book Full Specification

Complete 26 protocol requirements