Message Formats

Design Goals

Efficient overhead: Compact structure for scale
Fast parsing: Simple structure for high-performance processing
Easy implementation: Developers can implement in any language quickly
Human readable: JSON-based for debugging and development

Message Structure

All messages MUST follow this structure:

// Standard Message Format
{
  "from": "hive:agentid:abc123",
  "to": "hive:agentid:xyz789",
  "type": "task_request",
  "data": {
    /* Message-specific content */
  },
  "sig": "ed25519_signature"
}

Field Descriptions

Field	Type	Description	Required
`from`	String	Sender's agent ID	Yes
`to`	String	Recipient's agent ID	Yes
`type`	String	Message type (see types below)	Yes
`data`	Object	Message-specific payload	Yes
`sig`	String	Ed25519 signature of the message	Yes

Message Types

The Protocol defines the following essential message types:

Core Message Types

Type	Description
`task_request`	Request a task to be performed
`task_response`	Accept/reject a task request
`task_update`	Progress update during execution
`task_result`	Final task results
`task_error`	Error during task execution
`capability_query`	Request agent capabilities
`capability_response`	Agent capability advertisement

Optional Message Types

Type	Description
`heartbeat`	Agent availability signal
`agent_identity`	Agent Identification
`contract_proposal`	Formal contract negotiation
`auth_challenge`	Authentication challenge

Design Goal: Most agents only need the 7 core message types. This covers the majority of use cases with minimal complexity.

Message Examples

Task Request

Request an agent to perform a capability:

{
  "from": "hive:agentid:client123",
  "to": "hive:agentid:translator456",
  "type": "task_request",
  "data": {
    "task_id": "task-789",
    "capability": "text-translation",
    "params": {
      "text": "Hello world",
      "target_lang": "es"
    },
    "deadline": "2025-07-18T15:00:00Z"
  },
  "sig": "ed25519_signature_here"
}

Task Response

Accept or reject a task request:

{
  "from": "hive:agentid:translator456",
  "to": "hive:agentid:client123",
  "type": "task_response",
  "data": {
    "task_id": "task-789",
    "status": "accepted",
    "estimated_completion": "2025-07-18T14:45:00Z"
  },
  "sig": "ed25519_signature_here"
}

Task Result

Deliver completed task results:

{
  "from": "hive:agentid:translator456",
  "to": "hive:agentid:client123",
  "type": "task_result",
  "data": {
    "task_id": "task-789",
    "status": "completed",
    "result": {
      "translated_text": "Hola mundo"
    }
  },
  "sig": "ed25519_signature_here"
}

Capability Advertisement

Advertise agent capabilities:

{
  "from": "hive:agentid:translator456",
  "to": "registry",
  "type": "capability_response",
  "data": {
    "capabilities": [
      {
        "id": "text-translation",
        "input": { "text": "string", "target_lang": "string" },
        "output": { "translated_text": "string" }
      }
    ],
    "endpoint": "https://translator456.example.com/api"
  },
  "sig": "ed25519_signature_here"
}

Error Response

Simple error handling:

{
  "from": "hive:agentid:translator456",
  "to": "hive:agentid:client123",
  "type": "task_error",
  "data": {
    "task_id": "task-789",
    "code": 404,
    "error": "capability_not_found",
    "message": "text-translation not available",
    "retry": true
  },
  "sig": "ed25519_signature_here"
}

Capability Query

Request capabilities from an agent or registry:

{
  "from": "hive:agentid:client123",
  "to": "hive:agentid:translator456",
  "type": "capability_query",
  "data": {
    "capabilities": ["text-translation", "image-processing"]
  },
  "sig": "ed25519_signature_here"
}

Message Validation

Required Validation Steps

Structure Check: Ensure all required fields are present
Signature Verification: Verify Ed25519 signature using sender's public key
Agent ID Format: Validate agent ID format (hive:agentid:identifier)
Data Validation: Check data payload against capability requirements

Signature Generation

// Example signature generation (pseudo-code)
const messageToSign = JSON.stringify({
  from: "hive:agentid:abc123",
  to: "hive:agentid:xyz789",
  type: "task_request",
  data: {
    /* payload */
  },
});

const signature = ed25519.sign(messageToSign, privateKey);

Error Handling

For invalid messages, respond with:

{
  "from": "hive:agentid:receiver",
  "to": "hive:agentid:sender",
  "type": "task_error",
  "data": {
    "code": 400,
    "error": "invalid_message_format",
    "message": "Missing required field: task_id",
    "retry": false
  },
  "sig": "signature"
}

Implementation Guidelines

For Massive Scale (Millions of Agents)

Performance Optimizations:

Use connection pooling for HTTP requests
Implement message batching for high-frequency communications
Cache agent public keys to avoid repeated lookups
Use compression for large data payloads

Security Best Practices:

Always verify signatures before processing messages
Implement rate limiting to prevent abuse
Use TLS for all communications
Rotate keys periodically

Error Handling:

Respond to invalid messages with clear error codes
Implement exponential backoff for retries
Log security violations for monitoring

Security Critical: Always verify message signatures before processing. Invalid signatures indicate potential security threats.

Performance Tip: For high-throughput scenarios, consider implementing message batching to reduce network overhead.

Message Formats

On this page