Quick Start Guide

This quick start guide will help you build your first H.I.V.E. Protocol agent. You'll have a working agent that can process tasks and communicate with other agents.

Why This Approach?

🚀 Fast: Quick agent implementation
🔧 Simple: Only 7 message types, minimal complexity
📈 Scalable: Designed for concurrent agent operations
🎯 Focused: Covers most use cases with minimal complexity

Prerequisites

Node.js 18+ installed
Some time for implementation
Basic JavaScript knowledge

Step 1: Set Up Your Project

Create a minimal project:

# Create project directory
mkdir my-simple-agent
cd my-simple-agent

# Initialize npm project
npm init -y

# Install minimal dependencies
npm install express crypto
npm install --save-dev typescript tsx @types/node @types/express

# Initialize TypeScript
npx tsc --init

Approach: We're using minimal dependencies. No complex SDK required - just HTTP and crypto for signatures.

Step 2: Create Simple Agent

Create agent.ts with the minimal H.I.V.E. implementation:

// agent.ts
import express from "express";
import crypto from "crypto";

// Simple agent configuration
const AGENT_ID = "hive:agentid:" + crypto.randomBytes(8).toString("hex");
const PORT = 3000;

// Generate Ed25519 key pair (in production, save these!)
const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519", {
  publicKeyEncoding: { type: "spki", format: "pem" },
  privateKeyEncoding: { type: "pkcs8", format: "pem" },
});

console.log(`Agent ID: ${AGENT_ID}`);
console.log(`Public Key: ${publicKey.replace(/\n/g, "\\n")}`);

// Create Express app
const app = express();
app.use(express.json());

// Simple capability: text processing
const capabilities = [
  {
    id: "text-processing",
    input: { text: "string", operation: "string" },
    output: { result: "string" },
  },
];

For adding advanced AI processing capabilities, you can use: * AI SDK [Node.js] * Langchain [Python]

Step 3: Add Message Handling

Continue building the agent with simple message handling:

// Helper function to sign messages
function signMessage(message: any): string {
  const messageStr = JSON.stringify(message);
  return crypto
    .sign(null, Buffer.from(messageStr), privateKey)
    .toString("base64");
}

// Helper function to verify signatures
function verifySignature(
  message: any,
  signature: string,
  publicKeyPem: string
): boolean {
  try {
    const messageStr = JSON.stringify(message);
    return crypto.verify(
      null,
      Buffer.from(messageStr),
      publicKeyPem,
      Buffer.from(signature, "base64")
    );
  } catch {
    return false;
  }
}

// Simple task processing function
function processTask(capability: string, data: any) {
  if (capability === "text-processing") {
    const { text, operation } = data;

    switch (operation) {
      case "uppercase":
        return { result: text.toUpperCase() };
      case "lowercase":
        return { result: text.toLowerCase() };
      case "reverse":
        return { result: text.split("").reverse().join("") };
      case "count":
        return { result: text.length };
      default:
        throw new Error(`Unknown operation: ${operation}`);
    }
  }

  throw new Error(`Unknown capability: ${capability}`);
}

// Main task endpoint
app.post("/tasks", (req, res) => {
  try {
    const { from, to, type, data, sig } = req.body;

    // Basic validation
    if (type !== "task_request") {
      return res.status(400).json({
        from: AGENT_ID,
        to: from,
        type: "task_error",
        data: {
          error: "invalid_message_type",
          message: "Expected task_request",
          retry: false,
        },
        sig: signMessage({ error: "invalid_message_type" }),
      });
    }

    // Process the task
    const result = processTask(data.capability, data);

    // Send response
    const response = {
      from: AGENT_ID,
      to: from,
      type: "task_result",
      data: {
        task_id: data.task_id,
        status: "completed",
        result,
      },
    };

    res.json({
      ...response,
      sig: signMessage(response),
    });
  } catch (error) {
    const errorResponse = {
      from: AGENT_ID,
      to: req.body.from,
      type: "task_error",
      data: {
        task_id: req.body.data?.task_id,
        error: "processing_failed",
        message: error.message,
        retry: false,
      },
    };

    res.status(500).json({
      ...errorResponse,
      sig: signMessage(errorResponse),
    });
  }
});

Step 4: Add Discovery & Status Endpoints

Add the remaining endpoints to complete your agent:

// Capability discovery endpoint
app.get("/capabilities", (req, res) => {
  const response = {
    from: AGENT_ID,
    to: "discovery",
    type: "capability_response",
    data: {
      capabilities,
      endpoint: `http://localhost:${PORT}`,
    },
  };

  res.json({
    ...response,
    sig: signMessage(response),
  });
});

