Implementing EKP: A Walkthrough With the Test Vectors

The EuKollab Protocol, EKP, is published so that anyone can implement it, in any language, without asking EuKreate. Agents From Different Builders Need a Shared Language, part 11 of When AI Agents Collaborate, argued that a shared language has to be open, testable and versioned. This guide is about the second of those. It shows how an implementer checks two mechanisms of their work, canonical JSON and call receipts, against EKP’s published test vectors, and the shape of their messages against its schemas, before any message reaches the network. Passing these checks covers those mechanisms; it is not full EKP conformance, which section 5 comes back to.

What we tested. EKP 1.2 at the repository’s tag v1.2 (commit da9eb25), Python 3.13.6, jsonschema 4.26.0 and referencing 0.37.0. Cloning the repository and installing the two libraries need a network connection; everything after that runs locally.

git clone --branch v1.2 https://github.com/eukollab/ekp
cd ekp
python -m venv .venv && . .venv/bin/activate
pip install "jsonschema==4.26.0" "referencing==0.37.0"

Save the three files below in that folder, the root of the repository, and run them from there.

What is in the repository

Most of EKP is ordinary JSON over the Model Context Protocol, and a standard JSON Schema validator checks it. The vectors cover the part where “nearly right” is wrong: the bytes that get hashed and authenticated. Two implementations that disagree on one byte of a canonical form will disagree on every receipt they check.

1. Canonical JSON

Receipts and fingerprints are computed over ekl-json-1, EKP’s canonical JSON. It is RFC 8785 with EKP’s restrictions: keys sorted by UTF-16 code units, numbers written as ECMAScript writes them, integer literals within ±2^53, no duplicate keys, no NaN or Infinity, and no invalid Unicode such as a lone surrogate. A number with a fraction or an exponent is read as the nearest IEEE 754 double, as RFC 8785 requires, so 333333333.33333329 is written 333333333.3333333; the published vectors include that case. An integer literal beyond ±2^53 would lose digits that way, so it is refused instead. vectors/ekl-json-1.json holds valid inputs with their canonical form and SHA-256, and invalid inputs that must be refused.

Here is an implementation in Python, written from PROTOCOL.md. Save it as canonical.py:

"""ekl-json-1: RFC 8785 canonical JSON with EKP's restrictions, written from PROTOCOL.md section 9.5."""

import json
import math
from decimal import Decimal


def _number(x: float | int) -> str:
    if isinstance(x, int):
        # EKP: an integer literal must fit in ±2^53, so it is never rounded on the way in.
        if abs(x) > 2**53:
            raise ValueError("integer outside ±2^53")
        return str(x)
    if not math.isfinite(x):
        raise ValueError("NaN and Infinity have no JSON form")
    if x == 0:
        return "0"  # also -0.0
    # repr gives the shortest digits that read back as this double; Decimal splits them into digits and exponent.
    _, digit_tuple, exponent = Decimal(repr(abs(x))).normalize().as_tuple()
    digits = "".join(map(str, digit_tuple))
    k, n = len(digits), len(digits) + int(exponent)
    # ECMAScript's Number.prototype.toString layout: where the point goes, and when to use an exponent.
    if k <= n <= 21:
        text = digits + "0" * (n - k)
    elif 0 < n <= 21:
        text = digits[:n] + "." + digits[n:]
    elif -6 < n <= 0:
        text = "0." + "0" * -n + digits
    else:
        mantissa = digits if k == 1 else digits[0] + "." + digits[1:]
        text = f"{mantissa}e{'+' if n - 1 > 0 else '-'}{abs(n - 1)}"
    return ("-" if x < 0 else "") + text


def _string(s: str) -> str:
    # RFC 8785 requires an error for invalid Unicode. json.loads joins escaped surrogate pairs into one character,
    # so any surrogate left in a string is a lone one.
    if any("\ud800" <= c <= "\udfff" for c in s):
        raise ValueError("lone surrogate")
    return json.dumps(s, ensure_ascii=False)


def _value(v: object) -> str:
    if v is None or v is True or v is False:
        return json.dumps(v)
    if isinstance(v, (int, float)):
        return _number(v)
    if isinstance(v, str):
        return _string(v)
    if isinstance(v, list):
        return "[" + ",".join(_value(i) for i in v) + "]"
    if isinstance(v, dict):
        keys = sorted(v, key=lambda s: s.encode("utf-16-be", "surrogatepass"))
        return "{" + ",".join(_string(k) + ":" + _value(v[k]) for k in keys) + "}"
    raise ValueError(f"cannot canonicalise {type(v).__name__}")


def _no_duplicates(pairs: list[tuple[str, object]]) -> dict[str, object]:
    keys = [k for k, _ in pairs]
    if len(keys) != len(set(keys)):
        raise ValueError("duplicate keys")
    return dict(pairs)


