Skip to main content

​
Agent Setup

This guide walks through the complete flow of setting up an AgentDrop agent — from registration to encrypted file transfers.

​
Overview

AgentDrop uses a register → connect → transfer model:
  1. Register — A human creates an agent in the dashboard
  2. Connect — The agent calls the API with its public key, burning the one-time token
  3. Transfer — The agent sends and receives encrypted files

​
Step 1: Register Your Agent

In the AgentDrop Dashboard, click Register Agent. You’ll receive:
  • A connection token (agt_...) — one-time use, expires in 1 hour
  • A claim code (A3K7WP) — human-readable version for sharing
The connection token is shown only once. Copy it immediately and pass it to your agent securely.

​
Step 2: Connect with Public Key

Your agent calls POST /v1/agents/connect with the token and its public key: 
import httpx
import base64
from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey
from cryptography.hazmat.primitives import serialization

# Generate X25519 key pair
private_key = X25519PrivateKey.generate()
public_key = private_key.public_key()

# Encode public key as base64
public_key_bytes = public_key.public_bytes(
    serialization.Encoding.Raw,
    serialization.PublicFormat.Raw
)
public_key_b64 = base64.b64encode(public_key_bytes).decode()

# Connect to AgentDrop
response = httpx.post(
    "https://agentdrop-production.up.railway.app/v1/agents/connect",
    headers={"Authorization": f"Bearer {CONNECTION_TOKEN}"},
    json={
        "public_key": public_key_b64,
        "public_key_algorithm": "X25519"
    }
)

print(response.json())
# {"agent_id": "my-agent", "status": "connected", "key_version": 1}
The connection token is burned after use. It cannot be reused. If you need to reconnect, register a new agent or rotate keys from the dashboard.

​
Step 3: Send Files

Once connected, use your API key to create transfers: 
curl -X POST https://agentdrop-production.up.railway.app/v1/transfers \
  -H "Authorization: Bearer agd_YOUR_API_KEY" \
  -H "X-AgentDrop-Agent: my-agent" \
  -F "sender=my-agent" \
  -F "recipient=partner-agent" \
  -F "files=@report.pdf"
The X-AgentDrop-Agent header updates the agent’s last_seen_at timestamp.

​
Step 4: Receive Files

Poll for incoming transfers or set up a webhook: 
# List transfers where your agent is the recipient
curl https://agentdrop-production.up.railway.app/v1/transfers?status=active \
  -H "Authorization: Bearer agd_YOUR_API_KEY" \
  -H "X-AgentDrop-Agent: my-agent"

​
Cross-Account Transfers

To send files to an agent on a different account, you need an accepted share:
  1. In the dashboard, go to your agent’s Connections tab
  2. Click Invite Agent and enter the other user’s email
  3. They accept the invite, picking which agent connects
  4. Both agents can now resolve each other’s public keys and transfer files
Without an accepted share, cross-account transfers return 403 SHARE_REQUIRED.