agentguard-python-sdk

AgentGuard: Secure Payment & Consent Middleware for AI Agents

AgentGuard is a production-grade cryptographic middleware that enables AI agents to perform autonomous on-chain payments and generate verifiable consent proofs. It provides a zero-trust bridge between AI agents and the Algorand blockchain.

---

⚡ The Problem: Key Vulnerability in AI Agents

AI Agents often need to handle money (micropayments) and user data (consent). If you give an agent a private key, you risk:

1. Key Theft: The agent's memory or logs leaking the seed.
2. Unintended Spending: The agent's LLM "hallucinating" a purchase.
3. Non-Compliance: No audit trail of why a payment was made (violating DPDP standards).

🛡️ The Solution: AgentGuard Architecture

AgentGuard solves this using a Vaulted Delegation architecture:

• Hardened Vault (MCP): Your sensitive keys stay in a secure isolated server.
• Verifiable Consent: The SDK signs a cryptographic intent (Purpose + Amount + ID) which the Vault verifies before signing a blockchain transaction.
• Zero-Trust: The Backend never sees your keys; it only relays signed instructions.

---

📦 Installation

pip install agentguard-python-sdk

---

🚀 Quick Start (Request Signing)

AgentGuard uses dual-identity cryptography. Your Signer ID (Master Account) authenticates the request, while your Principal ID (Vault/LogicSig) handles the funds.

import asyncio
from agentguard import AgentGuardClient

async def main():
    # Initialize client with your Signer Identity
    # Note: private_key is used ONLY for request signing, never for on-chain spend.
    async with AgentGuardClient(
        principal_id="LOGICSIG_OR_VAULT_ADDRESS",
        private_key="MASTER_ACCOUNT_SEED_B64",
        backend_url="https://agentguard-backend-9s8j.onrender.com"
    ) as client:
        
        # Access a premium resource
        # The SDK automatically handles: 402 Challenge -> Consent Signing -> Payment Relay
        receipt = await client.pay_and_fetch(
            resource_url="https://premium-intel.service/data",
            purpose="Market Analysis",
            amount_algo="0.1" # Optional: SDK can auto-probe price
        )
        
        print(f"✅ Success! Data: {receipt.data}")
        print(f"🔗 Audit Trail: {receipt.audit_url}")

if __name__ == "__main__":
    asyncio.run(main())

---

🧩 Core Concepts

1. Identity Separation (Zero-Trust)

AgentGuard separates the Signer from the Payer:

• Signer (signer_id): Your Master Account. It signs the "Intent to Pay" via the SDK.
• Payer (principal_id): A LogicSig or Vault account. It contains the funds and has a pre-approved policy to pay only when the Master Account signs.

2. Purpose-Bound Consent (DPDP)

Every payment requires a purpose string. AgentGuard hashes this purpose into the blockchain transaction. This creates an irrefutable audit trail proving exactly what the user (or agent) consented to at the time of payment.

3. Capability Delegation (LogicSigs)

You can authorize specific amounts or windows of time for your agent:

from agentguard.types import DelegatedAuthorization, AuthorizationConstraints

auth = DelegatedAuthorization(
    authorization_id="auth-uuid-123",
    principal_id="LOGICSIG_ADDRESS",
    logic_sig_b64="...",
    constraints=AuthorizationConstraints(
        max_amount_microalgos=5000000, # 5 ALGO limit
        expires_at_unix=1716300000
    )
)
await client.authorize(auth)

---

🛠️ API Reference

AgentGuardClient

• pay_and_fetch(resource_url, purpose, ...): The primary method. Probes a resource, extracts the price, signs consent, performs payment via the vault, and returns the data.
• authorize(delegated_auth): Registers a LogicSig or delegated capability in the vault.
• verify(tx_id): Checks the blockchain and audit logs to verify a previous payment's validity.
• revoke(authorization_id): Immediately invalidates a delegated capability.

---

🔒 Security Policy

The SDK uses ED25519 for all request signatures. All payloads are canonicalized (Deterministic JSON sorting + NFC normalization) before signing to prevent "In-Flight Mutation" attacks.

---

© 2026 AgentGuard Team. Built for the Algorand Advanced Agentic Coding.