def _refuse(constant: str) -> float:
    raise ValueError(f"{constant} has no JSON form")


def canonical(text: str) -> str:
    return _value(json.loads(text, object_pairs_hook=_no_duplicates, parse_constant=_refuse))

The part that takes care is numbers. We rely on Python’s repr for the shortest digits that read back as the same double, which is also what ECMAScript’s algorithm produces; that agreement is a property to test, not to assume, and the vectors below test it for the cases they cover. What certainly differs is the layout: where the decimal point goes, and when to switch to an exponent. That is what the second half of _number does. Strings take care too: RFC 8785 requires invalid Unicode, such as a lone surrogate escaped as \ud800, to be an error, so _string refuses it; the published vectors include that case.

If you can, use a vetted RFC 8785 library in your language and add EKP’s restrictions to it, rather than write your own. Either way, check it as below.

2. Check it against the vectors

check_vectors.py runs every published vector, adds a few cases of our own, and verifies the published call receipt. It counts failures and exits non-zero if there are any, so it can stop a build:

"""Checks canonical.py against EKP's published vectors and a few cases of our own, and verifies the published
call receipt. Exits non-zero if anything fails, so it can gate a build."""

import hashlib
import hmac
import json
import sys

from canonical import canonical

failures = 0


def report(ok: bool, what: str, detail: str = "") -> None:
    global failures
    failures += not ok
    print("PASS" if ok else "FAIL", what, detail)


vectors = json.load(open("vectors/ekl-json-1.json"))
for v in vectors["valid"]:
    out = canonical(v["input"])
    report(out == v["canonical"] and hashlib.sha256(out.encode()).hexdigest() == v["sha256"], "valid:", v["name"])
for v in vectors["invalid"]:
    try:
        canonical(v["input"])
        report(False, "invalid:", f"{v['name']} (accepted)")
    except ValueError as refused:
        report(True, "invalid:", f"{v['name']} ({refused})")

# Cases of our own. A lone surrogate must be refused in a key too (RFC 8785, section 3.2.2.2). A number with a
# fraction or exponent is read as the nearest double and written as that double, as RFC 8785 requires.
OURS = [('{"\\udc00": 1}', None), ("[9007199254740993.0]", "[9007199254740992]"),
        ('["\\ud83d\\ude00"]', '["\U0001f600"]')]
for text, expected in OURS:
    try:
        out = canonical(text)
        report(out == expected, "ours:", f"{text} -> {out}")
    except ValueError as refused:
        report(expected is None, "ours:", f"{text} refused ({refused})")

r = json.load(open("vectors/call-receipt.json"))
receipt = r["receipt"]
key = hmac.new(r["receipt_secret"].encode(), b"ekl-receipt-1.1\x00" + receipt["key_id"].encode(), hashlib.sha256).digest()
tag = hmac.new(key, canonical(json.dumps(receipt)).encode(), hashlib.sha256).hexdigest()
digest = hashlib.sha256(canonical(json.dumps({**receipt, "auth_tag": tag})).encode()).hexdigest()
report(tag == r["auth_tag"], "receipt:", "auth_tag")
report(digest == r["receipt_digest"], "receipt:", "receipt_digest")

print(f"{failures} failure(s)")
sys.exit(1 if failures else 0)

$ python check_vectors.py
PASS valid: numbers
PASS valid: key order by UTF-16 code units
PASS valid: string escapes
PASS valid: nested invoice
PASS valid: empty
PASS invalid: duplicate keys (duplicate keys)
PASS invalid: NaN (NaN has no JSON form)
PASS invalid: Infinity (Infinity has no JSON form)
PASS invalid: integer beyond 2^53 (integer outside ±2^53)
PASS invalid: overflowing float (NaN and Infinity have no JSON form)
PASS invalid: lone surrogate (lone surrogate)
PASS ours: {"\udc00": 1} refused (lone surrogate)
PASS ours: [9007199254740993.0] -> [9007199254740992]
PASS ours: ["\ud83d\ude00"] -> ["😀"]
PASS receipt: auth_tag
PASS receipt: receipt_digest
0 failure(s)

Each invalid input is refused for the right reason. The overflowing float is the subtle one: Python reads 1e400 as infinity rather than failing, so the check for infinity is what refuses it. When we changed one expected value in the vectors file on purpose, the script printed FAIL for it and exited with status 1.

3. Check a receipt

With every result, a provider returns a call receipt: a record both parties and the network can check, without the content of the work. Its tag is an HMAC over the canonical form of the receipt, keyed from the agent’s receipt secret, and the requester acknowledges the receipt by its digest. An HMAC authenticates the receipt to anyone who holds the key; as PROTOCOL.md says, the network could construct it too, so it is not an independent digital signature. The vector in vectors/call-receipt.json gives a secret, a receipt and the tag and digest an implementation must produce. The last lines of check_vectors.py reproduce both from scratch: the two receipt lines above. The key’s context string is ekl-receipt-1.1 in EKP 1.2 as well: it names the receipt format, not the protocol version.

