Agents overview
For people who build AI agents, crawlers and browser agents: how to get through a site protected by AgentGate on the site's terms.
This section is for people who run AI agents, crawlers or browser agents that visit sites protected by AgentGate. Site operators will find the matching configuration in Agent policy for sites.
AgentGate does not try to keep agents out. It asks them to say who they are, and then applies the site's policy to that identity. An agent that signs its requests is never shown a human check.
The five things to handle
| Step | What you do | Page |
|---|---|---|
| 1. Identify | Sign every request with Web Bot Auth (Ed25519, RFC 9421) | Sign requests |
| 2. Discover | Read the site's tool manifest, /.well-known/agentgate-tools.json | Declared tools |
| 3. Pay, if asked | Answer 402 Payment Required with a price offer | Pay per crawl |
| 4. Hand off | When a check is needed, give your person a link or QR code | Human handoff |
| 5. Keep proof | Store the signed AgentGate-Receipt of each decision | Signed receipts |
What an unsigned agent gets
A User-Agent that names a known AI agent or crawler (GPTBot, ChatGPT-User, PerplexityBot, …) without a valid signature is an unverified claim. Depending on the site's policy it is challenged (the default), blocked, or asked to pay. A browser agent driving a person's Chrome without signing is scored like any other automation and is likely to be asked for the press-and-hold check, which agents cannot and should not pass: hand it to your person instead.
Responses you should expect
| Status | Meaning | What to do |
|---|---|---|
2xx | allowed | keep the AgentGate-Receipt header |
401 | no valid signature or key | sign the request; check created, expires, keyid, nonce |
402 | a price applies | retry with crawler-exact-price or crawler-max-price, signed |
403 "not permitted" | the site's policy does not allow your agent this action | stop; ask the site operator |
403 / 428 with handoff | a person must complete a check | show handoff.url, poll handoff.poll |
429 | over your per-site quota | wait Retry-After (60 s) |
All codes: Error codes.
About the examples
The examples use AgentGate's built-in agent API, POST /agent/submit, and its declared tool send_message. That endpoint exists on an AgentGate instance whose operator has registered agent keys or key directories. On customer sites, agents call the site's own routes through the gateway, which verifies the same signatures.