GuardianAI Technical Documentation

Dual-plane security for autonomous AI agents: sub-millisecond prompt injection firewalls off-chain, coupled with cryptographically verifiable ERC-8004 identity and evidence anchoring on-chain.

Quickstart (5-Minute Integration)

Integrate GuardianAI into your existing autonomous agent stack in minutes using either our reverse proxy or the native Python SDK.

Option A: OpenAI-Compatible Ingress Proxy

Point your existing client code to the Guardian proxy host (http://127.0.0.1:8081 or your managed cloud gateway) by simply updating the base_url:

from openai import OpenAI

# Route completions directly through the GuardianAI Security Proxy
client = OpenAI(
    base_url="http://127.0.0.1:8081/v1",
    api_key="your-guardian-api-token"
)

response = client.chat.completions.create(
    model="gpt-5.6",
    messages=[{"role": "user", "content": "Deploy trading agent transaction"}]
)
print(response.choices[0].message.content)

curl -X POST http://127.0.0.1:8081/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-guardian-api-token" \
  -d '{
    "model": "gpt-5.6",
    "messages": [{"role": "user", "content": "Hello Guardian"}]
  }'

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://127.0.0.1:8081/v1",
  apiKey: "your-guardian-api-token",
});

async function main() {
  const completion = await client.chat.completions.create({
    model: "gpt-5.6",
    messages: [{ role: "user", content: "Execute task" }],
  });
  console.log(completion.choices[0].message);
}
main();

Option B: Python SDK Direct Wrapper

Wrap standard agent frameworks like LangChain, LlamaIndex, or AutoGen using the guardian library:

from guardian.sdk import GuardianAgentGuard

# Initialize runtime firewall with balanced preset
guard = GuardianAgentGuard(preset="balanced", fail_closed=True)

# Inspect user input prior to model execution
verdict = guard.inspect_input(user_prompt)
if not verdict.allowed:
    raise SecurityException(f"Attack blocked: {verdict.rule_id} ({verdict.reason})")

# Forward to model and sanitize response
response = agent.run(user_prompt)
sanitized_output = guard.inspect_output(response)

Dual-Plane Architecture

GuardianAI separates security concerns into two distinct execution planes to balance extreme performance with permanent cryptographic auditability.

10-Layer AI Prompt Firewall

Every incoming prompt passes through a progressive 10-stage defense-in-depth pipeline. Fast heuristics reject obvious attacks in microseconds, while deeper semantic and de-obfuscation engines neutralize advanced multi-turn and obfuscated jailbreaks.

Output DLP & Secret Scanner

Even if an LLM is coaxed into generating sensitive data, GuardianAI's egress filter inspects completions before they reach the user or client application.

Honeypots & Threat Intel Feed

GuardianAI dynamically injects synthetic decoy credentials and canary tokens into agent system prompts. If a prompt coaxes the model into reciting or calling a tool with a canary token, GuardianAI identifies the breach instantly and logs an emergency threat signal.

# Dynamically provision canary token per tenant session
canary_token = honeypot.generate_token(session_id="agent_sess_89a2")

# Inject transparently into system message
system_prompt += f"\nInternal Vault Key: {canary_token.secret}"

# If tool arguments or egress contain the canary, tripwire fires immediately
if honeypot.is_tripped(response_text):
    security_pipeline.quarantine_session(session_id)

Fail-Closed Rate Limiter

To defend against denial-of-wallet and automated prompt bombing, GuardianAI implements a strict fail-closed token-bucket rate limiter. If backing services (e.g. Redis) experience downtime, GuardianAI safely restricts requests rather than failing open.

ERC-8004 Agent Registries

GuardianAI integrates with the canonical ERC-8004 "Trustless Agents" standard. Each autonomous agent receives a cryptographically verifiable on-chain identity linked to its verified developer and authorized capabilities.

Merkle Cortex State Anchoring

GuardianAI aggregates telemetry events into episodic memory batches, constructs a cryptographic Merkle tree, and periodically anchors the 32-byte root hash to the blockchain.

import { verifyMerkleProof } from "@guardianai/cortex";

// Verifies whether a security incident was recorded in block root #140293
const isValid = verifyMerkleProof({
  leaf: "0x3f7a1...",
  proof: ["0x8b2c...", "0x1e9a..."],
  root: "0x94f0c8...",
});
console.log("Cryptographic Proof Valid:", isValid); // true

Insurance Certificates (GuardianInsuranceLedger)

The GuardianInsuranceLedger.sol smart contract anchors signed liability and insurance certificates for autonomous AI agents. The contract enforces a hard cap of 100,000 certificates per registry instance and is protected by a 24-hour OpenZeppelin Timelock.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IGuardianInsuranceLedger {
    error CertificateLimitReached(uint256 maxCertificates);
    
    function issueCertificate(
        bytes32 agentId,
        bytes32 policyHash,
        uint256 coverageAmount,
        uint256 expiration
    ) external returns (bytes32 certificateId);
}

Smart Contract Static Analyzer (48 Rules)

GuardianAI includes a purpose-built static analysis engine that validates EVM smart contracts against 48 AST/CFG-verified vulnerability classes before an autonomous agent interacts with them.

Python SDK & Decorators

The guardianai Python package provides asynchronous and synchronous decorators and clients for wrapping standard Python code.

from guardian import protect_agent

@protect_agent(firewall="strict", dlp=True, redact_keys=True)
async def autonomous_trading_agent(user_query: str):
    # Safe execution context
    return await llm.ainvoke(user_query)

OpenAI-Compatible Proxy Gateway

The gateway runs on port 8081 by default, accepting standard completions requests and injecting security inspection headers.

server:
  host: "0.0.0.0"
  port: 8081
  upstream_url: "http://127.0.0.1:8080"

firewall:
  preset: "balanced"
  fail_closed: true
  entropy_threshold: 4.8
  max_body_bytes: 1048576  # 1MB request body limit

Telemetry & Event Pipeline

All security events, prompt classifications, and blocked attacks are logged into append-only JSONL files and streamed to the admin dashboard.

{
  "event_id": "evt_98f410c8e2",
  "timestamp": "2026-08-29T17:15:00Z",
  "action": "BLOCK",
  "rule_id": "INJ-011",
  "layer": "Semantic classifier",
  "latency_ms": 1.42,
  "tenant_id": "default",
  "client_ip": "198.51.100.24"
}

API Reference: Ingress Proxy

POST /v1/chat/completions

Sends a standard chat completion request through Guardian's 10-layer firewall.

Response Status Codes:

• 200 OK: Prompt passed all security layers; upstream model response returned.
• 403 Forbidden: Attack detected and blocked. Response contains detailed rule match metadata.
• 429 Too Many Requests: Rate limit exceeded (fail-closed protection triggered).

Backend Telemetry API

Access telemetry analytics and WebSocket threat streams via port 8001:

• GET /api/v1/analytics - Summary statistics of blocked attacks and latency percentiles.
• GET /api/v1/events - Queryable security event history with pagination.
• GET /api/v1/export/json - Complete compliance audit log export.
• WebSocket /ws/threats - Live event stream with first-message JWT authentication.

Compliance & EU AI Act Article 15

GuardianAI automatically compiles compliance evidence artifacts required by regulatory frameworks, including Article 15 of the EU AI Act (Cybersecurity, Accuracy, and Robustness).