01
Install
No package required — VeriSigil uses standard HTTP. Just add your API key.
Environment variable
# Add to your .env file VERISIGIL_API_KEY=your_api_key_here VERISIGIL_BASE_URL=https://verisigil-api-production.up.railway.app
Python — copy this class into your project
import requests, os class VeriSigilGuard: """ VeriSigil Runtime Guard — drop into any AI agent framework. Verifies identity, trust score, and policy before execution. """ def __init__(self, agent_id: str): self.agent_id = agent_id self.base_url = os.getenv("VERISIGIL_BASE_URL", "https://verisigil-api-production.up.railway.app") self.session = requests.Session() self.session.headers.update({ "x-api-key": os.getenv("VERISIGIL_API_KEY"), "Content-Type": "application/json" }) def verify(self, action_type: str, action_details: dict, resource: str) -> dict: """Call this before EVERY agent action. Returns decision dict.""" resp = self.session.post( f"{self.base_url}/v1/guard/verify", json={ "agent_id": self.agent_id, "action_type": action_type, "action_details": action_details, "resource": resource, "context": "production" }, timeout=10 ) return resp.json() def allow_or_raise(self, action_type: str, action_details: dict, resource: str): """Raises PermissionError if action is DENIED. Returns True if ALLOWED.""" result = self.verify(action_type, action_details, resource) if result["decision"] == "DENY": raise PermissionError(f"VeriSigil BLOCKED: {result['reason']}") if result["decision"] == "REQUIRE_HUMAN_APPROVAL": raise PermissionError(f"VeriSigil REQUIRES HUMAN APPROVAL: {result['reason']}") return True
02
Understand The Decisions
Every call returns one of three decisions in under 50ms.
ALLOW
Agent identity verified, trust score sufficient, action within policy. Proceed with execution.
REQUIRE_HUMAN_APPROVAL
Action is risky or exceeds policy threshold. A human must approve before execution continues.
DENY
Agent is revoked, expired, cloned, or below trust threshold. Block immediately.
Example response
{
"decision": "REQUIRE_HUMAN_APPROVAL",
"confidence": 0.94,
"reason": "Payment $5000 exceeds auto-allow threshold",
"agent_id": "vsa_1483d06a89c4",
"trust_score": 0.97,
"trust_level": "TRUSTED",
"execution_id": "exec_41c7f9d7",
"latency_ms": 41.2
}
03
Supported Action Types
Pass the action type that matches what your agent is about to do.
payment
Financial transactions — auto-blocked above $1,000 threshold
data_access
Database reads/writes — PII access requires GDPR certification
tool_use
Tool execution — blocks eval, exec, shell, file_delete automatically
api_call
External API calls — domain allowlist and rate policy enforced
send_email
Outbound communication — bulk sends require human approval
delete_records
Destructive operations — always escalated for critical risk
04
Framework Integrations
Copy the snippet for your framework and paste it into your agent code.
LangChain — wrap your AgentExecutor
from langchain.agents import AgentExecutor, create_openai_tools_agent from verisigil import VeriSigilGuard # paste the class above # Initialize guard with your agent's passport ID guard = VeriSigilGuard(agent_id="vsa_your_agent_id") # Wrap any tool call with the guard def guarded_tool_call(tool_name: str, tool_input: dict): # Verify BEFORE executing the tool guard.allow_or_raise( action_type="tool_use", action_details={"tool_name": tool_name, "input": tool_input}, resource=tool_name ) # If no exception raised — proceed with execution return tool_name.invoke(tool_input) # Example: payment tool def process_payment(amount_usd: float, recipient: str): guard.allow_or_raise( action_type="payment", action_details={"amount_usd": amount_usd, "recipient": recipient}, resource="stripe_api" ) # Payment approved — execute return stripe.charge(amount_usd, recipient)
OpenAI Assistants — intercept function calls
import openai from verisigil import VeriSigilGuard client = openai.OpenAI() guard = VeriSigilGuard(agent_id="vsa_your_agent_id") def handle_tool_call(tool_call): # Map OpenAI function name to action type action_map = { "send_payment": "payment", "query_database": "data_access", "send_email": "send_email", "delete_record": "delete_records", } action_type = action_map.get(tool_call.function.name, "api_call") # Verify before executing result = guard.verify( action_type=action_type, action_details=tool_call.function.arguments, resource=tool_call.function.name ) if result["decision"] != "ALLOW": return {"error": result["reason"], "decision": result["decision"]} # Approved — execute the function return execute_function(tool_call)
CrewAI — guard agent tasks
from crewai import Agent, Task, Crew from verisigil import VeriSigilGuard guard = VeriSigilGuard(agent_id="vsa_your_agent_id") # Create a guarded tool wrapper def guarded_database_write(data: dict) -> str: """Write data to database — verified by VeriSigil first.""" guard.allow_or_raise( action_type="data_access", action_details={"contains_pii": False, "operation": "write"}, resource="production_database" ) # Verified — write to database return database_write(data) # Attach to your CrewAI agent as a tool finance_agent = Agent( role="Finance Analyst", goal="Process financial transactions safely", tools=[guarded_database_write], verbose=True )
AutoGen — intercept before code execution
import autogen from verisigil import VeriSigilGuard guard = VeriSigilGuard(agent_id="vsa_your_agent_id") class GuardedUserProxy(autogen.UserProxyAgent): """UserProxyAgent with VeriSigil Runtime Guard.""" def execute_code_blocks(self, code_blocks): # Verify before any code execution guard.allow_or_raise( action_type="tool_use", action_details={ "tool_name": "code_execution", "language": code_blocks[0][0] if code_blocks else "unknown" }, resource="code_executor" ) # Approved — execute normally return super().execute_code_blocks(code_blocks) # Use in your AutoGen workflow proxy = GuardedUserProxy(name="guarded_proxy")
Raw Python — works with any framework
import requests, os API_KEY = os.getenv("VERISIGIL_API_KEY") BASE_URL = "https://verisigil-api-production.up.railway.app" def verify_before_execution(agent_id, action_type, action_details, resource): resp = requests.post( f"{BASE_URL}/v1/guard/verify", headers={"x-api-key": API_KEY, "Content-Type": "application/json"}, json={ "agent_id": agent_id, "action_type": action_type, "action_details": action_details, "resource": resource, "context": "production" }, timeout=10 ) return resp.json() # Usage example result = verify_before_execution( agent_id="vsa_your_agent_id", action_type="payment", action_details={"amount_usd": 5000, "recipient": "vendor@company.com"}, resource="stripe_api" ) if result["decision"] == "ALLOW": execute_payment() elif result["decision"] == "REQUIRE_HUMAN_APPROVAL": notify_human(result["reason"]) else: block_and_log(result["reason"])
05
API Reference
All endpoints. Base URL: verisigil-api-production.up.railway.app
| Endpoint | Method | Auth | Description |
|---|---|---|---|
| /v1/guard/verify | POST | API KEY | Runtime Guard — verify action before execution. Returns ALLOW/DENY/REQUIRE_HUMAN_APPROVAL. |
| /v1/action/evaluate | POST | API KEY | Evaluate agent action with EU AI Act Article 14 enforcement. |
| /v1/passport/issue | POST | API KEY | Issue a cryptographic Ed25519 passport for a new AI agent. |
| /verify/{agent_id} | GET | PUBLIC | Verify agent identity and get live trust score. |
| /v1/passport/{id}/audit | GET | PUBLIC | Get cryptographically signed audit log for any agent. |
| /v1/scan | POST | PUBLIC | Free security scanner — check agent config for vulnerabilities. |
| /v1/verifier/register | POST | PUBLIC | Register as a verifier and get your verifier API key. |
Full interactive docs → Test every endpoint live at
verisigil-api-production.up.railway.app/docs
Ready to integrate?
Get your API key, issue your first agent passport, and add Runtime Guard in 15 minutes.