AgentShield Documentation

📦 Installation

AgentShield works with any AI agent platform. Choose the method that fits your stack:

Option A — ClawHub OpenClaw · Hermes Agent

clawhub install agentshield-audit
agentshield-audit --auto

Option B — pip Python · LangChain · n8n · Any

pip install agentshield-audit
agentshield-audit --auto

# n8n (auto-detected)
agentshield-audit --auto

# LangChain / custom
agentshield-audit --name "MyBot" --platform langchain

👉 pypi.org/project/agentshield-audit

Option C — Docker Container · Self-Hosted n8n

docker run --rm \
  -v ~/.agentshield:/data/.agentshield \
  bartelmost/agentshield:latest \
  --name "MyBot" --platform langchain

👉 hub.docker.com/r/bartelmost/agentshield

Option D — Direct API Any Language

# No install needed — REST API, any HTTP client
curl https://agentshield.live/api/verify/agent_xyz
curl https://agentshield.live/api/registry/agents

Base URL: https://agentshield.live/api — No API key required for most endpoints.

Option E — MCP Server Claude Desktop · Cursor · VS Code · Continue.dev

// claude_desktop_config.json  (also works in Cursor, Continue.dev)
{
  "mcpServers": {
    "agentshield": {
      "url": "https://agentshield.live/mcp"
    }
  }
}

No install, no API key — one config line and AgentShield tools are available in your AI client. See full MCP docs ↓

Trust Handshake Protocol NEW

Agent-to-agent mutual verification with cryptographic signatures. See What's New for detailed overview.

Quick Reference

1. Verify Peer: GET /api/verify-peer/:agent_id - Fast trust check
2. Initiate: POST /api/trust-handshake/initiate - Start handshake
3. Sign: Both agents sign challenges with Ed25519 private keys
4. Complete: POST /api/trust-handshake/complete - Submit signatures
5. Track: GET /api/trust-handshake/history/:id - View reputation

Agent Registry

List All Agents

Returns all registered agents in the trust network.

Response

{
  "agents": [
    {
      "agent_id": "agent_1234567890ab",
      "agent_name": "SecureBot v2",
      "tier": "VERIFIED",
      "trust_score": 85,
      "status": "active",
      "registered_at": "2026-02-15T10:30:00Z",
      "last_verified": "2026-02-26T14:00:00Z"
    }
  ],
  "count": 1
}

Verify Agent Certificate

Public endpoint to verify an agent's certificate and check revocation status.

Response (Valid Certificate)

{
  "valid": true,
  "agent_id": "agent_1234567890ab",
  "agent_name": "SecureBot v2",
  "platform": "openclaw",
  "security_score": 85,
  "tier": "PATTERNS_CLEAN",
  "trust_score": 72,
  "trust_tier": "VERIFIED",
  "revoked": false,
  "expires_at": "2026-05-16T10:30:00Z"
}

Response (Revoked Certificate)

{
  "valid": false,
  "agent_id": "agent_1234567890ab",
  "status": "revoked",
  "revocation": {
    "revoked_at": "2026-02-20T18:45:00Z",
    "reason": "Security policy violation"
  }
}

Challenge-Response Verification

Generate a random challenge for the agent to sign.

Response

{
  "challenge": "verify:1234567890abcdef:1709046000",
  "expires_in": 300
}

Verify the agent's signed response.

Request

{
  "challenge": "verify:1234567890abcdef:1709046000",
  "response": "base64_ed25519_signature..."
}

Response

{
  "verified": true,
  "message": "Agent identity confirmed"
}

Certificate Revocation List (CRL)

AgentShield maintains a real-time Certificate Revocation List to track invalidated certificates. Certificates can be revoked for:

• Security policy violations
• Compromised private keys
• Manual revocation requests
• Failed re-verification audits

Product APIs

Token Optimizer

Analyze prompt efficiency and calculate monthly LLM cost savings (35-60% reduction typical).

Request

{
  "code": "BETA5",
  "system_prompt": "You are a helpful assistant called Kalle..."
}

Response

{
  "efficiency": {
    "current_tokens": 150,
    "optimized_tokens": 95,
    "monthly_savings": "$2,400",
    "redundancies_found": [
      "Duplicate instruction: 'Be helpful' (line 3 & 7)",
      "Verbose phrasing: 'regardless of how...' → 'never'"
    ]
  },
  "pdf_url": "/reports/agentshield-token-abc123.pdf"
}

Code Security Scan

Pattern-based malware and vulnerability detection for Python, JavaScript, and agent code.

Request

{
  "code": "BETA5",
  "code_content": "import subprocess\\nsubprocess.run(user_input, shell=True)"
}

Response

{
  "results": {
    "security_score": 25,
    "status": "CRITICAL",
    "findings": [
      "subprocess.run with shell=True (RCE risk)",
      "Direct user input in system call",
      "No input validation detected"
    ]
  },
  "pdf_url": "/reports/agentshield-code-xyz789.pdf"
}

Agent Security Assessment

Step 1: Initiate Audit

Start the Ed25519 certificate-based security assessment process.

Request

{
  "agent_name": "SecureBot v2",
  "platform": "openclaw",
  "public_key": "AAAA1234base64encodedEd25519publickey..."
}

Response

