Guide · Python
Vigil Python SDK & runtime protection guide
Integrate Vigil into a Python AI agent in about five minutes to stop prompt injections, data leaks and unsafe tool calls before they execute.
What is Vigil?
Vigil is an independent runtime control plane for AI agents and LLM applications. Your code sends prompts, retrieved documents and outputs to Vigil, receives an allow, flag or block verdict, and enforces it before the model or any tool runs.
Prerequisites
- Python 3.9 or newer with
aiohttp - An agent API key from your Vigil dashboard, stored in
VIGIL_API_KEY
pip install aiohttp
export VIGIL_API_KEY="trism_live_..." # per-agent key from your dashboardStep 1: Pre-flight scan (fail closed)
Timeouts, network errors, unexpected HTTP statuses and unknown verdicts all stop the agent — it never runs unprotected.
import asyncio
import os
import aiohttp
ENDPOINT = "https://vigiltrism.ai/api/public/v1/scan"
class SecurityViolationError(RuntimeError):
"""Blocked, or no valid verdict: the agent must not continue."""
async def verify_agent_input(user_prompt: str) -> dict:
# The API key identifies the agent - no agent_id field is needed.
headers = {
"Authorization": f"Bearer {os.environ['VIGIL_API_KEY']}",
"Content-Type": "application/json",
}
try:
timeout = aiohttp.ClientTimeout(total=10)
async with aiohttp.ClientSession(timeout=timeout) as session:
async with session.post(ENDPOINT, json={"input": user_prompt}, headers=headers) as response:
if response.status != 200:
# Fail closed. Do not log the body: it may contain sensitive data.
raise SecurityViolationError(f"Vigil check failed (HTTP {response.status})")
result = await response.json()
except (aiohttp.ClientError, asyncio.TimeoutError, ValueError) as error:
raise SecurityViolationError("Vigil unavailable; execution halted") from error
if not isinstance(result, dict) or result.get("decision") not in ("allow", "flag", "block"):
raise SecurityViolationError("Invalid Vigil verdict; execution halted")
return resultStep 2: Enforce the decision
async def run_agent_workflow(user_prompt: str) -> str:
try:
# 1. Pre-flight security check
result = await verify_agent_input(user_prompt)
except SecurityViolationError:
return "I'm sorry, I cannot process this request right now."
# 2. Strict decision enforcement
if result["decision"] == "block":
reasons = [v.get("message") for v in result.get("violations", []) if isinstance(v, dict)]
print("[SECURITY ALERT] Blocked by Vigil:", "; ".join(filter(None, reasons)) or "policy violation")
return "I'm sorry, but I cannot process this request due to security policies."
# 3. Continue with the redacted input when one is returned
safe_input = result.get("redacted_input") or user_prompt
return await execute_llm_and_tools(safe_input)Step 3: Check the output and tools
The full client adds retrieved-document scanning and a post-execution check on /executions with output redaction. Check planned tool calls before invoking them — a trace recorded afterwards cannot undo an action.
Get an API key
Register an agent on the free Starter plan, or try detection first in the free scanner.
Create a free account →