Agents Framework (@veridex/agents)

npm install @veridex/agents zod

import { createAgent, tool, OpenAIProvider } from '@veridex/agents';
import { z } from 'zod';
 
const agent = createAgent(
  {
    name: 'my-agent',
    description: 'A helpful assistant',
    instructions: 'You are a helpful assistant.',
    tools: [
      tool({
        name: 'greet',
        description: 'Greet a user',
        input: z.object({ name: z.string() }),
        safetyClass: 'read',
        async execute({ input }) {
          return { success: true, llmOutput: `Hello, ${input.name}!` };
        },
      }),
    ],
  },
  {
    modelProviders: {
      default: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
    },
  },
);
 
const result = await agent.run('Say hello to Alice');
console.log(result.output);

import {
  OpenAIProvider,
  AnthropicProvider,
  GeminiProvider,
  OpenAICompatibleProvider,
} from '@veridex/agents';
 
const agent = createAgent(definition, {
  modelProviders: {
    default: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
    reasoning: new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY }),
    fast: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY }),
    local: new OpenAICompatibleProvider({
      baseURL: 'http://localhost:11434/v1',
      model: 'llama3',
    }),
  },
});

import { tool, ToolSafetyClass } from '@veridex/agents';
 
const readTool = tool({
  name: 'lookup_order',
  description: 'Look up an order by ID',
  input: z.object({ orderId: z.string() }),
  safetyClass: 'read', // auto-allowed by default policy
  async execute({ input }) {
    return { success: true, llmOutput: `Order ${input.orderId}: shipped` };
  },
});

import { createResponseSeal, verifyResponseSeal } from '@veridex/agents';
 
// Seals are created automatically during agent runs.
// To verify a seal manually:
const isValid = verifyResponseSeal(
  seal,
  rawResponseBytes,
  apiKeyBytes,
);

interface ResponseEnvelope {
  runId: string;
  turnIndex: number;
  model: string;
  provider: string;
  output: string;
  tokensUsed: { prompt: number; completion: number };
  chainOfCustodySeal?: {
    algorithm: string;
    seal: string;   // hex-encoded HMAC
    rawHash: string; // SHA-256 of raw response
    timestamp: number;
  };
}

interface AgentIdentityClaims {
  iss: string;       // Issuer
  sub: string;       // Agent ID
  aud: string;       // Audience
  iat: number;       // Issued at
  exp: number;       // Expires
  scope: string[];   // Permissions
  agentName: string;
  agentVersion: string;
}
 
interface AgentIntegrityBinding {
  agentId: string;
  identityClaims: AgentIdentityClaims;
  codeHash: string;         // SHA-256 of agent code
  configHash: string;       // SHA-256 of agent configuration
  toolManifestHash: string; // SHA-256 of registered tools
  timestamp: number;
}

interface ExecutionNode {
  id: string;
  type: 'turn' | 'tool_call' | 'model_call' | 'policy_check' | 'approval';
  timestamp: number;
  data: Record<string, unknown>;
}
 
interface ExecutionEdge {
  from: string;
  to: string;
  type: 'triggered' | 'required' | 'produced';
}
 
interface ExecutionGraph {
  nodes: ExecutionNode[];
  edges: ExecutionEdge[];
  rootId: string;
}

const userLookup = tool({
  name: 'lookup_user',
  description: 'Look up user profile',
  input: z.object({ userId: z.string() }),
  safetyClass: 'read',
  ppiTags: ['name', 'email', 'address'], // PII categories this tool exposes
  async execute({ input }) {
    return { success: true, llmOutput: `User ${input.userId}: ...` };
  },
});

import { MemoryManager, InMemoryStore } from '@veridex/agents';
 
const memory = new MemoryManager({
  store: new InMemoryStore(),
  decayRate: 0.05,           // memory decay score per day
  compactionThreshold: 10,   // trigger compaction every 10 turns
});
 
// A. Working Memory: temporary scratchpad for the active run (auto-discarded)
await memory.setWorking('active_intent', 'payout_supplier_invoice');
 
// B. Episodic Memory: timestamped records of raw events, searchable via semantic index
await memory.writeEpisode({
  content: 'User requested a payout status check for INV-2026.',
  confidence: 0.95,
  tags: ['billing', 'invoice']
});
 
// C. Semantic Memory: consolidated factual records with confidence scoring & provenance
await memory.commitFact({
  subject: 'acme_operations',
  fact: '0x742d... is the verified Acme recipient wallet on Base',
  confidence: 1.0,
  provenance: 'manually_declared_by_owner'
});
 
// D. Procedural Memory: learned routines or strict operations manuals
await memory.storeProcedure({
  trigger: 'excessive_gas_spikes',
  actions: ['suspend_non_urgent_swaps', 'notify_engineering_channel']
});

import { PolicyEngine, ToolProposal, RuleVerdict } from '@veridex/agents';
 
const engine = new PolicyEngine();
 
// Register a custom verification rule
engine.registerRule({
  name: 'restrict_weekend_payments',
  description: 'Requires human escalation for any financial operations proposed on weekends',
  async evaluate(proposal: ToolProposal): Promise<RuleVerdict> {
    const isWeekend = [0, 6].includes(new Date().getDay());
    
    if (proposal.safetyClass === 'financial' && isWeekend) {
      return {
        verdict: 'escalate',
        reason: 'Out-of-hours financial transactions require explicit administrator sign-off.'
      };
    }
    
    return { verdict: 'allow' };
  }
});

import { MCPServerTransport, createAgent } from '@veridex/agents';
 
const agent = createAgent({
  name: 'mcp-treasury-helper',
  instructions: 'Expose local balance-checks and transfer tools over MCP.',
  tools: [/* your safety-classed tools */]
});
 
// Initialize the native MCP Server transport
const mcpServer = new MCPServerTransport({
  name: 'Veridex Treasury MCP Service',
  version: '1.2.0',
  agent
});
 
// Run over stdio (allows deep integration with any local developer environment)
await mcpServer.start();
console.log('Veridex MCP Server listening on standard I/O...');