MoltSpeak Protocol Specification

Version 0.1 (Draft)

Overview

MoltSpeak is a structured communication protocol designed for AI agents to communicate efficiently, securely, and unambiguously. It prioritizes:

Compactness: 10x reduction vs natural language for common operations
Security: E2E encryption, verified identities, explicit data classification
Privacy: PII detection, consent tracking, data minimization
Interoperability: Model-agnostic, platform-agnostic
Auditability: Human-readable when inspected

Why JSON?

Universal parser support, human-readable for audit/debug, sufficient for agent-scale throughput, easy to sign and encrypt (vs binary).

Design Principles

1. Fail-Safe Default

If a message is unclear, malformed, or missing required fields → DO NOT PROCESS. Return an error. Never guess.

2. Explicit Over Implicit

All context must be in the message. No assumptions about shared state.

3. Privacy by Default

PII is never transmitted unless explicitly tagged with consent proof.

4. Human Auditable

Messages use JSON (not binary) so humans can inspect, log, and debug.

5. Minimal Trust

Verify everything. Capabilities must be proven, not claimed.

6. Extensible Core

The protocol defines a stable core with namespaced extensions.

Quick Reference

┌────────────────────────────────────────────────────────┐ │ MoltSpeak Quick Ref │ ├────────────────────────────────────────────────────────┤ │ Message: {v, id, ts, op, from, to, p, cls, sig} │ │ │ │ Operations: │ │ hello - Initiate handshake │ │ verify - Challenge/response auth │ │ query - Request information │ │ respond - Reply to query │ │ task - Delegate work │ │ stream - Large/realtime data │ │ tool - Invoke tool │ │ consent - PII consent flow │ │ error - Error response │ │ │ │ Classifications: pub, int, conf, pii, sec │ │ │ │ Golden Rule: Unclear = Don't transmit │ └────────────────────────────────────────────────────────┘

Base Message Structure

JSON

{
  "v": "0.1",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "ts": 1703280000000,
  "op": "query",
  "from": {
    "agent": "claude-agent-7x9k",
    "org": "anthropic",
    "key": "ed25519:abc123..."
  },
  "to": {
    "agent": "gpt-assistant-m2n4",
    "org": "openai"
  },
  "p": {},
  "cls": "internal",
  "sig": "ed25519:..."
}

Field Reference

Full Name	Short Key	Type	Required
version	`v`	string	✓
message_id	`id`	string (UUID)	✓
timestamp	`ts`	integer (unix ms)	✓
operation	`op`	string	✓
sender	`from`	object	Most ops
recipient	`to`	object	Most ops
payload	`p`	object	✓
classification	`cls`	string	Recommended
signature	`sig`	string	Auth required
encryption	`enc`	object	-
reply_to	`re`	string (message id)	For responses
expires	`exp`	integer (unix ms)	-
capabilities_required	`cap`	array	-

Envelope Structure

Messages are wrapped in an envelope for transport:

JSON

{
  "moltspeak": "0.1",
  "envelope": {
    "encrypted": false,
    "compressed": false,
    "encoding": "utf-8"
  },
  "message": { ... }
}

Encrypted Envelope

JSON

{
  "moltspeak": "0.1",
  "envelope": {
    "encrypted": true,
    "algorithm": "x25519-xsalsa20-poly1305",
    "sender_public": "x25519:abc...",
    "nonce": "base64:..."
  },
  "ciphertext": "base64:..."
}

Identity Model

Each agent has:

Agent ID: Unique identifier (format: {model}-{role}-{instance})
Organization: The controlling entity
Public Key: Ed25519 for signing, X25519 for encryption
Capability Set: What operations this agent can perform
Trust Level: Determined by verification chain

Handshake Flow

