agenizai-sdk 2.5.0

Zero-trust ML Risk Oracle and Firewall for Algorand AI Agents

🛡️ Ageniz SDK

The Zero-Trust ML Risk Oracle and Firewall for Algorand AI Agents.

Ageniz is a developer-first security protocol that prevents AI Agents (like trading bots or autonomous assistants) from draining wallets through hallucinations, prompt injections, or malicious intent.

By routing all agent transactions through an off-chain Machine Learning Oracle and validating them on-chain via an immutable Smart Contract Vault, Ageniz provides enterprise-grade "Defense in Depth."

---

✨ Features

• ML Intent Scoring: Prevents prompt-injection attacks and anomalies before they reach the blockchain.
• Cryptographic Bait-and-Switch Protection: Recipient addresses and amounts are bound into the Oracle's Ed25519 signature.
• Replay Attack Immunity: Strict, timestamp-based Nonce tracking stored in Algorand Local State.
• 👻 Shadow Mode (New): Safely test the Oracle in production without gating payments to collect real-world training data.
• Automated x402 Routing: Seamlessly bundles security tolls and Vault payments into a single Atomic Transaction.

---

📦 Installation

pip install agenizai-sdk

---

🚀 Quickstart: Live Firewall Mode

1. Environment Setup

Create a .env file in your project root with your Algorand wallet details and Ageniz configuration:

# Your AI Agent's Wallet
DEPLOYER_MNEMONIC="your twenty five word algorand testnet mnemonic phrase goes here..."

# Ageniz Protocol Config
APP_ID=760267917
ORACLE_URL="https://ageniz-backend.onrender.com"

2. Execute a Protected Payment (pay())

In Live Firewall mode, the payment is strictly gated. The SDK automatically builds a 3-transaction Atomic Group (ABI Validation + Vendor Payment + Protocol Fee). If the ML Oracle flags the transaction, it never reaches the blockchain.

import os
from dotenv import load_dotenv
from ageniz_sdk.core import AgenizSDK

load_dotenv()

# 1. Initialize the Firewall
agent = AgenizSDK(
    wallet_mnemonic=os.getenv("DEPLOYER_MNEMONIC"),
    ageniz_api_key="your_developer_api_key",
    app_id=int(os.getenv("APP_ID")),
    oracle_url=os.getenv("ORACLE_URL")
)

# 2. Opt-in to the Vault (Required once per wallet for Nonce tracking)
agent.opt_in()

# 3. Execute a Protected Payment
print("Requesting payment authorization...")

result = agent.pay(
    recipient="YZ2L7MGFX35YUGVPB2YF3S4K3KQVNJ4BWYFIB3UVMJNQAPEME3MK7ME2DU",
    amount_algo=1.0,
    context="Paying external weather API for daily data fetch."
)

# 4. Handle the Verdict
if result["status"] == "SUCCESS":
    print(f"✅ Payment cleared firewall! TxID: {result['tx_id']}")
elif result["status"] == "BLOCKED":
    print(f"❌ Payment blocked by ML Oracle: {result['reason']}")

---

Shadow Mode: Observe & Train

For developers integrating Ageniz into an existing live agent, gating transactions immediately can be risky. Shadow Mode allows you to monitor your agent's behavior and see what Ageniz would have done, without actually blocking any payments.

Payment Clarification in Shadow Mode

When you use observe() instead of pay():

• No Atomic Group: The SDK submits a standard, direct Algorand PaymentTxn.
• No Gating: The transaction always executes on the blockchain, regardless of the ML verdict.
• No Fees/Custody: The Ageniz Smart Contract is bypassed entirely, and no protocol fees are charged.

Using observe()

result = agent.observe(
    recipient="YZ2L7MGFX35YUGVPB2YF3S4K3KQVNJ4BWYFIB3UVMJNQAPEME3MK7ME2DU",
    amount_algo=1.0,
    context="Testing weather API integration.",
    scenario_tag="beta_testing"
)

print(f"💸 Payment Executed! TxID: {result['tx_id']}")

# See what Ageniz WOULD have done:
print(f"Ageniz Verdict: {result['ageniz_verdict']}") 
if result['would_have_blocked']:
    print("⚠️ Warning: Ageniz would have blocked this transaction in Live Mode!")

# Save this ID to provide human feedback later
shadow_id = result["shadow_log_id"] 

🧠 Closing the Loop: Submitting Human Verdicts

Shadow Mode is designed for data collection and fine-tuning. Every observe() call logs the transaction details and the hypothetical ML verdict to the Ageniz database, returning a unique shadow_log_id.

Developers or human operators can later review these logs and submit a Human Verdict (LEGITIMATE, ATTACK, or AMBIGUOUS) to train the ML model on false positives/negatives.

You can submit ground-truth labels directly to the Ageniz REST API:

# Label a flagged transaction as a false positive (LEGITIMATE)
curl -X PATCH https://ageniz-backend.onrender.com/shadow/<shadow_log_id>/verdict \
  -H "Content-Type: application/json" \
  -d '{"human_verdict": "LEGITIMATE"}'

By running in Shadow Mode and labeling the data, you can build a perfectly tailored ML risk profile for your specific AI agent before switching your code to pay().

---

🔐 Architecture: The Non-Custodial Fortress

Ageniz does not rely solely on off-chain AI. It enforces security on-chain using an Atomic Verification Group.

When agent.pay() is called:

1. The SDK sends the request context to the Ageniz ML Oracle.
2. If deemed SAFE, the Oracle generates a cryptographic Ed25519 signature binding the exact (amount, recipient, nonce).
3. The SDK bundles this signature and the agent's payment into an Algorand Atomic Group.
4. The Ageniz Smart Contract (Txn 0) verifies the Oracle's signature via ed25519verify and peeks at the agent's payment (Txn 1) via Gtxn to ensure the amount and recipient were not tampered with. If the math matches, the payment executes trustlessly.

---

📊 Checking Agent Reputation

You can monitor your agent's standing with the protocol at any time:

status = agent.get_status()

print(f"Reputation Score : {status['reputation_score']}/100")
print(f"Velocity         : {status['velocity']} tx/hr")
print(f"Fee Tier         : {status['fee_tier']['tier']} ({status['fee_tier']['fee_pct']}%)")

---

📄 License

This project is licensed under the MIT License.