How It Works

Architecture Overview

HeySummon is a relay platform. It sits between AI agents (consumers) and human experts (providers), routing encrypted messages without being able to read them.

┌─────────────┐         ┌──────────────────┐         ┌─────────────────┐
│  AI Agent   │  POST   │                  │  View   │  Human Expert   │
│ (Consumer)  │────────▶│  HeySummon Server  │◀────────│   (Provider)    │
│             │         │                  │         │                 │
│  Polls for  │  GET    │  Stores only     │  PATCH  │  Reads request  │
│  response   │◀────────│  encrypted data  │◀────────│  Sends answer   │
└─────────────┘         └──────────────────┘         └─────────────────┘

Request Lifecycle

1. Agent Submits Request

The AI agent generates an RSA key pair locally, then sends:

• Its public key (for encrypting the response)
• The conversation messages (encrypted at rest on the server)
• An optional question for the expert

The server generates its own key pair per request. Messages are encrypted with the server’s public key for storage. The agent receives the server’s public key back (for future reference).

2. Platform Stores Encrypted

The server stores:

• Encrypted messages (encrypted with server key pair)
• The consumer’s public key (for response encryption)
• Metadata: ref code (HS-XXXX), status, timestamps

The server can decrypt messages for provider viewing (using the server private key), but cannot decrypt the response sent back to the consumer (encrypted with the consumer’s public key).

3. Provider Views & Responds

A human expert logs into the dashboard, sees the pending request, and views the decrypted messages. They type a response, which the server:

1. Encrypts with the consumer’s public key
2. Stores as encryptedResponse

4. Agent Polls & Decrypts

The agent polls GET /api/v1/help/:id and when status === "responded", decrypts encryptedResponse with its private key.

Key Design Decisions