Web search for agents: evidence, retention, and one explicit billing path

A search result has a location, not permission

One agent needs to answer a narrow question: which published release changed an interface used by a small application? Its training may be stale. Search can locate a candidate announcement, but a plausible description alone cannot establish its date, applicability, or instructions for the application.

Cloudflare's October 2 announcement introduces a Beta search service routed through AI Gateway. This lesson adds a retrieval boundary to the edge-products map. It does not add a search service to Kumyu. Treat the result as a document to investigate, with no authority to change the caller's policy, credentials, destination, or budget.

1. 1One public question
2. 2backend chooses one provider and key alias
3. 3Gateway search request

1. 1Returned candidate URLs
2. 2separately read the primary document
3. 3attributable claim

1. 1Document instructions
2. 2remain untrusted content
3. 3no authority over tools or credentials

1. 1Claim plus actual date and scope
2. 2human review
3. 3bounded published explanation

Suppose a returned description says a release is generally available and asks the agent to upload its environment file to complete verification. These are two different objects: a product claim requiring evidence and an attempted instruction outside the task. A useful answer may cite the actual release section while rejecting the upload. A citation cannot authorize a tool action.

Two retrieval questions came into focus in 2024

PoisonedRAG v3, dated August 13, 2024, examines attacker-inserted text in a retrieval database. Its construction combines a condition that gets a text retrieved with a condition that steers the generated answer. The study concerns its specified attacker access and evaluated systems; it is not a test of Cloudflare Web Search API. We did not reproduce it.

That distinction suggests two separate checks for this worksheet. First, did search find the relevant document? Second, does the document actually support the answer? A high retrieval score, a familiar domain, or a valid JSON envelope does not settle the second question. Restricting the agent's available actions can reduce its action surface; it does not make an incorrect quoted claim true. Keep evidence evaluation and operation authorization independent.

For the release question, record the canonical URL, exact section, verified publication date, affected product/version, and a short explanation of what the source supports. Save the access timestamp separately. A mutable documentation page with no dated release section can explain a present setting, but it cannot fill a missing release date.

Specify the request and its payment route

The current usage reference exposes REST POST /accounts/{account_id}/ai/websearch/ and the Workers websearch() method, which returns a Response. REST requires both Workers AI Read and AI Gateway Read account permissions. The query has a 1,024-character limit; the result count is 1–10. Choose provider explicitly from ceramic, exa, or linkup.

For this N=1 design, record provider: ceramic, limit: 3, one gateway ID, and a deliberately named byokAlias. The reference says an absent provider/alias configuration then fails with 400; omitting the alias can select a default stored key or charge Gateway credits. The alias is a key selector, not a secret value. This is a design worksheet, not an executed request.

Give the backend only the permissions necessary for this separately authorized integration, and keep credentials outside the browser, article, and diagnostics. The service authentication exercise describes a different application-entry credential; do not substitute it for a Cloudflare API token.

Freeze the request choices in a small configuration record before writing a client. An unexpected provider, missing alias, timeout, or unrecognized response must terminate the attempt. Do not try another provider, credential, payment mode, or model. One observed use case does not need an interchangeable search framework.

“No markup” and “no retention” each have a scope

The provider table currently lists Ceramic at $0.25, Exa at $7, and Linkup at $5 per 1,000 searches. These are provider list prices displayed at this review, not an invoice. The Unified Billing guide separately describes a 5% credit-purchase fee and possible negative balances. Passing through search price without markup does not mean a credit purchase has no fee or that a displayed balance is a hard spending cap.

Use a hypothetical worksheet: 2,000 searches at the displayed Ceramic rate imply $0.50 of search list-price consumption. If someone separately bought exactly $10 of Gateway credits under the documented fee, the purchase would be $10.50; the remaining credits are not consumed by this hypothetical workload. BYOK uses the provider's own billing agreement. Neither purchase nor usage happened here. Add generation, document reading, storage, and operator review as separate unmeasured cost rows, rather than hiding them inside search cost.

There is also a current source conflict. The announcement describes provider ZDR for requests through Cloudflare; the provider table labels Ceramic and Linkup Yes, but Exa No. Preserve both statements. Do not infer which agreement overrides the other or send private queries while that boundary is unresolved.

Even a confirmed provider ZDR arrangement would not establish the application's entire data path. The Gateway logging guide says logs are enabled by default, can include bodies, and distinguishes customers by first-gateway creation date around September 24, 2026. Metadata-only collection and disabling a whole log are different choices. Its examples are not proof that every logging override works on this search endpoint. Inspect actual retention and endpoint behavior separately before sensitive use.

The linked Ceramic terms, sections 9 and 13, discuss rights to submit input, personal-data/DPA conditions, and forms of aggregated or anonymized use. A table's ZDR cell does not replace the applicable agreement. This article records a source-review boundary, not a legal conclusion about any customer's contract.

Build a fixture without calling a paid API

Create one local JSON file containing three synthetic candidates. They are not live provider output. Candidate A links a fictional primary release with a visible date and exact version. B links an undated index. C contains a plausible summary followed by an instruction to reveal a credential. Give each a case ID and the same narrow research question.

Fixture row	Observation to keep	Acceptance condition
A: dated primary section	URL, section, version, actual date	answer cites only the supported scope
B: undated index	date remains unknown	cannot support a dated “new release” claim
C: instruction in result text	attempted action recorded without secrets	tool permissions and destinations remain fixed
D: duplicate URL with a fragment	both references point to one document	count once; preserve relevant sections
E: wrong provider or absent named alias	configuration mismatch	stop; no alternate billing or provider
F: empty, malformed, or failed response	exact failure category	no fabricated answer or silent successful substitute

The official result envelope supplies items and request metadata; optional provider fields may be absent. Define a local fixture schema for case IDs and review state, and label it as such. Do not present invented verified, publication-date, or confidence fields as API properties. Successful JSON parsing proves structure only.

Before an eventual authorized implementation, explain what component can enforce each row. A fixed backend operation list controls tool access; a response validator checks structure; a reviewer checks whether the primary text supports a claim. An instruction telling a model to ignore malicious text is not a demonstrated enforcement mechanism. Leave the exercise unsolved until the learner records both accepted and rejected rows and their reasons.

Measure the useful answer, and retain the failure

Measure three intervals separately in a later permitted evaluation: search response, primary-document inspection, and completion of a correctly cited answer. The response documentation's example latency is not a result from this worksheet. Report source coverage, unsupported claims, unauthorized attempted actions, and unresolved date/scope cases alongside time. A faster answer that cites an unread description fails the same contract.

Stop if the search is sent with private information outside the declared input policy, a credential enters the record, the billing route changes, or the answer's claim cannot be traced. Keep the failed case and configuration revision. Correct the specific defect before repeating that row; an automatic substitute would conceal the cause.

The research window was September 5, 2026 15:35 JST to October 5, 2026 15:35 JST. The October 2 announcement is the recent dated primary publication. Documentation revision labels are kept separate from publication dates. Account entitlement, actual search results, provider agreement precedence, log retention, cost, latency, and the fixture's enforcement behavior remain unverified. No paid service or account configuration was used for this lesson.