---
title: "Agent Bot Protection"
description: "Let your AI agent add Edge Shield bot protection to the forms and pages it deploys — free, in one API call."
url: https://edge.network/docs/agent/shield/
---

# Agent Bot Protection

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.

## See Also

[Server-Side Validation The siteverify contract in full](https://edge.network/docs/shield/siteverify) [Discovery Endpoint The agent's entry point](https://edge.network/docs/agent/discovery)
[Back to Docs](https://edge.network/docs) [Need help?](https://edge.network/support)