Build your first agent

Prerequisites

• Node.js 20+ or Bun 1.1+
• Git
• The kynetra-prime repository (or install via npm)

Install

Clone the reference implementation and install dependencies:

git clone https://github.com/HyperBridge/kynetra-prime
cd kynetra-prime
npm install

Or install the Web7 SDK standalone:

npm install @hyperbridge/forge

Create Identity

Every entity in Web7 needs a did:w7. Create identities for your principal and agent:

# Create a principal identity
npx tsx backend/cli/w7.ts id create alice
# → { "id": "did:w7:alice", "verificationMethod": [...] }

# Create an agent identity
npx tsx backend/cli/w7.ts id create skill/my-agent

# List all DIDs in registry
npx tsx backend/cli/w7.ts id list

Or in code:

import { getDIDRegistry } from "@hyperbridge/forge/amp";

const reg = getDIDRegistry();
const alice = reg.create("alice");
const agent = reg.create("skill/my-agent");

console.log(alice.id); // "did:w7:alice"

Hello Agent

Write a minimal ClearScript agent that handles a greet intent:

// hello.clear
import { prime, agent } from "web7/prime"

let greeter = agent {
  name:   "greeter",
  skills: ["greet"],
}

fn greeter.handle(intent) -> str {
  return "hello, " + intent.params.name
}

prime.register(greeter)

Or using the TypeScript SDK directly:

import {
  getDIDRegistry, createIntent, createDelegation,
  createInference, createOutcome, verifyPoO, anchor
} from "@hyperbridge/forge/amp";

const reg   = getDIDRegistry();
const alice = reg.create("alice");
const prime = reg.create("prime/main");
const agent = reg.create("skill/greeter");

Delegate Intent

Alice expresses an intent. Prime delegates it to the agent. The agent produces an inference and outcome.

// 1. Alice creates a signed intent
const intent = createIntent({
  from:   alice.id,
  to:     "skill:greeter",
  intent: { action: "greet", params: { name: "world" } },
  settle: { rail: "amp-escrow", amount: { amount: "1", currency: "USD" } },
});

// 2. Prime signs the delegation
const delegation = createDelegation(prime.id, intent, agent.id);

// 3. Agent records its inference
const inference = createInference(agent.id, delegation, {
  model:      "did:w7:model/greeter@sha256:abc",
  inputHash:  "0x01",
  outputHash: "0x02",
});

// 4. Agent attests the outcome
const outcome = createOutcome(
  agent.id, alice.id, inference.id,
  { ok: true, message: "hello, world" }
);

Or via the CLI in one command:

npx tsx backend/cli/w7.ts delegate \
  --from did:w7:alice \
  --to skill:greeter \
  --action greet \
  --json '{"name":"world"}'

Verify Outcome

Run the Proof-of-Outcome check and commit the AIG subgraph to L0:

import { verifyPoO, anchor } from "@hyperbridge/forge/amp";

const poo = verifyPoO({
  intent, delegation, inference, outcome,
  zkml:   { model: "did:w7:model/greeter@sha256:abc",
             inputHash: "0x01", outputHash: "0x02", proof: "stub" },
  policy: { allowed: true },
});

console.log(poo.ok);      // true
console.log(poo.checks);  // { intentSig: true, delegationSig: true, ... }

// Commit to L0 — returns Merkle root + block height
const { merkleRoot, l0 } = anchor(intent.id);
console.log(merkleRoot);  // "0xabc123..."

Run Conformance

Before shipping, verify your implementation passes all required tests:

npx tsx backend/cli/w7.ts conformance

# Expected output:
┌─────────────────────────┬──────┬─────────────────────┐
│ name                    │ ok   │ detail              │
├─────────────────────────┼──────┼─────────────────────┤
│ poo.attestor-path       │ true │                     │
│ poo.zkml-path           │ true │                     │
│ poo.reject-forged       │ true │ outcomeSig          │
│ poo.reject-bad-lineage  │ true │ lineage             │
│ l0.anchor               │ true │                     │
└─────────────────────────┴──────┴─────────────────────┘

