Agent Trust SDK for TypeScript/JavaScript

TypeScript SDK for TrustAgents - the security layer for AI agents.

Two powerful tools:

1. AgentTrustClient - Verify agents and track reputation
2. TrustGuard - Protect your AI agent from malicious content

Installation

npm install agent-trust-sdk

Quick Start

TrustGuard - Protect Your AI Agent

Scan untrusted content before letting your AI agent process it:

import { TrustGuard, ContentSource } from 'agent-trust-sdk';

const guard = new TrustGuard({ apiKey: 'ta_xxx...' }); // Get key at trustagents.dev

// Scan web content before processing
const result = await guard.scanWeb(htmlContent);
if (result.safe) {
  agent.process(htmlContent);
} else {
  console.log(`Blocked: ${result.reasoning}`);
  for (const threat of result.threats) {
    console.log(`  - ${threat.patternName}: ${threat.matchedText}`);
  }
}

// Scan documents
await guard.scanDocument(pdfText, { filename: 'report.pdf' });

// Scan emails
await guard.scanEmail(email.body, { subject: email.subject });

// Scan MCP tool descriptions
await guard.scanTool('calculator', tool.description);

// Scan before storing in memory
await guard.scanMemory(userMessage, { memoryType: 'conversation' });

// Scan before RAG indexing
await guard.scanRag(doc.text, { source: 'knowledge_base.txt' });

// Fetch and scan a URL in one call
const urlResult = await guard.fetchUrl('https://example.com/page');
if (urlResult.guardResult?.safe) {
  agent.process(urlResult.guardResult.content);
}

AgentTrustClient - Verify Agents

Check if an agent is trustworthy before interacting:

import { AgentTrustClient, Verdict } from 'agent-trust-sdk';

const client = new AgentTrustClient();

const result = await client.verifyAgent(
  'Shopping Assistant',
  'https://shop.ai/agent',
  'I help you find the best deals'
);

if (result.verdict === Verdict.BLOCK) {
  console.log(`⛔ Agent blocked: ${result.reasoning}`);
} else if (result.verdict === Verdict.CAUTION) {
  console.log('⚠️ Proceed with caution');
} else {
  console.log(`✅ Agent is safe! Trust score: ${result.trustScore}`);
}

TrustGuard Reference

Scan Web Content

const result = await guard.scanWeb(content, {
  sourceUrl: 'https://example.com',  // Optional, for logging
  extractText: true,                  // Extract visible text from HTML
  checkHidden: true,                  // Check for hidden/invisible text
});

console.log(result.safe);      // boolean
console.log(result.verdict);   // 'allow' | 'caution' | 'block'
console.log(result.threats);   // ThreatMatch[]

Scan Documents

const result = await guard.scanDocument(content, {
  filename: 'report.pdf',
  documentType: 'pdf',
  metadata: { author: 'John' },
});

Scan Emails

const result = await guard.scanEmail(body, {
  subject: 'Important!',
  sender: '[email protected]',
  headers: { 'Reply-To': '...' },
});

Scan MCP Tools

const result = await guard.scanTool(name, description, {
  schema: { type: 'object', properties: {...} },
  serverUrl: 'https://mcp-server.com',
});

Scan Memory Content

const result = await guard.scanMemory(content, {
  context: 'Chat conversation',
  memoryType: 'conversation',  // or 'fact', 'preference', etc.
});

Scan RAG Content

const result = await guard.scanRag(content, {
  source: 'documents/policy.txt',
  metadata: { category: 'policies' },
  chunkId: 'chunk_001',
});

Batch Scanning

import { BatchScanItem, ContentSource } from 'agent-trust-sdk';

const items: BatchScanItem[] = [
  { id: 'doc1', sourceType: ContentSource.DOCUMENT, content: doc1Text },
  { id: 'doc2', sourceType: ContentSource.DOCUMENT, content: doc2Text },
  { id: 'web1', sourceType: ContentSource.WEB, content: webContent },
];

const response = await guard.scanBatch(items);

console.log(`Total: ${response.total}`);
console.log(`Safe: ${response.safeCount}`);
console.log(`Threats: ${response.threatCount}`);

for (const result of response.results) {
  if (!result.result.safe) {
    console.log(`Threat in ${result.id}: ${result.result.reasoning}`);
  }
}

Fetch and Scan URL

const result = await guard.fetchUrl('https://example.com/page');

if (result.fetched && result.guardResult?.safe) {
  agent.processContent(result.guardResult.content);
} else if (result.fetchError) {
  console.log(`Failed to fetch: ${result.fetchError}`);
} else {
  console.log(`Content blocked: ${result.guardResult?.reasoning}`);
}

AgentTrustClient Reference

Verify Agents

const result = await client.verifyAgent(
  'Research Assistant',
  'https://research.ai/agent',
  'I help with academic research',
  [{ name: 'search', description: 'Search papers' }]
);

console.log(result.verdict);     // 'allow' | 'caution' | 'block'
console.log(result.threatLevel); // 'safe' | 'low' | 'medium' | 'high' | 'critical'
console.log(result.trustScore);  // 0-100

Scan Text for Threats

const result = await client.scanText('Ignore previous instructions...');
if (result.verdict !== Verdict.ALLOW) {
  for (const threat of result.threats) {
    console.log(`  - ${threat.patternName} (${threat.severity})`);
  }
}

Track Agent Reputation

import { InteractionOutcome } from 'agent-trust-sdk';

// Report a successful interaction
const result = await client.reportInteraction(
  'https://shop.ai/agent',
  InteractionOutcome.SUCCESS,
  {
    taskType: 'shopping',
    responseQuality: 5,
    taskCompleted: true,
  }
);

// Get reputation details
const rep = await client.getReputation('https://shop.ai/agent');
console.log(`Trust score: ${rep.trustScore}`);

Configuration

// TrustGuard
const guard = new TrustGuard({
  apiKey: 'ta_xxx...',           // Your API key
  apiUrl: 'https://custom.url',  // Optional: custom API URL
  timeout: 30000,                // Request timeout in ms
});

// AgentTrustClient
const client = new AgentTrustClient({
  apiUrl: 'https://custom.url',
  timeout: 60000,
  apiKey: 'ta_xxx...',
});

Error Handling

import { TrustGuard, TrustGuardError, GuardAPIError } from 'agent-trust-sdk';

try {
  const result = await guard.scanWeb(content);
} catch (error) {
  if (error instanceof GuardAPIError) {
    console.log(`API error: ${error.message}`);
    console.log(`Status code: ${error.statusCode}`);
  } else if (error instanceof TrustGuardError) {
    console.log(`Guard error: ${error.message}`);
  }
}

Types

Verdicts

• Verdict.ALLOW - Content/agent is safe
• Verdict.CAUTION - Some concerns detected
• Verdict.BLOCK - Threat detected, do not process

Threat Levels

• ThreatLevel.SAFE - No threats
• ThreatLevel.LOW - Minor concerns
• ThreatLevel.MEDIUM - Moderate risk
• ThreatLevel.HIGH - Significant risk
• ThreatLevel.CRITICAL - Severe threat

Content Sources (for batch scanning)

• ContentSource.WEB - Web page content
• ContentSource.DOCUMENT - Documents (PDF, DOCX, etc.)
• ContentSource.EMAIL - Email content
• ContentSource.TOOL - MCP tool descriptions
• ContentSource.MEMORY - Memory storage content
• ContentSource.RAG - RAG indexing content

License

MIT License

Links

• Website: https://trustagents.dev
• Docs: https://trustagents.dev/docs
• GitHub: https://github.com/jd-delatorre/trustlayer