vantio-agent-sdk · Vantio Optics (Python)

Vantio is the infrastructure control layer for autonomous AI. This package is Vantio Optics Observe for Python: record where the agent calls LLM APIs (host, size, process, trace) without storing prompts or completions. Optics is free. Optics does not block, redact, or cap spend on its own.

Optics helps you see. Phantom Engine is runtime protection on enrolled Linux — Observe, Enforce, and Control in one purchase, at $799/node/mo. Enterprise adds governance when you need proof and process on top — talk to sales. Continuous Assurance is how the suite stays true after install; it is not a separate product.

Optics (Free) · Phantom Engine ($799/node/mo) · Enterprise (talk to sales)

pip install vantio-agent-sdk

Prefixing vantio run python without this SDK does not intercept. Python support requires vantio-agent-sdk. Follow the current Python SDK example and verify that a supported outbound event appears before relying on the coverage state.

pip install vantio-agent-sdk
vantio run python agent.py

Optics: vantio.ai/optics · Pricing: vantio.ai/pricing · Docs: vantio.ai/docs

3.0.14 — packaging metadata only

This patch corrects PyPI project URLs and long-description product model: Optics (free), Phantom Engine ($799/node/mo — Observe, Enforce, and Control), Enterprise (talk to sales). Does not market any other standalone public SKU. SDK behavior is unchanged from 3.0.13.

v3.0.x — Breaking change from v2.x

v3.0.0+ is a complete rewrite. The old VantioSession / VANTIO_PROXY_ENDPOINT API is removed. The new API uses @shield (a decorator or async context manager) with zero dependencies and no proxy — observe runs inside your SDK, not through an external endpoint.

Migrate from v2.x:

# Old (v2.x) — remove this
from vantio.session import VantioSession
with VantioSession(agent_name="my-agent") as session: ...

# New (v3.x) — use this instead
from vantio import shield
@shield
async def run_agent(): ...
# or: async with shield() as ctx: ...

shield() — trace context

from vantio import shield, report_anomaly

# Decorator form
@shield
async def run_agent():
    result = await call_openai(prompt)
    return result

# Context manager form
async with shield() as ctx:
    print(f"Trace ID: {ctx.trace_id}")
    result = await run_agent()

get_current_trace_id()

Returns the active trace ID for the current async context, or None outside a shield() frame.

from vantio import shield, get_current_trace_id

async with shield() as ctx:
    trace_id = get_current_trace_id()  # same as ctx.trace_id

get_current_trace_id()  # None — outside shield() frame

fetch_policy() — policy retrieval

Fetches your tenant's governance policy from GET /api/v1/config. Fails open — if the control plane is unreachable, a permissive default policy is returned so your agent never stalls waiting for governance.

from vantio import fetch_policy, redact_pii
import os

policy = fetch_policy(os.environ["VANTIO_API_KEY"])

# Check enforcement flags
if policy.enforce:
    if "api.openai.com" in policy.blocked_hosts:
        raise RuntimeError("OpenAI is blocked by policy")

# Use with redact_pii for SDK-side PII scrubbing
if policy.pii_redact:
    result = redact_pii(user_input, policy.pii_types)
    prompt = result.text   # PII scrubbed before the LLM call

VantioPolicy fields:

redact_pii() — local PII scrubbing

Pure, side-effect-free local PII redaction using the same patterns as the CLI interceptor and @vantio/agent-sdk. No content leaves the process.

from vantio import redact_pii

result = redact_pii("Contact bob@example.com or call 555-123-4567")
# result.text       → "Contact [VANTIO_REDACTED:EMAIL] or call [VANTIO_REDACTED:PHONE]"
# result.redactions → ["email", "phone"]

Pass a custom pii_types list to control which categories are scanned (values are case-insensitive):

result = redact_pii(text, pii_types=["email", "ssn"])

Built-in categories: ssn, email, credit_card, phone.

RedactionResult fields:

report_anomaly() — cloud ingest

async with shield():
    await run_agent()
    await report_anomaly(
        target_host="api.openai.com",
        bytes_severed=14382,
        # Valid values: "OBSERVED" | "ALLOWED" | "REDACTED" | "BLOCKED_HOST" | "BLOCKED_SIZE" | "BLOCKED_SPEND"
        action_taken="BLOCKED_HOST",
    )

report_anomaly() must be called within a shield() context. It is a no-op unless VANTIO_CLOUD_INGEST=true. Non-fatal — never crashes the agent.

Environment variables

Anonymous telemetry (opt-out)

The SDK sends a single anonymous usage ping per process the first time shield() runs. It contains only aggregate, non-identifying metadata — a random anonymous id, the Python version, the OS string, and an event name. It never sends prompts, completions, API keys, emails, or any content/PII. Fire-and-forget on a daemon thread; never blocks.

export VANTIO_TELEMETRY_DISABLED=1   # or
export DO_NOT_TRACK=1

What gets captured

• Which LLM endpoint was called
• Response size in bytes
• Process ID and timestamp
• A trace ID linking calls in the same shield() / vantio run python wrap

What never gets captured: prompts, completions, or any content from your requests.

Zero dependencies

Core tracing requires only the Python standard library (contextvars, asyncio, hashlib, hmac, re). Cloud ingest and anonymous telemetry use urllib.request and threading. No aiohttp, no httpx, no requests.

MIT License · vantio.ai/optics · vantio.ai/phantom · vantio.ai/enterprise · vantio.ai/pricing · vantio.ai/docs