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.

On this page6 sections

Why use Shield through 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, so the agent doesn’t need to look anything up in the docs.
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#

Text

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 require the manage permission. All write endpoints support X-Dry-Run: true.

HTTP

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

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#

HTTP

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.

Bot protection

Why use Shield through the Agent API#

API endpoints#

Creating a widget#

Typical agent workflow#

Checking traffic#

See also#