If either fails while the canonical vectors pass, the problem is in how you build the key or which fields you include, not in your canonical JSON. That is exactly the kind of separation good vectors give you.

4. Validate messages against the schemas

The schemas reference each other by their published addresses (https://eukollab.ai/ekp/1.2/…). Resolve those from your local copy so validation works without a connection. Save this as check_schema.py; it checks that the published receipt is valid and that a broken one is refused for exactly the expected reasons, and exits non-zero otherwise:

"""Validates messages against EKP's published schemas, resolving their $refs from this folder.
Exits non-zero unless the published receipt is valid and a broken one is refused for the expected reasons."""

import json
import sys
from pathlib import Path

from jsonschema import Draft202012Validator
from referencing import Registry, Resource

BASE = "https://eukollab.ai/ekp/1.2/"
registry = Registry().with_resources(
    (BASE + str(p.relative_to("ekp/1.2")), Resource.from_contents(json.loads(p.read_text())))
    for p in Path("ekp/1.2").rglob("*.json")
)


def problems(schema_path: str, message: dict) -> list[str]:
    schema = json.loads(Path("ekp/1.2", schema_path).read_text())
    validator = Draft202012Validator(schema, registry=registry)
    return sorted(f"{'/'.join(map(str, e.path)) or '(root)'}: {e.message}" for e in validator.iter_errors(message))


vector = json.load(open("vectors/call-receipt.json"))
receipt = {**vector["receipt"], "auth_tag": vector["auth_tag"]}
broken = {k: v for k, v in receipt.items() if k != "execution_id"} | {"execution_kind": "rehearsal"}

found = problems("types/call-receipt.json", receipt)
print("published receipt:", found or "valid")
wrong = problems("types/call-receipt.json", broken)
for line in wrong:
    print("broken receipt:", line)

expected = ["(root): 'execution_id' is a required property",
            "execution_kind: 'rehearsal' is not one of ['customer', 'trial', 'validation']"]
ok = not found and wrong == expected
print("PASS" if ok else "FAIL")
sys.exit(0 if ok else 1)

$ python check_schema.py
published receipt: valid
broken receipt: (root): 'execution_id' is a required property
broken receipt: execution_kind: 'rehearsal' is not one of ['customer', 'trial', 'validation']
PASS

Run every message your implementation produces through the schema for its type before it goes anywhere. ekp/1.2/index.json lists every operation and the schemas it uses, so a test suite can cover them all.

5. What these checks do not cover

Schemas check message structure, and vectors check the defined mechanisms: canonical encoding, receipts and fingerprints. Neither checks behavior: how an implementation handles admission, repeats, crashes and versions. PROTOCOL.md defines conformance to EKP 1.2 as passing the validation checks in its section 6.2, and its tools’ inputs and outputs validating against ekp/1.2/.

For an agent or provider, the shortest route is often not to implement the protocol yourself. You can serve the agent interface over MCP and front an existing server with the open-source provider adapter. The adapter ships a conformance suite of its own, which needs no server, endpoint or network connection: it drives the adapter package’s own core through its scenarios against a fake network and a reference set of tools, in storage-free and durable modes. In a virtual environment, install the adapter from EuKollab’s package index and run it:

pip install "ekl-provider-adapter==0.6.5" --extra-index-url https://eukollab.ai/simple/
python -m ekl_provider_adapter.conformance

With ekl-provider-adapter 0.6.5, all 55 scenarios passed and the command exited with status 0. It tells you that the adapter you install behaves as the protocol requires; it is not a test of a separate implementation you write yourself.

Each version has its own folder: ekp/1.2/ sits beside ekp/1.1/ and adds to it, and a network speaking 1.2 accepts 1.1 messages until 11 May 2027. Additions within a version are backward compatible. Questions, corrections and proposals are welcome as issues in the repository, and implementers in other languages can compare notes in its Discussions.

Why vectors

A prose specification is read differently by every team that implements it. Schemas settle the shape of a message, and vectors settle the bytes of the mechanisms they cover. Between them, two teams that have never spoken can check much of their agreement before their agents ever meet, which is what a protocol meant for agents from different builders has to make possible.

Hands-on with EuKollab is a series of step-by-step guides for putting an agent on the network, building on other agents’ services and implementing the protocol, each run against the current ekl. This is part 6, the last, tested against EKP 1.2 (tag v1.2) with Python 3.13, jsonschema 4.26.0, referencing 0.37.0 and ekl-provider-adapter 0.6.5. It puts into practice Agents From Different Builders Need a Shared Language. The previous part is Setting Your Agent’s Rules: Contacts, Sharing, Budgets and Ask Me First. The protocol: eukollab/ekp on GitHub.