Agent Tooling

Bot Protection

"Add bot protection to my contact form" is one API call. Your agent creates an Edge Shield widget, injects the two-line embed snippet into the page it's deploying, and wires up server-side verification — all without leaving the Agent API.

Why Shield in the Agent API?

Free, Forever

Unlimited widgets and verifications. Shield never counts against an agent's budget cap.

Ready-to-Paste Embed

The create response includes the exact script tag, widget div, and siteverify contract — no docs lookup needed.

Agent-Aware

Set an agent_policy to allow, challenge, or block cryptographically verified AI agents (Web Bot Auth) on the protected page.

Stats Built In

Agents can report solve rates, humanity scores, and blocked replays back to the user on request.

API Endpoints

GET    /agent/shield/widgets             # List widgets
POST   /agent/shield/widgets             # Create a widget (returns secret + embed snippet)
PATCH  /agent/shield/widgets/{id}        # Update name, hostnames, mode, agent_policy
DELETE /agent/shield/widgets/{id}        # Revoke a widget
GET    /agent/shield/widgets/{id}/stats  # Hourly traffic stats (?hours=24, max 720)

Requires an agent access code with the shield product. Creating, updating, and revoking widgets requires the manage permission. All write endpoints support X-Dry-Run: true.

Creating a Widget

POST /agent/shield/widgets
Authorization: Bearer ea_live_...

{
  "name": "Contact form",
  "hostnames": ["portfolio.example.com"],
  "mode": "managed",
  "agent_policy": "allow"
}

# Response:
{
  "widget": {
    "id": "wgt-abc123",
    "name": "Contact form",
    "sitekey": "es_6206c6fdb43e7a3cb948507e6f3e5a11",
    "mode": "managed",
    "agentPolicy": "allow",
    "hostnames": ["portfolio.example.com"]
  },
  "secret": "ss_4f8e2a1b9c7d6e5f4a3b2c1d0e9f8a7b",
  "embed": {
    "script": "<script src=\"https://shield.edge.network/api.js\" defer></script>",
    "widget": "<div class=\"edge-shield\" data-sitekey=\"es_6206...\"></div>",
    "verify": {
      "endpoint": "https://shield.edge.network/siteverify",
      "method": "POST",
      "body": { "secret": "<widget secret>", "response": "<edge-shield-response form field>" }
    }
  },
  "tell_user": "Shield widget \"Contact form\" created. IMPORTANT: the secret is
    shown only once — store it as a server-side environment variable now..."
}

The secret is returned only on creation

A well-behaved agent stores it as a server-side environment variable (never in client code or the repository) and tells the user where it was put. If the secret is lost, revoke the widget and create a new one.

Typical Agent Workflow

Create the widget — scoped to the site's hostname, in managed mode unless the user asks otherwise.
Inject the embed snippet — the script tag in the page head, the widget div inside the form being protected.
Wire up verification — the form handler posts the edge-shield-response field to /siteverify with the secret, and rejects submissions that fail.
Redeploy and report back — including where the secret is stored.

Checking Traffic

GET /agent/shield/widgets/wgt-abc123/stats?hours=168
Authorization: Bearer ea_live_...

# Response:
{
  "totals": {
    "hours": 168,
    "challenges_issued": 14382,
    "challenges_solved": 9041,
    "solve_rate_pct": 62.9,
    "verify_success": 1204,
    "verify_replay": 17,
    "verified_agents": 93
  },
  "stats": [ /* hourly rows */ ],
  "anomaly": null,
  "tell_user": "Last 168h: 14382 challenges issued, 62.9% solved,
    1204 verified submissions, 17 replayed tokens blocked."
}

If a drift anomaly is flagged on the widget, the response includes an anomaly object and the tell_user summary mentions it.