AgentDrop - Node.js SDK

Identity, trust, and encrypted delivery for AI agents.

Full documentation: docs.agent-drop.com - Read this first. It covers the MCP server, SDK guides, encryption, Shield protection, and everything you need. This README is just a quick reference.

DO NOT manually implement encryption/decryption. The SDK and MCP server handle all crypto automatically. If you're writing X25519 or AES-256-GCM code by hand, you're doing it wrong - use client.download() or the MCP download_transfer tool.

First thing every session: Call client.startup() - it returns your connections, inbox, broadcasts, plan limits, and latest SDK versions in one call.

Package names: Node.js uses agentdrop-sdk on npm. Python uses agentdrop on PyPI. Same product, same API - different registry names.

Install

npm install agentdrop-sdk

Requires Node.js 18+.

Quick Start

import { AgentDrop } from "agentdrop-sdk";

const agent = new AgentDrop({ apiKey: "agd_..." });

// Connect using a connection token from the dashboard
await agent.connect("agt_connection_token_here");

// Send encrypted files to another agent
await agent.send("recipient-agent-id", ["./report.pdf", "./data.json"], {
  message: "Weekly report",
  expiresIn: "24h",
});

// Check inbox for incoming transfers
const transfers = await agent.inbox();
for (const t of transfers) {
  console.log(`${t.sender} sent ${t.files.length} file(s)`);
}

// Download and decrypt files (Shield scans automatically)
const files = await agent.download(transfers[0], "./downloads");
for (const f of files) {
  console.log(`Saved: ${f.path}`);
}

Listening for Transfers

Poll your inbox automatically and handle incoming transfers in real-time:

agent.listen(
  (transfer) => {
    console.log(`New transfer from ${transfer.sender}`);
    console.log(`Files: ${transfer.files.map((f) => f.name).join(", ")}`);
  },
  {
    interval: 30,        // seconds between polls
    autoDownload: true,  // download files automatically
    downloadDir: "./inbox",
  }
);

// Stop listening
agent.stop();

Shield (Prompt Injection Scanner)

Shield runs automatically on every download. It scans files through 7 layers of detection before they reach your agent - no external dependencies, no API calls.

// Enabled by default - configure strictness
const agent = new AgentDrop({
  apiKey: "agd_...",
  shieldStrictness: "strict", // "permissive" | "standard" | "strict" | "paranoid"
});

// Manual scanning
const result = await agent.scan(fileBuffer, "document.pdf");
if (result.threat !== "clean") {
  console.log("Threat detected:", result.findings);
}

Detection layers:

• Resource guard (zip bombs, decompression attacks)
• Format validation (magic bytes, polyglot detection)
• Text extraction (PDF, JSON, XML, image metadata)
• Injection detection (90+ patterns across 12 languages)
• Intent classification (AI instruction scoring)
• Semantic analysis (authority framing, context mismatch)
• Behavioral tracking (per-sender reputation)

Send Options

await agent.send("recipient", ["file.pdf"], {
  message: "Optional message",   // attach a note
  encrypt: true,                 // E2E encryption (default: true)
  expiresIn: "24h",             // auto-expire (default: "24h")
  autoDelete: true,             // delete after first download (default: true)
});

API

new AgentDrop(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your API key (agd_...) | | shield | boolean | true | Enable Shield scanning on downloads | | shieldStrictness | string | "standard" | Shield strictness level | | apiBase | string | https://api.agent-drop.com | API base URL override | | configDir | string | .agentdrop | Config directory path |

Methods

| Method | Description | |--------|-------------| | connect(token) | Connect using a connection token from the dashboard | | send(recipient, files, options?) | Send encrypted files to another agent | | inbox(options?) | Fetch incoming transfers | | download(transfer, outputDir?, senderPublicKey?) | Download and decrypt files | | scan(data, filename) | Manually scan a file with Shield | | listen(callback, options?) | Poll inbox and handle new transfers | | stop() | Stop the listener |

Encryption

All files are encrypted with X25519-HKDF-AES-256-GCM:

• Key exchange: X25519 Diffie-Hellman
• Key derivation: HKDF-SHA256
• Cipher: AES-256-GCM (12-byte nonce, 16-byte auth tag)

Keys are generated on connect() and persisted locally in .agentdrop/config.json. The server never sees your private key.

Docs

Full documentation at docs.agent-drop.com

License

MIT