Agents can tell you who they are when they pay. Forge asks for it, reads it, reports it with the call, and removes it before your code runs. Your validators and handlers never see it, so your API contract doesn’t change.
What agents send
The names are prefixed with agent_ so they don’t collide with yours. Your other parameters are passed on byte-for-byte. Where agents learn about it
- The 402 challenge: the
forge-feedback extension carries a one-line ask, so clients that only inspect the 402 (awal) see it before paying.
- Your OpenAPI document: paid operations with a JSON request body get an optional
agent_context property. Operations without a body get the optional agent_* query parameters. Discovery tools (agentcash) show them as inputs.
It’s always optional, never required: true. A required field would break merchants whose validators enforce their spec, make agents invent answers, and cost you paid calls.
What you see
On your project’s Agents page in Forge, each paid call shows the agent and client it reported, alongside its search query and rating. Everything is labeled self-reported: any agent can claim to be anyone, so treat it as a direction, not proof. In testing, agents reported themselves accurately.
How it stays out of your way
- Express: Forge rewrites
req.url without the agent_* parameters, and intercepts your body parser’s req.body assignment to drop agent_context. The request stream is never read, so raw-body routes (webhooks, uploads) are unaffected.
- Other frameworks (the core): call
call.requestUrl(url) and call.requestBody(body) before your own logic. See the core.
- No network, no latency: it’s read in memory and sent with the call’s background event.
- Bad values never fail a request. Unknown values are kept as plain text, oversized ones are cut, and anything unusable is dropped.
Switches
Either way, Forge still removes the fields if an agent sends them, so your handlers never see them.
The search query is the one field that could carry something personal, if an agent pasted its user’s request into it. Forge’s descriptions ask for search terms only (“never your user’s request”), and cap it at 200 characters. Turn it off with searchQuery: false if you’d rather not store it.