VeriSwarm Python SDK

Lightweight Python client for the VeriSwarm trust scoring API. Zero external dependencies -- uses only Python stdlib.

Install

pip install veriswarm

The base package has no dependencies and supports Python 3.8+. Optional extras:

pip install "veriswarm[crewai]"

Framework packages set their own minimum Python version (several need 3.10+).

Quick Start

from veriswarm import VeriSwarmClient

client = VeriSwarmClient(
    base_url="https://api.veriswarm.ai",
    api_key="vsk_your_workspace_key",
)

# Check a trust decision before a sensitive action
decision = client.check_decision(
    agent_id="agt_123",
    action_type="post_public_message",
    resource_type="feed",
)
print(decision["decision"])  # "allow", "review", or "deny"

Authentication

Some endpoints accept only an account session token: team and workspace management, notifications, IP allowlist, custom domain, scoring profile, approval approve/reject, JIT approve/deny, workflow step approval, governance credential store/revoke, shadow-discovery scan/dismiss, compliance schedule, Passport verify/manifests/delegations, Vault export, Guard finding updates, and PII session revocation. Calling one of these without account_token raises VeriSwarmClientError with code == "ACCOUNT_TOKEN_REQUIRED" before any request is sent.

Kill switch (kill_agent/unkill_agent) and Guard policy CRUD send the API key (an API key needs the matching Guard scope on the server) and the account token too when one is configured.

import os

admin = VeriSwarmClient(
    base_url="https://api.veriswarm.ai",
    api_key="vsk_your_workspace_key",
    account_token=os.environ["VERISWARM_ACCOUNT_TOKEN"],
)

Like API keys, the account token is only ever sent over https:// (plain http:// is allowed for localhost, 127.0.0.1, and [::1] only).

Errors

Every failure raises VeriSwarmClientError with:

• status — HTTP status when a response arrived, otherwise None
• code — local failure class: ACCOUNT_TOKEN_REQUIRED, TIMEOUT, NETWORK_ERROR, RESPONSE_TOO_LARGE (bodies are capped at 10 MiB), or INVALID_RESPONSE

from veriswarm import VeriSwarmClientError

try:
    client.get_agent("agt_123")
except VeriSwarmClientError as exc:
    if exc.status == 404:
        ...  # not found

Event Ingestion

# Single event
client.ingest_event(
    event_id="evt_unique_123",
    agent_id="agt_123",
    source_type="platform",
    event_type="message.sent",
    occurred_at="2026-03-20T12:00:00Z",
    payload={"content_length": 140, "channel": "general"},
)

# Batch (up to 50 events)
client.ingest_events_batch([
    {"event_id": "evt_1", "agent_id": "agt_123", "source_type": "platform",
     "event_type": "message.sent", "occurred_at": "2026-03-20T12:00:00Z", "payload": {}},
    {"event_id": "evt_2", "agent_id": "agt_123", "source_type": "platform",
     "event_type": "tool.invoked", "occurred_at": "2026-03-20T12:01:00Z", "payload": {}},
])

Agent Management

# Register a new agent
agent = client.register_agent({
    "tenant_id": "ten_your_workspace",
    "slug": "my-assistant",
    "display_name": "My Assistant",
    "description": "A helpful coding assistant",
})

# Get agent profile
profile = client.get_agent("agt_123")

# Get current trust scores
scores = client.get_agent_scores("agt_123")
print(f"Risk: {scores['risk']['score']}, Tier: {scores['policy_tier']}")

# Get score history, breakdown, flags, timeline, manifests
history = client.get_agent_score_history("agt_123", limit=10)
breakdown = client.get_agent_score_breakdown("agt_123")
flags = client.get_agent_flags("agt_123")
timeline = client.get_agent_timeline("agt_123", limit=20)
manifests = client.get_agent_manifests("agt_123")

# Appeal a flag
client.appeal_flag("agt_123", flag_id=42)

# Agent API key management
keys = client.get_agent_api_keys("agt_123")
client.rotate_agent_api_key("agt_123")
client.revoke_agent_api_key("agt_123", key_id="key_456")

