VeriSwarm Python SDK

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

Install

pip install veriswarm

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"

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(finding_id=1, updates={"status": "resolved"})

# Guard policies
policies = client.list_guard_policies()
client.create_guard_policy({"name": "block-sql", "pattern": "DROP TABLE", "action": "block"})
client.update_guard_policy(policy_id=1, updates={"enabled": 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"], enabled=True)

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(slug="my-agent")

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