// Simple status endpoint
app.get("/status", (req, res) => {
  res.json({
    agent_id: AGENT_ID,
    status: "online",
    capabilities: capabilities.map((c) => c.id),
    uptime: process.uptime(),
  });
});

// Start the server
app.listen(PORT, () => {
  console.log(`🚀 H.I.V.E. Agent running at http://localhost:${PORT}`);
  console.log(`📋 Capabilities: ${capabilities.map((c) => c.id).join(", ")}`);
  console.log(`🔍 Try: curl http://localhost:${PORT}/status`);
});

Step 5: Create a Simple Test Client

Create test-client.ts to test your agent:

// test-client.ts
import crypto from "crypto";

// Generate client keys
const { publicKey: clientPublicKey, privateKey: clientPrivateKey } =
  crypto.generateKeyPairSync("ed25519", {
    publicKeyEncoding: { type: "spki", format: "pem" },
    privateKeyEncoding: { type: "pkcs8", format: "pem" },
  });

const CLIENT_ID =
  "hive:agentid:client-" + crypto.randomBytes(4).toString("hex");

function signMessage(message: any): string {
  const messageStr = JSON.stringify(message);
  return crypto
    .sign(null, Buffer.from(messageStr), clientPrivateKey)
    .toString("base64");
}

async function sendTaskRequest() {
  const taskRequest = {
    from: CLIENT_ID,
    to: "hive:agentid:agent", // Will be ignored by our simple agent
    type: "task_request",
    data: {
      task_id: "test-" + Date.now(),
      capability: "text-processing",
      text: "Hello H.I.V.E. Protocol!",
      operation: "uppercase",
    },
  };

  const message = {
    ...taskRequest,
    sig: signMessage(taskRequest),
  };

  try {
    const response = await fetch("http://localhost:3000/tasks", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(message),
    });

    const result = await response.json();
    console.log("✅ Task completed!");
    console.log("📤 Sent:", taskRequest.data.text);
    console.log("📥 Result:", result.data.result.result);
  } catch (error) {
    console.error("❌ Error:", error);
  }
}

// Test the agent
console.log(`🧪 Testing agent with client: ${CLIENT_ID}`);
sendTaskRequest();

Step 6: Set Up Scripts & Test

Update your package.json:

{
  "scripts": {
    "start": "tsx agent.ts",
    "test": "tsx test-client.ts"
  }
}

Step 7: Run & Test Your Agent

Terminal 1 - Start your agent:

npm start

You should see:

Agent ID: hive:agentid:a1b2c3d4
🚀 H.I.V.E. Agent running at http://localhost:3000
📋 Capabilities: text-processing
🔍 Try: curl http://localhost:3000/status

Terminal 2 - Test it:

npm test

You should see:

🧪 Testing agent with client: hive:agentid:client-x1y2
✅ Task completed!
📤 Sent: Hello H.I.V.E. Protocol!
📥 Result: HELLO H.I.V.E. PROTOCOL!

🎉 Congratulations!

You've built a working H.I.V.E. Protocol agent! Your agent can:

✅ Process text transformation tasks
✅ Sign and verify messages with Ed25519
✅ Handle the 7 core message types
✅ Advertise its capabilities
✅ Communicate with other agents

What You Built (Minimal Implementation)

Simple message format for efficient communication
Basic task processing without contract overhead
Ed25519 signatures for security
HTTP endpoints for communication
Capability advertisement for discovery

Next Steps: Upgrade Your Agent

🟡 Upgrade to Standard Implementation

Add WebSocket support for real-time updates
Implement basic task agreements (lightweight contracts)
Add multiple discovery methods
Enhanced error handling

🔴 Upgrade to Advanced Implementation (Full)

Complete protocol implementation
Advanced security features
Federation support
Full backward compatibility

🚀 Production Checklist

Save private keys securely (not in code!)
Add rate limiting and input validation
Implement proper logging and monitoring
Add health checks and graceful shutdown
Connect to a real registry service
Add more capabilities for your use case

Why This Approach Works

Minimal implementation provides most benefits with no complexity:

✅ Fast to implement: Quick setup using familiar technologies
✅ Easy to debug: Simple message format
✅ Highly scalable: Designed for concurrent operations
✅ Production ready: Add security and monitoring
✅ Upgrade path: Clear path to more features

Production Tip: Many successful H.I.V.E. deployments start with minimal implementation and only upgrade specific components as needed. You don't need all features to be effective!

Security: This example is for learning. In production, store private keys securely, validate all inputs, and implement proper authentication.

Quick Start Guide

On this page