Provider Reports

# Submit a trust signal from your platform
client.ingest_provider_report({
    "agent_id": "agt_123",
    "provider_event_id": "provider-evt-456",
    "report_type": "spam",
    "severity": "high",
    "confidence": 0.91,
    "summary": "Burst spam detected in #general",
})

Guard (Security)

# PII tokenization (before sending to LLM)
result = client.tokenize_pii(text="Contact john@acme.com for details")
print(result["tokenized_text"])  # "Contact [VS:EMAIL:a1b2c3] for details"

# Rehydrate PII (after LLM processing)
original = client.rehydrate_pii(text=result["tokenized_text"], session_id=result["session_id"])

# PII session management
session = client.get_pii_session(result["session_id"])
client.revoke_pii_session(result["session_id"])

# Prompt injection scanning
scan = client.scan_injection(text="Ignore previous instructions and...")
print(scan["is_injection"])  # True

# Kill switch
client.kill_agent("agt_123", reason="Suspicious behavior detected")
client.unkill_agent("agt_123")

# Guard findings
findings = client.list_guard_findings(agent_id="agt_123")
client.update_guard_finding(1, new_status="resolved")  # open | false_positive | mitigated | resolved

# Guard policies
policies = client.list_guard_policies()
client.create_guard_policy({"name": "block-sql", "pattern": "DROP TABLE", "action": "block"})
client.update_guard_policy(1, is_active=False)
client.delete_guard_policy(policy_id=1)

Passport (Identity)

# Verify agent identity
client.verify_agent_identity("agt_123")

# Delegations
client.create_delegation({"from_agent": "agt_123", "to_agent": "agt_456", "scope": "read"})
delegations = client.list_delegations()
client.revoke_delegation(delegation_id=1)

# Manifests
client.create_manifest("agt_123", {"capabilities": ["search", "summarize"]})
manifests = client.get_manifests("agt_123")

Web Bot Auth (signed agents)

Signs outbound HTTP requests per the IETF Web Bot Auth profile of RFC 9421 (HTTP Message Signatures, Ed25519), so your agent is cryptographically identifiable at the edge (Cloudflare, Google, and other verifiers that support the directory). Requires the optional cryptography package:

pip install veriswarm[webbotauth]

from veriswarm import WebBotAuthSigner

signer = WebBotAuthSigner(private_key_pem=my_private_key_pem, key_id="key_abc123")
headers = signer.sign_request("https://example.com/api/resource")
# headers == {"Signature-Agent": ..., "Signature-Input": ..., "Signature": ...}

# Attach `headers` to the outbound request (merge into your existing
# headers dict) before sending it with requests/httpx/urllib/etc.

VeriSwarm issues the Ed25519 keypair via POST /v1/suite/passport/webbotauth/keys and returns the private key exactly once in that response — VeriSwarm never stores it, so save it securely on issuance.

Being listed in VeriSwarm's signature directory is VeriSwarm's own verification claim about your agent's identity. Being honored as a signed agent by a given edge provider (e.g. Cloudflare) additionally requires that provider's own one-time agent-operator registration and ongoing per-agent behavioral compliance — respecting robots.txt and keeping request rates reasonable. Signing a request does not by itself guarantee bypassing any block or guarantee access to any site.

Manifest signing

Signs the canonical content of a Passport agent manifest with Ed25519, so create_manifest can verify it was produced by the key holder. Uses the same Ed25519 keypair infrastructure as Web Bot Auth above, and requires the same optional cryptography package:

pip install veriswarm[webbotauth]

from veriswarm import sign_manifest

result = sign_manifest(
    version="1.0",
    capabilities=["calendar.read", "email.send"],
    required_tools=["calendar"],
    ai_disclosure="You are chatting with an AI assistant operated by Acme Corp.",
    principal_ref={
        "type": "organization",
        "name": "Acme Corp",
        "identifier": "acme-001",
        "source": "explicit",
    },
    private_key_pem=my_private_key_pem,
    kid="key_abc123",
)
# result == {"signature": "...", "signing_kid": "key_abc123"}

