Agentify SDK middleware

Every seller SDK ships Agentify middleware for its language’s dominant boundary: a fetch-handler wrapper in TypeScript, ASGI and WSGI adapters in Python, net/http middleware in Go, and Rack middleware in Ruby. Mount it in front of your marketing site, and agent traffic gets agentified markdown while everyone else gets your site untouched. All four implement one contract:

Only GET requests are considered; every other method passes through.
Detection is one predicate over the request’s Accept and User-Agent headers: markdown-preferring or AI-agent traffic matches.
A match short-circuits with 200 text/markdown, forwarding the Agentify response’s cache-control and etag so your CDN caches the markdown too, plus Vary: accept, user-agent so a shared cache never hands it to a browser.
Any Agentify failure falls through to your app. A missing key, a network error, a non-200, a timeout — the middleware never breaks your site. The worst case is an agent seeing HTML.

Configure the key

Agentify calls use a dedicated config field holding a zc_ key with the agentify:convert scope; when unset, they fall back to the combined apiKey. The field has no construction-time requirement — a client that never agentifies needs no key — so a missing key surfaces as a typed error at call time, which the middleware absorbs by falling through.

const zeroClick = createSeller({
  signingSecrets: {
    [process.env.ZEROCLICK_SIGNING_SECRET_KID!]:
      process.env.ZEROCLICK_SIGNING_SECRET!,
  },
  apiKey: process.env.ZEROCLICK_API_KEY!,
  agentifyKey: process.env.ZEROCLICK_AGENTIFY_KEY!,
});

zeroclick = create_async_seller(
    signing_secrets={
        os.environ["ZEROCLICK_SIGNING_SECRET_KID"]: os.environ[
            "ZEROCLICK_SIGNING_SECRET"
        ]
    },
    api_key=os.environ["ZEROCLICK_API_KEY"],
    agentify_key=os.environ["ZEROCLICK_AGENTIFY_KEY"],
)

seller, err := sellers.New(sellers.Config{
	SigningSecrets: secrets,
	APIKey:         os.Getenv("ZEROCLICK_API_KEY"),
	AgentifyKey:    os.Getenv("ZEROCLICK_AGENTIFY_KEY"),
	ServiceSlug:    "product-watch",
})

config.zeroclick.api_key = ENV.fetch("ZEROCLICK_API_KEY")
config.zeroclick.agentify_key = ENV.fetch("ZEROCLICK_AGENTIFY_KEY")
config.zeroclick.signing_secrets = ZeroClick::Sellers.secrets_from_env

Conversion runs a full pipeline on the API side, so Agentify calls default to a 10-second timeout (agentifyTimeoutMs / agentify_timeout_seconds / AgentifyTimeout), independent of the allowance check’s much tighter one.

Mount the middleware

import { withAgentify } from "@zeroclickai/sellers";

// Wrap the fetch handler that serves your site. Works anywhere the SDK
// works: Node.js servers, Hono, Next.js route handlers, edge runtimes.
const handler = withAgentify(zeroClick, (request) => renderPage(request));

export default { fetch: handler };

# ASGI (Starlette, FastAPI) — pass the async client:
from zeroclick_sellers.adapters import AgentifyAsgiMiddleware

app.add_middleware(AgentifyAsgiMiddleware, seller=zeroclick)

# WSGI (Flask, Django) — pass the blocking client from create_seller:
from zeroclick_sellers.adapters import AgentifyWsgiMiddleware

app.wsgi_app = AgentifyWsgiMiddleware(app.wsgi_app, seller=zeroclick)

// A plain func(http.Handler) http.Handler, like Meter and Identify: it
// composes with net/http, chi, gorilla/mux, and gin's WrapH.
mux.Handle("/", seller.Agentify(sellers.AgentifyOptions{})(site))

# Rails: mount it in config/application.rb. Omit `seller:` and the
# middleware resolves the process-wide client on the first request.
config.middleware.use ZeroClick::Sellers::Middleware::Agentify

# Outside Rails, pass the client explicitly:
use ZeroClick::Sellers::Middleware::Agentify, seller: SELLER

Mount it in front of the pages agents read — your marketing routes — not in front of your billed API, which already speaks to agents through your storefront. If your marketing site runs as its own process, configure a client there the same way; the middleware only ever uses the Agentify key.

Options

Each middleware takes the same three options, named in its language’s idiom:

Option	TypeScript	Python	Go	Ruby
The seller whose storefront to inline (`sel_…`); needed only by multi-seller organizations	`seller`	`seller_id`	`Seller`	`seller_id`
Override the public URL to convert for a request	`resolveUrl`	`resolve_url`	`ResolveURL`	`resolve_url`
Observe the fail-open path; never re-raised	`onError`	`on_error`	`OnError`	`on_error`

By default the middleware converts the URL the agent requested, as far as your process can see it. Behind a proxy or load balancer that rewrites the scheme or host, override it — the API fetches this URL from the outside, so it must be the public one:

const handler = withAgentify(zeroClick, renderPage, {
  resolveUrl: (request) =>
    `https://www.acme.com${new URL(request.url).pathname}`,
});

Failing open, observably

The middleware exists to add an agent-readable representation, never to add an outage: any error on the Agentify path serves your HTML instead. That silence is deliberate, and it also means a misconfigured key looks exactly like working HTML — so wire the error hook to your logger:

const handler = withAgentify(zeroClick, renderPage, {
  onError: (error, request) =>
    logger.warn({ error, url: request.url }, "agentify fell through to HTML"),
});

In Go, a nil OnError falls back to the client’s configured Logger.

Verify

With the middleware mounted, the same page answers both audiences:

# An agent gets markdown that references your storefront:
curl -s -H "Accept: text/markdown, text/html, */*" https://www.acme.com/pricing | head -20

# A browser Accept header gets your HTML, unchanged:
curl -s -H "Accept: text/html,application/xhtml+xml" https://www.acme.com/pricing | head -5

The first request of a page takes a few seconds while the conversion runs; repeats are served from cache. This also satisfies the markdown step of enable agent traffic: the served document inlines your storefront, which is exactly what verification checks for.

Get started

Concepts

Integrate your API

Your agent storefront

Agentify

Resources

Agentify SDK middleware

Configure the key

Mount the middleware

Options

Failing open, observably

Verify

Next steps

SPA setup

REST quickstart

​Configure the key

​Mount the middleware

​Options

​Failing open, observably

​Verify

​Next steps

SPA setup

REST quickstart

Configure the key

Mount the middleware

Options

Failing open, observably

Verify

Next steps