┌─────────────┐ ┌─────────────┐ │ Agent A │ │ Agent B │ └──────┬──────┘ └──────┬──────┘ │ │ │ 1. HELLO (my identity, my caps) │ │────────────────────────────────────────>│ │ │ │ 2. HELLO_ACK (your identity, my caps) │ │<────────────────────────────────────────│ │ │ │ 3. VERIFY (challenge) │ │────────────────────────────────────────>│ │ │ │ 4. VERIFY_RESPONSE (signed challenge) │ │<────────────────────────────────────────│ │ │ │ 5. SESSION_ESTABLISHED │ │<───────────────────────────────────────>│ │ │

HELLO Message

JSON

{
  "v": "0.1",
  "op": "hello",
  "from": {
    "agent": "claude-assistant-a1b2",
    "org": "anthropic",
    "key": "ed25519:mKj8Gf2...",
    "enc_key": "x25519:nL9hHg3..."
  },
  "p": {
    "protocol_versions": ["0.1"],
    "capabilities": ["query", "task", "stream"],
    "extensions": ["tool-use", "memory"],
    "max_message_size": 1048576,
    "supported_cls": ["public", "internal", "confidential"]
  },
  "ts": 1703280000000,
  "sig": "ed25519:..."
}

Verification

After hello exchange, agents verify each other's identity:

JSON

{
  "v": "0.1",
  "op": "verify",
  "p": {
    "challenge": "random-256-bit-value",
    "timestamp": 1703280001000
  },
  "sig": "ed25519:..."
}

After verification, a session is established with:

Session ID: Shared reference for this conversation
Session Key: Derived via X25519 key exchange
Expiry: Session timeout (default: 1 hour)

All Operations

Operation	Purpose	Response
`hello`	Initiate handshake	hello_ack
`verify`	Challenge-response auth	verify_response
`query`	Request information	respond
`respond`	Reply to query	-
`task`	Delegate work	task_ack / respond
`stream`	Large/realtime data	stream chunks
`tool`	Invoke tool	respond
`consent`	PII consent flow	consent_response
`error`	Error response	-

query

Request information from another agent.

JSON

{
  "op": "query",
  "p": {
    "domain": "weather",
    "intent": "forecast",
    "params": {
      "location": "Tokyo",
      "timeframe": "+1d"
    },
    "response_format": {
      "type": "structured",
      "schema": "weather-forecast-v1"
    }
  }
}

respond

Reply to a query. Must include re field referencing the original message.

JSON

{
  "op": "respond",
  "re": "550e8400-e29b-41d4-a716-446655440000",
  "p": {
    "status": "success",
    "data": {
      "location": "Tokyo",
      "date": "2024-12-23",
      "high_c": 12,
      "low_c": 5,
      "conditions": "partly-cloudy"
    },
    "schema": "weather-forecast-v1"
  }
}

task

Delegate a task to another agent with constraints and callbacks.

JSON

{
  "op": "task",
  "p": {
    "action": "create",
    "task_id": "task-789",
    "type": "research",
    "description": "Find recent papers on transformer efficiency",
    "constraints": {
      "max_results": 10,
      "recency": "6mo",
      "sources": ["arxiv", "semanticscholar"]
    },
    "deadline": 1703283600000,
    "priority": "normal",
    "callback": {
      "on_complete": true,
      "on_progress": false
    }
  }
}

tool

Invoke a tool through another agent.

JSON

{
  "op": "tool",
  "p": {
    "action": "invoke",
    "tool": "web-search",
    "input": {
      "query": "MoltSpeak protocol",
      "max_results": 5
    }
  },
  "cap": ["tool.invoke"]
}

stream

For large or real-time data.

JSON

{
  "op": "stream",
  "p": {
    "action": "start",
    "stream_id": "stream-456",
    "type": "text",
    "chunk_size": 1024
  }
}

consent

Handle human data consent flows for PII.

JSON

{
  "op": "consent",
  "p": {
    "action": "request",
    "data_types": ["calendar", "email"],
    "purpose": "Schedule coordination",
    "duration": "session",
    "human": "user:jane@example.com"
  }
}

error

Structured error with code, category, and recovery hints.

JSON