Extend Your Existing App

Have an existing app? Wrap it as a Web7 agent in 3 steps:

npm install @hyperbridge/forge

const reg   = getDIDRegistry();
const myApp = reg.create("skill/my-app");

app.post("/handle-intent", async (req) => {
  // Your existing logic here
  const result = await myExistingHandler(req.body);

  // Wrap as signed AMP outcome
  const outcome = createOutcome(
    myApp.id, req.body.from,
    req.body.inferenceId, result
  );
  const poo = verifyPoO({ ...req.body, outcome, policy: { allowed: true } });
  anchor(req.body.intentId);
  return { outcome, poo };
});

Integration Pattern: Wrapping an OpenAI Call as a Web7 Agent

This pattern shows how to take an existing OpenAI API call and make it a fully accountable Web7 agent — with consent gating, signed inference records, PoO verification, and AIG anchoring. No changes to your OpenAI usage; you just wrap the call.

Step 1 — Register the agent and load modules

import {
  getDIDRegistry, createIntent, createDelegation,
  createInference, createOutcome, verifyPoO, anchor
} from "@hyperbridge/forge/amp";
import { getMemory, SCOPE } from "@hyperbridge/forge/memory";
import { getConsentLedger, PURPOSES } from "@hyperbridge/forge/consent";
import { createHash } from "node:crypto";

// Register identities
const reg     = getDIDRegistry();
const alice   = reg.create("alice");           // the user
const prime   = reg.create("prime/main");      // the orchestrator
const openai  = reg.create("skill/openai-gpt"); // this agent

// Deterministic model DID — pin the exact model version you call
const MODEL_DID = "did:w7:model/openai-gpt-4o@2024-08-06";

// Memory store: one session-scoped store per principal
const mem     = getMemory({ scope: SCOPE.SESSION, did: alice.id });
const ledger  = getConsentLedger();

Step 2 — Gate on consent before touching user data

// Check that alice has granted this agent permission to call external AI APIs
const grant = ledger.latest(alice.id, openai.id);
if (!grant || !grant.purposes.includes(PURPOSES.AI_PROCESSING)) {
  throw new Error("No consent: alice has not granted AI processing to skill/openai-gpt");
}

// Record the exact consent version used — AIG will reference this later
const consentId = grant.id;

Step 3 — Build the AMP delegation chain

// Alice creates a signed intent for a summarisation task
const intent = createIntent({
  from:   alice.id,
  to:     openai.id,
  intent: {
    action: "summarise",
    params: { text: userInput, maxWords: 120 },
  },
  settle: { rail: "amp-escrow", amount: { amount: "0.02", currency: "USD" } },
  meta:   { consentId },
});

// Prime delegates to the OpenAI skill agent
const delegation = createDelegation(prime.id, intent, openai.id);

Step 4 — Call OpenAI and record hashes

// Hash the prompt before sending — never store raw PII in the AIG
const inputHash = createHash("sha256")
  .update(JSON.stringify(intent.intent.params))
  .digest("hex");

// Your existing OpenAI call — unchanged
const raw = await fetch("https://api.openai.com/v1/chat/completions", {
  method:  "POST",
  headers: {
    "Authorization": `Bearer ${process.env.OPENAI_API_KEY}`,
    "Content-Type":  "application/json",
  },
  body: JSON.stringify({
    model:    "gpt-4o",
    messages: [
      { role: "system",  content: "Summarise the user's text in the requested word count." },
      { role: "user",    content: intent.intent.params.text },
    ],
    max_tokens: 200,
  }),
});
const response    = await raw.json();
const summary     = response.choices[0].message.content;

// Hash the output — this goes into the inference record, not the raw text
const outputHash = createHash("sha256").update(summary).digest("hex");

