HexaEightAgent 1.6.866

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);

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}");
}