Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
index 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.md
index 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.ts
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
index 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.ts
index 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(),
z
diff --git a/packages/eve/src/compiler/normalize-manifest.test.ts b/packages/eve/src/compiler/normalize-manifest.test.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 }),
});
}