Step 5 — Produce a signed outcome and verify PoO

// Create a signed inference record (model DID + I/O hashes — no raw data)
const inference = createInference(openai.id, delegation, {
  model:      MODEL_DID,
  inputHash:  "0x" + inputHash,
  outputHash: "0x" + outputHash,
});

// Attest the outcome
const outcome = createOutcome(
  openai.id, alice.id, inference.id,
  { ok: true, summary }
);

// Run PoO — checks intent sig, delegation sig, inference path, output hash
const poo = verifyPoO({
  intent, delegation, inference, outcome,
  zkml:   { model: MODEL_DID, inputHash: inference.inputHash,
             outputHash: inference.outputHash, proof: "attestor" },
  policy: { allowed: true },
});

if (!poo.ok) throw new Error("PoO failed: " + JSON.stringify(poo.checks));

// Store summary in alice's session memory and commit to AIG
mem.set("last_summary", summary);
const { merkleRoot } = anchor(intent.id);

console.log("✓ Summary:", summary);
console.log("✓ AIG root:", merkleRoot);
console.log("✓ PoO checks:", poo.checks);

Complete example as an HTTP handler

// server.ts — drop-in Express/Hono/Fastify handler
import {
  getDIDRegistry, createIntent, createDelegation,
  createInference, createOutcome, verifyPoO, anchor
} from "@hyperbridge/forge/amp";
import { getMemory, SCOPE }    from "@hyperbridge/forge/memory";
import { getConsentLedger, PURPOSES } from "@hyperbridge/forge/consent";
import { createHash } from "node:crypto";

const reg    = getDIDRegistry();
const prime  = reg.create("prime/main");
const openai = reg.create("skill/openai-gpt");
const MODEL  = "did:w7:model/openai-gpt-4o@2024-08-06";

export async function handleSummarise(req: {
  principalDid: string;
  text:         string;
  maxWords?:    number;
}) {
  const principal = reg.resolve(req.principalDid) ?? reg.create(req.principalDid);
  const ledger    = getConsentLedger();
  const grant     = ledger.latest(principal.id, openai.id);

  if (!grant?.purposes.includes(PURPOSES.AI_PROCESSING))
    return { error: "consent_required", status: 403 };

  const intent     = createIntent({ from: principal.id, to: openai.id,
                       intent: { action: "summarise", params: req },
                       settle: { rail: "amp-escrow",
                                 amount: { amount: "0.02", currency: "USD" } } });
  const delegation = createDelegation(prime.id, intent, openai.id);
  const inputHash  = createHash("sha256").update(req.text).digest("hex");

  const apiRes = await fetch("https://api.openai.com/v1/chat/completions", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
               "Content-Type": "application/json" },
    body: JSON.stringify({ model: "gpt-4o", max_tokens: req.maxWords ?? 200,
      messages: [{ role: "user", content: req.text }] }),
  });
  const summary    = (await apiRes.json()).choices[0].message.content as string;
  const outputHash = createHash("sha256").update(summary).digest("hex");

  const inference  = createInference(openai.id, delegation, {
    model: MODEL, inputHash: "0x"+inputHash, outputHash: "0x"+outputHash });
  const outcome    = createOutcome(openai.id, principal.id, inference.id,
                       { ok: true, summary });
  const poo        = verifyPoO({ intent, delegation, inference, outcome,
                       zkml: { model: MODEL, inputHash: inference.inputHash,
                               outputHash: inference.outputHash, proof: "attestor" },
                       policy: { allowed: true } });

  if (!poo.ok) return { error: "poo_failed", checks: poo.checks, status: 500 };

  getMemory({ scope: SCOPE.SESSION, did: principal.id }).set("last_summary", summary);
  const { merkleRoot } = anchor(intent.id);

  return { summary, merkleRoot, outcomeId: outcome.id, poo: poo.checks };
}

Next Steps