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.

The AgentTrust TypeScript SDK ships as source in sdks/typescript/ and has not been published to npm. The npm package literally named agentrust-sdk belongs to an unrelated third-party project — installing it will not give you this SDK. Build from source until an official release is announced.

# From the repository root
cd sdks/typescript
npm install
npm run build      # emits dist/

# Then reference it from your service
npm install /absolute/path/to/sdks/typescript

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, BlockedError, 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) {
  // NOTE: client.validate() never throws BlockedError — only client.wrap({ blockOnBlock: true })
  // does. This catch handles the explicit throw above.
  console.error('Governance check failed:', e);
}

Best Practices

Use loadConfig() to centralize env var reading
Pass an explicit framework when you want per-framework analytics — the client defaults to "Custom"
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 SDK Reference
API: Validate
sdks/typescript/examples/express-middleware.ts in the repository

TypeScript Quickstart