L7 - Protocol

The Protocol layer (L7) is the outermost layer of the ARAL architecture, responsible for external communication, protocol translation, and interoperability with other systems.

---

Overview

The Protocol layer acts as the agent’s “ambassador” to the outside world, translating between external protocols and the internal Envelope format used throughout ARAL.

---

Core Responsibilities

Protocol Translation

Convert external protocols to internal Envelope format

Authentication

Verify identity of external callers

Rate Limiting

Protect against abuse and overload

API Documentation

Expose OpenAPI/AsyncAPI specifications

---

Supported Protocols

Protocol Matrix

Protocol	Support	Use Case	Priority
MCP	MUST	Model Context Protocol	High
A2A	SHOULD	Agent-to-Agent	High
REST	MUST	HTTP APIs	High
gRPC	MAY	High-performance	Medium
WebSocket	SHOULD	Real-time	Medium
GraphQL	MAY	Flexible queries	Low

---

Key Requirements

Protocol Support

Requirement	Description
MCP Compatibility	Must support Model Context Protocol
REST APIs	Must expose HTTP/REST endpoints
Message Validation	Validate all incoming messages
Envelope Transform	Convert to internal Envelope format

Security

Requirement	Description
Authentication	Verify caller identity (OAuth2/OIDC)
Authorization	Check permissions before processing
TLS Required	Use TLS 1.3+ for external communication
Request Signing	Support cryptographic request signing

Reliability

Requirement	Description
Rate Limiting	Prevent abuse and overload
Timeout Handling	Enforce request timeouts
Error Responses	Return structured, helpful errors
Compression	Support gzip/brotli compression

---

Model Context Protocol (MCP)

Request Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "web_search",
    "arguments": {
      "query": "ARAL specification"
    }
  }
}

Response Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 10 results for 'ARAL specification'"
      }
    ]
  }
}

MCP to Envelope Translation

{
  "envelope": {
    "id": "generated-uuid",
    "trace_id": "generated-trace-uuid",
    "timestamp": "2026-01-15T12:00:00Z",
    "version": "1.0",
    "source": {
      "layer": "L7",
      "protocol": "mcp",
      "caller_id": "external-client"
    },
    "destination": {
      "layer": "L3",
      "capability_id": "web_search"
    },
    "payload": {
      "query": "ARAL specification"
    },
    "metadata": {
      "mcp_request_id": 1,
      "mcp_method": "tools/call"
    }
  }
}

---

REST API

Endpoint Design

GET    /api/v1/agents/{agent_id}/status
POST   /api/v1/agents/{agent_id}/invoke
GET    /api/v1/agents/{agent_id}/capabilities
POST   /api/v1/agents/{agent_id}/capabilities/{capability_id}
GET    /api/v1/agents/{agent_id}/memory
POST   /api/v1/agents/{agent_id}/memory
DELETE /api/v1/agents/{agent_id}/memory/{memory_id}

Request Example

POST /api/v1/agents/agent-123/capabilities/web_search
Authorization: Bearer eyJhbGc...
Content-Type: application/json
X-Trace-Id: trace-uuid

{
  "parameters": {
    "query": "ARAL specification",
    "max_results": 10
  }
}

Response Example

HTTP/1.1 200 OK
Content-Type: application/json
X-Trace-Id: trace-uuid
X-Request-Id: request-uuid

{
  "success": true,
  "result": {
    "results": [...]
  },
  "execution_time_ms": 1234
}

---

Authentication & Authorization

OAuth 2.0 / OIDC

POST /api/v1/agents/agent-123/invoke
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "capability": "web_search",
  "parameters": {...}
}

JWT Token Validation

{
  "token_validation": {
    "algorithm": "RS256",
    "issuer": "https://auth.example.com",
    "audience": "aral-agent-api",
    "claims": {
      "sub": "user-123",
      "scope": ["agent:read", "agent:invoke"],
      "exp": 1737024000
    }
  }
}

mTLS (Mutual TLS)

{
  "mtls": {
    "enabled": true,
    "client_cert_required": true,
    "trusted_ca": "/path/to/ca.crt",
    "verify_depth": 2
  }
}

---

Rate Limiting

Configuration

{
  "rate_limits": {
    "global": {
      "requests_per_second": 100,
      "burst": 20
    },
    "per_user": {
      "requests_per_minute": 60,
      "requests_per_hour": 1000
    },
    "per_ip": {
      "requests_per_second": 10
    }
  }
}

Rate Limit Headers

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1737024000
Retry-After: 42

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again in 42 seconds."
}

---

WebSocket Support

Connection

const ws = new WebSocket('wss://agent.example.com/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'subscribe',
    agent_id: 'agent-123',
    channels: ['status', 'events']
  }));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log('Received:', message);
};

Message Format

{
  "type": "event",
  "timestamp": "2026-01-15T12:00:00Z",
  "agent_id": "agent-123",
  "event": "decision_made",
  "data": {
    "decision_id": "uuid",
    "action": "web_search",
    "confidence": 0.95
  }
}

---

Error Responses

Standard Error Format

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required parameter 'query'",
    "details": {
      "field": "query",
      "expected_type": "string"
    },
    "trace_id": "uuid",
    "timestamp": "2026-01-15T12:00:00Z"
  }
}

Error Codes

Code	HTTP Status	Description
invalid_request	400	Malformed or invalid request
unauthorized	401	Missing or invalid authentication
forbidden	403	Insufficient permissions
not_found	404	Resource not found
rate_limit_exceeded	429	Too many requests
internal_error	500	Internal server error
service_unavailable	503	Service temporarily unavailable

---

OpenAPI Specification

Automatic Generation

{
  "openapi": "3.1.0",
  "info": {
    "title": "ARAL Agent API",
    "version": "1.0.0",
    "description": "API for interacting with ARAL-compliant agents"
  },
  "servers": [
    {
      "url": "https://agent.example.com/api/v1"
    }
  ],
  "paths": {
    "/agents/{agent_id}/invoke": {
      "post": {
        "summary": "Invoke agent capability",
        "parameters": [...],
        "requestBody": {...},
        "responses": {...}
      }
    }
  }
}

---

Protocol Negotiation

Content-Type Negotiation

POST /api/v1/agents/agent-123/invoke
Accept: application/json, application/protobuf;q=0.9
Content-Type: application/json

Version Negotiation

GET /api/v1/agents/agent-123/status
X-API-Version: 2.0

Response:

HTTP/1.1 200 OK
X-API-Version: 2.0
X-Supported-Versions: 1.0, 2.0

---

Best Practices

1. Always Use TLS: Encrypt all external communication
2. Implement Authentication: Verify caller identity
3. Rate Limit Aggressively: Protect against abuse
4. Validate All Inputs: Never trust external data
5. Return Structured Errors: Help callers debug
6. Document Your API: Generate OpenAPI specs
7. Support Protocol Negotiation: Allow client preferences
8. Log External Interactions: Maintain audit trail
9. Implement Timeouts: Prevent hanging connections
10. Version Your APIs: Enable backward compatibility

---

Protocol-Specific Features

MCP

Tool calling, streaming, context management

REST

CRUD operations, pagination, filtering

WebSocket

Real-time events, bidirectional streaming

gRPC

High performance, streaming, type safety

---

Related Layers

• L6 - Orchestration: Receives translated Envelopes
• Specification: Full requirements for L7 Protocol
• Security: Security requirements for external communication

---

External Resources

• Model Context Protocol (MCP)
• OpenAPI Specification
• OAuth 2.0
• WebSocket Protocol

---

© 2026 IbIFACE — CC BY 4.0