1. Connect. Give the SDK a Forge API key and mount its adapter outside your existing payment handler. The collector is built in. The SDK observes requests; it does not require a manual paid-route list.
  2. Observe. Your auth, pricing and payment code still decide every response. The SDK identifies the agent behind each request and records how far it got, without changing what agents see.
  3. Review. The SDK batches events to Forge in the background. The service’s Activity page shows every agent session.
Agent context is off by default. With agentContext: true (agent_context=True), agents are invited to include their name and search query, and Forge records them when sent, but it stays optional. { required: true } (AgentContextOptions(required=True)) rejects paid requests without it with HTTP 400 before payment processing. Caller-supplied context is not authenticated identity. Configure agent context. Event capture does not call Forge on your API’s response path. A collector outage can lose activity but does not change merchant responses. Failure behavior.

​
What the SDK reports

With just an API key, the SDK reports these events in the background, never on your request path: Visits show an agent’s whole path through your service, from landing to payment. Forge only reports them for agents: a request signed with Web Bot Auth, or any client that isn’t a browser. People browsing your site, and asset files (images, CSS, scripts, fonts), are never reported. A visit records the method, the path without its query string, the status, the response time and the client headers below; never bodies or query values. At most 120 visits a minute are reported per process, and never at the expense of challenges or paid calls. Every event carries a fixed set of client headers, read by name and nothing else: user-agent, x-client-id, x-session-id, the wallet-address headers, referer, payment-retry, cf-worker, the Sentry release from baggage, and the Web Bot Auth headers signature-agent, signature-input and signature. Forge uses them to tell which agent and client made a call; Web Bot Auth signatures are cryptographic proof of the agent’s operator. Express, Hono, fetch handlers and Python (ASGI) see every request. In Next.js, Forge sees the routes you wrap with withForge, so visits cover those.