Architecture

System Overview

flowchart LR
  A[Agent / Platform Client] --> B[API Gateway]
  B --> C[Registration Service]
  B --> D[Event Ingestion Service]
  D --> E[Event Store - Postgres]
  D --> F[Queue / Worker]
  F --> G[Gate Scoring Engine]
  F --> H[Rule Engine]
  G --> I[Score Snapshots]
  H --> J[Moderation Flags]
  G --> K[Policy Tier Calculator]
  H --> K
  K --> L[Decision API]
  E --> M[Audit Timeline API]
  I --> N[Admin Dashboard]
  J --> N
  M --> N
  L --> N

Services

SaaS Control Plane

Hosted by VeriSwarm: Gate scoring engine, policy decisions, moderation/audit dashboard.

Customer-hosted: Agent runtimes, optional event forwarders/connectors.

API Gateway

Auth, request validation, routing, and rate limiting.

Registration Service

Agent profile CRUD, sponsor/owner metadata, identity claims and verification state.

Event Ingestion

Receives signed events, validates against schema, deduplicates via event ID, persists raw and normalized forms, and enqueues scoring tasks.

Gate (Scoring Engine)

Computes Identity, Risk, and Reliability scores. Maintains Autonomy label as advisory output. Emits explanations and score deltas.

Rule Engine

Detects severe incidents, generates moderation flags, applies penalties and temporary restrictions.

Policy Tier Calculator

Derives tier from score state and critical rules. Generates allow/deny/review decisions by action type.

Dashboard

Agent list, score cards, event timeline, flag review, manual overrides, and Suite (Guard, Passport, Vault) management.

VeriSwarm Suite

Guard

Real-time enforcement and scanning for agent security. Pattern-based detection of sensitive data in event streams, PII tokenization (detect, replace with reversible [VS:TYPE:ID] tokens, rehydrate on demand), kill switch for immediate capability revocation, and a tool registry for approved tools and MCP servers.

Guard Proxy

A transparent MCP proxy that sits between agents and upstream MCP tool servers. Every tool call passes through Guard Proxy, which applies PII filtering, policy enforcement, prompt-injection scanning, and audit logging before forwarding requests to the destination server. Three deployment modes are available: cloud-hosted (managed by VeriSwarm), Docker (self-hosted container), and local (run directly on the agent host).

Passport

Verified identity and delegation for trusted agents. Identity verification ("blue checkmark"), signed capability manifests, and fine-grained user-to-agent permission grants.

Vault

Immutable audit trails and governance proof. Hash-chained append-only ledger, cryptographic integrity verification, and time-limited signed exports for compliance.

MCP Server

A thin translation layer exposing all 25 VeriSwarm API tools via the Model Context Protocol. Compatible with Claude Desktop, Cursor, and any MCP client. Contains no business logic — every tool call maps to a REST API request. See MCP Server docs for setup and tool details.

Event Taxonomy

22 standardized event types across six categories: tool usage (4), content (3), task execution (4), security (4), identity (5), and interaction (2). Legacy event types are automatically mapped to taxonomy equivalents for backward compatibility. See the Data Model for the full list.

Scoring Profiles

5 preset profiles customize which signals matter most: general, high_security, social_platform, developer_tools, marketplace. Each adjusts signal weights, composite trust weights, tier thresholds, and risk bands. Enterprise tenants can further customize weights via the API.

Portable Credentials

Agents can request signed JWT credentials (ES256, 1-hour TTL) containing their current trust scores. Any system can verify these by fetching the public key from /.well-known/jwks.json, enabling a trust network where agents carry credentials across platforms.

Data Flow

  1. Agent registers.
  2. Platform or agent posts signed events.
  3. Event is validated and stored.
  4. Worker recomputes affected score dimensions.
  5. Policy tier recalculates.
  6. Flags generated if thresholds trigger.
  7. Dashboard and Decision API reflect latest state.

Security

  • Signed event payload support
  • Separate auth for admin, platform, and agent keys
  • Immutable audit events
  • Role separation across admin, moderator, and operator
  • Rate limiting on all endpoints