Agents Framework API Reference

npm install @veridex/agents zod

npm install @veridex/agents-react @veridex/agents-adapters @veridex/agents-openclaw @veridex/agents-control-plane

import { createAgent, tool, OpenAIProvider } from '@veridex/agents';
import { z } from 'zod';
 
const agent = createAgent(
  {
    id: 'my-agent',
    name: 'My Agent',
    model: { provider: 'openai', model: 'gpt-4o-mini' },
    instructions: 'You are a helpful assistant.',
    tools: [],
    maxTurns: 10,
  },
  {
    modelProviders: {
      openai: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
    },
    enableTracing: true,
    enableCheckpoints: true,
  },
);

interface AgentDefinition {
  id: string;
  name: string;
  model: ModelConfig;
  instructions: string;
  tools?: ToolContract[];
  maxTurns?: number;                     // default: 10
  handoffs?: HandoffHandler[];
  payment?: PaymentConfig;
  metadata?: Record<string, unknown>;
}
 
interface ModelConfig {
  provider: string;                      // 'openai' | 'anthropic' | custom
  model: string;                         // e.g. 'gpt-4o', 'claude-sonnet-4-20250514'
  fallback?: ModelConfig;
  temperature?: number;
}

interface RuntimeOptions {
  modelProviders?: Record<string, ModelProvider>;
  veridexSDK?: unknown;                  // optional @veridex/sdk instance
  agentWallet?: unknown;                 // optional @veridex/agentic-payments wallet
  enableTracing?: boolean;
  enableCheckpoints?: boolean;
}

// Start a run
const result = await agent.run('What is the status of order ORD-1042?');
 
// result shape
interface RunResult {
  output: string;
  state: RunState;            // 'completed' | 'failed' | 'suspended'
  turns: Turn[];
  runId: string;
}
 
type RunState = 'pending' | 'running' | 'completed' | 'failed' | 'suspended' | 'cancelled';

import { tool } from '@veridex/agents';
import { z } from 'zod';
 
const searchOrders = tool({
  name: 'search_orders',
  description: 'Search orders by customer email.',
  input: z.object({
    email: z.string().email(),
    limit: z.number().int().min(1).max(100).default(10),
  }),
  safetyClass: 'read',
  timeoutMs: 5000,
  retries: 2,
  idempotent: true,
  async execute({ input }) {
    const orders = await db.orders.findByEmail(input.email, input.limit);
    return {
      success: true,
      llmOutput: `Found ${orders.length} orders.`,
      data: orders,
    };
  },
});

interface ToolContract<TInput = unknown, TOutput = unknown> {
  name: string;
  description: string;
  input: z.ZodType<TInput> | Record<string, unknown>;
  output?: z.ZodType<TOutput> | Record<string, unknown>;
  safetyClass: ToolSafetyClass;
  execute: (params: ToolExecuteParams<TInput>) => Promise<ToolResult>;
  timeoutMs?: number;
  retries?: number;
  idempotent?: boolean;
  permissions?: string[];
  costEstimate?: (input: TInput) => CostEstimate;
  metadata?: Record<string, unknown>;
}
 
type ToolSafetyClass = 'read' | 'write' | 'network' | 'financial' | 'destructive' | 'privileged';
 
interface ToolResult {
  success: boolean;
  llmOutput: string;
  data?: unknown;
  error?: string;
  metadata?: Record<string, unknown>;
}

const registry = agent.tools;
 
registry.register(searchOrders);
registry.get('search_orders');           // ToolContract | undefined
registry.has('search_orders');           // boolean
registry.list();                         // ToolContract[]
registry.remove('search_orders');        // boolean

import {
  PolicyEngine,
  blockSafetyClasses,
  requireApprovalFor,
  maxRunSpendUSD,
  maxTokenBudget,
  allowChains,
} from '@veridex/agents';
 
const engine = agent.policyEngine;
 
// Block all destructive and privileged tools
engine.register(blockSafetyClasses(['destructive', 'privileged'], agent.tools.list()));
 
// Require human approval for financial tools
engine.register(requireApprovalFor(['financial'], agent.tools.list()));
 
// Cap spend and token usage per run
engine.register(maxRunSpendUSD(50));
engine.register(maxTokenBudget(100_000));
 