{
  "audit_id": "audit_abc123def456",
  "agent_id": "agent_xyz789abc",
  "status": "pending_challenge",
  "challenge": "a85dc6ca8ca2f980f07d1239369de907...",
  "challenge_expires": "2026-03-07T14:15:00Z",
  "message": "Sign the challenge with your private key and POST to /api/agent-audit/challenge"
}

Step 2: Complete Challenge

Submit signed challenge to verify identity.

Request

{
  "audit_id": "audit_abc123def456",
  "challenge_response": "base64_ed25519_signature..."
}

Response

{
  "audit_id": "audit_abc123def456",
  "agent_id": "agent_xyz789abc",
  "status": "authenticated",
  "authenticated_at": "2026-03-07T14:10:00Z",
  "next_step": "Run security tests and POST results to /api/agent-audit/complete"
}

Step 3: Submit Results

Submit audit results and receive certificate.

Request (Option A - Simple Format)

{
  "audit_id": "audit_abc123def456",
  "score": 85,
  "passed": 72,
  "total": 77
}

Request (Option B - Detailed Format)

{
  "audit_id": "audit_abc123def456",
  "test_results": {
    "test_prompt_injection": {
      "score": 10,
      "passed": true,
      "severity": "HIGH"
    },
    "test_data_leak": {
      "score": 8,
      "passed": false,
      "severity": "CRITICAL"
    }
  }
}

Response

{
  "certificate": {
    "header": {
      "alg": "Ed25519",
      "typ": "AGENT-CERT-v1"
    },
    "payload": {
      "sub": "agent_xyz789abc",
      "iss": "agentshield.live",
      "iat": 1709823300,
      "exp": 1717599300,
      "agent_name": "SecureBot v2",
      "public_key": "AAAA1234...",
      "score": 85,
      "tier": "PATTERNS_CLEAN",
      "tests_passed": 72,
      "tests_total": 77
    },
    "signature": "base64_signature...",
    "certificate_hash": "sha256:abc123..."
  },
  "agent_id": "agent_xyz789abc",
  "security_score": 85,
  "tier": "PATTERNS_CLEAN",
  "trust_score": 42,
  "trust_tier": "BASIC",
  "tests_passed": 72,
  "tests_total": 77,
  "issued_at": "2026-03-07T14:15:00Z",
  "expires_at": "2026-06-05T14:15:00Z",
  "verify_url": "https://agentshield.live/api/verify/agent_xyz789abc"
}

Security Tiers

Code Examples

Python - Registry Lookup

import requests

response = requests.get('https://agentshield.live/api/registry/agents')
agents = response.json()['agents']

for agent in agents:
    print(f"{agent['agent_name']} - Trust: {agent['trust_score']} - Tier: {agent['tier']}")

JavaScript - Trust Handshake NEW

// 1. Verify peer before handshake
const verifyResp = await fetch(
  'https://agentshield.live/api/verify-peer/agent_b?min_score=70'
);
const { trusted } = await verifyResp.json();

if (!trusted) {
  console.log('Agent B not trustworthy!');
  return;
}

// 2. Initiate handshake
const initiateResp = await fetch(
  'https://agentshield.live/api/trust-handshake/initiate',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      requester_id: 'agent_a',
      target_id: 'agent_b'
    })
  }
);

const handshake = await initiateResp.json();
const { handshake_id, requester, target } = handshake;

// 3. Sign challenges (both agents)
const requesterSig = await signChallenge(requester.challenge);
const targetSig = await signChallenge(target.challenge);

// 4. Complete handshake
const completeResp = await fetch(
  'https://agentshield.live/api/trust-handshake/complete',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      handshake_id,
      requester_signature: requesterSig,
      target_signature: targetSig
    })
  }
);

const result = await completeResp.json();
console.log('Session key:', result.session_key);
console.log('Trust bonus:', result.trust_bonus);

Python - Complete Audit Flow (v1.4.0)

import requests
import base64
from cryptography.hazmat.primitives.asymmetric import ed25519

# 1. Generate keypair
private_key = ed25519.Ed25519PrivateKey.generate()
public_key = private_key.public_key()
public_key_b64 = base64.b64encode(
    public_key.public_bytes_raw()
).decode('utf-8')

# 2. Initiate audit
resp = requests.post('https://agentshield.live/api/agent-audit/initiate', json={
    'agent_name': 'MyAgent v1.0',
    'platform': 'openclaw',
    'public_key': public_key_b64
})
data = resp.json()
audit_id = data['audit_id']
challenge = data['challenge']

# 3. Sign challenge
signature = private_key.sign(challenge.encode('utf-8'))
signature_b64 = base64.b64encode(signature).decode('utf-8')

resp = requests.post('https://agentshield.live/api/agent-audit/challenge', json={
    'audit_id': audit_id,
    'challenge_response': signature_b64
})
print(resp.json())

# 4. Run local tests (77 security tests)
# ... your test logic here ...

# 5. Submit results (Client-First - Simple Format)
resp = requests.post('https://agentshield.live/api/agent-audit/complete', json={
    'audit_id': audit_id,
    'score': 85,
    'passed': 72,
    'total': 77
})

certificate = resp.json()
print(f"Certificate issued! Score: {certificate['security_score']}")
print(f"Verify at: {certificate['verify_url']}")