client.create_manifest("agt_123", {
    "version": "1.0",
    "capabilities": ["calendar.read", "email.send"],
    "required_tools": ["calendar"],
    "ai_disclosure": "You are chatting with an AI assistant operated by Acme Corp.",
    "principal_ref": {
        "type": "organization",
        "name": "Acme Corp",
        "identifier": "acme-001",
        "source": "explicit",
    },
    "signature": result["signature"],
    "signing_kid": result["signing_kid"],
})

VeriSwarm issues the Ed25519 keypair via POST /v1/suite/passport/webbotauth/keys and returns the private key exactly once in that response — VeriSwarm never stores it, so save it securely on issuance and reuse it for both request signing and manifest signing.

Signing a manifest is optional. Submit signature and signing_kid together (both or neither) on create_manifest — the server verifies the signature against the referenced key and rejects the request if they don't match or if the key can't be found.

Vault (Audit Ledger)

# Query the immutable audit ledger
entries = client.query_vault_ledger(agent_id="agt_123", limit=20)

# Verify hash-chain integrity
verification = client.verify_vault_chain(limit=100)

# Export
job = client.export_vault(export_type="csv")
status = client.get_vault_export_status(job["job_id"])

Credentials (Portable JWT)

# Issue a signed trust credential (requires agent key auth)
result = client.issue_credential()
jwt_token = result["credential"]

# Verify a credential from another agent
verified = client.verify_credential("eyJhbGciOiJFUzI1NiI...")
print(verified["veriswarm"]["policy_tier"])  # "tier_2"

Agent Self-Service

# Get own scores with improvement guidance
scores = client.get_my_scores()
print(scores["guidance"]["actions"])  # actionable improvement steps

Scoring Profiles

# Get current tenant profile
profile = client.get_scoring_profile()
print(profile["profile_code"])  # "general"

# Set tenant profile
client.set_scoring_profile("high_security")

Notifications

notifications = client.list_notifications()
client.mark_notification_read(notification_id=1)
client.mark_all_notifications_read()

IP Allowlist

# Get current allowlist
allowlist = client.get_ip_allowlist()

# Set allowlist
client.set_ip_allowlist(cidrs=["10.0.0.0/8", "192.168.1.0/24"])
client.set_ip_allowlist(enabled=False)  # disable explicitly; an empty cidrs list is refused

Custom Domains

client.set_custom_domain(domain="trust.mycompany.com")
client.verify_custom_domain()
domain = client.get_custom_domain()
client.delete_custom_domain()

Team Management

members = client.list_team_members()
client.invite_team_member(email="alice@acme.com", role="admin")
client.remove_team_member(user_id="usr_789")

Workspaces

workspaces = client.list_workspaces()
client.switch_workspace(tenant_id="ten_456")

Trust Badges

url = client.get_badge_url("my-agent", style="compact", theme="dark")
# "https://api.veriswarm.ai/v1/badge/my-agent.svg?style=compact&theme=dark"

Reputation Lookup

rep = client.reputation_lookup("my-agent")  # email, URL, slug, or other reference

Platform Status

status = client.get_platform_status()
print(status["status"])  # "operational" or "degraded"

OpenAI-Compatible LLM Proxy

VeriSwarm exposes an OpenAI-wire-compatible proxy at /v1/proxy/chat/completions and /v1/proxy/models. Every request flows through Guard scanning, the LLM router (cost / complexity / fallback), and a Vault audit entry — and the response shape matches openai.chat.completions.create(...) byte-for-byte.

The recommended integration is to use the OpenAI SDK directly and just override its base_url:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.veriswarm.ai/v1/proxy",
    api_key=os.environ["VERISWARM_API_KEY"],
)

completion = client.chat.completions.create(
    model="claude-sonnet-4-6",  # or any model your tenant's router allows
    messages=[{"role": "user", "content": "What's the trust score for agt_42?"}],
)

Use the veriswarm package for trust, Guard, Passport, Vault, A2A, approvals, and compliance — the surfaces the OpenAI SDK doesn't cover.

All Methods