// Restrict to specific chains
engine.register(allowChains(['base', 'optimism']));

interface PolicyRule {
  id: string;
  name: string;
  description: string;
  priority?: number;                     // lower = evaluated first
  evaluate(ctx: PolicyContext): PolicyCheckResult | Promise<PolicyCheckResult>;
}
 
interface PolicyCheckResult {
  verdict: 'allow' | 'deny' | 'escalate';
  reason?: string;
  metadata?: Record<string, unknown>;
}

const approvals = agent.approvals;
 
// Add approval routes
approvals.addRoute({
  match: (proposal, policy) => policy.verdict === 'escalate',
  mode: 'human_required',
  timeoutMs: 300_000,                    // 5 minutes
});
 
// Register handlers
approvals.registerHandler('human_required', async (request) => {
  // send to Slack, email, or dashboard
  return { approved: true, decidedBy: 'ops-team' };
});
 
// Inspect pending requests
const pending = approvals.getPending();
 
// Resolve a request programmatically
approvals.resolve(requestId, true, 'admin@company.com', 'Looks safe.');

type ApprovalMode =
  | 'auto_allow'
  | 'auto_block'
  | 'human_required'
  | 'dual_approval'
  | 'policy_pack';
 
interface ApprovalRequest {
  id: string;
  runId: string;
  agentId: string;
  turnIndex: number;
  proposal: ActionProposal;
  policyDecision: PolicyDecision;
  mode: ApprovalMode;
  reason?: string;
  createdAt: number;
  expiresAt?: number;
}
 
interface ApprovalDecision {
  requestId: string;
  approved: boolean;
  decidedBy: string;
  reason?: string;
  decidedAt: number;
  conditions?: Record<string, unknown>;
}

const memory = agent.memory;
 
// Write a memory entry
await memory.write({
  tier: 'episodic',
  content: 'User prefers email notifications over SMS.',
  scope: 'session',
  tags: ['preferences'],
  confidence: 0.9,
  ttlMs: 86_400_000,                    // 24 hours
});
 
// Search memory
const results = await memory.search({
  query: 'notification preference',
  tiers: ['episodic', 'semantic'],
  limit: 5,
});
 
// Compact old entries
const { removedCount, retainedCount } = await memory.compact();

type MemoryTier = 'working' | 'episodic' | 'semantic' | 'procedural';
type MemoryScope = 'run' | 'session' | 'global';
 
interface MemoryEntry {
  id: string;
  tier: MemoryTier;
  content: string;
  scope?: MemoryScope;
  confidence: number;
  tags: string[];
  ttlMs: number;
  createdAt: number;
  lastAccessedAt: number;
}

const cp = agent.checkpoints;
 
// Save a checkpoint
await cp.save(runId, agentId, turnIndex, stateObject, 'approval');
 
// Restore the latest checkpoint
const latest = await cp.loadLatest(runId);
if (latest) {
  const state = cp.parseState(latest);
  // resume the run from this state
}
 
// List all checkpoints for a run
const all = await cp.list(runId);

interface Checkpoint {
  id: string;
  runId: string;
  agentId: string;
  turnIndex: number;
  state: string;                         // JSON-serialized run state
  createdAt: number;
  reason: 'suspend' | 'approval' | 'handoff' | 'periodic' | 'error';
  metadata?: Record<string, unknown>;
}

const compiler = agent.context;
 
const plan = compiler.compile({
  maxTokens: 4096,
  sections: [
    { id: 'instructions', content: agent.definition.instructions, priority: 1 },
    { id: 'memory', content: memoryText, priority: 2 },
    { id: 'history', content: conversationHistory, priority: 3, truncation: 'tail' },
  ],
});
 
// plan.totalTokens — actual tokens used
// plan.hadTruncation — true if any section was truncated

interface ContextCompilerOptions {
  maxTokens: number;
  sections: ContextSectionInput[];
}
 
interface ContextSectionInput {
  id: string;
  content: string;
  priority: number;                      // lower = more important
  truncation?: TruncationStrategy;       // 'head' | 'tail' | 'middle' | 'none'
}
 
