Agent Edge Network: Architecture and Request Flow

The Bluesky Agent Edge Network (AEN) is a self-contained edge drop-in you install in your own app. Each drop-in — a Next.js middleware.ts, a Cloudflare Worker, a WordPress plugin, or a snippet for any other stack — is zero-dependency, runs in your request path, identifies verified AI crawlers, serves them pre-generated answer-optimized content, and reports every hit back to Bluesky.

Every drop-in runs inside your own stack, not as a reverse proxy — Bluesky stays out of your traffic path. A zero-code CNAME reverse-proxy (Bluesky-hosted) is on the roadmap, not shipped. See Supported platforms.

What the AEN does

On each request, the middleware runs these steps in order:

Detect

The middleware fetches a verified bot registry (botset) from the Bluesky control plane, caches it in-process for one hour, and matches the incoming User-Agent token against it. If there is no match, the normal page is served.

Protect your search ranking

Before anything else, classic search-index bots — Googlebot, Bingbot, and Applebot (isSearchIndex) — are never served the variant. They always receive your normal page. See Cloaking Firewall for why branching them would cloak Search itself.

Verify

For a matched non-search bot, the middleware verifies the source IP against the vendor’s published CIDR ranges. A verified IP is IP_VERIFIED; an unverified token match is UA_ONLY and is treated as unverified. Only verified crawlers whose purpose class is enabled are eligible to be served.

Serve (or pass through)

If the request is eligible and the site is in default serve mode, the middleware fetches the pre-generated artifact for that URL and returns its markdown field as the response body (Content-Type: text/markdown). If no artifact exists, or the bot is not eligible, the normal page is served instead.

Report telemetry

A fire-and-forget hit is posted to the control plane with the bot name, path, status, user-agent, IP, trust level, purpose class, and what was served. It is called with .catch(() => {}), so it never blocks or errors the response. This powers Agent Analytics.

There is no LLM call on the request path. Artifacts are generated offline and cached ahead of time. In this drop-in v0 the artifact is fetched from the control plane per served request; a productized edge caches it.

Detection trust tiers

Detection assigns an ascending trust level. The core library defines four tiers:

Tier	How it is established	In v0 drop-in
`SIGNED`	Web Bot Auth signature verified (RFC 9421 / Ed25519)	Not verified
`IP_VERIFIED`	Source IP inside the vendor’s published CIDR ranges	Yes (IPv4)
`DNS_VERIFIED`	Reverse-DNS confirmation, resolved engine-side / async	Not on path
`UA_ONLY`	User-Agent token matched but nothing verified	Unverified

Only SIGNED and IP_VERIFIED are treated as verified and can be served the variant. The shipped middleware verifies by IPv4 CIDR only; SIGNED and DNS_VERIFIED exist in the core but are not performed by the drop-in.

A User-Agent alone proves nothing — it is trivially spoofed. An unverified token match tops out at UA_ONLY and always receives the normal page.

Request flow at a glance

Incoming request
      │
      ▼
┌─────────────────────┐
│  Fetch bot registry │  ← GET /api/v1/edge/botset (cached 1 h)
│  Match User-Agent   │
└────────┬────────────┘
         │ no match?
         ├──────────────────────────────▶ NextResponse.next() (passthrough)
         │
         │ isSearchIndex? (Googlebot/Bingbot/Applebot)
         ├──────────────────────────────▶ NextResponse.next() (cloaking firewall)
         │
         ▼
┌─────────────────────┐
│  Verify source IP   │  against vendor CIDR list
│  Check purpose      │  USER_TRIGGERED | RETRIEVAL
└────────┬────────────┘
         │ verified + purpose enabled + SERVE_MODE = "default"?
         ├──────────────────────────────▶ GET /api/v1/edge/artifact?u=<sha256(url)>
         │                                serve markdown if found, else passthrough
         │
         ▼
┌─────────────────────┐
│  Fire telemetry     │  ← POST /api/v1/edge/telemetry (non-blocking)
└─────────────────────┘

Control-plane endpoints

The AEN talks to four /api/v1/edge/ endpoints. Every call carries an Authorization: Bearer <edgeToken> header. The shipped drop-in v0 calls three of them (botset, artifact, telemetry) and hardcodes its serve config; fuller adapters additionally poll config.

Bot registry

GET /api/v1/edge/botsetReturns the verified bots with UA tokens, CIDR ranges, purpose classes, and the isSearchIndex flag. Cached in-process for one hour.

Artifact fetch

GET /api/v1/edge/artifact?u=<sha256>Returns the pre-generated artifact for a URL, addressed by the SHA-256 hash of its full URL. The response carries the artifact’s markdown, jsonLd, and cleanHtml fields; the drop-in serves the markdown field.

Telemetry

POST /api/v1/edge/telemetryAccepts a { hits: [...] } array. Non-blocking. Powers Agent Analytics.

Config

GET /api/v1/edge/configPer-site serve config: serveMode, enabledPurposes, pathAllow, pathDeny. Polled by productized adapters on a TTL; the v0 drop-in hardcodes these instead.

All endpoints live under:

https://app.trybluesky.com/api/v1/edge/

Authentication

Every control-plane call uses an edge token — a per-site secret, scoped to a single domain and revocable independently of your account API key.

Authorization: Bearer aen_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The edge token is not your account API key. It is scoped to one site and can be revoked without affecting your account or other sites. Store it as the AEN_EDGE_TOKEN environment variable — never commit it to source control.

You provision a domain in Agent Analytics to mint its edge token, then set it as AEN_EDGE_TOKEN in your host’s environment (for example, in Vercel project settings). See the Quickstart.

Supported platforms

Available now
Roadmap

Next.js / Vercel — a self-contained middleware.ts or the @trybluesky/aen package. See the Next.js Middleware guide.
Cloudflare — a drop-in Worker that runs on your own zone.
WordPress / PHP — a plugin you upload and activate.
Any other stack — Node, PHP, Ruby, nginx or Apache via the custom integration snippets.

All of them are the same ~40 lines of logic, verified by published IP ranges, zero dependencies.

Serve modes

The full serve-mode vocabulary is off, shadow, canary:<pct>, and default. Sites start in shadow so you can validate detection before serving anything to real crawlers. The shipped v0 drop-in supports shadow and default; the control plane understands all four.

Mode	Behavior
`off`	Never serve the variant.
`shadow`	Serve the human page to everyone, but log what it would have served.
`canary:<pct>`	Serve a deterministic percentage of eligible requests; the rest pass through.
`default`	Serve the artifact to all eligible verified answer-engine agents.

Once you see verified hits in Agent Analytics, promote the serve mode from shadow toward default. See Serve modes for the full progression.

​What the AEN does

​Detection trust tiers

​Request flow at a glance

​Control-plane endpoints

Bot registry

Artifact fetch

Telemetry

Config

​Authentication

​Supported platforms

​Serve modes

What the AEN does

Detection trust tiers

Request flow at a glance

Control-plane endpoints

Authentication

Supported platforms

Serve modes