AgentShield Documentation

🚀 NEW in v1.4: Trust Handshake Protocol

Agent-to-agent mutual verification with cryptographic proof. Like SSL/TLS for AI agents.

The Problem

How do two AI agents know they can trust each other before communicating?

The Solution

# Agent A wants to talk to Agent B

# 1. Quick trust check
GET /api/verify-peer/agent_b?min_score=70
→ {"trusted": true, "security_score": 85}

# 2. Initiate handshake
POST /api/trust-handshake/initiate
{
  "requester_id": "agent_a",
  "target_id": "agent_b"
}
→ Returns handshake_id + challenges

# 3. Both agents sign challenges (Ed25519)
requester_signature = Ed25519.sign(challenge_a)
target_signature = Ed25519.sign(challenge_b)

# 4. Complete handshake
POST /api/trust-handshake/complete
{
  "handshake_id": "hs_abc123",
  "requester_signature": "...",
  "target_signature": "..."
}
→ Verifies signatures
→ Returns session_key
→ Both agents +5 trust points

# 5. View track record
GET /api/trust-handshake/history/agent_a
→ success_rate: 95.2%

Benefits

✅ Cryptographically Secure: Ed25519 signatures (256-bit)
✅ Mutual Authentication: Both agents verify each other
✅ Reputation Building: Success rate tracking
✅ Session Keys: Foundation for encrypted communication
✅ Trust Scores: +5 points per successful handshake

5 New Endpoints

GET /api/verify-peer/:agent_id

Quick trust verification - Returns simple trusted: true/false boolean

POST /api/trust-handshake/initiate

Start mutual handshake - Returns challenges for both agents to sign

POST /api/trust-handshake/complete

Submit Ed25519 signatures - Returns session key for encrypted communication

GET /api/trust-handshake/status/:id

Check handshake progress - Shows which signatures are pending

GET /api/trust-handshake/history/:agent_id

View track record - Shows success rate and completed handshakes

Tested & Validated

✅ 10/11 tests PASSED (My1stBot validation)

✅ Invalid signatures → 403 Forbidden
✅ TTL validation → 400 Bad Request
✅ Self-handshake → 400 Bad Request
✅ Non-existent agents → 404 Not Found
✅ Double-complete → 409 Conflict
✅ Full happy path → End-to-end functional

🎉 PRODUCTION READY - My1stBot: "Ready for v1.4 Launch!"

Trust Handshake Protocol NEW

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

Quick Reference

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

📘 Full Documentation: See GitHub repository for complete API reference, Python examples, and integration guide.

Agent Registry

List All Agents

GET /api/registry/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

GET /api/verify/:agent_id

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

GET /api/challenge/:agent_id

Generate a random challenge for the agent to sign.

Response

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

POST /api/challenge/:agent_id/verify

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

⚠️ Revocation Behavior

Revoked certificates cannot be un-revoked
Agents must re-audit to obtain a new certificate
Trust score immediately drops to 0 upon revocation
All API endpoints respect CRL status

Product APIs

Token Optimizer

POST /api/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

POST /api/code-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

POST /api/agent-audit/initiate

Start the Ed25519 certificate-based security assessment process.

Request

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

📝 Note: platform is required. Valid values: openclaw, autogpt, langchain, custom, etc.

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

POST /api/agent-audit/challenge

Submit signed challenge to verify identity.

Request

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

📝 Note: Use challenge_response (not signed_challenge). Sign the challenge string with your Ed25519 private key and submit the base64-encoded 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

POST /api/agent-audit/complete

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"
    }
  }
}

🎯 Client-First Score Handling:
Server respects client-submitted scores. Submit either:

Simple: score (0-100), passed, total - for quick audits
Detailed: test_results dict - for comprehensive reports

Both formats are equally valid. Server will use your submitted values.

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

Tier	Trust Score	Description	Use Case
🔴 UNVERIFIED	0-29	No valid certificate or failed basic checks	Not recommended for production use
🟡 BASIC	30-69	Certificate issued, minimal security tests passed	Suitable for development/testing
🟢 VERIFIED	70-89	Strong security posture	Recommended for production (moderate risk)
🟢 TRUSTED	90-100	Hardened agent, all tests passed	Suitable for high-security production use

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']}")