Quickstart

Get MandateZ running in under 5 minutes

Quickstart

MandateZ ships first-class SDKs for both TypeScript and Python. They produce byte-identical Ed25519 signatures, so an event signed from Python verifies cleanly from TypeScript and vice versa.

Install

TypeScript

npm install @mandatez/sdk

1. Generate an Agent Identity

Every agent gets a unique ID and Ed25519 keypair:

TypeScript

import { generateAgentIdentity } from '@mandatez/sdk';

const identity = await generateAgentIdentity();
// { agent_id: 'ag_V1StGXR8_Z5jdHi6B-myT',
//   public_key: 'base64...',
//   private_key: 'base64...' }

Save identity.private_key in your secret manager immediately. It is not recoverable if lost. Never commit it to source control.

2. Create a Client

The client wires together signing, policy, and transport:

TypeScript

import { MandateZClient } from '@mandatez/sdk';

const client = new MandateZClient({
  agentId: identity.agent_id,
  ownerId: 'your_org_id',
  privateKey: identity.private_key,
  supabaseUrl: process.env.SUPABASE_URL!,
  supabaseAnonKey: process.env.SUPABASE_ANON_KEY!,
});

3. Track an Action

One method call — signed, validated, and emitted:

TypeScript

const event = await client.track({
  action_type: 'read',
  resource: 'emails',
});

console.log(event.event_id);  // UUID
console.log(event.outcome);   // 'allowed'
console.log(event.signature); // Ed25519 signature

4. Add a Policy (Optional)

Block or flag actions before they execute:

TypeScript

const client = new MandateZClient({
  agentId: identity.agent_id,
  ownerId: 'your_org_id',
  privateKey: identity.private_key,
  supabaseUrl: process.env.SUPABASE_URL!,
  supabaseAnonKey: process.env.SUPABASE_ANON_KEY!,
  policies: [{
    id: 'pol_prod',
    owner_id: 'your_org_id',
    name: 'Production',
    rules: [
      { id: 'r1', action_types: ['export', 'delete'], resource_pattern: '*', effect: 'block' },
      { id: 'r2', action_types: ['payment'], resource_pattern: 'api/*', effect: 'flag' },
    ],
  }],
});

const blocked = await client.track({
  action_type: 'export',
  resource: 'customer_data',
});
console.log(blocked.outcome); // 'blocked'

5. Verify an Event

Anyone with the public key can verify the signature:

TypeScript

import { verifyEvent } from '@mandatez/sdk';

const valid = await verifyEvent(event);
console.log(valid); // true

Python: Framework Integrations

The Python SDK ships with callbacks for the two most popular agent frameworks:

LangChain

from langchain_openai import ChatOpenAI
from mandatez import MandateZClient
from mandatez.integrations.langchain import MandateZCallbackHandler

client = MandateZClient(...)
llm = ChatOpenAI(callbacks=[MandateZCallbackHandler(client)])
# every tool call is now a signed event

Install the matching extra once:

pip install "mandatez[langchain]"
pip install "mandatez[crewai]"

Next Steps

• track() API Reference — full options and examples
• Protocol Specification — the open standard
• Dashboard — live event monitoring