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

pip install mandatez

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...' }

from mandatez import generate_agent_identity

identity = generate_agent_identity()
# AgentIdentity(
#   agent_id='ag_c065af93bcf9',
#   public_key='base64...',
#   private_key='hex...'
# )

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!,
});

import os
from mandatez import MandateZClient

client = MandateZClient(
    agent_id=identity.agent_id,
    owner_id="your_org_id",
    private_key=identity.private_key,
    supabase_url=os.environ["SUPABASE_URL"],
    supabase_anon_key=os.environ["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

import asyncio

async def main():
    event = await client.track(action_type="read", resource="emails")
    print(event.event_id)  # UUID
    print(event.outcome)   # 'allowed'
    print(event.signature) # Ed25519 signature

asyncio.run(main())

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'

from mandatez import MandateZClient, Policy, PolicyRule

client = MandateZClient(
    agent_id=identity.agent_id,
    owner_id="your_org_id",
    private_key=identity.private_key,
    supabase_url=os.environ["SUPABASE_URL"],
    supabase_anon_key=os.environ["SUPABASE_ANON_KEY"],
    policies=[
        Policy(
            id="pol_prod",
            owner_id="your_org_id",
            name="Production",
            rules=[
                PolicyRule(id="r1", action_types=["export", "delete"],
                           resource_pattern="*", effect="block"),
                PolicyRule(id="r2", action_types=["payment"],
                           resource_pattern="api/*", effect="flag"),
            ],
        ),
    ],
)

blocked = await client.track(action_type="export", resource="customer_data")
print(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

from mandatez import verify_event

valid = verify_event(event.to_dict())
print(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

from crewai import Task, Crew
from mandatez import MandateZClient
from mandatez.integrations.crewai import governed_agent

client = MandateZClient(...)
analyst = governed_agent(
    mandatez_client=client,
    role="Market Analyst",
    goal="Research market trends",
    backstory="A seasoned analyst with 10 years of experience.",
)

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