interface ContextPlan {
  sections: ContextSection[];
  totalTokens: number;
  budgetTokens: number;
  hadTruncation: boolean;
  compiledAt: number;
}

const bus = agent.events;
 
// Listen for specific events
const unsub = bus.on('tool_started', (event) => {
  console.log(`Tool ${event.toolName} started at turn ${event.turnIndex}`);
});
 
// Listen for all events
bus.onAny((event) => {
  console.log(event.type, event.timestamp);
});
 
// One-shot listener
bus.once('run_completed', (event) => {
  console.log('Run finished:', event.runId);
});
 
// Access the full immutable log
const log = agent.eventLog;
const allEvents = log.getAll();
const toolEvents = log.getByType('tool_completed');

type TraceEventType =
  | 'run_started' | 'run_completed' | 'run_failed' | 'run_suspended'
  | 'turn_started' | 'turn_completed'
  | 'tool_started' | 'tool_completed' | 'tool_failed'
  | 'model_called' | 'model_responded'
  | 'policy_evaluated' | 'approval_requested' | 'approval_resolved'
  | 'memory_written' | 'checkpoint_saved'
  | 'handoff_initiated' | 'handoff_completed';

import { HookRegistry, HookRunner } from '@veridex/agents';
 
agent.hooks.register({
  name: 'log-tool-calls',
  phase: 'before_tool',
  priority: 10,
  async execute(context) {
    console.log('About to call tool:', context.toolName);
  },
});
 
agent.hooks.register({
  name: 'block-after-hours',
  phase: 'before_run',
  async execute() {
    const hour = new Date().getHours();
    if (hour < 6 || hour > 22) {
      return { override: 'deny', reason: 'Outside business hours' };
    }
  },
});

type HookPhase =
  | 'before_run' | 'after_run'
  | 'before_turn' | 'after_turn'
  | 'before_tool' | 'after_tool'
  | 'on_error';
 
interface RuntimeHook {
  name: string;
  phase: HookPhase;
  priority?: number;                     // lower = runs first
  timeoutMs?: number;
  execute(context: unknown): Promise<HookResult | void> | HookResult | void;
}
 
interface HookResult {
  annotations?: Record<string, unknown>;
  override?: 'continue' | 'retry' | 'pause' | 'deny';
  reason?: string;
}

import { OpenAIProvider } from '@veridex/agents';
 
const provider = new OpenAIProvider({
  apiKey: process.env.OPENAI_API_KEY,
  organization: 'org-xxx',              // optional
  baseUrl: 'https://api.openai.com/v1', // optional
});
 
const response = await provider.complete(
  [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Hello!' },
  ],
  {
    temperature: 0.7,
    maxTokens: 1024,
    tools: [searchOrders],               // optional tool contracts
  },
);

import { AnthropicProvider } from '@veridex/agents';
 
