AgentTrust Docs

Overview

The TypeScript/Node.js SDK provides AgentTrustClient, client.wrap(), and loadConfig() for Node.js services. It lives in sdks/typescript/ and is not yet published to npm.

Why It Matters

Node.js backends, Express APIs, and serverless functions need native TypeScript governance integration.

Prerequisites

Not on npm yet. The npm package named agentrust-sdk is an unrelated third-party project.

cd sdks/typescript && npm install && npm run build
npm install /absolute/path/to/sdks/typescript   # from your service

Node.js ≥ 18 (uses native fetch). Zero runtime dependencies.

Step-by-Step Guide

Imports

import {
  AgentTrustClient,
  loadConfig,
  AgentTrustError,
  BlockedError,
  GatewayUnavailableError,
  TierGateError,
} from 'agentrust-sdk';

AgentTrustClient

// Config keys are gatewayUrl / apiKey / timeoutMs / failureMode / enabled.
// Anything you omit falls back to loadConfig()'s env-var defaults.
const client = new AgentTrustClient({
  gatewayUrl: process.env.AGENTRUST_GATEWAY_URL,
  apiKey: process.env.AGENTRUST_API_KEY,
  timeoutMs: 10000,
  failureMode: 'open',  // 'open' | 'closed'
});

const result = await client.validate({
  agentId: 'my-agent',
  user: 'alice',
  input: 'user query',
  output: { answer: 'response' },
  framework: 'Custom',
});

wrap() runs your function first, then validates the result. Unlike Python's @harness it does not pre-check, so a block decision cannot stop the call from happening — it only stops the result from being returned to the caller.

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

Options: user (default "unknown"), input (defaults to the agent ID), and blockOnBlock — throw BlockedError when the decision outcome is block.

wrap() does not read the wrapped function's runtime arguments. Whatever you pass as opts.user / opts.input is recorded on every invocation, so a wrapper without them audits every call as user: "unknown". For per-call identity, call validate() yourself.

wrap() sends no framework, so the client's default applies. That default is "Custom" — an accepted Framework enum value. Pass framework explicitly on validate() when you want per-framework analytics to be meaningful.

loadConfig()

const config = loadConfig();  // reads AGENTRUST_* env vars
const client = new AgentTrustClient(config);

Environment variables

Variable	Default
`AGENTRUST_GATEWAY_URL`	`http://localhost:8000`
`AGENTRUST_API_KEY`	—
`AGENTRUST_ENABLED`	`true`
`AGENTRUST_FAILURE_MODE`	`open`
`AGENTRUST_TIMEOUT_MS`	`10000`

Limitations vs Python SDK

Feature	Python	TypeScript
`POST /v1/runtime/validate`	✅	✅
Pre-check / post-check (two-phase gate)	✅	❌ — validate only
Embedded gateway	✅	❌
Queue mode	✅	❌
Framework adapters	✅	❌
Auto-instrument	✅	❌
CLI	✅	❌
Retry / backoff	✅	❌
`wrap()` helper	❌	✅

Because the TypeScript SDK never calls /v1/runtime/pre-check, it cannot prevent a high-risk action from executing — only from being returned. For pre-execution blocking, call /v1/runtime/pre-check directly or use the Python SDK.

Examples

See sdks/typescript/examples/basic.ts and express-middleware.ts.

Best Practices

Use AGENTRUST_API_KEY (not AGENTRUST_KEY)
Set blockOnBlock: true for high-stakes endpoints
Share one AgentTrustClient instance per process

TypeScript SDK Reference