{
  "op": "error",
  "re": "original-message-id",
  "p": {
    "code": "E_INVALID_PARAM",
    "category": "validation",
    "message": "Parameter 'location' is required for weather queries",
    "field": "p.params.location",
    "recoverable": true,
    "suggestion": {
      "action": "retry",
      "fix": "Add location parameter"
    }
  }
}

Capability Categories

Category	Capabilities
core	query, respond, error
task	task.create, task.status, task.cancel
stream	stream.start, stream.chunk, stream.end
tool	tool.invoke, tool.list
memory	memory.store, memory.retrieve
human	human.consent, human.notify
code	code.execute, code.sandbox

Capability Attestation

Capabilities can be self-declared (low trust), org-attested (signed by organization), or verified through challenge-response.

JSON

{
  "capability": "code.execute",
  "attestation": {
    "type": "org-signed",
    "org": "anthropic",
    "signature": "ed25519:...",
    "expires": 1735689600000
  }
}

Data Classification

Every message MUST have a classification tag (cls field).

Level	Tag	Description	Handling
Public	`pub`	Safe for anyone	No restrictions
Internal	`int`	Agent-to-agent only	Log ok, no human view by default
Confidential	`conf`	Sensitive business data	Encrypted, limited retention
PII	`pii`	Personal data	Consent required, masked by default
Secret	`sec`	Credentials, keys	Never log, memory-only

PII Handling

When transmitting PII, messages must include consent proof:

JSON

{
  "cls": "pii",
  "pii_meta": {
    "types": ["name", "email", "location"],
    "consent": {
      "granted_by": "user:jane@example.com",
      "purpose": "calendar-sync",
      "expires": 1703366400000,
      "proof": "consent-token:abc123"
    },
    "mask_fields": ["email"]
  }
}

Automatic PII Detection

Agents MUST scan outgoing messages for PII patterns (emails, phone numbers, addresses, names, IDs, etc.). If detected without consent tag → BLOCK TRANSMISSION.

Extension Mechanism

MoltSpeak can be extended via namespaced extensions.

JSON

{
  "op": "query",
  "p": { ... },
  "ext": {
    "anthropic.reasoning": {
      "show_thinking": true,
      "confidence_threshold": 0.8
    },
    "openai.functions": {
      "allowed_functions": ["search", "calculate"]
    }
  }
}

Extension Rules

Extensions MUST be namespaced: {org}.{extension}
Core operations MUST NOT require extensions
Unsupported extensions MUST be ignored (not error)
Extensions can extend but not override core behavior

Error Codes

Code	Category	Description
`E_PARSE`	protocol	Message not valid JSON
`E_VERSION`	protocol	Unsupported protocol version
`E_SCHEMA`	validation	Message doesn't match schema
`E_MISSING_FIELD`	validation	Required field missing
`E_INVALID_PARAM`	validation	Parameter value invalid
`E_AUTH_FAILED`	auth	Authentication failed
`E_SIGNATURE`	auth	Signature verification failed
`E_CAPABILITY`	auth	Required capability not held
`E_CONSENT`	privacy	PII transmitted without consent
`E_CLASSIFICATION`	privacy	Classification level mismatch
`E_RATE_LIMIT`	transport	Too many requests
`E_TIMEOUT`	transport	Operation timed out
`E_TASK_FAILED`	execution	Task could not complete
`E_INTERNAL`	execution	Internal agent error

Transport

MoltSpeak is transport-agnostic. Recommended transports:

HTTPS - Most common, REST-style
WebSocket - For streaming/bidirectional
gRPC - High-performance scenarios
Message Queue - Async, decoupled

HTTP Endpoints (Reference)

HTTP

POST /moltspeak/v0.1/message     # Single message
POST /moltspeak/v0.1/batch       # Batch messages
WS   /moltspeak/v0.1/stream      # WebSocket stream

Message Size Limits

Context	Limit
Single message	1 MB
Batch message	10 MB
Stream chunk	64 KB
Session total	100 MB