const provider = new AnthropicProvider({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

interface ModelProvider {
  complete(
    messages: ModelMessage[],
    options?: ModelCompletionOptions,
  ): Promise<ModelResponse>;
}
 
interface ModelMessage {
  role: 'user' | 'assistant' | 'system';
  content: string;
}
 
interface ModelResponse {
  content: string;
  toolCalls?: Array<{ id: string; name: string; arguments: unknown }>;
  usage: ModelUsage;
  finishReason: string;
}
 
interface ModelUsage {
  promptTokens: number;
  completionTokens: number;
  totalTokens: number;
}

interface AuditBundle {
  id: string;
  runId: string;
  agentId: string;
  startedAt: number;
  completedAt?: number;
  toolExecutions: ToolExecutionSummary[];
  policies: Record<string, unknown>;
  approvals: Record<string, unknown>;
}
 
type AuditExportFormat = 'json' | 'jsonl' | 'csv';

import { MCPServerTransport } from '@veridex/agents';
 
const mcp = new MCPServerTransport({
  serverName: 'my-agent-mcp',
  serverVersion: '1.0.0',
  tools: agent.tools.list(),
});
 
await mcp.connect();

import { ACPTransport } from '@veridex/agents';
 
const acp = new ACPTransport({
  agentCard: {
    name: 'my-agent',
    description: 'Handles order lookups',
    capabilities: [
      { name: 'lookup_order', description: 'Find orders', inputSchema: {} },
    ],
  },
});
 
await acp.connect();

import { A2ATransport } from '@veridex/agents';
 
const a2a = new A2ATransport({
  agentCard: {
    name: 'coordinator',
    description: 'Coordinates between specialist agents',
    capabilities: [],
  },
});
 
await a2a.connect();

interface Transport {
  connect(): Promise<void>;
  disconnect(): Promise<void>;
  send(request: unknown): Promise<unknown>;
}
 
type TransportState = 'disconnected' | 'connecting' | 'connected' | 'error';

import { ReplayProvider, TraceRecorder } from '@veridex/agents';
 
// Record interactions during a live run
const recorder = new TraceRecorder();
// ... run agent with recorder attached ...
const trace = recorder.getTrace();
 
// Replay later
const replay = new ReplayProvider(trace.interactions);
const response = await replay.complete(messages);

import { compareTraces, serializeGoldenTrace, deserializeGoldenTrace } from '@veridex/agents';
 
const result = compareTraces(baseline, current);
console.log(result.identical);          // boolean
console.log(result.similarityScore);    // 0..1
console.log(result.diffs);             // EventDiff[]

type ActionProposal =
  | { type: 'tool_call'; toolName: string; arguments: unknown }
  | { type: 'handoff'; targetAgent: string; message: string }
  | { type: 'memory_write'; tier: MemoryTier; content: string }
  | { type: 'final_answer'; content: string }
  | { type: 'approval_request'; reason: string };

import { AgentProvider } from '@veridex/agents-react';
 
function App() {
  return (
    <AgentProvider runtime={agent}>
      <ChatUI />
    </AgentProvider>
  );
}

const { definition, state } = useAgent();

const { run, state, result, error, isLoading } = useRun();
 
// Start a run
await run('What is order ORD-1042?');
 
// state: 'pending' | 'running' | 'completed' | 'failed' | 'suspended'

interface UseRunReturn {
  run: (input: string, options?: RunOptions) => Promise<RunResult>;
  state: RunState;
  result?: RunResult;
  error?: Error;
  isLoading: boolean;
}

const { stream, cancel } = useTurnStream();

const { pending, resolve } = useApprovals();
 
// Render approval inbox
{pending.map(req => (
  <div key={req.id}>
    <p>{req.proposal.toolName} needs approval</p>
    <button onClick={() => resolve(req.id, true)}>Approve</button>
    <button onClick={() => resolve(req.id, false)}>Deny</button>
  </div>
))}

interface UseApprovalsReturn {
  pending: ApprovalRequest[];
  resolve: (requestId: string, approved: boolean) => Promise<void>;
}

const { events, latest } = useTrace();

const { entries, write, search, clear } = useMemory();
 
await write({
  tier: 'episodic',
  content: 'User prefers dark mode.',
  tags: ['preferences'],
});

const { snapshot, estimateSpend } = useBudget();
// snapshot.spent, snapshot.budget, snapshot.percentUtilized

interface BudgetSnapshot {
  spent: number;
  budget: number;
  percentUtilized: number;
}

const { plan, recompile } = useContextPlan();

const { tools, register, remove } = useToolRegistry();

const { balance, send, history } = usePayments();

const { identity, isVerified } = useAgentIdentity();

const { score, history } = useAgentReputation();

const { importSkills, translateSession } = useOpenClawBridge();

interface FrameworkAdapter<TImport, TExport> {
  readonly name: string;
  readonly framework: string;
  readonly frameworkVersion: string;
  importAgent(config: TImport): ImportResult;
  exportAgent(definition: AgentDefinition): ExportResult<TExport>;
  importTool(toolDef: unknown): ToolContract;
}

import { OpenAIAgentsAdapter } from '@veridex/agents-adapters';
 
const adapter = new OpenAIAgentsAdapter();
 
// Import an OpenAI agent config into Veridex
const { definition, warnings } = adapter.importAgent({
  name: 'My OpenAI Agent',
  instructions: 'Help users with billing.',
  model: 'gpt-4o',
  tools: [{ type: 'function', function: { name: 'lookup', ... } }],
});
 
// Export a Veridex definition back to OpenAI format
const { config, warnings: exportWarnings } = adapter.exportAgent(myAgent.definition);

import { LangGraphAdapter } from '@veridex/agents-adapters';
 
const adapter = new LangGraphAdapter();
const { definition } = adapter.importAgent(langGraphConfig);

import { PydanticAIAdapter } from '@veridex/agents-adapters';
 
const adapter = new PydanticAIAdapter();
const { definition } = adapter.importAgent(pydanticAIConfig);

import { OpenAPIImporter } from '@veridex/agents-adapters';
 
const importer = new OpenAPIImporter();
const tools = importer.importTools(openAPISpec, {
  baseUrl: 'https://api.example.com',
  auth: { type: 'bearer', value: process.env.API_TOKEN },
});
 
// Each path+method becomes a ToolContract

interface OpenAPIImportOptions {
  baseUrl?: string;
  auth?: { type: 'bearer' | 'api-key'; value: string };
  toolNameTransform?: (path: string, method: string) => string;
}

import { OpenAIRuntimeBridge, LangGraphRuntimeBridge, PydanticAIRuntimeBridge } from '@veridex/agents-adapters';
 
const bridge = new OpenAIRuntimeBridge({
  name: 'billing-assistant',
  endpoint: 'https://api.openai.com/v1/agents/asst_xxx',
  apiKey: process.env.OPENAI_API_KEY,
});
 
// Use as a Veridex tool
const tool = bridge.asTool({ name: 'ask_billing_agent' });
 
// Use as a handoff target
const handoff = bridge.asHandoffHandler();
 
// Or invoke directly
const result = await bridge.invoke({
  prompt: 'What is the refund policy?',
  context: { customerId: 'C-123' },
});

interface ExecutableAgentBridge {
  readonly name: string;
  invoke(input: BridgeInvocation): Promise<BridgeInvocationResult>;
  asTool(options?: BridgeToolOptions): ToolContract;
  asHandoffHandler(): HandoffHandler;
}
 
interface BridgeInvocation {
  prompt: string;
  history?: unknown[];
  context?: Record<string, unknown>;
  threadId?: string;
  signal?: AbortSignal;
}
 
interface BridgeInvocationResult {
  success: boolean;
  output: string;
  error?: string;
  metadata?: Record<string, unknown>;
}

import { parseWorkspaceContextFiles, compileContextSections } from '@veridex/agents-openclaw';
 
const files = {
  'AGENTS.md': agentsMdContent,
  'IDENTITY.md': identityMdContent,
  'TOOLS.md': toolsMdContent,
};
 
const contextFiles = parseWorkspaceContextFiles(files);
const compiled = compileContextSections(contextFiles);
// compiled is Record<string, string> keyed by context type

type ContextFileType =
  | 'AGENTS' | 'BOOTSTRAP' | 'HEARTBEAT' | 'IDENTITY'
  | 'MEMORY' | 'USER' | 'SOUL' | 'TOOLS' | 'RULES' | 'KNOWLEDGE';

import { parseSkillDocument, importSkillDocument, importSkillManifest } from '@veridex/agents-openclaw';
 
// Parse a SKILL.md file
const doc = parseSkillDocument('web-search/SKILL.md', skillMdContent);
// doc.frontmatter — parsed YAML frontmatter
// doc.instructions — the markdown body
// doc.frontmatter.tools — skill definitions
 
// Import into a Veridex tool contract
const { tool, warnings } = importSkillDocument(doc);
 
// Import a full manifest of skills
const { tools, warnings: allWarnings } = importSkillManifest(manifest);

interface OpenClawSkill {
  id: string;
  name: string;
  description?: string;
  inputSchema?: Record<string, unknown>;
  outputSchema?: Record<string, unknown>;
  tags?: string[];
  mutates?: boolean;
  requiresNetwork?: boolean;
  requiresApproval?: boolean;
  timeoutSeconds?: number;
}
 
interface SkillImportResult {
  tool: ToolContract;
  warnings: string[];
}

import { toACPAgentCard, fromACPCapabilities, createRemoteAgentTool } from '@veridex/agents-openclaw';
 
// Export your agent as an ACP card
const card = toACPAgentCard(agent.definition);
 
// Import another agent's ACP capabilities as Veridex tools
const tools = fromACPCapabilities(remoteCard.capabilities);
 
// Create a tool that calls a remote ACP agent
const remoteTool = createRemoteAgentTool({
  name: 'research-agent',
  description: 'Performs deep research',
  endpoint: 'https://agents.example.com/research',
  auth: { type: 'bearer', token: process.env.RESEARCH_AGENT_TOKEN },
  timeoutMs: 30_000,
});

interface ACPAgentCard {
  name: string;
  description: string;
  version?: string;
  capabilities: ACPCapability[];
  endpoint?: string;
  metadata?: Record<string, unknown>;
}
 
interface ACPCapability {
  name: string;
  description: string;
  inputSchema?: Record<string, unknown>;
  outputSchema?: Record<string, unknown>;
  tags?: string[];
}
 
interface RemoteAgentConfig {
  name: string;
  description: string;
  endpoint: string;
  auth?: { type: 'bearer' | 'api-key' | 'none'; token?: string; headerName?: string };
  capabilities?: ACPCapability[];
  timeoutMs?: number;
  invoker?: ACPInvoker;
}

import { translateSession, translateSessions, translateEvent } from '@veridex/agents-openclaw';
 
const result = translateSession(openClawSession);
// result.events — Veridex-format trace events
// result.warnings — any translation issues
 
// Batch translate
const results = translateSessions(openClawSessions);

import { PolicyPackManager } from '@veridex/agents-control-plane';
 
const manager = new PolicyPackManager();
 
// Create a policy pack
const pack = manager.create({
  name: 'production-safety',
  description: 'Standard safety rules for production agents',
  version: '1.0.0',
  rules: [
    { type: 'block_safety_class', params: { classes: ['destructive', 'privileged'] }, enabled: true },
    { type: 'max_spend', params: { limitUSD: 100 }, enabled: true },
    { type: 'require_approval', params: { classes: ['financial'] }, enabled: true },
  ],
  tags: ['production', 'safety'],
});
 
// List, update, delete
const packs = manager.list(['production']);
manager.update(pack.id, { version: '1.1.0' });
manager.delete(pack.id);
 
// System packs are immutable
manager.registerSystemPack({ name: 'core-safety', ... });
 
// Snapshot and restore
const snapshot = manager.snapshot();
manager.load(snapshot);

interface PolicyPack {
  id: string;
  name: string;
  description: string;
  version: string;
  rules: PolicyRuleDefinition[];
  tags?: string[];
  immutable?: boolean;
  createdAt: number;
  updatedAt: number;
}
 
interface PolicyRuleDefinition {
  type: string;
  params: Record<string, unknown>;
  enabled: boolean;
  description?: string;
}

import { TraceStore, InMemoryTraceStore } from '@veridex/agents-control-plane';
 
const store = new TraceStore(new InMemoryTraceStore());
 
// Ingest a trace
const record = await store.ingest({
  runId: 'run-001',
  agentId: 'ops-agent',
  tenantId: 'tenant-acme',
  startedAt: Date.now() - 5000,
  completedAt: Date.now(),
  state: 'completed',
  turnCount: 3,
  totalTokens: 1500,
  totalCostUSD: 0.02,
  events: traceEvents,
});
 
// Query traces
const traces = await store.query({
  agentId: 'ops-agent',
  state: 'completed',
  startAfter: Date.now() - 86_400_000, // last 24h
  limit: 50,
});
 
// Verify content hash (tamper detection)
const valid = await store.verify(record.id);
 
// Purge expired traces
const purged = await store.purgeExpired();

interface TraceRecord {
  id: string;
  runId: string;
  agentId: string;
  tenantId?: string;
  startedAt: number;
  completedAt?: number;
  state: 'completed' | 'failed' | 'cancelled';
  turnCount: number;
  totalTokens: number;
  totalCostUSD?: number;
  events: unknown[];
  contentHash?: string;
  metadata?: Record<string, unknown>;
}
 
interface TraceQuery {
  runId?: string;
  agentId?: string;
  tenantId?: string;
  state?: TraceRecord['state'];
  startAfter?: number;
  startBefore?: number;
  limit?: number;
  offset?: number;
}

import { ApprovalWorkflowEngine } from '@veridex/agents-control-plane';
 
const engine = new ApprovalWorkflowEngine();
 
// Register a workflow
engine.registerWorkflow({
  id: 'high-risk',
  name: 'High Risk Approval',
  description: 'Two-step escalation for high-risk actions',
  escalationChain: [
    { name: 'Team Lead', approvers: ['lead@company.com'], timeoutSeconds: 300, minApprovals: 1 },
    { name: 'VP Engineering', approvers: ['vp@company.com'], timeoutSeconds: 600, minApprovals: 1 },
  ],
  defaultMode: 'block',
});
 
// Start an approval
const approval = engine.startApproval('high-risk', 'run-001', 'agent-x', 'Transfer $10K', 0.9);
 
// Vote
engine.vote(approval.id, 'lead@company.com', true, 'Looks correct');
 
// Process timeouts (call periodically)
const timedOut = engine.processTimeouts();

interface ApprovalWorkflow {
  id: string;
  name: string;
  description: string;
  escalationChain: ApprovalEscalationStep[];
  autoApproveAfterSeconds?: number;
  defaultMode: 'block' | 'flag' | 'auto-approve';
}
 
interface ApprovalEscalationStep {
  name: string;
  approvers: string[];
  timeoutSeconds: number;
  minApprovals: number;
}
 
interface ActiveApproval {
  id: string;
  workflowId: string;
  currentStep: number;
  runId: string;
  agentId: string;
  proposal: string;
  riskScore: number;
  approvals: ApprovalVote[];
  createdAt: number;
  currentStepDeadline: number;
  resolution?: 'approved' | 'denied' | 'auto-approved' | 'escalated' | 'timed-out';
}

import { exportTraces, generateEvidenceBundle } from '@veridex/agents-control-plane';
 
// Export traces in JSON, JSONL, or CSV
const result = await exportTraces(traces, 'jsonl', {
  includeMetadata: true,
  startTime: Date.now() - 86_400_000,
  compress: false,
});
// result.data — the exported string
// result.contentHash — SHA-256 hash for verification
 
// Generate a tamper-evident evidence bundle
const bundle = await generateEvidenceBundle(
  traceId,
  policyDecisions,
  approvalDecisions,
);
// bundle.contentHash — combined hash of trace + policy + approvals

type ExportFormat = 'json' | 'jsonl' | 'csv';
 
interface AuditExportResult {
  format: ExportFormat;
  data: string | Buffer;
  contentHash: string;
  exportedAt: number;
}
 
interface EvidenceBundle {
  id: string;
  runId: string;
  version: string;
  traceHash: string;
  policyHash: string;
  approvalHash: string;
  contentHash: string;
  generatedAt: number;
  traceId: string;
  policyDecisions: unknown[];
  approvalDecisions: unknown[];
}

import { TenantManager } from '@veridex/agents-control-plane';
 
const tenants = new TenantManager();
 
const tenant = tenants.create({
  name: 'Acme Corp',
  config: {
    maxConcurrentRuns: 10,
    dailySpendLimitUSD: 500,
    allowedProviders: ['openai'],
    auditEnabled: true,
    traceRetentionDays: 90,
    deploymentMode: 'managed',
  },
});
 
// Update config
tenants.update(tenant.id, { dailySpendLimitUSD: 1000 });
 
// List all tenants
const all = tenants.list();

interface Tenant {
  id: string;
  name: string;
  status: 'active' | 'suspended' | 'pending';
  config: TenantConfig;
  metadata?: Record<string, unknown>;
  createdAt: number;
}
 
interface TenantConfig {
  maxConcurrentRuns?: number;
  dailySpendLimitUSD?: number;
  allowedProviders?: string[];
  auditEnabled?: boolean;
  traceRetentionDays?: number;
  deploymentMode?: 'local' | 'self-hosted' | 'private-cloud' | 'managed';
}

import { startControlPlaneServer } from '@veridex/agents-control-plane';
 
const server = await startControlPlaneServer({
  port: 4500,
  storageBackend: 'postgres',
  postgres: {
    connectionString: process.env.DATABASE_URL,
  },
  authRequired: true,
  bootstrapTokens: [
    { token: process.env.ADMIN_TOKEN, role: 'admin' },
  ],
  traceRetentionDays: 90,
});