AgentTrust Docs

Overview

Setup guide for the TypeScript/Node.js SDK. Provides AgentTrustClient, wrap() helper, and Express middleware patterns.

Why It Matters

Node.js services and Express APIs need the same runtime governance as Python agents. The TypeScript SDK uses native fetch with zero runtime dependencies.

Prerequisites

Node.js ≥ 18
npm or yarn

Step-by-Step Guide

1. Install

npm install agentrust-sdk
# or
yarn add agentrust-sdk

2. Configure environment

export AGENTRUST_GATEWAY_URL=http://localhost:8000
export AGENTRUST_API_KEY=at_team_your_key    # Note: AGENTRUST_API_KEY (not AGENTRUST_KEY)
export AGENTRUST_ENABLED=true
export AGENTRUST_FAILURE_MODE=open
export AGENTRUST_TIMEOUT_MS=10000

3. Validate an execution

import { AgentTrustClient, BlockedError } from 'agentrust-sdk';

const client = new AgentTrustClient();

const result = await client.validate({
  agentId: 'my-agent',
  user: 'alice',
  input: 'Process this request',
  output: { answer: 'done' },
});

console.log(result.decision.outcome);

4. Wrap a function

import { AgentTrustClient } from 'agentrust-sdk';

const client = new AgentTrustClient();

const safeAgent = client.wrap('my-agent', async (user: string, input: string) => {
  return { answer: await callLlm(input) };
}, { blockOnBlock: true });

await safeAgent('alice', 'hello');

5. Express middleware

See sdks/typescript/examples/express-middleware.ts for a complete example.

Examples

Basic validation:

import { AgentTrustClient, loadConfig } from 'agentrust-sdk';

const config = loadConfig();
const client = new AgentTrustClient(config);

try {
  const result = await client.validate({
    agentId: 'payment-agent',
    user: 'bob',
    input: 'Transfer $100',
    output: { status: 'approved' },
    framework: 'Custom',
  });
  if (result.decision.outcome === 'block') {
    throw new Error('Governance blocked this output');
  }
} catch (e) {
  if (e instanceof BlockedError) {
    console.error('Blocked by AgentTrust:', e.message);
  }
}

Best Practices

Use loadConfig() to centralize env var reading
Set blockOnBlock: true in wrap() for fail-closed behavior
TypeScript SDK does not support queue failure mode — use Python SDK for air-gap buffering
Align env var names with your deployment platform (note AGENTRUST_API_KEY vs Python's AGENTRUST_KEY)

Common Mistakes

Using AGENTRUST_KEY instead of AGENTRUST_API_KEY in Node.js
Expecting embedded gateway support (Python-only feature)
Not handling BlockedError when blockOnBlock is enabled

Troubleshooting

Issue	Fix
`fetch failed`	Verify `AGENTRUST_GATEWAY_URL` is reachable
Auth 401/403	Check `AGENTRUST_API_KEY` header
Type errors	Ensure `@types/node` is installed

TypeScript Quickstart