Backdated Web Tools - OpenReward

Introduction

BackSearchToolset gives an agent web search and page fetch bounded to a cutoff date — “the web as it existed on or before date X”. Every request carries an as_of date and the backing corpus only returns documents published on or before it. This is what makes the tools leakage-safe for evaluation and prediction tasks: an agent researching a question dated to the past never sees anything published after the cutoff. There are two ways to use it:

As an environment toolset — declare BackSearchToolset and the agent gets web_search / web_fetch tools.
Standalone — call Backsearch / Backfetch directly from any Python or agent loop, no environment required.

Requires openreward >= 0.1.134. The web tools authenticate with your standard OPENREWARD_API_KEY — no separate key is needed.

Configuration

The only required setting is your OpenReward API key (the same key the rest of the SDK uses). In a hosted environment it is forwarded automatically as a session secret.

export OPENREWARD_API_KEY="or_xxxxxxxx"

Variable	Required	Purpose
`OPENREWARD_API_KEY`	yes	Your OpenReward API key (the web service uses the same key)
`OPENREWARD_WEB_AS_OF`	no	Default cutoff date (ISO `YYYY-MM-DD`); a per-call or per-env `as_of` overrides it
`OPENREWARD_WEB_SEARCH_URL` / `OPENREWARD_WEB_FETCH_URL` / `OPENREWARD_WEB_DOMAIN_INFO_URL`	no	Override backend endpoints (default: `https://search.openreward.ai/*`)
`OPENREWARD_WEB_SKIP_PREFLIGHT`	no	Set to `1` to skip the domain-policy preflight
`OPENREWARD_WEB_PREAPPROVED_HOSTS`	no	Comma-separated hosts whose fetched content is returned verbatim

Search runs over a fixed historical corpus. Choose as_of dates inside the covered window — dates outside it return no results. Confirm the current coverage with the OpenReward team.

Using the toolset in an environment

Declare BackSearchToolset at class level. Unlike the harness toolsets, it is not sandbox-backed — it talks to the web service over HTTP — so your environment does not need a self.sandbox.

from openreward.environments import Environment, Split, TextBlock
from openreward.toolsets import BackSearchToolset

class ResearchEnv(Environment):
    toolsets = [BackSearchToolset]

    # Optional cutoff. May be a plain attribute, a @property, or a zero-arg
    # callable — it is read live on every tool call (see "Progressing the
    # cutoff" below).
    web_as_of = "2025-12-01"

    @classmethod
    def list_splits(cls):
        return [Split(name="test", type="test")]

    @classmethod
    def list_tasks(cls, split):
        return [{"id": "1", "question": "What happened with X in late 2025?"}]

    def get_prompt(self):
        return [TextBlock(text="Research the question using web_search and web_fetch, then answer with sources.")]

The agent then sees two tools:

Tool	Input	Output
`web_search`	`query` (≥ 2 chars), optional `allowed_domains` or `blocked_domains` (never both)	A `Links:` list of `{title, url}` sources plus a reminder to cite them
`web_fetch`	`url`, `prompt`	Extracted page text (or a `REDIRECT DETECTED` notice to re-call with the new URL)

Selecting it by name in a session

BackSearchToolset is a registered built-in, so a client can also attach it to a session by name:

from openreward import OpenReward

or_client = OpenReward()
env = or_client.environments.get(name="MyOrg/ResearchEnv")
tasks = env.list_tasks(split="test")

with env.session(task=tasks[0], toolset="backsearch") as session:
    result = session.call_tool("web_search", {"query": "US interest rate decision December 2025"})
    print(result.blocks[0].text)

Composing with other toolsets

Because it needs no sandbox, BackSearchToolset composes cleanly with sandbox-backed toolsets — e.g. web research plus a file workspace:

from openreward.toolsets import BackSearchToolset, CLIToolset

class ResearchAndCodeEnv(Environment):
    toolsets = [BackSearchToolset, CLIToolset]
    # ... CLIToolset needs self.sandbox; BackSearchToolset does not ...

All tools from both toolsets are exposed, and the framework rejects duplicate tool names. BackSearchToolset uses web_search / web_fetch, which do not collide with the file/CLI toolsets.

Progressing the cutoff

The cutoff is resolved on every tool call, in priority order:

an explicit as_of= passed to the toolset constructor (a static pin), else
env.web_as_of, else
the OPENREWARD_WEB_AS_OF environment variable, else
the backend default (today).

Because env.web_as_of is read live — not snapshotted when the toolset is built — an environment whose simulated clock advances stays correctly bounded to its current day. Expose it as a @property or a callable:

class TimeSteppedEnv(Environment):
    toolsets = [BackSearchToolset]

    @property
    def web_as_of(self) -> str:
        return self.sim_clock.today().isoformat()   # advances as the task steps

This matters because the framework builds and caches one toolset instance per environment for the whole session — a construction-time snapshot would freeze the date at the first call.

Standalone usage

The same backdated search and fetch are available without an environment:

import asyncio
from openreward.tools import Backsearch, Backfetch

async def main():
    bs = Backsearch(as_of="2025-12-01")
    result = await bs.run("US interest rate decision December 2025")
    if result.ok:
        print(result.output)                 # citation-ready text
        for hit in result.data["hits"]:
            print(hit["title"], "->", hit["url"])

    bf = Backfetch(as_of="2025-12-01")
    page = await bf.run("https://example.com/article", "Summarise the key points")
    if page.ok:
        print(page.data["content"])

asyncio.run(main())

Both run(...) calls return a WebToolResult:

Field	Meaning
`.ok`	`True` on success, `False` on a recoverable error
`.output`	The string to show a model (the result, or an error message)
`.data`	Structured payload — search: `{query, hits, mode}`; fetch: `{url, prompt, content}`
`.error_code` / `.error_message`	Set when `.ok` is `False` (e.g. `not-configured`, `invalid-url`, `domain-blocked`)

Backsearch.run accepts allowed_domains / blocked_domains and a per-call as_of; Backfetch.run takes a url, a prompt, and a per-call as_of.

Notes

Citations. Search output is formatted so the model is reminded to cite the returned URLs as markdown links in its final answer.
Caching. Fetches are cached in-process for 15 minutes, keyed by (cutoff, url), so repeated fetches at the same cutoff are fast and never mix content across dates.
Soft errors. Bad inputs (unparseable URL, blocked domain, missing key) come back as a normal result with .ok == False and a clear message rather than as an exception, so an agent can read it and recover.

Next Steps

Using Toolsets

Compose document toolsets and build custom ones

Harness Toolsets

Expose agent-native CLI tool surfaces backed by a sandbox

Building Agentic Environments

Create sandbox-based environments from scratch

Keeping Secrets Secret

How API keys and secrets reach your environment

​Introduction

​Configuration

​Using the toolset in an environment

​Selecting it by name in a session

​Composing with other toolsets

​Progressing the cutoff

​Standalone usage

​Notes

​Next Steps

Using Toolsets

Harness Toolsets

Building Agentic Environments

Keeping Secrets Secret

Introduction

Configuration

Using the toolset in an environment

Selecting it by name in a session

Composing with other toolsets

Progressing the cutoff

Standalone usage

Notes

Next Steps