Capability Format

The Protocol uses a streamlined format that focuses on essential information. This approach enables faster discovery and matching for scalable agent systems.

Design Philosophy

The capability format focuses on what agents actually need to know:

What the capability does (ID)
What inputs it requires
What outputs it provides

Capability Format

Agents can advertise/register capabilities using this essential format:

{
  "capabilities": [
    {
      "id": "text-translation",
      "input": {
        "text": "string",
        "source_lang": "string",
        "target_lang": "string"
      },
      "output": {
        "translated_text": "string"
      }
    },
    {
      "id": "image-resize",
      "input": {
        "image_url": "string",
        "width": "number",
        "height": "number"
      },
      "output": {
        "resized_image_url": "string"
      }
    }
  ]
}

Benefits of this approach:

Faster parsing and discovery matching
Easy to generate programmatically
Human readable for debugging
Type-safe with clear input/output contracts

Capability Components

Essential Fields Only

Field	Description	Required
`id`	Unique capability identifier	Yes
`input`	Input parameter types	Yes
`output`	Output field types	Yes

That's it! No version numbers, categories, examples, or performance metrics.

Input/Output Specification

Simple type system:

"string" - Text data
"number" - Numeric data
"boolean" - True/false values
"object" - Nested JSON object
"array" - List of items

Example specifications:

// Text processing capability
{
  "id": "text-processing",
  "input": { "text": "string", "operation": "string" },
  "output": { "result": "string" }
}

// Data analysis capability
{
  "id": "data-analysis",
  "input": { "dataset": "array", "analysis_type": "string" },
  "output": { "insights": "object", "confidence": "number" }
}

// File conversion capability
{
  "id": "file-convert",
  "input": { "file_url": "string", "target_format": "string" },
  "output": { "converted_file_url": "string" }
}

Advanced Types

For more complex scenarios, you can add validation:

{
  "id": "image-processing",
  "input": {
    "image_url": "string",
    "operation": { "type": "string", "enum": ["resize", "crop", "filter"] },
    "width": { "type": "number", "min": 1, "max": 4000 },
    "height": { "type": "number", "min": 1, "max": 4000 }
  },
  "output": {
    "processed_image_url": "string",
    "metadata": "object"
  }
}

Advertisement Methods

Agents can advertise their capabilities through several mechanisms:

Registry Publication

Agents register their capabilities with a central or federated registry:

POST /registry/agents HTTP/1.1
Host: www.openhive.sh
Content-Type: application/json

{
  "agentId": "agent-abc123",
  "publicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
  "endpoints": {
    "http": "https://agent-abc123.example.com/api",
    "websocket": "wss://agent-abc123.example.com/ws"
  },
  "capabilities": [ /* capability objects */ ]
}

Capability Endpoint

Agents expose a standard endpoint for capability discovery:

GET /capabilities HTTP/1.1
Host: agent-abc123.example.com
Accept: application/json

Capability Discovery

Agents can discover capabilities through complementary methods:

Registry Query

Querying a registry for agents with specific capabilities:

GET /registry/agents?capability=text-translation&language=es HTTP/1.1
Host: www.openhive.sh
Accept: application/json

Direct Query

Directly querying an agent for its capabilities:

{
  "messageType": "capability_query",
  "payload": {
    "queryType": "ALL"
  }
}

Or for specific capabilities:

{
  "messageType": "capability_query",
  "payload": {
    "queryType": "SPECIFIC",
    "capabilityIds": ["text-translation", "image-generation"]
  }
}

Implementation Considerations

When implementing capability advertisement and discovery:

Accurate Descriptions: Ensure capability descriptions are accurate and complete
Versioning: Clearly version capabilities to handle compatibility
Update Frequency: Balance between freshness and network overhead
Validation: Validate capability descriptions against the schema
Caching: Implement appropriate caching strategies for efficiency

Agents should never advertise capabilities they cannot reliably provide. Misrepresenting capabilities damages trust in the network.

When advertising capabilities, include detailed parameter specifications to help potential requesters understand exactly what inputs are required and what constraints apply.

Capability Format

On this page