Register Your First Agent

This walkthrough takes you from zero to a running agent with a trust score. You will register an agent, record a behavioral signal, and read back the computed trust score — all using @vorionsys/atsf-core.

Prerequisites

• Node.js >= 18.0.0
• TypeScript >= 5.0.0

npm install @vorionsys/atsf-core

---

1. Create the Trust Engine

The trust engine is the runtime that evaluates agent behavior and computes trust scores on a 0–1000 scale across eight tiers (T0 Sandbox through T7 Autonomous).

import { createTrustEngine } from '@vorionsys/atsf-core';

const engine = createTrustEngine({
  failureThreshold: 0.3,
  successThreshold: 0.7,
  gainRate: 0.05, // canonical gain rate from BASIS
});

gainRate controls how quickly trust accumulates. The value 0.05 is the BASIS canonical default — it feeds into the logarithmic gain formula, which means early gains come faster and high-trust gains require sustained effort.

---

2. Register an Agent

Every agent starts at trust score 0 in the PROVISIONING lifecycle state. No exceptions, no inheritance. This is a deliberate design choice — trust is earned through demonstrated behavior.

const agent = await engine.initializeEntity('my-first-agent', 0);

console.log(agent.score);   // 0
console.log(agent.level);   // 0 (T0 — Sandbox)

The second argument is the initial tier. Agents begin at T0 with a score of 0. They must pass a qualification course (31 exercises across 9 canary categories) to reach T1 Observed at score 200.

For this tutorial, we will simulate qualification by recording successful signals directly.

---

3. Record a Behavioral Signal

Signals are the raw observations that the trust engine uses to update scores. Each signal has a value between 0.0 (total failure) and 1.0 (perfect execution).

await engine.recordSignal({
  id: crypto.randomUUID(),
  entityId: 'my-first-agent',
  type: 'behavioral.task_completed',
  value: 0.85,
  source: 'system',
  timestamp: new Date().toISOString(),
  metadata: {
    task: 'document-classification',
    riskLevel: 'READ',
  },
});

What happens under the hood

When a signal is recorded:

1. The engine classifies it as success (>= 0.7), failure (<= 0.3), or neutral.
2. For successes, the gain formula runs: gain = 0.05 × ln(1 + C - S) × ∛R where C is the observation ceiling, S is the current score, and R is the risk multiplier.
3. The score updates, tier boundaries are checked, and any tier-change events fire.

---

4. Recalculate and Read Trust

After recording signals, recalculate the agent's trust score:

const result = await engine.calculate('my-first-agent');

console.log(`Score: ${result.score}`);
console.log(`Tier:  T${result.level}`);
console.log(`Name:  ${result.levelName}`);

The score reflects accumulated behavioral evidence. A single signal will not move the score dramatically — the logarithmic formula ensures that trust builds gradually.

---

5. Listen for Tier Changes

The engine emits events when an agent crosses a tier boundary:

engine.on('trust:tier_changed', (event) => {
  console.log(
    `${event.entityId} moved ${event.direction}: ` +
    `${event.previousLevelName} → ${event.newLevelName} ` +
    `(score: ${event.newScore})`
  );
});

Tier changes are significant — they unlock (or revoke) capabilities. Moving from T0 to T1 means the agent can start performing read-only operations. Moving from T3 to T4 unlocks full operational capability.

---

6. Record Multiple Signals

Trust builds through consistent behavior over time. Here is a helper to simulate a batch of successful operations:

async function recordBatch(
  engine: ReturnType<typeof createTrustEngine>,
  entityId: string,
  count: number,
  value: number = 0.85,
) {
  for (let i = 0; i < count; i++) {
    await engine.recordSignal({
      id: crypto.randomUUID(),
      entityId,
      type: 'behavioral.task_completed',
      value,
      source: 'system',
      timestamp: new Date().toISOString(),
      metadata: { batch: true, index: i },
    });
  }

  return engine.calculate(entityId);
}

// Record 20 successful signals
const updated = await recordBatch(engine, 'my-first-agent', 20);
console.log(`After 20 signals: score=${updated.score}, tier=T${updated.level}`);

---

7. Connect to Cognigate (Optional)

Once you have a trust engine running, you can connect it to the Cognigate governance enforcement API for production use:

import { Cognigate } from '@vorionsys/cognigate';

const client = new Cognigate({
  apiKey: process.env.COGNIGATE_API_KEY!,
});

const registeredAgent = await client.agents.create({
  name: 'MyFirstAgent',
  description: 'Learning the ropes',
  initialCapabilities: ['read:*'],
});

const status = await client.trust.getStatus(registeredAgent.id);
console.log(`Remote trust: ${status.trustScore} (${status.tierName})`);

---

Full Working Example

Put it all together in a single file:

// first-agent.ts
import { createTrustEngine } from '@vorionsys/atsf-core';

async function main() {
  const engine = createTrustEngine({
    failureThreshold: 0.3,
    successThreshold: 0.7,
    gainRate: 0.05,
  });

  // Register
  const agent = await engine.initializeEntity('demo-agent', 0);
  console.log(`Registered: score=${agent.score}, tier=T${agent.level}`);

  // Listen for tier changes
  engine.on('trust:tier_changed', (e) => {
    console.log(`  ⬆ Tier change: ${e.previousLevelName} → ${e.newLevelName}`);
  });

  // Record signals
  for (let i = 0; i < 25; i++) {
    await engine.recordSignal({
      id: crypto.randomUUID(),
      entityId: 'demo-agent',
      type: 'behavioral.task_completed',
      value: 0.9,
      source: 'system',
      timestamp: new Date().toISOString(),
      metadata: { iteration: i },
    });
  }

  // Final score
  const final = await engine.calculate('demo-agent');
  console.log(`Final: score=${final.score}, tier=T${final.level} (${final.levelName})`);
}

main().catch(console.error);

Run it:

npx tsx first-agent.ts

---

Key Takeaways

• Every agent starts at score 0, tier T0 (Sandbox). No exceptions.
• Trust is earned through behavioral signals — there is no shortcut.
• The gain formula is logarithmic: early gains are faster, high-trust gains require sustained consistent performance.
• Tier changes unlock capabilities. T0 is sandboxed. T1 is read-only. T4 gives full operational access.

---

Next Steps

• Trust Scoring Basics — understand the 0–1000 scale and what each tier means
• Your First Canary Probe — set up automated behavioral testing
• Eight-Tier Model — deep dive into T0 through T7