The Open Framework for Building Agents
feat(eve): allow OpenAI hosted web search on AI Gateway (#4555)
Ben Pankowf9b6d41daa8e
diff --git a/.changeset/gateway-openai-web-search.md b/.changeset/gateway-openai-web-search.mdnew file mode 100644index 000000000..38de51c2f--- /dev/null+++ b/.changeset/gateway-openai-web-search.md@@ -0,0 +1,5 @@+---+"eve": patch+---++`webSearch({ provider: "openai" })` selects OpenAI's hosted web search for OpenAI models routed through AI Gateway, so search runs server-side with URL citations instead of going to Exa. Other Gateway models don't get `web_search` with this setting unless you set `fallback`, for example `webSearch({ provider: "openai", fallback: "exa" })`.diff --git a/docs/concepts/built-in-tools.md b/docs/concepts/built-in-tools.mdindex b12cdd051..06e367167 100644--- a/docs/concepts/built-in-tools.md+++ b/docs/concepts/built-in-tools.md@@ -218,6 +218,22 @@ export default webSearch({ provider: "browserbase" });Use a [Gateway model ID](../agent-config#set-the-model) to route searches through Browserbase. AI Gateway executes the search using `AI_GATEWAY_API_KEY` or Vercel project OIDC credentials; no `BROWSERBASE_API_KEY` is needed. See [Browserbase Search on AI Gateway](https://vercel.com/docs/ai-gateway/models-and-providers/web-search#using-browserbase-search).+Select OpenAI's hosted web search for an OpenAI model routed through AI Gateway:++```ts title="agent/tools/web_search.ts"+import { webSearch } from "eve/tools/web_search";++export default webSearch({ provider: "openai" });+```++OpenAI runs the search server-side and returns URL citations, and AI Gateway uses its usual credentials, so no `OPENAI_API_KEY` is needed. OpenAI hosted search serves only OpenAI models, so any other Gateway model, including one picked by a dynamic model resolver, doesn't get `web_search`. eve picks the search tool from the requested model, so when AI Gateway's own `models` fallback serves a call with a non-OpenAI model, that call runs without search. Set `fallback` to give those models a provider that works with any Gateway model (`"exa"`, `"parallel"`, or `"browserbase"`):++```ts title="agent/tools/web_search.ts"+import { webSearch } from "eve/tools/web_search";++export default webSearch({ provider: "openai", fallback: "exa" });+```+The `provider` setting applies only to AI Gateway models. Unsupported direct providers omit `web_search`.Replace provider-managed search with an authored implementation:diff --git a/docs/reference/typescript-api.md b/docs/reference/typescript-api.mdindex 30f9eee77..165cff77b 100644--- a/docs/reference/typescript-api.md+++ b/docs/reference/typescript-api.md@@ -61,7 +61,7 @@ Tool-wide authoring helpers and types such as `defineTool`, `defineWorkflowTool``AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentLimitsDefinition` is exported for `defineAgent({ limits })`. `AgentWorkflowDefinition`, `AgentWorkflowRetentionDefinition`, and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape. `WebSearchToolInput` and `WebSearchProvider` are exported from `eve/tools/web_search`.-`webSearch({ provider })` selects `"exa"`, `"parallel"`, or `"browserbase"` for AI Gateway search using the Gateway model's credentials. Direct provider models keep their native search implementation when supported. See [Built-in tools](../concepts/built-in-tools#web_search) for setup and provider behavior.+`webSearch({ provider })` selects `"exa"`, `"parallel"`, `"browserbase"`, or `"openai"` for AI Gateway search using the Gateway model's credentials. `"openai"` applies only to OpenAI models; set `fallback` to `"exa"`, `"parallel"`, or `"browserbase"` to give other Gateway models search, which they otherwise don't get. Direct provider models keep their native search implementation when supported. See [Built-in tools](../concepts/built-in-tools#web_search) for setup and provider behavior.`defineInstructions` accepts `{ content: string, role?: "system" | "user" }`; omitted `role` means `"system"`. Its `eve/instructions` version of `defineDynamic` accepts only `session.started` and `turn.started` handlers returning `defineInstructions(...)` or `null`. The legacy `{ markdown: string }` definition remains available as a deprecated system-role form.diff --git a/packages/eve/extension-contracts/compatibility/tool/v82.ts b/packages/eve/extension-contracts/compatibility/tool/v82.tsnew file mode 100644index 000000000..b6b6dd714--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/tool/v82.ts@@ -0,0 +1,5 @@+import { webSearch } from "#public/tools/web-search.js";++// Epoch 82 web search accepted only exa, parallel, and browserbase; epoch 83+// adds provider "openai" with an optional fallback. Existing selections keep working.+export default webSearch({ provider: "parallel" });diff --git a/packages/eve/extension-contracts/reports/tool/v83.json b/packages/eve/extension-contracts/reports/tool/v83.jsonnew file mode 100644index 000000000..f0a454eff--- /dev/null+++ b/packages/eve/extension-contracts/reports/tool/v83.json@@ -0,0 +1,29 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "tool",+ "epoch": 83,+ "sha256": "d9f4c51c5843514c42b3fda3567a67c70fff4ed8a4e576b35315e9d61a465261",+ "exports": [+ "AgentRouterInput",+ "AgentRouterTool",+ "WorkflowStepToolContext",+ "WorkflowTool",+ "WorkflowToolDefinition",+ "WorkflowToolInput",+ "WorkflowToolOptions",+ "agentRouter",+ "decide",+ "defaultWebSearch",+ "defineTool",+ "defineWorkflowTool",+ "disableTool",+ "isDisabledToolSentinel",+ "isWebSearchToolDefinition",+ "serializeModelInputSchema",+ "toolOutput",+ "toolOutputPart",+ "toolResultFrom",+ "webSearch",+ "workflow"+ ]+}diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.tsindex 9982b5729..ed5551a62 100644--- a/packages/eve/src/compiler/extension-compatibility.ts+++ b/packages/eve/src/compiler/extension-compatibility.ts@@ -22,9 +22,9 @@ interface ExtensionCapabilityContract {const EXTENSION_CAPABILITY_CONTRACTS = {extension: { current: 1, supported: [1], dropped: {} },tool: {- current: 82,+ current: 83,supported: [- 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 29, 30, 31, 32, 34, 35, 76, 77, 78, 80, 81, 82,+ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 29, 30, 31, 32, 34, 35, 76, 77, 78, 80, 81, 82, 83,],dropped: {14: "TaskExec.delegated was removed; migrate to workflow-backed background tools",diff --git a/packages/eve/src/compiler/manifest.ts b/packages/eve/src/compiler/manifest.tsindex 5d875f1ee..2e0e398f3 100644--- a/packages/eve/src/compiler/manifest.ts+++ b/packages/eve/src/compiler/manifest.ts@@ -22,6 +22,7 @@ import type {SkillPackageSourceRef,} from "#shared/source-ref.js";import type { NamedSkillDefinition } from "#shared/skill-definition.js";+import { WEB_SEARCH_FALLBACK_PROVIDERS, WEB_SEARCH_PROVIDERS } from "#shared/web-search.js";import {AGENT_WORKFLOW_RETENTION_VALUES,type InternalAgentDefinition,@@ -847,8 +848,9 @@ const compiledToolBehaviorSchema: z.ZodType<CompiledToolBehavior> = z.strict(),z.object({+ fallback: z.enum(WEB_SEARCH_FALLBACK_PROVIDERS).optional(),kind: z.literal("provider-tool"),- provider: z.enum(["exa", "parallel", "browserbase"]),+ provider: z.enum(WEB_SEARCH_PROVIDERS),}).strict(),zdiff --git a/packages/eve/src/compiler/normalize-manifest.test.ts b/packages/eve/src/compiler/normalize-manifest.test.tsindex 3eded0de1..6343d1e76 100644--- a/packages/eve/src/compiler/normalize-manifest.test.ts+++ b/packages/eve/src/compiler/normalize-manifest.test.ts@@ -38,7 +38,7 @@ import { defineWorkflowTool } from "#tools/workflow-definition.js";import { defineTool, disableTool } from "#tools/definition.js";import { defineMemory } from "#public/memory/index.js";import { defineDynamic } from "#dynamic/definition.js";-import { webSearch } from "#tools/provided/web-search.js";+import { webSearch, type WebSearchToolInput } from "#tools/provided/web-search.js";import { agent as agentTool } from "#tools/framework/agent.js";function manifest() {@@ -320,13 +320,17 @@ describe("compileAgentManifest source graph", () => {});});- it.each(["parallel", "browserbase"] as const)(- "preserves %s search through serialization and runtime preparation",- async (provider) => {+ it.each<WebSearchToolInput>([+ { provider: "parallel" },+ { provider: "browserbase" },+ { fallback: "exa", provider: "openai" },+ ])(+ "preserves the %o search selection through serialization and runtime preparation",+ async (selection) => {const sourceRegistry = registry([{logicalPath: "tools/web_search.ts",- loadNamespace: async () => ({ default: webSearch({ provider }) }),+ loadNamespace: async () => ({ default: webSearch(selection) }),},]);const compiled = await compileAgentManifest(manifest(), {@@ -345,7 +349,7 @@ describe("compileAgentManifest source graph", () => {expect(serialized.tools.find((tool) => tool.name === "web_search")).toMatchObject({behavior: {availability: [],- handling: { kind: "provider-tool", provider },+ handling: { kind: "provider-tool", ...selection },},hasExecute: false,});@@ -357,7 +361,7 @@ describe("compileAgentManifest source graph", () => {});expect(graph.root.turnAgent.tools.find((tool) => tool.name === "web_search")).toMatchObject({behavior: {- handling: { kind: "provider-tool", provider },+ handling: { kind: "provider-tool", ...selection },},});},diff --git a/packages/eve/src/compiler/normalize-tool.ts b/packages/eve/src/compiler/normalize-tool.tsindex 01d5b5397..75f4f0ba4 100644--- a/packages/eve/src/compiler/normalize-tool.ts+++ b/packages/eve/src/compiler/normalize-tool.ts@@ -76,7 +76,7 @@ export async function compileToolEntry(definition: {behavior: {availability: [],- handling: { kind: "provider-tool", provider: entry.provider },+ handling: { kind: "provider-tool", ...entry.selection },},description:"Search the web for real-time information. Use this to find up-to-date information about current events, recent developments, or topics that may have changed since the knowledge cutoff.",diff --git a/packages/eve/src/harness/provider-tools.test.ts b/packages/eve/src/harness/provider-tools.test.tsindex 923b89eff..88be9f42f 100644--- a/packages/eve/src/harness/provider-tools.test.ts+++ b/packages/eve/src/harness/provider-tools.test.ts@@ -3,6 +3,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";import { MockLanguageModelV3 } from "ai/test";import { resolveModelProfile } from "#harness/model-profile.js";+import type { WebSearchSelection } from "#shared/web-search.js";import {WEB_SEARCH_ANTHROPIC_OUTPUT_SCHEMA,WEB_SEARCH_EXA_OUTPUT_SCHEMA,@@ -89,12 +90,16 @@ describe("resolveWebSearchBackend", () => {openaiWebSearch.mockClear();});- it.each([+ it.each<[string, WebSearchSelection | undefined, string | null]>([["openai/gpt-5.4", undefined, "exa"],- ["openai/gpt-5.4", "parallel", "parallel"],+ ["openai/gpt-5.4", { provider: "parallel" }, "parallel"],+ ["openai/gpt-5.4", { provider: "openai" }, "openai"],["anthropic/claude-opus-4.6", undefined, "exa"],- ] as const)("uses Gateway search for Gateway model %s", (model, provider, expected) => {- expect(resolveWebSearchBackend(resolveModelProfile(model), provider)).toBe(expected);+ // OpenAI's hosted search serves only OpenAI models: other models use the fallback, if any.+ ["anthropic/claude-opus-4.6", { provider: "openai" }, null],+ ["anthropic/claude-opus-4.6", { fallback: "parallel", provider: "openai" }, "parallel"],+ ])("uses Gateway search for Gateway model %s with %o", (model, selection, expected) => {+ expect(resolveWebSearchBackend(resolveModelProfile(model), selection)).toBe(expected);});it.each([@@ -105,7 +110,7 @@ describe("resolveWebSearchBackend", () => {["some-provider", null],] as const)("uses native search for direct provider %s when it has one", (provider, expected) => {const model = new MockLanguageModelV3({ provider });- expect(resolveWebSearchBackend(resolveModelProfile(model), "exa")).toBe(expected);+ expect(resolveWebSearchBackend(resolveModelProfile(model))).toBe(expected);});it("uses Anthropic webSearch_20250305 to avoid the unsupported beta header", async () => {diff --git a/packages/eve/src/harness/provider-tools.ts b/packages/eve/src/harness/provider-tools.tsindex 2bdfb38e1..57a4876f2 100644--- a/packages/eve/src/harness/provider-tools.ts+++ b/packages/eve/src/harness/provider-tools.ts@@ -10,7 +10,7 @@ import {WEB_SEARCH_TOOL_NAME,} from "#harness/provider-tool-schemas.js";import type { JsonObject } from "#shared/json.js";-import type { WebSearchProvider } from "#shared/web-search.js";+import type { WebSearchSelection } from "#shared/web-search.js";/*** The provider backend resolved for one web search tool invocation.@@ -71,15 +71,20 @@ export function resolveWebSearchOutputSchema(}/**- * Determines the web search backend for a model: the configured search provider (Exa by- * default) on AI Gateway, the provider's native search for direct OpenAI, Anthropic, and Google- * models, and none (`null`) for any other direct model.+ * Determines the web search backend for a model: the selected search provider on AI Gateway+ * (Exa by default), or its fallback when the provider can't serve the model; the provider's+ * native search for direct OpenAI, Anthropic, and Google models; and none (`null`) otherwise.*/export function resolveWebSearchBackend(profile: ModelProfile,- gatewayProvider: WebSearchProvider = "exa",+ selection: WebSearchSelection = { provider: "exa" },): WebSearchBackend | null {- if (profile.gateway) return gatewayProvider;+ if (profile.gateway) {+ // OpenAI's hosted search serves only OpenAI models.+ return selection.provider === "openai" && profile.provider !== "openai"+ ? (selection.fallback ?? null)+ : selection.provider;+ }return NATIVE_WEB_SEARCH_PROVIDERS.has(profile.provider)? (profile.provider as WebSearchBackend): null;diff --git a/packages/eve/src/harness/tools.ts b/packages/eve/src/harness/tools.tsindex b2ee0f3f0..7a91a4426 100644--- a/packages/eve/src/harness/tools.ts+++ b/packages/eve/src/harness/tools.ts@@ -14,11 +14,14 @@ import { stashToolInterrupt } from "#harness/tool-interrupts.js";import { isApprovedToolCall, markApprovalRecheck } from "#harness/approval-recheck.js";import { toModelSchema } from "#tools/schema.js";import { normalizeToolJsonOutput } from "#harness/tool-model-output.js";+import { createLogger } from "#internal/logging.js";import type { ToolExecuteOptions } from "#tools/definition.js";import { isAsyncIterable } from "#shared/async-iterable.js";import { executeWithToolStub } from "#tool-stubs/execute.js";import { iterateAsApprover, runAsApprover } from "#harness/hitl/approved-call-callers.js";+const log = createLogger("harness.tools");+/*** Builds an AI SDK `ToolSet` from unified harness tool definitions, described* by `describe`. Each call's output is projected by the entry `resolve`@@ -186,8 +189,14 @@ export async function buildToolSetWithProviderTools(input: {definition.execute === undefined &&!disabled?.has(definition.name)) {- const backend = resolveWebSearchBackend(input.profile, handling.provider);+ const backend = resolveWebSearchBackend(input.profile, handling);if (backend === null) {+ log.debug("model has no web search backend; leaving the tool out", {+ gateway: input.profile.gateway,+ modelProvider: input.profile.provider,+ searchProvider: handling.provider,+ tool: definition.name,+ });delete tools[definition.name];} else {tools[definition.name] = await resolveWebSearchProviderTool(backend);diff --git a/packages/eve/src/internal/authored-definition/schema-backed.test.ts b/packages/eve/src/internal/authored-definition/schema-backed.test.tsindex 93c909171..0033c3260 100644--- a/packages/eve/src/internal/authored-definition/schema-backed.test.ts+++ b/packages/eve/src/internal/authored-definition/schema-backed.test.ts@@ -115,16 +115,40 @@ describe("normalizeToolDefinition", () => {expect(entry).toEqual({ kind: "disabled" });});- it.each(["exa", "parallel", "browserbase"] as const)(+ it.each(["exa", "parallel", "browserbase", "openai"] as const)("normalizes the %s web search provider",(provider) => {expect(normalizeToolDefinition(webSearch({ provider }), FAILURE_MESSAGE)).toEqual({kind: "web-search-tool",- provider,+ selection: { provider },});},);+ it("normalizes a web search fallback provider", () => {+ expect(+ normalizeToolDefinition(webSearch({ fallback: "exa", provider: "openai" }), FAILURE_MESSAGE),+ ).toEqual({ kind: "web-search-tool", selection: { fallback: "exa", provider: "openai" } });+ });++ it("rejects a fallback that can't serve every Gateway model", () => {+ expect(() =>+ normalizeToolDefinition(+ { fallback: "openai", kind: "eve:web-search-tool", provider: "openai" },+ FAILURE_MESSAGE,+ ),+ ).toThrow('Expected "fallback" to be one of: exa, parallel, browserbase');+ });++ it("rejects a fallback for a provider that serves every Gateway model", () => {+ expect(() =>+ normalizeToolDefinition(+ { fallback: "parallel", kind: "eve:web-search-tool", provider: "exa" },+ FAILURE_MESSAGE,+ ),+ ).toThrow('"fallback" applies only to provider "openai"');+ });+it("rejects an unsupported web search provider", () => {expect(() =>normalizeToolDefinition({ kind: "eve:web-search-tool", provider: "other" }, FAILURE_MESSAGE),diff --git a/packages/eve/src/internal/authored-definition/schema-backed.ts b/packages/eve/src/internal/authored-definition/schema-backed.tsindex 3ff2ba976..6ec2c3933 100644--- a/packages/eve/src/internal/authored-definition/schema-backed.ts+++ b/packages/eve/src/internal/authored-definition/schema-backed.ts@@ -9,7 +9,11 @@ import { isObject } from "#shared/guards.js";import type { JsonObject } from "#shared/json.js";import { isDisabledToolSentinel } from "#tools/definition.js";import { isWebSearchToolDefinition } from "#tools/provided/web-search.js";-import type { WebSearchProvider } from "#shared/web-search.js";+import {+ WEB_SEARCH_FALLBACK_PROVIDERS,+ WEB_SEARCH_PROVIDERS,+ type WebSearchSelection,+} from "#shared/web-search.js";import {expectBoolean,expectFunction,@@ -78,7 +82,7 @@ type MutableNormalizedAuthoredTool = {type NormalizedToolEntry =| { readonly kind: "tool"; readonly definition: NormalizedAuthoredTool }| { readonly kind: "disabled" }- | { readonly kind: "web-search-tool"; readonly provider: WebSearchProvider }+ | { readonly kind: "web-search-tool"; readonly selection: WebSearchSelection }| {readonly kind: "dynamic-tool";readonly eventNames: readonly DynamicToolEventName[];@@ -111,12 +115,23 @@ export function normalizeToolDefinition(value: unknown, message: string): Normal`${message} Provider tools can't be deferred: the provider has to see their definition. Remove "deferred".`,);}- expectOnlyKnownKeys(record, ["kind", "provider"], message);- const provider = expectString(record.provider, message);- if (provider !== "exa" && provider !== "parallel" && provider !== "browserbase") {- throw new Error(`${message} Expected "provider" to be one of: exa, parallel, browserbase.`);+ expectOnlyKnownKeys(record, ["fallback", "kind", "provider"], message);+ const provider = expectOneOf(record.provider, WEB_SEARCH_PROVIDERS, "provider", message);+ if (record.fallback === undefined) {+ return { kind: "web-search-tool", selection: { provider } };}- return { kind: "web-search-tool", provider };+ if (provider !== "openai") {+ throw new Error(+ `${message} "fallback" applies only to provider "openai"; provider "${provider}" serves every AI Gateway model.`,+ );+ }+ const fallback = expectOneOf(+ record.fallback,+ WEB_SEARCH_FALLBACK_PROVIDERS,+ "fallback",+ message,+ );+ return { kind: "web-search-tool", selection: { fallback, provider } };}const record = expectObjectRecord(value, message);@@ -273,3 +288,16 @@ function assertNoOwnTaskIdInput(inputSchema: JsonObject | null, message: string)`${message} inputSchema declares "${TASK_ID_INPUT}", which eve adds to a serve tool's model input to send a call to a running task. Rename the field.`,);}++function expectOneOf<const T extends string>(+ value: unknown,+ allowed: readonly T[],+ field: string,+ message: string,+): T {+ const text = expectString(value, message);+ if (!(allowed as readonly string[]).includes(text)) {+ throw new Error(`${message} Expected "${field}" to be one of: ${allowed.join(", ")}.`);+ }+ return text as T;+}diff --git a/packages/eve/src/public/tools/web-search.ts b/packages/eve/src/public/tools/web-search.tsindex 2d68f3114..117cd14de 100644--- a/packages/eve/src/public/tools/web-search.ts+++ b/packages/eve/src/public/tools/web-search.ts@@ -1,6 +1,7 @@import webSearchDefinition from "#tools/provided/web-search.js";export {+ type WebSearchFallbackProvider,type WebSearchProvider,type WebSearchToolDefinition,type WebSearchToolInput,diff --git a/packages/eve/src/shared/web-search.ts b/packages/eve/src/shared/web-search.tsindex 74746077d..721ad31ac 100644--- a/packages/eve/src/shared/web-search.ts+++ b/packages/eve/src/shared/web-search.ts@@ -1,2 +1,19 @@-/** Web search providers available through Vercel AI Gateway. */-export type WebSearchProvider = "exa" | "parallel" | "browserbase";+/** Web search providers that AI Gateway runs for any Gateway model. */+export const WEB_SEARCH_FALLBACK_PROVIDERS = ["exa", "parallel", "browserbase"] as const;++/**+ * Web search providers available through Vercel AI Gateway. `openai` is OpenAI's hosted search,+ * which serves only OpenAI models.+ */+export const WEB_SEARCH_PROVIDERS = [...WEB_SEARCH_FALLBACK_PROVIDERS, "openai"] as const;++export type WebSearchProvider = (typeof WEB_SEARCH_PROVIDERS)[number];++export type WebSearchFallbackProvider = (typeof WEB_SEARCH_FALLBACK_PROVIDERS)[number];++/** The Gateway search an agent selected, and what a model the provider can't serve uses instead. */+export interface WebSearchSelection {+ readonly provider: WebSearchProvider;+ /** Used when `provider` can't serve the model; without it, that model gets no `web_search`. */+ readonly fallback?: WebSearchFallbackProvider;+}diff --git a/packages/eve/src/tools/behavior.ts b/packages/eve/src/tools/behavior.tsindex 464306a1a..06df80b29 100644--- a/packages/eve/src/tools/behavior.ts+++ b/packages/eve/src/tools/behavior.ts@@ -1,4 +1,4 @@-import type { WebSearchProvider } from "#shared/web-search.js";+import type { WebSearchSelection } from "#shared/web-search.js";import type { WorkflowToolEntryPoint } from "#tools/workflow-entry-point.js";/** Session facts that can hide a selected tool without changing source composition. */@@ -7,7 +7,7 @@ export type ToolAvailabilityCondition = "root-session";/** Native behavior declared by a selected compiled tool. */export type CompiledToolHandling =| { readonly kind: "dispatch"; readonly action: "self-agent" }- | { readonly kind: "provider-tool"; readonly provider: WebSearchProvider }+ | ({ readonly kind: "provider-tool" } & WebSearchSelection)| {readonly kind: "workflow-tool";readonly entryPoint: WorkflowToolEntryPoint;diff --git a/packages/eve/src/tools/provided/web-search.ts b/packages/eve/src/tools/provided/web-search.tsindex 81e7910e3..1c92ac740 100644--- a/packages/eve/src/tools/provided/web-search.ts+++ b/packages/eve/src/tools/provided/web-search.ts@@ -1,15 +1,26 @@-import type { WebSearchProvider } from "#shared/web-search.js";+import type { WebSearchFallbackProvider, WebSearchProvider } from "#shared/web-search.js";import { frameworkTool } from "./framework-tool.js";-export type { WebSearchProvider };+export type { WebSearchFallbackProvider, WebSearchProvider };const WEB_SEARCH_TOOL_KIND = "eve:web-search-tool";-/** Configuration accepted by {@link webSearch}. */-export interface WebSearchToolInput {- /** Provider to use when the agent model is routed through AI Gateway. */- readonly provider: WebSearchProvider;-}+/**+ * Configuration accepted by {@link webSearch}: the provider to use when the agent model is routed+ * through AI Gateway.+ */+export type WebSearchToolInput =+ | {+ /** OpenAI's hosted search, which serves only OpenAI models. */+ readonly provider: "openai";+ /** Provider for non-OpenAI Gateway models. Without it, those models don't get `web_search`. */+ readonly fallback?: WebSearchFallbackProvider;+ }+ | {+ /** A search provider that AI Gateway runs for any Gateway model. */+ readonly provider: WebSearchFallbackProvider;+ readonly fallback?: never;+ };/*** Provider-managed web search configuration.@@ -21,6 +32,7 @@ export interface WebSearchToolInput {export interface WebSearchToolDefinition {readonly kind: typeof WEB_SEARCH_TOOL_KIND;readonly provider: WebSearchProvider;+ readonly fallback?: WebSearchFallbackProvider;}/**@@ -41,6 +53,7 @@ export function webSearch(input: WebSearchToolInput): WebSearchToolDefinition {return frameworkTool({kind: WEB_SEARCH_TOOL_KIND,provider: input.provider,+ ...(input.fallback !== undefined && { fallback: input.fallback }),});}