Agent Protocol

Draft

This section is under construction.

Connection Handshake (Duplex v2)

The SimpleX agent manages the connection handshake, which establishes a bidirectional encrypted channel between two parties.

Step 1: Joiner → Contact Queue

Joiner sends AgentConnInfoReply (tag 'D', 0x44) containing:

• Reply Queue addresses
• Joiner's profile (ConnInfo)

Step 2: Initiator → Reply Queue

Initiator sends AgentConfirmation (tag 'C', 0x43) containing:

• Agent version
• E2E encryption parameters (X3DH keys)
• Encrypted ConnInfo (Initiator's profile)

Step 3: Joiner → Reply Queue

Joiner sends AgentConfirmation (tag 'C') to confirm.

Step 4: HELLO Exchange

Both parties exchange HELLO messages (tag 'H', 0x48) to signal the connection is secured.

AgentMsgEnvelope Tags

Tag	Hex	Name	Content
'C'	0x43	AgentConfirmation	Version + E2E params + ConnInfo
'M'	0x4D	AgentMessage	AMessage header + body
'I'	0x49	AgentInvitation	Invitation data

AMessage Tags (within AgentMessage)

Tag	Hex	Name	Content
'I'	0x49	AgentConnInfo	Profile only (no queues)
'D'	0x44	AgentConnInfoReply	Reply queues + profile
'H'	0x48	HELLO	Empty — connection secured signal
'M'	0x4D	A_MSG	Chat message body
'A'	0x41	A_RCVD	Delivery receipt

ClientMessage Format

After decrypting all encryption layers, the ClientMessage contains:

┌─────────────────┬────────────────────────────┐
│ PrivHeader      │ Body (AgentMsgEnvelope)    │
└─────────────────┴────────────────────────────┘

PrivHeader Values

Byte	Meaning
0x00	PHEmpty — No additional header
0x4B ('K')	PHConfirmation — Contains Ed25519 auth key