DEVELOPERS · HANDSHAKEComing soon

The agent-to-agent
handshake.

kya-handshake/0.1: before two agents work together, both prove who they are, who they act for and what they may do, in three signed messages. Part of the Zuger Agent Protocol (ZAP). Built on open standards.

THE THREE MESSAGES

Three messages.
Both sides check.

Each message is a JWS signed with the sender’s agent key, carried in an HTTP message signed with the same key.

InitiatorResponder

01HELLO

Who the initiator is, its credential with only the disclosures the responder asks for, who it acts for, what it wants to do and the versions it speaks. A fresh nonce.

To the responder

02HELLO-BACK

The responder’s own credential and nonce, and its decision: accept, refuse with a code, or wait for a person’s approval. If it accepts, its terms and the version chosen.

To the initiator

03CONFIRM

The initiator echoes the responder’s nonce and signs a hash of the first two messages. That hash is the session’s id.

To the responder

Session open: fifteen minutes at most, and never past either credential’s expiry. Every request in it is signed.

THE SESSION

One hash,
both keys.

The session id

A SHA-256 hash over the first two messages, exactly as sent. A CONFIRM over other messages is refused as a downgrade.

How long it lasts

From the responder’s answer, fifteen minutes at most, and ending early if either credential expires.

Requests inside it

Each carries the session id in a signed header. A revocation is seen at the next handshake, which is why sessions are short.

TRANSPORTS

Where it runs.

TransportHowStatus
HTTPSHELLO and CONFIRM are POST requests to the responder’s handshake endpoint; HELLO-BACK is the signed response. Every signature lives 60 seconds at most.Draft
A2AAn agent card names the handshake as an extension, and the handshake runs over HTTPS before the A2A calls.Draft
MCPNot this handshake. MCP sessions follow KYA-OS instead.Planned
# ① HELLO, as it travels over HTTPS
POST /handshake HTTP/1.1
Content-Type: application/jwt
Content-Digest: sha-256=:…:
Signature-Input: kya=("@method" "@target-uri" "@authority" "content-digest");created=…;expires=…;nonce="<nonce_a>";keyid="…";alg="ed25519";tag="kya/v0.1"
Signature: kya=:…:

<compact JWS, typ kya-hs-hello+jwt>

RESULT CODES

Every answer
has a code.

Checks run in a fixed order, and the first failure is the answer.

CodeMeaning
HS_OKEvery check passed.
HS_UNTRUSTED_ISSUERThe credential’s issuer is not on the local trust list, or not at that assurance.
HS_BAD_SIGNATUREThe issuer’s signature, or the disclosures, do not verify.
HS_EXPIREDThe credential, or the session, has expired.
HS_REVOKEDThe credential is revoked, or its status cannot be read.
HS_NOT_LOGGEDNo valid inclusion proof in the public log.
HS_KEY_MISMATCHA message or its signature is not made by the credential’s key.
HS_REPLAYNot fresh: a nonce used before, or a time outside the window.
HS_LOW_ASSURANCEAssurance below the policy’s minimum, or a required disclosure missing.
HS_OUT_OF_SCOPEThe scopes asked for are not covered, or the chain of who acts for whom is too deep.
HS_LOW_REPUTATIONReputation below the policy’s minimum.
HS_BLOCKEDThe operator or agent is blocked, or the skill is not offered.
HS_NEEDS_APPROVALThe value is above the threshold: a person decides.
HS_TIMEOUTA wait for a person’s approval passed its time limit.
HS_CHANNEL_MISMATCHThe binding in the application failed. It is not a TLS result.
HS_DOWNGRADEA lower version than both sides offer, or a transcript over other messages.
HS_BAD_ALGAn algorithm not on the allow list.
HS_FROZENThe agent is frozen.
HS_MALFORMEDThe input fails before any cryptography: its shape, its size or its version.

CONFORMANCE CHECKLIST

What an implementation checks,
in this order.

  1. The envelope: a compact JWS of the expected type, exactly its fields, a version and a transport in common, and a signature present.
  2. The algorithm is on the allow list.
  3. The issuer is on the local trust list.
  4. The credential’s signature is valid.
  5. Not expired, not revoked, not frozen.
  6. Logged in the public log, with a valid inclusion proof.
  7. Signed by the credential’s key, with a fresh nonce, inside the time window, bound to this exchange and with no downgrade.
  8. Assurance at the policy’s minimum, and the required disclosures made.
  9. The scopes cover what is asked for.
  10. Reputation at the policy’s minimum.
  11. Not blocked, and the skill allowed.
  12. The value at or under the threshold, or a person decides.

WHAT IT PROVES

What it proves,
and what it does not.

It proves

Each side holds its credential’s key, freshly, over a nonce the other side chose, for this address, inside this exchange. A message cannot be moved to another exchange or peer without failing.

It does not prove

That the exchange ran over a particular TLS connection: a party that ends TLS for one side can relay messages unchanged. Nor that an agent behaves well.

Not yet

A formal model of these claims. An outside specialist will build it before the handshake is public.

Formal verification

CODE AND VECTORS

Code and test vectors.

TypeScript and Python

The handshake ships in the SDKs. They are not published yet.

Coming soon

Test vectors

A case for every result code, made deterministically. They will be published with the specification.

Coming soon
Built on open standards

The rest of the protocol.

The five layers, the specifications and what passes its tests.

Developer docsStandards