Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

feat: introduce built-in web search capabilities in TrueFoundry (#761)

Sujai Kumar Guptae4c4b56d8b8a
diff --git a/.changeset/20260916102001-regenerate-sdk-from-openapi.md b/.changeset/20260916102001-regenerate-sdk-from-openapi.md
new file mode 100644
index 000000000..efd8ff00f
--- /dev/null
+++ b/.changeset/20260916102001-regenerate-sdk-from-openapi.md
@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge-sdk": patch
+---
+
+Regenerate SDK from updated OpenAPI spec.
diff --git a/.changeset/web-search-provider.md b/.changeset/web-search-provider.md
new file mode 100644
index 000000000..f2e25e671
--- /dev/null
+++ b/.changeset/web-search-provider.md
@@ -0,0 +1,6 @@
+---
+"@truefoundry/trueforge-core": minor
+"@truefoundry/trueforge": minor
+---
+
+Add built-in web search/fetch system tools (Parallel via `parallel-web`), gated by `AgentSpec.config.web_search` (default off) and TrueFoundry-mode host env `TRUEFOUNDRY_WEB_SEARCH_PROVIDER`. New drafts seed `web_search.enabled` from `/capabilities` when a provider is configured.
diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.json
index 1ae21eca9..4e1f73d07 100644
--- a/.github/fern/openapi/openapi.json
+++ b/.github/fern/openapi/openapi.json
@@ -502,12 +502,16 @@
},
"skill": {
"$ref": "#/components/schemas/SkillCapability"
+ },
+ "web_search": {
+ "$ref": "#/components/schemas/WebSearchCapability"
}
},
"required": [
"sandbox",
"skill",
- "settings"
+ "settings",
+ "web_search"
],
"type": "object"
},
@@ -3572,6 +3576,9 @@
"sandbox": {
"enabled": false,
"file_downloads": true
+ },
+ "web_search": {
+ "enabled": false
}
},
"properties": {
@@ -3596,6 +3603,9 @@
},
"sandbox": {
"$ref": "#/components/schemas/SandboxConfig"
+ },
+ "web_search": {
+ "$ref": "#/components/schemas/WebSearchConfig"
}
},
"type": "object"
@@ -5622,6 +5632,31 @@
],
"type": "object"
},
+ "WebSearchCapability": {
+ "properties": {
+ "enabled": {
+ "description": "Whether a host web-search provider is configured.",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "enabled"
+ ],
+ "type": "object"
+ },
+ "WebSearchConfig": {
+ "default": {
+ "enabled": false
+ },
+ "properties": {
+ "enabled": {
+ "default": false,
+ "description": "Enable built-in web search and fetch tools. Default: false (host must configure a provider).",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
"ZaiModelProvider": {
"additionalProperties": false,
"properties": {
diff --git a/docs/openapi.json b/docs/openapi.json
index 1ae21eca9..4e1f73d07 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -502,12 +502,16 @@
},
"skill": {
"$ref": "#/components/schemas/SkillCapability"
+ },
+ "web_search": {
+ "$ref": "#/components/schemas/WebSearchCapability"
}
},
"required": [
"sandbox",
"skill",
- "settings"
+ "settings",
+ "web_search"
],
"type": "object"
},
@@ -3572,6 +3576,9 @@
"sandbox": {
"enabled": false,
"file_downloads": true
+ },
+ "web_search": {
+ "enabled": false
}
},
"properties": {
@@ -3596,6 +3603,9 @@
},
"sandbox": {
"$ref": "#/components/schemas/SandboxConfig"
+ },
+ "web_search": {
+ "$ref": "#/components/schemas/WebSearchConfig"
}
},
"type": "object"
@@ -5622,6 +5632,31 @@
],
"type": "object"
},
+ "WebSearchCapability": {
+ "properties": {
+ "enabled": {
+ "description": "Whether a host web-search provider is configured.",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "enabled"
+ ],
+ "type": "object"
+ },
+ "WebSearchConfig": {
+ "default": {
+ "enabled": false
+ },
+ "properties": {
+ "enabled": {
+ "default": false,
+ "description": "Enable built-in web search and fetch tools. Default: false (host must configure a provider).",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
"ZaiModelProvider": {
"additionalProperties": false,
"properties": {
diff --git a/packages/trueforge-core/package.json b/packages/trueforge-core/package.json
index 44f04de67..b457bbbbf 100644
--- a/packages/trueforge-core/package.json
+++ b/packages/trueforge-core/package.json
@@ -116,6 +116,7 @@
"ai": "^7.0.82",
"dedent": "^1.7.2",
"openai": "^7.5.0",
+ "parallel-web": "^1.3.3",
"ulid": "^3.0.2",
"undici": "7.29.0",
"winston": "^3.19.0",
diff --git a/packages/trueforge-core/src/agent-session/ITurnResourceResolver.ts b/packages/trueforge-core/src/agent-session/ITurnResourceResolver.ts
index 585ef2d5f..791ab963e 100644
--- a/packages/trueforge-core/src/agent-session/ITurnResourceResolver.ts
+++ b/packages/trueforge-core/src/agent-session/ITurnResourceResolver.ts
@@ -4,6 +4,7 @@ import type { AgentDefinition } from '../core/runtime/AgentDefinition';
import type { AgentInfo } from '../core/runtime/AgentThread.types';
import type { Sandbox, SandboxInfo } from '../core/sandbox/Sandbox';
import type { AgentTracing } from '../core/tracing/AgentTracing';
+import type { IWebSearchProvider } from '../core/web-search/WebSearchProvider';
import type { TurnRecord } from './models/TurnRecord';
import type { AgentSpec } from './schemas/agentSpec';
@@ -18,6 +19,11 @@ export interface ResolvedAgentDefinition {
* per-request state (secrets, providers, caches) freely.
*/
export interface ITurnResourceResolver<TTurnCustom extends object = Record<string, never>> {
+ /**
+ * Host web-search backend. When set and `config.web_search.enabled`, builtins
+ * register search/fetch system tools. Omit when the host has no provider configured.
+ */
+ readonly webSearchProvider?: IWebSearchProvider | undefined;
/** Forwarded to AgentThread / orchestrator / RemoteMCP. */
readonly logger: Logger;
/** Called exactly once per run, before any other method. */
diff --git a/packages/trueforge-core/src/agent-session/SessionHandle.ts b/packages/trueforge-core/src/agent-session/SessionHandle.ts
index 1aad0297a..825a8f042 100644
--- a/packages/trueforge-core/src/agent-session/SessionHandle.ts
+++ b/packages/trueforge-core/src/agent-session/SessionHandle.ts
@@ -467,6 +467,7 @@ export class SessionHandle<
isChild,
sandboxAvailable: Boolean(input.sandbox),
tracing: input.tracing,
+ webSearchProvider: input.resolver.webSearchProvider,
logger: input.resolver.logger,
}),
...(extraCapabilities ?? []),
@@ -522,6 +523,7 @@ export class SessionHandle<
isChild: true,
sandboxAvailable: Boolean(input.sandbox),
tracing: input.tracing,
+ webSearchProvider: input.resolver.webSearchProvider,
logger: input.resolver.logger,
}),
...(extraCapabilities ?? []),
diff --git a/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts b/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts
index 0e097ed8f..8e6edaa78 100644
--- a/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts
+++ b/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts
@@ -9,6 +9,7 @@ import type { AgentInfo } from '../core/runtime/AgentThread.types';
import type { Sandbox, SandboxInfo } from '../core/sandbox/Sandbox';
import type { AgentTracing } from '../core/tracing/AgentTracing';
import { NOOP_AGENT_TRACING } from '../core/tracing/NoopAgentTracing';
+import type { IWebSearchProvider } from '../core/web-search/WebSearchProvider';
import type { ITurnResourceResolver, ResolvedAgentDefinition } from './ITurnResourceResolver';
import type { TurnRecord } from './models/TurnRecord';
import type { AgentSpec } from './schemas/agentSpec';
@@ -82,11 +83,17 @@ export class TurnResourceResolver<
* session is bound by reference; omit only if all sessions use inline agents.
*/
agent?: ((agentId: string) => Promise<AgentSpec>) | undefined;
+ /** Host web-search backend; omit when not configured. */
+ webSearchProvider?: IWebSearchProvider | undefined;
/** Forwarded to RemoteMCP / AgentThread (required by their constructors). */
logger: Logger;
},
) {}
+ get webSearchProvider(): IWebSearchProvider | undefined {
+ return this.deps.webSearchProvider;
+ }
+
get logger(): Logger {
return this.deps.logger;
}
diff --git a/packages/trueforge-core/src/agent-session/builtinsFromSpec.ts b/packages/trueforge-core/src/agent-session/builtinsFromSpec.ts
index 87ef04cc9..cb0139088 100644
--- a/packages/trueforge-core/src/agent-session/builtinsFromSpec.ts
+++ b/packages/trueforge-core/src/agent-session/builtinsFromSpec.ts
@@ -10,8 +10,10 @@ import { currentDateTime } from '../core/capabilities/builtins/CurrentDateTime';
import { dynamicSubAgents } from '../core/capabilities/builtins/DynamicSubAgents';
import { largeToolResponse } from '../core/capabilities/builtins/LargeToolResponse';
import { openUI } from '../core/capabilities/builtins/OpenUI';
+import { webSearch } from '../core/capabilities/builtins/WebSearch';
import type { AgentDefinition } from '../core/runtime/AgentDefinition';
import type { AgentTracing } from '../core/tracing/AgentTracing';
+import type { IWebSearchProvider } from '../core/web-search/WebSearchProvider';
import type { AgentSpec } from './schemas/agentSpec';
export function builtinsFromSpec(input: {
@@ -21,9 +23,10 @@ export function builtinsFromSpec(input: {
isChild: boolean;
sandboxAvailable: boolean;
tracing: AgentTracing;
+ webSearchProvider: IWebSearchProvider | undefined;
logger: Logger;
}): AgentCapability[] {
- const { spec, definition, isChild, sandboxAvailable, tracing, logger } = input;
+ const { spec, definition, isChild, sandboxAvailable, tracing, webSearchProvider, logger } = input;
const config = spec.config;
const capabilities: AgentCapability[] = [currentDateTime({ tracing })];
@@ -63,5 +66,9 @@ export function builtinsFromSpec(input: {
capabilities.push(openUI({ preload: false, tracing }));
}
+ if (webSearchProvider && config.web_search.enabled) {
+ capabilities.push(webSearch({ provider: webSearchProvider, tracing }));
+ }
+
return capabilities;
}
diff --git a/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts b/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts
index f6c126262..8aaa3c5d0 100644
--- a/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts
+++ b/packages/trueforge-core/src/agent-session/schemas/agentSpec.ts
@@ -198,6 +198,15 @@ const AskUserQuestionsConfigSchema = z
})
.openapi('AskUserQuestionsConfig');
+const WebSearchConfigSchema = z
+ .object({
+ enabled: z
+ .boolean()
+ .default(false)
+ .describe('Enable built-in web search and fetch tools. Default: false (host must configure a provider).'),
+ })
+ .openapi('WebSearchConfig');
+
export const RuntimeConfigSchema = z
.object({
iteration_limit: z
@@ -217,6 +226,7 @@ export const RuntimeConfigSchema = z
})),
generative_ui: GenerativeUIConfigSchema.default(() => ({ enabled: true })),
ask_user_questions: AskUserQuestionsConfigSchema.default(() => ({ enabled: true })),
+ web_search: WebSearchConfigSchema.default(() => ({ enabled: false })),
})
.openapi('RuntimeConfig');
diff --git a/packages/trueforge-core/src/core/capabilities/builtins/WebSearch.ts b/packages/trueforge-core/src/core/capabilities/builtins/WebSearch.ts
new file mode 100644
index 000000000..312e641d7
--- /dev/null
+++ b/packages/trueforge-core/src/core/capabilities/builtins/WebSearch.ts
@@ -0,0 +1,128 @@
+import dedent from 'dedent';
+import { z } from 'zod';
+import { InstructionBuilder } from '../../InstructionBuilder';
+import { type CallToolResponse, toolResultResponse } from '../../mcp/IMCPServer';
+import { defineTool, LocalToolMCP, type ToolDefinition } from '../../mcp/LocalToolMCP';
+import type { AgentTracing } from '../../tracing/AgentTracing';
+import type { IWebSearchProvider } from '../../web-search/WebSearchProvider';
+import type { AgentCapability } from '../AgentCapability';
+
+export const WEB_SEARCH_SERVER_ID = 'web-search';
+export const WEB_SEARCH_TOOL_NAME = 'web_search';
+export const WEB_FETCH_TOOL_NAME = 'web_fetch';
+export const WEB_SEARCH_REMINDER_TAG = 'web-search';
+
+const webSearchInputSchema = z
+ .object({
+ search_queries: z
+ .array(z.string().min(1))
+ .min(1)
+ .max(5)
+ .describe(
+ 'Keyword search queries (prefer 3–6 words each; 2–3 queries often beat one long query). Operators such as site:domain, filetype:pdf, intitle:word, -term, and "exact phrase" may work when the backend supports them.',
+ ),
+ objective: z
+ .string()
+ .min(1)
+ .optional()
+ .describe('Natural-language goal for the search. Helps the backend focus hits when provided.'),
+ })
+ .strict();
+
+const webFetchInputSchema = z
+ .object({
+ urls: z
+ .array(z.url())
+ .min(1)
+ .max(5)
+ .describe('Page URLs to extract (up to 5). Prefer specific hit URLs from web_search.'),
+ objective: z
+ .string()
+ .min(1)
+ .optional()
+ .describe('Optional goal used to focus extracted excerpts when the page is large.'),
+ })
+ .strict();
+
+/** What the tool does — param details live on the Zod schema `.describe`s. */
+const WEB_SEARCH_TOOL_DESCRIPTION =
+ 'Search the web. Returns ranked hits with titles, URLs, and snippets. Prefer concise keyword queries; use multiple related queries in one call when useful.';
+
+/** What the tool does — param details live on the Zod schema `.describe`s. */
+const WEB_FETCH_TOOL_DESCRIPTION = `Extract page content from URLs as markdown/text (no LLM summarization). Prefer specific hit URLs from ${WEB_SEARCH_TOOL_NAME} when snippets are not enough.`;
+
+/**
+ * Cross-tool policy (when / how to combine search + fetch).
+ * Per-tool behavior and params stay on tool descriptions / schema describes.
+ */
+export function buildWebSearchInstruction(builder: InstructionBuilder): void {
+ builder.addSection(
+ WEB_SEARCH_REMINDER_TAG,
+ dedent`
+ The Agent has two system tools for live web access: ${WEB_SEARCH_TOOL_NAME} (search) and ${WEB_FETCH_TOOL_NAME} (extract page content).
+
+ When to use them:
+ - The user asks to search, browse, verify, look up, or get latest information.
+ - Facts may have changed recently (news, prices, laws, schedules, product specs, software APIs/docs, people in roles, rates, scores).
+ - The answer needs direct quotes, links, or precise source attribution.
+ - A specific page, paper, dataset, or site is referenced and its contents were not provided.
+
+ How to use them:
+ - Start with ${WEB_SEARCH_TOOL_NAME} for discovery; follow with ${WEB_FETCH_TOOL_NAME} on the best URLs when snippets are not enough.
+ - Prefer primary and authoritative sources.
+ `.trim(),
+ );
+}
+
+export class WebSearchTools extends LocalToolMCP {
+ readonly name = WEB_SEARCH_SERVER_ID;
+ readonly displayName = 'WebSearch';
+ readonly #provider: IWebSearchProvider;
+
+ constructor(options: { provider: IWebSearchProvider; tracing: AgentTracing }) {
+ super({ tracing: options.tracing });
+ this.#provider = options.provider;
+ }
+
+ private tools: ToolDefinition[] = [
+ defineTool({
+ name: WEB_SEARCH_TOOL_NAME,
+ description: WEB_SEARCH_TOOL_DESCRIPTION,
+ schema: webSearchInputSchema,
+ handler: input => this.runSearch(input),
+ }),
+ defineTool({
+ name: WEB_FETCH_TOOL_NAME,
+ description: WEB_FETCH_TOOL_DESCRIPTION,
+ schema: webFetchInputSchema,
+ handler: input => this.runFetch(input),
+ }),
+ ];
+
+ protected getTools(): ToolDefinition[] {
+ return this.tools;
+ }
+
+ private async runSearch(input: z.infer<typeof webSearchInputSchema>): Promise<CallToolResponse> {
+ const result = await this.#provider.search({
+ search_queries: input.search_queries,
+ objective: input.objective,
+ });
+ return toolResultResponse({ text: JSON.stringify(result) });
+ }
+
+ private async runFetch(input: z.infer<typeof webFetchInputSchema>): Promise<CallToolResponse> {
+ const result = await this.#provider.fetch({
+ urls: input.urls,
+ objective: input.objective,
+ });
+ return toolResultResponse({ text: JSON.stringify(result) });
+ }
+}
+
+export function webSearch(options: { provider: IWebSearchProvider; tracing: AgentTracing }): AgentCapability {
+ return {
+ systemToolSets: [new WebSearchTools(options)],
+ instructionBuilders: [buildWebSearchInstruction],
+ };
+}
diff --git a/packages/trueforge-core/src/core/index.ts b/packages/trueforge-core/src/core/index.ts
index 76cafcf45..7b150ba91 100644
--- a/packages/trueforge-core/src/core/index.ts
+++ b/packages/trueforge-core/src/core/index.ts
@@ -46,6 +46,14 @@ export {
largeToolResponse,
} from './capabilities/builtins/LargeToolResponse';
export { openUI } from './capabilities/builtins/OpenUI';
+export {
+ WEB_FETCH_TOOL_NAME,
+ WEB_SEARCH_REMINDER_TAG,
+ WEB_SEARCH_SERVER_ID,
+ WEB_SEARCH_TOOL_NAME,
+ buildWebSearchInstruction,
+ webSearch,
+} from './capabilities/builtins/WebSearch';
// MCP contracts
export type { ApprovalDecision } from './events/schema';
@@ -174,6 +182,18 @@ export { SANDBOX_IMAGE_URI } from './sandbox/sandboxImage';
export { existingSandboxIdForProvider, formatSandboxId, parseSandboxId, rawSandboxId } from './sandbox/sandboxRef';
export type { SandboxRefParts } from './sandbox/sandboxRef';
+// Web search
+export { ParallelWebSearchProvider } from './web-search/ParallelWebSearchProvider';
+export type { ParallelSearchMode, ParallelWebSearchProviderOptions } from './web-search/ParallelWebSearchProvider';
+export { WebSearchProviders } from './web-search/WebSearchProvider';
+export type {
+ IWebSearchProvider,
+ WebFetchPage,
+ WebFetchPages,
+ WebSearchHit,
+ WebSearchHits,
+} from './web-search/WebSearchProvider';
+
// Skills: the ISkillMounter seam lets hosts plug in their own skill sources
export { InstructionBuilder } from './InstructionBuilder';
export { SKILLS_PREAMBLE, SkillMounter, getSkillPath, renderSkillPromptBody } from './sandbox/skills';
diff --git a/packages/trueforge-core/src/core/web-search/ParallelWebSearchProvider.ts b/packages/trueforge-core/src/core/web-search/ParallelWebSearchProvider.ts
new file mode 100644
index 000000000..af846a385
--- /dev/null
+++ b/packages/trueforge-core/src/core/web-search/ParallelWebSearchProvider.ts
@@ -0,0 +1,77 @@
+import Parallel from 'parallel-web';
+import {
+ WebSearchProviders,
+ type IWebSearchProvider,
+ type WebFetchPages,
+ type WebSearchHits,
+} from './WebSearchProvider';
+
+export type ParallelSearchMode = 'turbo' | 'fast' | 'basic' | 'advanced';
+
+/** Keep search payloads under the large-tool-response individual threshold (~6k tokens). */
+const PARALLEL_SEARCH_MAX_RESULTS = 5;
+const PARALLEL_SEARCH_MAX_CHARS_PER_RESULT = 500;
+const PARALLEL_SEARCH_MAX_CHARS_TOTAL = 4000;
+
+export interface ParallelWebSearchProviderOptions {
+ apiKey: string;
+ /** Parallel Search mode preset. Caller supplies the default (e.g. `turbo`). */
+ mode: ParallelSearchMode;
+}
+
+/**
+ * Parallel Search + Extract via the official `parallel-web` SDK.
+ */
+export class ParallelWebSearchProvider implements IWebSearchProvider {
+ readonly id = WebSearchProviders.Parallel;
+ readonly #client: Parallel;
+ readonly #mode: ParallelSearchMode;
+
+ constructor(options: ParallelWebSearchProviderOptions) {
+ this.#client = new Parallel({ apiKey: options.apiKey });
+ this.#mode = options.mode;
+ }
+
+ async search(input: { search_queries: string[]; objective: string | undefined }): Promise<WebSearchHits> {
+ const response = await this.#client.search({
+ search_queries: input.search_queries,
+ ...(input.objective ? { objective: input.objective } : {}),
+ mode: this.#mode,
+ max_chars_total: PARALLEL_SEARCH_MAX_CHARS_TOTAL,
+ advanced_settings: {
+ max_results: PARALLEL_SEARCH_MAX_RESULTS,
+ excerpt_settings: { max_chars_per_result: PARALLEL_SEARCH_MAX_CHARS_PER_RESULT },
+ },
+ });
+ return {
+ hits: response.results.map(result => ({
+ title: result.title ?? '',
+ url: result.url,
+ snippet: result.excerpts.join('\n\n'),
+ published_at: result.publish_date ?? null,
+ })),
+ };
+ }
+
+ async fetch(input: { urls: string[]; objective: string | undefined }): Promise<WebFetchPages> {
+ const response = await this.#client.extract({
+ urls: input.urls,
+ ...(input.objective ? { objective: input.objective } : {}),
+ });
+ const pages = [
+ ...response.results.map(result => ({
+ url: result.url,
+ title: result.title ?? null,
+ content: result.full_content ?? result.excerpts.join('\n\n'),
+ error: null,
+ })),
+ ...response.errors.map(err => ({
+ url: err.url,
+ title: null,
+ content: '',
+ error: err.content ?? err.error_type,
+ })),
+ ];
+ return { pages };
+ }
+}
diff --git a/packages/trueforge-core/src/core/web-search/WebSearchProvider.ts b/packages/trueforge-core/src/core/web-search/WebSearchProvider.ts
new file mode 100644
index 000000000..3c39cef7d
--- /dev/null
+++ b/packages/trueforge-core/src/core/web-search/WebSearchProvider.ts
@@ -0,0 +1,40 @@
+/** Supported host web-search backends (env `TRUEFOUNDRY_WEB_SEARCH_PROVIDER.name`). */
+export enum WebSearchProviders {
+ Parallel = 'parallel',
+}
+
+/** One search hit in the provider-normalized shape. */
+export interface WebSearchHit {
+ title: string;
+ url: string;
+ snippet: string;
+ published_at: string | null;
+}
+
+/** Normalized search response — stable across providers. */
+export interface WebSearchHits {
+ hits: WebSearchHit[];
+}
+
+/** One fetched page (or per-URL error) in the provider-normalized shape. */
+export interface WebFetchPage {
+ url: string;
+ title: string | null;
+ content: string;
+ error: string | null;
+}
+
+/** Normalized fetch/extract response — stable across providers. */
+export interface WebFetchPages {
+ pages: WebFetchPage[];
+}
+
+/**
+ * Host-supplied web search backend. Implementations map vendor APIs onto
+ * {@link WebSearchHits} / {@link WebFetchPages} so the capability tools stay provider-agnostic.
+ */
+export interface IWebSearchProvider {
+ readonly id: WebSearchProviders;
+ search(input: { search_queries: string[]; objective: string | undefined }): Promise<WebSearchHits>;
+ fetch(input: { urls: string[]; objective: string | undefined }): Promise<WebFetchPages>;
+}
diff --git a/packages/trueforge-core/tests/agent-session/agentSpecDefaults.test.ts b/packages/trueforge-core/tests/agent-session/agentSpecDefaults.test.ts
index f41c1e846..2b118f5ad 100644
--- a/packages/trueforge-core/tests/agent-session/agentSpecDefaults.test.ts
+++ b/packages/trueforge-core/tests/agent-session/agentSpecDefaults.test.ts
@@ -10,6 +10,7 @@ describe('AgentSpec RuntimeConfig defaults', () => {
expect(spec.config.dynamic_sub_agents).toEqual({ enabled: true });
expect(spec.config.context_management.compaction).toEqual({ enabled: true });
expect(spec.config.context_management.large_tool_response.enabled).toBe(true);
+ expect(spec.config.web_search).toEqual({ enabled: false });
});
it('accepts an explicit input-token compaction trigger', () => {
diff --git a/packages/trueforge-core/tests/agent-session/builtinsFromSpec.test.ts b/packages/trueforge-core/tests/agent-session/builtinsFromSpec.test.ts
index b8588461b..34663804c 100644
--- a/packages/trueforge-core/tests/agent-session/builtinsFromSpec.test.ts
+++ b/packages/trueforge-core/tests/agent-session/builtinsFromSpec.test.ts
@@ -5,8 +5,15 @@ import {
OPENUI_SERVER_ID,
buildOpenUIInstruction,
} from '../../src/core/capabilities/builtins/OpenUI';
+import {
+ WEB_FETCH_TOOL_NAME,
+ WEB_SEARCH_SERVER_ID,
+ WEB_SEARCH_TOOL_NAME,
+ buildWebSearchInstruction,
+} from '../../src/core/capabilities/builtins/WebSearch';
import type { AgentDefinition } from '../../src/core/runtime/AgentDefinition';
import { NOOP_AGENT_TRACING } from '../../src/core/tracing/NoopAgentTracing';
+import { WebSearchProviders, type IWebSearchProvider } from '../../src/core/web-search/WebSearchProvider';
import { makeMockILLM, makeSilentLogger } from '../core/harnessMocks';
function makeDefinition(): AgentDefinition {
@@ -18,6 +25,7 @@ function makeDefinition(): AgentDefinition {
function runBuiltins(input: {
spec: ReturnType<typeof AgentSpecSchema.parse>;
isChild?: boolean;
+ webSearchProvider?: Parameters<typeof builtinsFromSpec>[0]['webSearchProvider'];
}): ReturnType<typeof builtinsFromSpec> {
return builtinsFromSpec({
spec: input.spec,
@@ -25,6 +33,7 @@ function runBuiltins(input: {
isChild: input.isChild ?? false,
sandboxAvailable: false,
tracing: NOOP_AGENT_TRACING,
+ webSearchProvider: input.webSearchProvider,
logger: makeSilentLogger(),
});
}
@@ -99,3 +108,52 @@ describe('builtinsFromSpec generative_ui', () => {
expect(listed.result.tools.map(t => t.name)).toEqual([GET_OPENUI_INSTRUCTIONS_TOOL_NAME]);
});
});
+
+describe('builtinsFromSpec web_search', () => {
+ const provider: IWebSearchProvider = {
+ id: WebSearchProviders.Parallel,
+ search: () => Promise.resolve({ hits: [] }),
+ fetch: () => Promise.resolve({ pages: [] }),
+ };
+
+ it('omits web search tools when the provider is missing', () => {
+ const capabilities = runBuiltins({
+ spec: AgentSpecSchema.parse({
+ model: { name: 'provider/model' },
+ config: { web_search: { enabled: true } },
+ }),
+ });
+ expect(capabilities.some(cap => cap.systemToolSets?.some(ts => ts.name === WEB_SEARCH_SERVER_ID))).toBe(false);
+ });
+
+ it('omits web search tools when enabled is false', () => {
+ const capabilities = runBuiltins({
+ spec: AgentSpecSchema.parse({
+ model: { name: 'provider/model' },
+ config: { web_search: { enabled: false } },
+ }),
+ webSearchProvider: provider,
+ });
+ expect(capabilities.some(cap => cap.systemToolSets?.some(ts => ts.name === WEB_SEARCH_SERVER_ID))).toBe(false);
+ });
+
+ it('registers web_search and web_fetch with instruction guidance when enabled', async () => {
+ const capabilities = runBuiltins({
+ spec: AgentSpecSchema.parse({
+ model: { name: 'provider/model' },
+ config: { web_search: { enabled: true } },
+ }),
+ webSearchProvider: provider,
+ });
+ const webSearchCap = capabilities.find(cap => cap.systemToolSets?.some(ts => ts.name === WEB_SEARCH_SERVER_ID));
+ expect(webSearchCap?.instructionBuilders?.[0]).toBe(buildWebSearchInstruction);
+ const toolSet = webSearchCap?.systemToolSets?.find(ts => ts.name === WEB_SEARCH_SERVER_ID);
+ const listed = await toolSet?.listTools();
+ if (!listed || 'authRequired' in listed) {
+ throw new Error('expected listTools result');
+ }
+ expect(listed.result.tools.map(t => t.name)).toEqual([WEB_SEARCH_TOOL_NAME, WEB_FETCH_TOOL_NAME]);
+ expect(listed.result.tools[0]?.description).toContain('ranked hits');
+ expect(listed.result.tools[1]?.description).toContain('markdown/text');
+ });
+});
diff --git a/packages/trueforge-core/tests/core/capabilities/builtins/WebSearch.test.ts b/packages/trueforge-core/tests/core/capabilities/builtins/WebSearch.test.ts
new file mode 100644
index 000000000..c0d99860a
--- /dev/null
+++ b/packages/trueforge-core/tests/core/capabilities/builtins/WebSearch.test.ts
@@ -0,0 +1,20 @@
+import {
+ WEB_FETCH_TOOL_NAME,
+ WEB_SEARCH_REMINDER_TAG,
+ WEB_SEARCH_TOOL_NAME,
+ buildWebSearchInstruction,
+} from '../../../../src/core/capabilities/builtins/WebSearch';
+import { InstructionBuilder } from '../../../../src/core/InstructionBuilder';
+
+describe('buildWebSearchInstruction', () => {
+ it('adds when-to-search guidance referencing both tools', () => {
+ const builder = new InstructionBuilder('capabilities');
+ buildWebSearchInstruction(builder);
+ const text = builder.build();
+ expect(text).toContain(WEB_SEARCH_REMINDER_TAG);
+ expect(text).toContain(WEB_SEARCH_TOOL_NAME);
+ expect(text).toContain(WEB_FETCH_TOOL_NAME);
+ expect(text).toContain('may have changed recently');
+ expect(text).toContain('Start with');
+ });
+});
diff --git a/packages/trueforge-sdk/src/api/types/CapabilitiesData.ts b/packages/trueforge-sdk/src/api/types/CapabilitiesData.ts
index d0c622726..aed652eb7 100644
--- a/packages/trueforge-sdk/src/api/types/CapabilitiesData.ts
+++ b/packages/trueforge-sdk/src/api/types/CapabilitiesData.ts
@@ -6,4 +6,5 @@ export interface CapabilitiesData {
sandbox: TrueForge.SandboxCapability;
settings: TrueForge.SettingsCapability;
skill: TrueForge.SkillCapability;
+ webSearch: TrueForge.WebSearchCapability;
}
diff --git a/packages/trueforge-sdk/src/api/types/RuntimeConfig.ts b/packages/trueforge-sdk/src/api/types/RuntimeConfig.ts
index 75f66462f..d5557ed1f 100644
--- a/packages/trueforge-sdk/src/api/types/RuntimeConfig.ts
+++ b/packages/trueforge-sdk/src/api/types/RuntimeConfig.ts
@@ -10,4 +10,5 @@ export interface RuntimeConfig {
/** Max agent-loop iterations per turn (1–1024). Default: 100. */
iterationLimit?: number;
sandbox?: TrueForge.SandboxConfig;
+ webSearch?: TrueForge.WebSearchConfig;
}
diff --git a/packages/trueforge-sdk/src/api/types/WebSearchCapability.ts b/packages/trueforge-sdk/src/api/types/WebSearchCapability.ts
new file mode 100644
index 000000000..93fea9cea
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/WebSearchCapability.ts
@@ -0,0 +1,6 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export interface WebSearchCapability {
+ /** Whether a host web-search provider is configured. */
+ enabled: boolean;
+}
diff --git a/packages/trueforge-sdk/src/api/types/WebSearchConfig.ts b/packages/trueforge-sdk/src/api/types/WebSearchConfig.ts
new file mode 100644
index 000000000..9481fed31
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/WebSearchConfig.ts
@@ -0,0 +1,6 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export interface WebSearchConfig {
+ /** Enable built-in web search and fetch tools. Default: false (host must configure a provider). */
+ enabled?: boolean;
+}
diff --git a/packages/trueforge-sdk/src/api/types/index.ts b/packages/trueforge-sdk/src/api/types/index.ts
index c88fa727c..53ded384c 100644
--- a/packages/trueforge-sdk/src/api/types/index.ts
+++ b/packages/trueforge-sdk/src/api/types/index.ts
@@ -227,4 +227,6 @@ export * from "./UserMessageContent.js";
export * from "./UserMessageContentItem.js";
export * from "./UserToolApprovalEvent.js";
export * from "./UserToolResponseEvent.js";
+export * from "./WebSearchCapability.js";
+export * from "./WebSearchConfig.js";
export * from "./ZaiModelProvider.js";
diff --git a/packages/trueforge-sdk/src/serialization/types/CapabilitiesData.ts b/packages/trueforge-sdk/src/serialization/types/CapabilitiesData.ts
index 79e221913..e672f889d 100644
--- a/packages/trueforge-sdk/src/serialization/types/CapabilitiesData.ts
+++ b/packages/trueforge-sdk/src/serialization/types/CapabilitiesData.ts
@@ -6,6 +6,7 @@ import type * as serializers from "../index.js";
import { SandboxCapability } from "./SandboxCapability.js";
import { SettingsCapability } from "./SettingsCapability.js";
import { SkillCapability } from "./SkillCapability.js";
+import { WebSearchCapability } from "./WebSearchCapability.js";
export const CapabilitiesData: core.serialization.ObjectSchema<
serializers.CapabilitiesData.Raw,
@@ -14,6 +15,7 @@ export const CapabilitiesData: core.serialization.ObjectSchema<
sandbox: SandboxCapability,
settings: SettingsCapability,
skill: SkillCapability,
+ webSearch: core.serialization.property("web_search", WebSearchCapability),
});
export declare namespace CapabilitiesData {
@@ -21,5 +23,6 @@ export declare namespace CapabilitiesData {
sandbox: SandboxCapability.Raw;
settings: SettingsCapability.Raw;
skill: SkillCapability.Raw;
+ web_search: WebSearchCapability.Raw;
}
}
diff --git a/packages/trueforge-sdk/src/serialization/types/RuntimeConfig.ts b/packages/trueforge-sdk/src/serialization/types/RuntimeConfig.ts
index 148babae8..aa017b5d7 100644
--- a/packages/trueforge-sdk/src/serialization/types/RuntimeConfig.ts
+++ b/packages/trueforge-sdk/src/serialization/types/RuntimeConfig.ts
@@ -8,6 +8,7 @@ import { ContextManagementConfig } from "./ContextManagementConfig.js";
import { DynamicSubAgentsConfig } from "./DynamicSubAgentsConfig.js";
import { GenerativeUiConfig } from "./GenerativeUiConfig.js";
import { SandboxConfig } from "./SandboxConfig.js";
+import { WebSearchConfig } from "./WebSearchConfig.js";
export const RuntimeConfig: core.serialization.ObjectSchema<serializers.RuntimeConfig.Raw, TrueForge.RuntimeConfig> =
core.serialization.object({
@@ -17,6 +18,7 @@ export const RuntimeConfig: core.serialization.ObjectSchema<serializers.RuntimeC
generativeUi: core.serialization.property("generative_ui", GenerativeUiConfig.optional()),
iterationLimit: core.serialization.property("iteration_limit", core.serialization.number().optional()),
sandbox: SandboxConfig.optional(),
+ webSearch: core.serialization.property("web_search", WebSearchConfig.optional()),
});
export declare namespace RuntimeConfig {
@@ -27,5 +29,6 @@ export declare namespace RuntimeConfig {
generative_ui?: GenerativeUiConfig.Raw | null;
iteration_limit?: number | null;
sandbox?: SandboxConfig.Raw | null;
+ web_search?: WebSearchConfig.Raw | null;
}
}
diff --git a/packages/trueforge-sdk/src/serialization/types/WebSearchCapability.ts b/packages/trueforge-sdk/src/serialization/types/WebSearchCapability.ts
new file mode 100644
index 000000000..1294b73b1
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/WebSearchCapability.ts
@@ -0,0 +1,18 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+
+export const WebSearchCapability: core.serialization.ObjectSchema<
+ serializers.WebSearchCapability.Raw,
+ TrueForge.WebSearchCapability
+> = core.serialization.object({
+ enabled: core.serialization.boolean(),
+});
+
+export declare namespace WebSearchCapability {
+ export interface Raw {
+ enabled: boolean;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/WebSearchConfig.ts b/packages/trueforge-sdk/src/serialization/types/WebSearchConfig.ts
new file mode 100644
index 000000000..d07086217
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/WebSearchConfig.ts
@@ -0,0 +1,18 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+
+export const WebSearchConfig: core.serialization.ObjectSchema<
+ serializers.WebSearchConfig.Raw,
+ TrueForge.WebSearchConfig
+> = core.serialization.object({
+ enabled: core.serialization.boolean().optional(),
+});
+
+export declare namespace WebSearchConfig {
+ export interface Raw {
+ enabled?: boolean | null;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/index.ts b/packages/trueforge-sdk/src/serialization/types/index.ts
index c88fa727c..53ded384c 100644
--- a/packages/trueforge-sdk/src/serialization/types/index.ts
+++ b/packages/trueforge-sdk/src/serialization/types/index.ts
@@ -227,4 +227,6 @@ export * from "./UserMessageContent.js";
export * from "./UserMessageContentItem.js";
export * from "./UserToolApprovalEvent.js";
export * from "./UserToolResponseEvent.js";
+export * from "./WebSearchCapability.js";
+export * from "./WebSearchConfig.js";
export * from "./ZaiModelProvider.js";
diff --git a/packages/trueforge-sdk/tests/wire/server.test.ts b/packages/trueforge-sdk/tests/wire/server.test.ts
index 69cccd5eb..ddf469707 100644
--- a/packages/trueforge-sdk/tests/wire/server.test.ts
+++ b/packages/trueforge-sdk/tests/wire/server.test.ts
@@ -14,6 +14,7 @@ describe("ServerClient", () => {
sandbox: { enabled: true },
settings: { enabled: true },
skill: { enabled: true, reason: "reason" },
+ web_search: { enabled: true },
},
};
@@ -38,6 +39,9 @@ describe("ServerClient", () => {
enabled: true,
reason: "reason",
},
+ webSearch: {
+ enabled: true,
+ },
},
});
});
diff --git a/packages/trueforge/.env.example b/packages/trueforge/.env.example
index e3ccf1885..bd905fcf2 100644
--- a/packages/trueforge/.env.example
+++ b/packages/trueforge/.env.example
@@ -220,6 +220,9 @@ POSTGRES_PORT=5432
## Directory holding the mTLS cert triple (tls.crt / tls.key / ca.crt) when TRUEFOUNDRY_MTLS_ENABLED=true.
# TRUEFOUNDRY_MTLS_CERTS_DIR=/etc/tls/truefoundry
+## Built-in web search (TrueFoundry mode only). JSON object; unset disables search/fetch system tools.
+# TRUEFOUNDRY_WEB_SEARCH_PROVIDER={"name":"parallel","api_key":"YOUR_PARALLEL_API_KEY"}
+
## Shared sandbox for all tenants (TrueFoundry mode only). PUT settings is disabled (424).
# TRUEFOUNDRY_SANDBOX_ENABLED=false
# TRUEFOUNDRY_SANDBOX_PROVIDER=daytona
diff --git a/packages/trueforge/src/apis/capabilities.ts b/packages/trueforge/src/apis/capabilities.ts
index a7cc4151f..6920521e2 100644
--- a/packages/trueforge/src/apis/capabilities.ts
+++ b/packages/trueforge/src/apis/capabilities.ts
@@ -9,6 +9,7 @@ import { getCapabilitiesRoute } from '../routes/capabilityRoutes';
import { isLocalSandboxFallbackEnabled } from '../sandbox/localRuntime';
import { checkSnapshotStatus } from '../sandbox/providerUtils';
import type { SandboxBuildStatus } from '../schemas/sandboxProvider';
+import { resolveWebSearchProvider } from '../websearch/providers';
/**
* Why skills are unavailable, keyed off the sandbox build status.
@@ -45,12 +46,14 @@ export function createCapabilitiesRouter<TTransaction>(deps: {
}
const sandboxEnabled = status === 'ready' || (status === undefined && isLocalSandboxFallbackEnabled());
const settingsEnabled = hasAdminRole(requestContext);
+ const webSearchEnabled = resolveWebSearchProvider() !== undefined;
return c.json(
{
data: {
sandbox: { enabled: sandboxEnabled },
skill: sandboxEnabled ? { enabled: true } : { enabled: false, reason: skillDisabledReason(status) },
settings: { enabled: settingsEnabled },
+ web_search: { enabled: webSearchEnabled },
},
},
200,
diff --git a/packages/trueforge/src/apis/turns.ts b/packages/trueforge/src/apis/turns.ts
index be5bef3d3..a5068b69b 100644
--- a/packages/trueforge/src/apis/turns.ts
+++ b/packages/trueforge/src/apis/turns.ts
@@ -14,6 +14,7 @@ import {
type TurnInputItem,
type TurnRecordWithoutSnapshot,
} from '@truefoundry/trueforge-core/agent-session';
+import type { IWebSearchProvider } from '@truefoundry/trueforge-core/core';
import {
AgentHarnessError,
existingSandboxIdForProvider,
@@ -63,6 +64,7 @@ import {
} from '../runtime/sessionResources';
import { checkSnapshotStatus } from '../sandbox/providerUtils';
import { MAX_SESSION_TITLE_LENGTH } from '../schemas/session';
+import { resolveWebSearchProvider } from '../websearch/providers';
import { canReadAgentBoundResource } from './agentAccess';
export function toWireTurn(record: TurnRecordWithoutSnapshot): Turn {
@@ -146,6 +148,7 @@ function createTurnResolver(deps: {
sandboxProviderStore: ISandboxProviderStore;
agentStore: IAgentStore;
modelProviderStore: IModelProviderStore;
+ webSearchProvider: IWebSearchProvider | undefined;
logger: Logger;
signal: AbortSignal;
userRef: string;
@@ -159,6 +162,7 @@ function createTurnResolver(deps: {
sandboxProviderStore,
agentStore,
modelProviderStore,
+ webSearchProvider,
logger,
signal,
userRef,
@@ -268,6 +272,7 @@ function createTurnResolver(deps: {
}
return record.manifest;
},
+ webSearchProvider,
logger,
});
}
@@ -405,6 +410,7 @@ export async function beginTurnExecution(params: {
sandboxProviderStore: deps.sandboxProviderStore,
agentStore: deps.agentStore,
modelProviderStore: deps.modelProviderStore,
+ webSearchProvider: resolveWebSearchProvider(),
logger: deps.logger,
signal: abortController.signal,
userRef,
diff --git a/packages/trueforge/src/config.ts b/packages/trueforge/src/config.ts
index c4b7fe5e5..18782286c 100644
--- a/packages/trueforge/src/config.ts
+++ b/packages/trueforge/src/config.ts
@@ -158,6 +158,37 @@ export function parseTenantIdToAllowedModelProviderAccounts(raw: string | undefi
}
}
+/**
+ * Parsed `TRUEFOUNDRY_WEB_SEARCH_PROVIDER` JSON. Empty / unset → `undefined` (feature off).
+ * Requires `name: "parallel"` and non-empty `api_key`.
+ */
+export interface TrueFoundryWebSearchProviderEnv {
+ name: 'parallel';
+ api_key: string;
+}
+
+export function parseTrueFoundryWebSearchProvider(
+ raw: string | undefined,
+): TrueFoundryWebSearchProviderEnv | undefined {
+ if (!raw?.trim()) {
+ return undefined;
+ }
+ try {
+ const parsed = z.record(z.string(), z.string()).parse(JSON.parse(raw));
+ const name = parsed['name']?.trim();
+ const apiKey = parsed['api_key']?.trim();
+ if (name !== 'parallel' || !apiKey) {
+ throw new Error('missing or unsupported name, or missing api_key');
+ }
+ return { name: 'parallel', api_key: apiKey };
+ } catch (error) {
+ throw new Error(
+ 'Environment variable TRUEFOUNDRY_WEB_SEARCH_PROVIDER must be a JSON object with "name":"parallel" and non-empty "api_key" (e.g. {"name":"parallel","api_key":"..."})',
+ { cause: error },
+ );
+ }
+}
+
/** Parses a positive-integer env var, falling back to `defaultValue` when unset/blank. */
function parsePositiveInt(options: { envKey: string; raw: string | undefined; defaultValue: number }): number {
const { envKey, raw, defaultValue } = options;
@@ -763,6 +794,12 @@ export type DistributedServerConfiguration = SharedServerConfiguration & {
* Env: `TRUEFOUNDRY_TENANT_ID_TO_ALLOWED_MODEL_PROVIDER_ACCOUNTS`.
*/
TRUEFOUNDRY_TENANT_ID_TO_ALLOWED_MODEL_PROVIDER_ACCOUNTS: Record<string, string[]>;
+ /**
+ * Optional built-in web search provider (TrueFoundry mode only). JSON object
+ * `Record<string, string>` with `name` (`parallel`) and `api_key`.
+ * Unset / empty → web search tools are not registered. Env: `TRUEFOUNDRY_WEB_SEARCH_PROVIDER`.
+ */
+ TRUEFOUNDRY_WEB_SEARCH_PROVIDER: TrueFoundryWebSearchProviderEnv | undefined;
};
export type ServerConfiguration = StandaloneServerConfiguration | DistributedServerConfiguration;
@@ -948,6 +985,9 @@ const configuration: ServerConfiguration = standalone
TRUEFOUNDRY_TENANT_ID_TO_ALLOWED_MODEL_PROVIDER_ACCOUNTS: parseTenantIdToAllowedModelProviderAccounts(
getEnv('TRUEFOUNDRY_TENANT_ID_TO_ALLOWED_MODEL_PROVIDER_ACCOUNTS', { required: false }),
),
+ TRUEFOUNDRY_WEB_SEARCH_PROVIDER: parseTrueFoundryWebSearchProvider(
+ getEnv('TRUEFOUNDRY_WEB_SEARCH_PROVIDER', { required: false }),
+ ),
};
export function isOidcConfigured(
diff --git a/packages/trueforge/src/db/postgres/migrations/20260916_000001_agent_web_search.ts b/packages/trueforge/src/db/postgres/migrations/20260916_000001_agent_web_search.ts
new file mode 100644
index 000000000..30743eda4
--- /dev/null
+++ b/packages/trueforge/src/db/postgres/migrations/20260916_000001_agent_web_search.ts
@@ -0,0 +1,27 @@
+import { sql, type Kysely } from 'kysely';
+
+/** Seed `config.web_search.enabled=false` on existing named agents. */
+export async function up<TDatabase>(db: Kysely<TDatabase>): Promise<void> {
+ // Seed config when absent, then merge web_search (jsonb_set alone only creates the last path element).
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+ await sql`
+ UPDATE agent
+ SET manifest = jsonb_set(
+ coalesce(manifest, '{}'::jsonb),
+ '{config}',
+ coalesce(manifest->'config', '{}'::jsonb) || '{"web_search":{"enabled":false}}'::jsonb,
+ true
+ )
+ WHERE manifest->'config'->'web_search' IS NULL
+ `.execute(db);
+}
+
+/** Remove the explicit web_search config block written by up. */
+export async function down<TDatabase>(db: Kysely<TDatabase>): Promise<void> {
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+ await sql`
+ UPDATE agent
+ SET manifest = manifest #- '{config,web_search}'
+ WHERE manifest ? 'config'
+ `.execute(db);
+}
diff --git a/packages/trueforge/src/db/sqlite/migrations/20260916_000001_agent_web_search.ts b/packages/trueforge/src/db/sqlite/migrations/20260916_000001_agent_web_search.ts
new file mode 100644
index 000000000..a15d57861
--- /dev/null
+++ b/packages/trueforge/src/db/sqlite/migrations/20260916_000001_agent_web_search.ts
@@ -0,0 +1,29 @@
+import { type Kysely, sql } from 'kysely';
+
+/**
+ * Seed `config.web_search.enabled=false` on existing named agents.
+ * Mirrors db/postgres/migrations/20260916_000001_agent_web_search.ts.
+ */
+export async function up<TDatabase>(db: Kysely<TDatabase>): Promise<void> {
+ await sql`
+ UPDATE agent
+ SET manifest = jsonb_set(
+ coalesce(manifest, jsonb('{}')),
+ '$.config',
+ jsonb_patch(
+ coalesce(jsonb_extract(manifest, '$.config'), jsonb('{}')),
+ jsonb('{"web_search":{"enabled":false}}')
+ )
+ )
+ WHERE json_extract(manifest, '$.config.web_search') IS NULL
+ `.execute(db);
+}
+
+/** Remove the explicit web_search config block written by up. */
+export async function down<TDatabase>(db: Kysely<TDatabase>): Promise<void> {
+ await sql`
+ UPDATE agent
+ SET manifest = jsonb_remove(manifest, '$.config.web_search')
+ WHERE json_extract(manifest, '$.config.web_search') IS NOT NULL
+ `.execute(db);
+}
diff --git a/packages/trueforge/src/routes/capabilityRoutes.ts b/packages/trueforge/src/routes/capabilityRoutes.ts
index 9774f755f..e02def40f 100644
--- a/packages/trueforge/src/routes/capabilityRoutes.ts
+++ b/packages/trueforge/src/routes/capabilityRoutes.ts
@@ -23,11 +23,18 @@ const SettingsCapabilitySchema = z
})
.openapi('SettingsCapability');
+const WebSearchCapabilitySchema = z
+ .object({
+ enabled: z.boolean().describe('Whether a host web-search provider is configured.'),
+ })
+ .openapi('WebSearchCapability');
+
const CapabilitiesDataSchema = z
.object({
sandbox: SandboxCapabilitySchema,
skill: SkillCapabilitySchema,
settings: SettingsCapabilitySchema,
+ web_search: WebSearchCapabilitySchema,
})
.openapi('CapabilitiesData');
diff --git a/packages/trueforge/src/runtime/sessionResources.ts b/packages/trueforge/src/runtime/sessionResources.ts
index ce75c31ef..c1287be3e 100644
--- a/packages/trueforge/src/runtime/sessionResources.ts
+++ b/packages/trueforge/src/runtime/sessionResources.ts
@@ -23,6 +23,7 @@ import { LocalSandboxProvider } from '../sandbox/local/provider/LocalSandboxProv
import { getCachedLocalSandboxSupport, isLocalSandboxFallbackEnabled } from '../sandbox/localRuntime';
import { toSandboxProviderFromRecord } from '../sandbox/providerUtils';
import type { ReasoningEffort } from '../schemas/modelProvider';
+import { resolveWebSearchProvider } from '../websearch/providers';
export interface McpConnection {
url: string;
@@ -354,4 +355,10 @@ export async function validateAgentSpec({
});
}
}
+
+ if (spec.config.web_search.enabled && resolveWebSearchProvider() === undefined) {
+ throw new HTTPException(422, {
+ message: 'web_search is enabled but no web-search provider is configured',
+ });
+ }
}
diff --git a/packages/trueforge/src/websearch/providers.ts b/packages/trueforge/src/websearch/providers.ts
new file mode 100644
index 000000000..7f16efc28
--- /dev/null
+++ b/packages/trueforge/src/websearch/providers.ts
@@ -0,0 +1,14 @@
+import { ParallelWebSearchProvider, type IWebSearchProvider } from '@truefoundry/trueforge-core/core';
+import configuration, { isTrueFoundryModeEnabled } from '../config';
+
+/** Build the host web-search backend (TrueFoundry mode only), or `undefined` when unset. */
+export function resolveWebSearchProvider(): IWebSearchProvider | undefined {
+ if (!isTrueFoundryModeEnabled(configuration)) {
+ return undefined;
+ }
+ const env = configuration.TRUEFOUNDRY_WEB_SEARCH_PROVIDER;
+ if (!env) {
+ return undefined;
+ }
+ return new ParallelWebSearchProvider({ apiKey: env.api_key, mode: 'turbo' });
+}
diff --git a/packages/trueforge/tests/unit/apis/capabilities.test.ts b/packages/trueforge/tests/unit/apis/capabilities.test.ts
index 5181e79a7..720398a5a 100644
--- a/packages/trueforge/tests/unit/apis/capabilities.test.ts
+++ b/packages/trueforge/tests/unit/apis/capabilities.test.ts
@@ -97,6 +97,7 @@ describe('capabilities routers', () => {
reason: 'Skills run in a sandbox, which is not configured.',
},
settings: { enabled: true },
+ web_search: { enabled: false },
},
});
});
@@ -119,6 +120,7 @@ describe('capabilities routers', () => {
sandbox: { enabled: true },
skill: { enabled: true },
settings: { enabled: true },
+ web_search: { enabled: false },
},
});
});
@@ -135,6 +137,7 @@ describe('capabilities routers', () => {
sandbox: { enabled: true },
skill: { enabled: true },
settings: { enabled: true },
+ web_search: { enabled: false },
},
});
});
@@ -266,6 +269,7 @@ describe('capabilities routers', () => {
reason: 'Skills run in a sandbox, which is not configured.',
},
settings: { enabled: true },
+ web_search: { enabled: false },
},
});
@@ -281,6 +285,7 @@ describe('capabilities routers', () => {
reason: 'Skills run in a sandbox, which is not configured.',
},
settings: { enabled: false },
+ web_search: { enabled: false },
},
});
});
diff --git a/packages/trueforge/tests/unit/runtime/sessionResources.test.ts b/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
index 376665160..c48863b1e 100644
--- a/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
+++ b/packages/trueforge/tests/unit/runtime/sessionResources.test.ts
@@ -5,6 +5,7 @@ import {
type SessionAgent,
type SessionHandle,
} from '@truefoundry/trueforge-core/agent-session';
+import { WebSearchProviders, type IWebSearchProvider } from '@truefoundry/trueforge-core/core';
import { HTTPException } from 'hono/http-exception';
import { validateGitAgentSkills } from '../../../src/db/gitSkillMounts';
import { migrateSqliteToLatest } from '../../../src/db/migrateSqlite';
@@ -27,6 +28,17 @@ import {
} from '../../../src/runtime/sessionResources';
import { setCachedLocalSandboxSupport } from '../../../src/sandbox/localRuntime';
import type { ReasoningEffort } from '../../../src/schemas/modelProvider';
+import { resolveWebSearchProvider } from '../../../src/websearch/providers';
+
+jest.mock('../../../src/websearch/providers', () => ({
+ resolveWebSearchProvider: jest.fn(() => undefined),
+}));
+
+const mockWebSearchProvider: IWebSearchProvider = {
+ id: WebSearchProviders.Parallel,
+ search: () => Promise.resolve({ hits: [] }),
+ fetch: () => Promise.resolve({ pages: [] }),
+};
async function createGatewayMetadataSession(input: { agent: SessionAgent }): Promise<SessionHandle> {
const sessions = new Sessions({ sessionStore: new InMemorySessionStore() });
@@ -164,6 +176,8 @@ describe('localSandboxSessionSegment', () => {
describe('validateAgentSpec', () => {
afterEach(() => {
setCachedLocalSandboxSupport(undefined);
+ jest.mocked(resolveWebSearchProvider).mockReset();
+ jest.mocked(resolveWebSearchProvider).mockReturnValue(undefined);
});
async function setup(options?: { reasoningEfforts?: ReasoningEffort[] | undefined }) {
@@ -342,6 +356,40 @@ describe('validateAgentSpec', () => {
} satisfies Partial<HTTPException>);
});
+ it('rejects web_search.enabled with 422 when no web-search provider is configured', async () => {
+ const stores = await setup();
+ await expect(
+ validateAgentSpec({
+ spec: AgentSpecSchema.parse({
+ model: { name: 'test-provider/test-model' },
+ instructions: 'test',
+ config: { web_search: { enabled: true } },
+ }),
+ tenant_id: 'default',
+ ...stores,
+ }),
+ ).rejects.toMatchObject({
+ status: 422,
+ message: expect.stringContaining('no web-search provider is configured'),
+ } satisfies Partial<HTTPException>);
+ });
+
+ it('admits web_search.enabled when a web-search provider resolves', async () => {
+ const stores = await setup();
+ jest.mocked(resolveWebSearchProvider).mockReturnValueOnce(mockWebSearchProvider);
+ await expect(
+ validateAgentSpec({
+ spec: AgentSpecSchema.parse({
+ model: { name: 'test-provider/test-model' },
+ instructions: 'test',
+ config: { web_search: { enabled: true } },
+ }),
+ tenant_id: 'default',
+ ...stores,
+ }),
+ ).resolves.toBeUndefined();
+ });
+
it('rejects skills when no sandbox provider is configured', async () => {
const stores = await setup();
await stores.skillStore.upsertSkill({
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 19bd91a16..ac02199bb 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -280,6 +280,9 @@ importers:
openai:
specifier: ^7.5.0
+ parallel-web:
+ specifier: ^1.3.3
+ version: 1.3.3
ulid:
specifier: ^3.0.2
version: 3.0.2
@@ -1080,12 +1083,6 @@ packages:
cpu: [ppc64]
os: [aix]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ==}
- engines: {node: '>=18'}
- cpu: [ppc64]
- os: [aix]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==}
engines: {node: '>=18'}
@@ -1104,12 +1101,6 @@ packages:
cpu: [arm64]
os: [android]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg==}
- engines: {node: '>=18'}
- cpu: [arm64]
- os: [android]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==}
engines: {node: '>=18'}
@@ -1128,12 +1119,6 @@ packages:
cpu: [arm]
os: [android]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ==}
- engines: {node: '>=18'}
- cpu: [arm]
- os: [android]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==}
engines: {node: '>=18'}
@@ -1152,12 +1137,6 @@ packages:
cpu: [x64]
os: [android]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng==}
- engines: {node: '>=18'}
- cpu: [x64]
- os: [android]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==}
engines: {node: '>=18'}
@@ -1176,12 +1155,6 @@ packages:
cpu: [arm64]
os: [darwin]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q==}
- engines: {node: '>=18'}
- cpu: [arm64]
- os: [darwin]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==}
engines: {node: '>=18'}
@@ -1200,12 +1173,6 @@ packages:
cpu: [x64]
os: [darwin]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ==}
- engines: {node: '>=18'}
- cpu: [x64]
- os: [darwin]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==}
engines: {node: '>=18'}
@@ -1224,12 +1191,6 @@ packages:
cpu: [arm64]
os: [freebsd]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw==}
- engines: {node: '>=18'}
- cpu: [arm64]
- os: [freebsd]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==}
engines: {node: '>=18'}
@@ -1248,12 +1209,6 @@ packages:
cpu: [x64]
os: [freebsd]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ==}
- engines: {node: '>=18'}
- cpu: [x64]
- os: [freebsd]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==}
engines: {node: '>=18'}
@@ -1272,12 +1227,6 @@ packages:
cpu: [arm64]
os: [linux]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g==}
- engines: {node: '>=18'}
- cpu: [arm64]
- os: [linux]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==}
engines: {node: '>=18'}
@@ -1296,12 +1245,6 @@ packages:
cpu: [arm]
os: [linux]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ==}
- engines: {node: '>=18'}
- cpu: [arm]
- os: [linux]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==}
engines: {node: '>=18'}
@@ -1320,12 +1263,6 @@ packages:
cpu: [ia32]
os: [linux]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w==}
- engines: {node: '>=18'}
- cpu: [ia32]
- os: [linux]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==}
engines: {node: '>=18'}
@@ -1344,12 +1281,6 @@ packages:
cpu: [loong64]
os: [linux]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg==}
- engines: {node: '>=18'}
- cpu: [loong64]
- os: [linux]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==}
engines: {node: '>=18'}
@@ -1368,12 +1299,6 @@ packages:
cpu: [mips64el]
os: [linux]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ==}
- engines: {node: '>=18'}
- cpu: [mips64el]
- os: [linux]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==}
engines: {node: '>=18'}
@@ -1392,12 +1317,6 @@ packages:
cpu: [ppc64]
os: [linux]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ==}
- engines: {node: '>=18'}
- cpu: [ppc64]
- os: [linux]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==}
engines: {node: '>=18'}
@@ -1416,12 +1335,6 @@ packages:
cpu: [riscv64]
os: [linux]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ==}
- engines: {node: '>=18'}
- cpu: [riscv64]
- os: [linux]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==}
engines: {node: '>=18'}
@@ -1440,12 +1353,6 @@ packages:
cpu: [s390x]
os: [linux]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag==}
- engines: {node: '>=18'}
- cpu: [s390x]
- os: [linux]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==}
engines: {node: '>=18'}
@@ -1464,12 +1371,6 @@ packages:
cpu: [x64]
os: [linux]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA==}
- engines: {node: '>=18'}
- cpu: [x64]
- os: [linux]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==}
engines: {node: '>=18'}
@@ -1488,12 +1389,6 @@ packages:
cpu: [arm64]
os: [netbsd]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw==}
- engines: {node: '>=18'}
- cpu: [arm64]
- os: [netbsd]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==}
engines: {node: '>=18'}
@@ -1512,12 +1407,6 @@ packages:
cpu: [x64]
os: [netbsd]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg==}
- engines: {node: '>=18'}
- cpu: [x64]
- os: [netbsd]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==}
engines: {node: '>=18'}
@@ -1536,12 +1425,6 @@ packages:
cpu: [arm64]
os: [openbsd]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q==}
- engines: {node: '>=18'}
- cpu: [arm64]
- os: [openbsd]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==}
engines: {node: '>=18'}
@@ -1560,12 +1443,6 @@ packages:
cpu: [x64]
os: [openbsd]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw==}
- engines: {node: '>=18'}
- cpu: [x64]
- os: [openbsd]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==}
engines: {node: '>=18'}
@@ -1584,12 +1461,6 @@ packages:
cpu: [arm64]
os: [openharmony]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg==}
- engines: {node: '>=18'}
- cpu: [arm64]
- os: [openharmony]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==}
engines: {node: '>=18'}
@@ -1608,12 +1479,6 @@ packages:
cpu: [x64]
os: [sunos]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ==}
- engines: {node: '>=18'}
- cpu: [x64]
- os: [sunos]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==}
engines: {node: '>=18'}
@@ -1632,12 +1497,6 @@ packages:
cpu: [arm64]
os: [win32]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA==}
- engines: {node: '>=18'}
- cpu: [arm64]
- os: [win32]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==}
engines: {node: '>=18'}
@@ -1656,12 +1515,6 @@ packages:
cpu: [ia32]
os: [win32]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg==}
- engines: {node: '>=18'}
- cpu: [ia32]
- os: [win32]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==}
engines: {node: '>=18'}
@@ -1680,12 +1533,6 @@ packages:
cpu: [x64]
os: [win32]
- '@esbuild/[email protected]':
- resolution: {integrity: sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A==}
- engines: {node: '>=18'}
- cpu: [x64]
- os: [win32]
-
'@esbuild/[email protected]':
resolution: {integrity: sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==}
engines: {node: '>=18'}
@@ -4831,11 +4678,6 @@ packages:
engines: {node: '>=18'}
hasBin: true
- resolution: {integrity: sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==}
- engines: {node: '>=18'}
- hasBin: true
-
resolution: {integrity: sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==}
engines: {node: '>=18'}
@@ -6352,6 +6194,9 @@ packages:
resolution: {integrity: sha512-yQA4H19AmPEoMUeavPMDIe1higySl/gH/yaQrkT/s07Qp+7pp2hYz30N3z2l5BkjVkF9Ow6o0wjJamm2y7Sn0A==}
+ resolution: {integrity: sha512-TX8zRvWQ+OSF9U4uuc5kyGx83t1c9AlgT/dRhpCgngYLMN2e0rMiH1Mhmnlmv7WTVn/jAdhtT7cAuJYyEwgXRQ==}
+
resolution: {integrity: sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==}
engines: {node: '>=6'}
@@ -8500,9 +8345,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8512,9 +8354,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8524,9 +8363,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8536,9 +8372,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8548,9 +8381,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8560,9 +8390,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8572,9 +8399,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8584,9 +8408,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8596,9 +8417,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8608,9 +8426,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8620,9 +8435,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8632,9 +8444,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8644,9 +8453,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8656,9 +8462,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8668,9 +8471,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8680,9 +8480,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8692,9 +8489,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8704,9 +8498,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8716,9 +8507,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8728,9 +8516,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8740,9 +8525,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8752,9 +8534,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8764,9 +8543,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8776,9 +8552,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8788,9 +8561,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -8800,9 +8570,6 @@ snapshots:
'@esbuild/[email protected]':
optional: true
- '@esbuild/[email protected]':
- optional: true
-
'@esbuild/[email protected]':
optional: true
@@ -11101,10 +10868,10 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
'@eslint-community/regexpp': 4.12.2
'@typescript-eslint/scope-manager': 8.68.0
@@ -12172,35 +11939,6 @@ snapshots:
'@esbuild/win32-ia32': 0.27.7
'@esbuild/win32-x64': 0.27.7
- optionalDependencies:
- '@esbuild/aix-ppc64': 0.28.1
- '@esbuild/android-arm': 0.28.1
- '@esbuild/android-arm64': 0.28.1
- '@esbuild/android-x64': 0.28.1
- '@esbuild/darwin-arm64': 0.28.1
- '@esbuild/darwin-x64': 0.28.1
- '@esbuild/freebsd-arm64': 0.28.1
- '@esbuild/freebsd-x64': 0.28.1
- '@esbuild/linux-arm': 0.28.1
- '@esbuild/linux-arm64': 0.28.1
- '@esbuild/linux-ia32': 0.28.1
- '@esbuild/linux-loong64': 0.28.1
- '@esbuild/linux-mips64el': 0.28.1
- '@esbuild/linux-ppc64': 0.28.1
- '@esbuild/linux-riscv64': 0.28.1
- '@esbuild/linux-s390x': 0.28.1
- '@esbuild/linux-x64': 0.28.1
- '@esbuild/netbsd-arm64': 0.28.1
- '@esbuild/netbsd-x64': 0.28.1
- '@esbuild/openbsd-arm64': 0.28.1
- '@esbuild/openbsd-x64': 0.28.1
- '@esbuild/openharmony-arm64': 0.28.1
- '@esbuild/sunos-x64': 0.28.1
- '@esbuild/win32-arm64': 0.28.1
- '@esbuild/win32-ia32': 0.28.1
- '@esbuild/win32-x64': 0.28.1
-
optionalDependencies:
'@esbuild/aix-ppc64': 0.28.2
@@ -12229,7 +11967,6 @@ snapshots:
'@esbuild/win32-arm64': 0.28.2
'@esbuild/win32-ia32': 0.28.2
'@esbuild/win32-x64': 0.28.2
- optional: true
@@ -14254,6 +13991,8 @@ snapshots:
+
dependencies:
callsites: 3.1.0
@@ -15307,7 +15046,7 @@ snapshots:
dependencies:
- esbuild: 0.28.1
+ esbuild: 0.28.2
optionalDependencies:
fsevents: 2.3.3
@@ -15342,7 +15081,7 @@ snapshots:
dependencies:
'@typescript-eslint/typescript-estree': 8.68.0([email protected])([email protected])
diff --git a/python/trueforge_sdk/.fern/metadata.json b/python/trueforge_sdk/.fern/metadata.json
deleted file mode 100644
index 9b44c3fd9..000000000
--- a/python/trueforge_sdk/.fern/metadata.json
+++ /dev/null
@@ -1,29 +0,0 @@
-{
- "cliVersion": "5.121.1",
- "generatorName": "fernapi/fern-python-sdk",
- "generatorVersion": "5.29.0",
- "generatorConfig": {
- "package_name": "trueforge_sdk",
- "optional_auth": true,
- "stream_abstraction": true,
- "use_request_defaults": "all",
- "inline_path_params": true,
- "pydantic_config": {
- "enum_type": "forward_compatible_python_enums",
- "frozen": false,
- "skip_validation": true
- },
- "client": {
- "class_name": "BaseTrueForge",
- "filename": "base_client.py",
- "exported_class_name": "TrueForge",
- "exported_filename": "client.py"
- },
- "pyproject_python_version": ">=3.10"
- },
- "originGitCommit": "cd4e388af4a643e6e9b4c7df40ab488fb2059b1e",
- "originGitCommitIsDirty": true,
- "invokedBy": "ci",
- "requestedVersion": "0.2.0-rc.8",
- "ciProvider": "github"
-}
\ No newline at end of file
diff --git a/python/trueforge_sdk/.fernignore b/python/trueforge_sdk/.fernignore
index 98192b7ca..34601c02f 100644
--- a/python/trueforge_sdk/.fernignore
+++ b/python/trueforge_sdk/.fernignore
@@ -1,2 +1,3 @@
src/trueforge_sdk/events.py
tests/test_events.py
+.fern/metadata.json
diff --git a/python/trueforge_sdk/src/trueforge_sdk/__init__.py b/python/trueforge_sdk/src/trueforge_sdk/__init__.py
index f336deeec..8ce5e6e85 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/__init__.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/__init__.py
@@ -236,6 +236,8 @@ if typing.TYPE_CHECKING:
UserMessageContentItem,
UserToolApprovalEvent,
UserToolResponseEvent,
+ WebSearchCapability,
+ WebSearchConfig,
ZaiModelProvider,
)
from .errors import (
@@ -502,6 +504,8 @@ _dynamic_imports: typing.Dict[str, str] = {
"UserMessageContentItem": ".types",
"UserToolApprovalEvent": ".types",
"UserToolResponseEvent": ".types",
+ "WebSearchCapability": ".types",
+ "WebSearchConfig": ".types",
"ZaiModelProvider": ".types",
"__version__": ".version",
"agents": ".agents",
@@ -785,6 +789,8 @@ __all__ = [
"UserMessageContentItem",
"UserToolApprovalEvent",
"UserToolResponseEvent",
+ "WebSearchCapability",
+ "WebSearchConfig",
"ZaiModelProvider",
"__version__",
"agents",
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py b/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
index c242e7818..940d2b96a 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
@@ -235,6 +235,8 @@ if typing.TYPE_CHECKING:
from .user_message_content_item import UserMessageContentItem
from .user_tool_approval_event import UserToolApprovalEvent
from .user_tool_response_event import UserToolResponseEvent
+ from .web_search_capability import WebSearchCapability
+ from .web_search_config import WebSearchConfig
from .zai_model_provider import ZaiModelProvider
_dynamic_imports: typing.Dict[str, str] = {
"ActionRequiredEvent": ".action_required_event",
@@ -466,6 +468,8 @@ _dynamic_imports: typing.Dict[str, str] = {
"UserMessageContentItem": ".user_message_content_item",
"UserToolApprovalEvent": ".user_tool_approval_event",
"UserToolResponseEvent": ".user_tool_response_event",
+ "WebSearchCapability": ".web_search_capability",
+ "WebSearchConfig": ".web_search_config",
"ZaiModelProvider": ".zai_model_provider",
}
@@ -721,5 +725,7 @@ __all__ = [
"UserMessageContentItem",
"UserToolApprovalEvent",
"UserToolResponseEvent",
+ "WebSearchCapability",
+ "WebSearchConfig",
"ZaiModelProvider",
]
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/capabilities_data.py b/python/trueforge_sdk/src/trueforge_sdk/types/capabilities_data.py
index fe095fd67..20a93f6a0 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/types/capabilities_data.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/capabilities_data.py
@@ -8,12 +8,14 @@ from ..core.unchecked_base_model import UncheckedBaseModel
from .sandbox_capability import SandboxCapability
from .settings_capability import SettingsCapability
from .skill_capability import SkillCapability
+from .web_search_capability import WebSearchCapability
class CapabilitiesData(UncheckedBaseModel):
sandbox: SandboxCapability
settings: SettingsCapability
skill: SkillCapability
+ web_search: WebSearchCapability
if IS_PYDANTIC_V2:
model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/runtime_config.py b/python/trueforge_sdk/src/trueforge_sdk/types/runtime_config.py
index 322242491..50bcc389a 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/types/runtime_config.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/runtime_config.py
@@ -10,6 +10,7 @@ from .context_management_config import ContextManagementConfig
from .dynamic_sub_agents_config import DynamicSubAgentsConfig
from .generative_ui_config import GenerativeUiConfig
from .sandbox_config import SandboxConfig
+from .web_search_config import WebSearchConfig
class RuntimeConfig(UncheckedBaseModel):
@@ -23,6 +24,7 @@ class RuntimeConfig(UncheckedBaseModel):
"""
sandbox: typing.Optional[SandboxConfig] = None
+ web_search: typing.Optional[WebSearchConfig] = None
if IS_PYDANTIC_V2:
model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/web_search_capability.py b/python/trueforge_sdk/src/trueforge_sdk/types/web_search_capability.py
new file mode 100644
index 000000000..6951fba2f
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/web_search_capability.py
@@ -0,0 +1,22 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+
+
+class WebSearchCapability(UncheckedBaseModel):
+ enabled: bool = pydantic.Field()
+ """
+ Whether a host web-search provider is configured.
+ """
+
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/web_search_config.py b/python/trueforge_sdk/src/trueforge_sdk/types/web_search_config.py
new file mode 100644
index 000000000..d16bfa015
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/web_search_config.py
@@ -0,0 +1,22 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+
+
+class WebSearchConfig(UncheckedBaseModel):
+ enabled: typing.Optional[bool] = pydantic.Field(default=False)
+ """
+ Enable built-in web search and fetch tools. Default: false (host must configure a provider).
+ """
+
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow