Contracts Documentation

Overview

Contracts are machine-readable JSON documents that define capabilities, requirements, and metadata for participants in the CyberAi ecosystem.

Contract Types

Agent Contracts

Define AI agents that perform specific tasks such as security audits, code analysis, or automated workflows.

Location: /contracts/agents/

Repository Contracts

Define code repositories that provide functionality, tools, or services to the ecosystem.

Location: /contracts/repos/

Runner Contracts

Define execution environments where agents can run. (Coming soon)

Location: /contracts/runners/

Contract Schema

All contracts must conform to the contract schema defined in /contracts/contract.schema.json.

Required Fields

{
  "version": "1.0.0",          // Semantic version{'
'}  "type": "agent",             // agent | repository | runner{'
'}  "metadata": {'{'}{'
'}    "name": "example-agent",   // Unique name{'
'}    "description": "...",      // Clear description{'
'}    "owner": "org-name"        // Owner identifier{'
'}  {'},'}{'
'}  "capabilities": {'{'}{'
'}    // What the entity can do{'
'}  {'}'}{'
'}{'}'}

Optional Fields

requirements - Dependencies and permissions
compliance - Security and certification info

Creating a Contract

Step 1: Choose a Template

Start with an example contract:

contracts/agents/example-agent.json
contracts/repos/cyberai.json

Step 2: Fill in Details

{
  "$schema": "../contract.schema.json",{'
'}  "version": "1.0.0",{'
'}  "type": "agent",{'
'}  "metadata": {'{'}{'
'}    "name": "my-security-agent",{'
'}    "description": "Custom security analysis agent",{'
'}    "owner": "my-org",{'
'}    "repository": "https://github.com/my-org/my-agent",{'
'}    "tags": ["security", "analysis"]{'
'}  {'},'}{'
'}  "capabilities": {'{'}{'
'}    "actions": [{'
'}      {'{'}{'
'}        "name": "scan",{'
'}        "description": "Scan code for vulnerabilities",{'
'}        "parameters": {'{'}{'
'}          "target": "string"{'
'}        {'}'}{'
'}      {'}'}{'
'}    ]{'
'}  {'}'}{'
'}{'}'}

Step 3: Validate

npm install -g ajv-cli
ajv validate -s contracts/contract.schema.json -d "contracts/agents/my-security-agent.json"

Step 4: Submit

Create a pull request with your contract.

Validation

Contracts are automatically validated on every commit via the contracts-validate.yml workflow.

Manual Validation

# Validate all contracts
./tools/audit/audit.sh

# Validate specific contract
ajv validate -s contracts/contract.schema.json -d "contracts/agents/your-contract.json"

Best Practices

Use semantic versioning for contract versions
Provide clear, detailed descriptions
Include all required permissions
Document all capabilities and actions
Keep contracts up-to-date with implementation
Tag contracts appropriately for discoverability

Examples

API Access

Contracts can be accessed via the GitHub API or directly from the repository:

# Get all agent contracts
curl https://api.github.com/repos/SolanaRemix/CyberAi/contents/contracts/agents

# Get specific contract
curl https://raw.githubusercontent.com/SolanaRemix/CyberAi/main/contracts/agents/example-agent.json