HexaEightAgent 1.6.861

HexaEight Agent Library

Overview

The HexaEight Agent Library enables secure, end-to-end encrypted communication between AI agents.

Installation

dotnet add package HexaEight.Agent

Core Classes and Methods

1. AgentConfig Class

Initialization

• SetClientCredentials(string clientId, string tokenServerUrl): Sets up client credentials
• SetResourceName(string resourceName): Sets the resource name
• SetLoginToken(string loginToken): Sets the login token
• SetRsOwner(string rsOwner): Sets the resource owner

Agent Management

• CreateAIParentAgent(string filename, bool loadEnv = false, string clientId = "", string tokenServerUrl = "", bool logging = false): Creates a new parent agent
• LoadAIParentAgent(string filename, bool loadEnv = false, string clientId = "", string tokenServerUrl = "", bool logging = false): Loads an existing parent agent
• CreateAIChildAgent(string agentPassword, string filename, bool loadEnv = false, string clientId = "", string tokenServerUrl = "", bool logging = false): Creates a new child agent
• LoadAIChildAgent(string agentPassword, string filename, bool loadEnv = false, string clientId = "", string tokenServerUrl = "", bool logging = false): Loads an existing child agent
• ActivateParentAgent(): Activates the parent agent
• GetAgentname(): Gets the current agent's name
• GetInternalIdentity(): Gets the agent's internal identity

Environment Management

• LoadHexaEightVariablesFromEnvFile(string envFilePath, EnvironmentVariableTarget target = EnvironmentVariableTarget.Process): Loads environment variables from a file
• GetAllEnvironmentVariables(): Gets all HexaEight environment variables

Configuration

• SaveConfiguration(string loginToken, string encryptedResourceId, string filename): Saves agent configuration
• CleanConfiguration(string filename): Removes agent configuration
• ReadConfiguration(string filename): Reads agent configuration

2. Session Object (JWT)

Message Encryption/Decryption

• EncryptTextMessageToDestination(string message, string destination): Encrypts a message
• DecryptTextMessage(string encryptedMessage): Decrypts a message

JWT Operations

• CreateEncryptedJWTTokenUsingSharedKey(string destination, int expiryMinutes, long kgt, string sharedKey): Creates a JWT token
• ValidateTokenUsingSharedKey(string token, string sharedKey): Validates a JWT token
• GetResourceNameFromJWT(string token): Gets resource name from JWT
• GetKGTFromJWT(string token): Gets KGT from JWT

Payload Management

• AddPayloadItem(string key, string value): Adds an item to the payload
• ClearAllPayloadItems(): Clears all payload items

Loading Environment Files from env-file (Generated after installing Machine Token License)

var (resourceName, machineToken, secret, licenseCode) =  EnvironmentManager.GetAllEnvironmentVariables();

Create a Parent Agent

var agent = new AgentConfig();
agent.SetClientCredentials(CLIENT_ID, "https://your-token-server.com");
bool success = agent.CreateAIParentAgent("parent_config.json");

Create a Child Agent

var parentAgent = new AgentConfig();
parentAgent.LoadAIParentAgent("parent_config.json");
parentAgent.CreateAIChildAgent("secure-password", "child_agent.json");

Loading Parent Agent

var parentagent = new AgentConfig();
parentagent.SetClientCredentials(CLIENT_ID, TOKEN_SERVER_URL);
bool success = parentagent.LoadAIParentAgent(PARENT_CONFIG_FILE);

Loading Child Agent

var childAgent = new AgentConfig();
childAgent.SetClientCredentials(CLIENT_ID, TOKEN_SERVER_URL);
bool success = childAgent.LoadAIChildAgent(password, childConfigFile);

Encrypting and Decrypting Messages

// Send an encrypted message
string message = "Hello from the parent agent!";
string encrypted = parentagent.Session.EncryptTextMessageToDestination
(
                message, 
                "anotheragent.hostname.com"
);

// Decrypt a message
string decrypted = childAgent.Session.DecryptTextMessage(encrypted);
Console.WriteLine($"Decrypted message: {decrypted}");

JWT Operations (Parent Agent Only)

// Generate timestamp in minutes since Unix epoch
Int64 kgt = (long)Math.Round((DateTime.UtcNow - new DateTime(1970, 1, 1, 0, 0, 0)).TotalMinutes);

// Get pre-shared key using auth.hexaeight.com
var sk = parentAgent.Session!.HEClient.GetPreSharedKeyByKnownName(destinationResourceName, kgt.ToString()).GetAwaiter().GetResult();

// Clear and add payload
parentAgent.Session?.ClearAllPayloadItems();
parentAgent.Session.AddPayloadItem("BODY", "Your secure message content");

// Create JWT using shared key method
string encryptedJWT = parentAgent.Session!.CreateEncryptedJWTTokenUsingSharedKey(
                            destinationResourceName,
                            expiryMinutes,
                            kgt,
                            sk);

// Decrypting JWT using shared key method

Int64 kgt = anotherparentAgent.Session!.GetKGTFromJWT(jwtToken);

