L3 - Capabilities

The Capabilities layer (L3) defines the actions and tools available to agents, providing a structured interface for interacting with external systems and services.

---

Overview

Capabilities are the agent’s “hands” - they enable agents to perform actions beyond pure reasoning. Each capability is a well-defined, validated, and permissioned action that the agent can invoke.

---

Core Concepts

Schema Validation

Input and output schemas ensure type safety and predictability

Permission Model

Declare required permissions for security enforcement

Rate Limiting

Control resource usage and prevent abuse

Error Handling

Graceful degradation and retry mechanisms

---

Capability Definition

Full Schema

{
  "id": "capability-uuid",
  "name": "web_search",
  "version": "1.0.0",
  "description": "Search the web for information",
  "category": "information_retrieval",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "minLength": 1 },
      "max_results": { "type": "integer", "minimum": 1, "maximum": 20 }
    },
    "required": ["query"]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "results": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "title": { "type": "string" },
            "url": { "type": "string", "format": "uri" },
            "snippet": { "type": "string" }
          }
        }
      }
    }
  },
  "permissions": ["network:read"],
  "rate_limit": {
    "requests": 100,
    "period": "1m"
  },
  "timeout_ms": 30000,
  "retry_policy": {
    "max_attempts": 3,
    "backoff_multiplier": 2,
    "initial_delay_ms": 1000
  }
}

---

Key Requirements

Schema & Validation

Requirement	Description
Input Schema	Declare and validate all input parameters
Output Schema	Declare and validate all outputs
Type Safety	Enforce strong typing at runtime

Security & Permissions

Requirement	Description
Permission Declaration	Explicitly declare required permissions
Permission Enforcement	Never exceed declared permissions
Access Logging	Log all capability invocations with trace ID

Reliability

Requirement	Description
Timeout Handling	Implement configurable timeouts
Retry Logic	Use exponential backoff for transient failures
Error Handling	Return structured errors without leaking internals
Cancellation	Support request cancellation

---

Permission Model

Permission Scopes

{
  "permissions": [
    "network:read",      // Read from network (HTTP GET, DNS)
    "network:write",     // Write to network (HTTP POST/PUT)
    "filesystem:read",   // Read local files
    "filesystem:write",  // Write local files
    "database:read",     // Read from database
    "database:write",    // Write to database
    "secrets:read",      // Access secret vault
    "compute:execute"    // Execute compute operations
  ]
}

---

Rate Limiting

Configuration

{
  "rate_limit": {
    "requests": 100,
    "period": "1m",
    "burst": 10
  }
}

Rate Limit Response

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests",
  "retry_after_seconds": 42,
  "limit": 100,
  "remaining": 0,
  "reset_at": "2026-01-15T12:05:00Z"
}

---

Invocation Pattern

Request

{
  "capability_id": "web_search",
  "parameters": {
    "query": "ARAL specification",
    "max_results": 10
  },
  "trace_id": "uuid",
  "timeout_ms": 30000
}

Success Response

{
  "success": true,
  "result": {
    "results": [
      {
        "title": "ARAL Standard Documentation",
        "url": "https://aral-standard.org",
        "snippet": "The open standard for AI agent architectures..."
      }
    ]
  },
  "execution_time_ms": 1234,
  "cost_estimate": {
    "compute": 0.001,
    "network": 0.0005
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "timeout",
    "message": "Request exceeded timeout of 30000ms",
    "retryable": true
  },
  "execution_time_ms": 30000
}

---

Retry Policy

Exponential Backoff

{
  "retry_policy": {
    "max_attempts": 3,
    "backoff_multiplier": 2,
    "initial_delay_ms": 1000,
    "max_delay_ms": 10000,
    "retry_on": ["timeout", "network_error", "rate_limit"]
  }
}

Retry Schedule:

• Attempt 1: immediate
• Attempt 2: 1000ms delay
• Attempt 3: 2000ms delay

---

Best Practices

1. Define Clear Schemas: Comprehensive input/output validation prevents errors
2. Declare Minimal Permissions: Follow principle of least privilege
3. Implement Timeouts: Prevent hanging requests
4. Use Exponential Backoff: Handle transient failures gracefully
5. Provide Cost Estimates: Help orchestrators make informed decisions
6. Log Invocations: Maintain audit trail for debugging
7. Validate Everything: Check inputs and outputs against schemas

---

Common Capability Types

Information Retrieval

Web search, database queries, API calls

Data Processing

Transformation, analysis, aggregation

Communication

Email, chat, notifications

Storage

File operations, database writes

---

Related Layers

• L4 - Reasoning: Decides which capabilities to invoke
• L5 - Persona: Constrains allowed capabilities
• L6 - Orchestration: Routes capability requests
• Specification: Full requirements for L3 Capabilities

---

© 2026 IbIFACE — CC BY 4.0