Guide

Agent to Agent

The minimum viable two-agent setup. Alice sends Bob a Sessioned envelope over any transport; Bob decrypts and replies; Alice decrypts the reply. Both sides already know each other's identity Name.

Prerequisites

Two HexaEight identities (Alice + Bob), each with its own env-file + hexaeight.mac.
Each side knows the other's Name (the HEXAEIGHT_RESOURCENAME).
An out-of-band channel to share a sessionId (typically just the first message of your application protocol).

Step 1 — Alice initiates

using HexaEight.Bridge;

var alice    = new Client();
string bob   = "bob.example.com";
string sid   = Guid.NewGuid().ToString();
long   kgt   = CurrentKgt();

// Alice fetches her half of the ASK pair for Bob
string ask = await alice.FetchAskAsync(bob, kgt);
alice.PinAskForSession(sid, ask);

string envelope = await alice.EncryptEnvelopeAsync(
    recipient: bob,
    body:      "ping",
    sessionId: sid);

// Hand `envelope` and `sid` to Bob over any transport.
await SendOverWire(bob, envelope, sid);

Step 2 — Bob receives and replies

using HexaEight.Bridge;

var bob      = new Client();
string alice = "alice.example.com";
(string envelope, string sid) = await ReceiveFromWire();

// Bob fetches HIS half of the ASK pair for Alice
string ask = await bob.FetchAskAsync(alice, CurrentKgt());
bob.PinAskForSession(sid, ask);

DecryptedEnvelope msg = await bob.DecryptEnvelopeAsync(envelope);

Console.WriteLine($"From: {msg.Sender}  Body: {msg.Body}");
// From: alice.example.com  Body: ping

// Reply on the same session
string reply = await bob.EncryptEnvelopeAsync(
    recipient: alice,
    body:      "pong",
    sessionId: sid);
await SendOverWire(alice, reply, sid);

Step 3 — Alice reads the reply

(string envelope2, _) = await ReceiveFromWire();
var reply = await alice.DecryptEnvelopeAsync(envelope2);
Console.WriteLine(reply.Body);   // "pong"

Why this works

The platform issued Alice the encrypt-side ASK for (Alice → Bob) and Bob the decrypt-side ASK for (Alice → Bob). Neither side ever transmitted a key.
Both sides pinned their respective ASK under sha256(sid), so the wire envelopes carry only the session hash — no identity metadata.
The sender's Name is written into the encrypted inner JSON during encryption. Bob recovers it as msg.Sender — cryptographically verified, impossible to forge.

Once the session is established

Subsequent messages in either direction skip the ASK fetch — the cache hit makes each encrypt/decrypt sub-200ms.

// No more FetchAskAsync needed on either side — the session-pinned ASK is reused
var env = await alice.EncryptEnvelopeAsync(bob, "another message", sessionId: sid);
var msg = await alice.DecryptEnvelopeAsync(replyFromBob);