Agent context

Optional and off by default. Forge identifies agents and their sessions without it; agent context only adds what an agent chooses to tell you.

The SDK can collect an agent type and the search query that led to a paid request. These are self-reported claims, not authenticated agent or payer identity. Agent context is off by default. Turn it on and the SDK asks for context everywhere agents look, and records it whenever an agent sends it, but never rejects a request without it unless you make it required. Your existing paying clients keep working unchanged.

Node	Python	Behavior
not set, or `false`	not set, or `False`	Off (default): nothing is asked for or recorded.
`agentContext: true`	`agent_context=True`	Optional: asked for and recorded, never required.
`{ searchQuery: false }`	`AgentContextOptions(search_query=False)`	Optional, agent name only.
`{ required: true }`	`AgentContextOptions(required=True)`	Required: payment-bearing requests without valid context get HTTP 400 before payment processing.
`{ required: true, searchQuery: false }`	`AgentContextOptions(required=True, search_query=False)`	Required, agent name only.

Only required: true rejects requests. Optional fields are filled less often than required ones, but no paid call ever fails because of them.

Changed in @forgeintel/sdk 0.5.0-beta.17 and forgeintel-sdk 0.1.0b14: agent context used to be on (optional) by default, and true used to mean required. If you relied on the default, set agentContext: true. If you set true to require context, use { required: true }.

For JSON requests, callers send:

{
  "input": "business data",
  "agent_context": {
    "agent_type": "Codex",
    "search_query": "company enrichment API"
  }
}

For requests without a JSON body, callers can use agent_type and agent_search_query query parameters. Use direct as the search query when no search occurred. The SDK strips these fields before passing the request to your business handler. Before making context required on a live service, check that your paid clients can send it. Any agent name is accepted. Common spellings are normalized (Claude and claude-code are recorded as Claude Code), and other names are kept as given. When context is required, the field only has to be present and non-empty.

Where agents see it

Forge declares the field (as optional or required, matching your setting) everywhere an agent reads your service before paying:

OpenAPI: on paid operations in the document the SDK enriches.
The 402 challenge: in a forge-agent-context extension, for clients that print extensions.
Bazaar: if your route declares a bazaar extension, Forge adds the field to its schema, with a placeholder example so the extension stays valid and your listing stays in Bazaar. Payments are unaffected; x402 accepts extensions that gain fields. Forge never adds a Bazaar declaration you didn’t make.

The SDK also observes known client headers automatically; it does not need the caller to self-report a payment client name. How the SDK works.

In the dashboard

The service’s Activity page sorts every request into one caller type:

Agents: the request carried agent context, a known agent user-agent (such as Claude-User), or came from a detected agent wallet (awal, AgentCash, pay.sh or x402scan MCP). A wallet call without context is shown as “Unidentified agent” with its client; context adds the agent’s name and search query.
Crawlers and Monitors: known indexers and uptime probes, by user-agent.
Unidentified: everything else, such as plain node, curl or browser requests.

The categories add up to All callers.

Start

Integrate

Guides

Agent context

Where agents see it

In the dashboard

​Where agents see it

​In the dashboard

Where agents see it

In the dashboard