var jwtowner = anotherparentAgent.Session!.GetResourceNameFromJWT(jwtToken);

var sharedkey = await anotherparentAgent.Session!.HEClient.GetPreSharedKeyByKnownName(jwtowner, kgt.ToString());

var validationResult = anotherparentAgent.Session!.ValidateTokenUsingSharedKey(jwtToken, sharedkey);
Console.WriteLine(validationResult);

*****************Not addedd

Encrypted Inference Operations

// Get gatekeeper information (agent name + IAM name)
string gatekeeperInfo = await parentAgent.GetGatekeeper();
// Returns: "agentname;iamname"

Getting Shared Keys for Encrypted Communication

// Get shared keys for both full gatekeeper info and first entry
string sharedKeysJson = await parentAgent.GetGatekeepersSharedKey(gatekeeperInfo);
// Returns JSON: {"fullKey":"...","firstKey":"...","gatekeeperInfo":"...","firstEntry":"...","timeKey":"..."}

Creating Encrypted Inference Requests

// Create an encrypted inference with large message support (up to 30k+ context)
string largeMessage = "Your large AI inference request with LARGE context...";
string gatekeeperInfo = await parentAgent.GetGatekeeper();
string encryptedInference = await parentAgent.GenerateEncryptedInference(largeMessage, gatekeeperInfo);

// Returns JSON with identifier and message parts:
// {"identifier":"encrypted_guid_hash_responseto","message":"encrypted_full_message"}

Creating Encrypted Inference Responses

// Respond to an encrypted inference using the original request ID
string responseMessage = "Your AI model response...";
string gatekeeperInfo = await parentAgent.GetGatekeeper();
string originalRequestId = "guid-from-original-request";

string encryptedResponse = await parentAgent.GenerateEncryptedInferenceResponse(
    responseMessage, 
    gatekeeperInfo, 
    originalRequestId);

// Returns JSON: {"identifier":"encrypted_responseid_hash_responseto","message":"encrypted_response"}

Complete Encrypted Inference Workflow

// Step 1: Load parent agent
var agent = new AgentConfig();
agent.EnableDebugMode();
bool loaded = agent.LoadAIParentAgent("parent_config.json", loadenv: true);

if (loaded)
{
    // Step 2: Get gatekeeper info
    string gatekeeper = await agent.GetGatekeeper();
    
    // Step 3: Create encrypted inference request
    string prompt = "Explain quantum computing in simple terms...";
    string encryptedRequest = await agent.GenerateEncryptedInference(prompt, gatekeeper);
    
    // Step 4: Send to AI service (encryptedRequest contains identifier + message)
    // ... AI processing ...
    
    // Step 5: Create encrypted response (when responding)
    string aiResponse = "Quantum computing uses quantum mechanics...";
    string requestId = "extracted-from-received-request";
    string encryptedResponse = await agent.GenerateEncryptedInferenceResponse(
        aiResponse, gatekeeper, requestId);
}

Key Features of Encrypted Inference

• Large Message Support: Handles messages up to 30k+ characters
• Two-Part Encryption: Identifier encrypted with first key, message with full key
• Time-Based Security: Uses 15-minute rotating time windows for key generation
• Request/Response Tracking: Links responses to original requests via ID
• Multi-Party Support: Compatible with multi-party approval workflows
• SHA256 Integrity: Each message includes hash for integrity verification

New JWT Signing & Verification Features

var agent = new AgentConfig();
agent.EnableDebugMode();

// Load signing credentials from folder
agent.SetSigningFolder("./signing-creds");

// Sign a message
var signResult = await agent.SignMessageAsync("test@example.com", "Hello World!");

if (signResult.Success)
{
    // Verify the message
    var verifyResult = await agent.VerifyJwtAsync(signResult.Jwt, "Hello World!", "test@example.com");
    
    if (verifyResult.Success)
    {
        Console.WriteLine("🎉 End-to-end JWT signing and verification successful!");
    }
}

// When done with signing
agent.DisableSigningMode();

var agent = new AgentConfig();
agent.EnableDebugMode();

// Load signing credentials from folder
agent.SetSigningFolder("./signing-creds");

// Create and verify complete JWT message JSON
string jwtJson = await agent.CreateJwtMessageAsync("user@example.com", "Important message");
var result = await agent.VerifyJwtMessageAsync(jwtJson);

if (result.Success)
{
    Console.WriteLine($"Message verified: {result.DecryptedPayload}");
}

var agent = new AgentConfig();
// NO need to load signing environment!

// Works with complete JWT message JSON
string jwtMessageJson = @"{
    ""Msg ID"": ""1758512411180"",
    ""message"": ""Hello, World!"",
    ""signedjwt"": ""eyJhbGc...""
}";

var result = await agent.VerifyJwtMessageAsync(jwtMessageJson, "user@example.com");

if (result.Success)
{
    Console.WriteLine("✅ JWT message verified without signing environment!");
    Console.WriteLine($"User: {result.UserHash}");
    Console.WriteLine($"Message ID: {result.MessageId}");
}