agents 0.26.0 → 0.28.0

package/dist/tool-CTp72Jb_.d.ts

@@ -0,0 +1,278 @@
+//#region src/web/search/contract.d.ts
+/**
+ * The `web_search` tool contract: its name, what it tells the model, what the
+ * model passes in, what comes back, and how results are rendered for the
+ * model. Shared by every executor of the tool — the harness-executed
+ * adapters in `agents/websearch/*` today, and a gateway-executed variant in
+ * `agents/models/*` once AI Gateway server tools ship — so a `web_search` call
+ * looks the same in a transcript whoever ran it.
+ */
+/**
+ * The tool's name, as the model calls it and as it appears in transcripts.
+ * `web_search` is the name models know from Anthropic's and OpenAI's built-in
+ * search tools.
+ */
+declare const WEB_SEARCH_TOOL_NAME = "web_search";
+/** The default number of results when the model doesn't ask for a count. */
+declare const DEFAULT_WEB_SEARCH_LIMIT = 5;
+/** The most results one search can return; the API rejects more. */
+declare const MAX_WEB_SEARCH_LIMIT = 10;
+/** The longest query the API accepts, in characters. */
+declare const MAX_WEB_SEARCH_QUERY_LENGTH = 1024;
+/**
+ * Per-result description length in the model's view, in characters. Provider
+ * descriptions run to ~8,000 characters (Ceramic returns page text), which at
+ * ten results is 80 KB of context per search. The full text stays in the
+ * host-side output.
+ */
+declare const DEFAULT_WEB_SEARCH_DESCRIPTION_CHARS = 600;
+/** What the model says when it wants a search. */
+type WebSearchToolInput = {
+  /** The search query. */ query: string /** How many results to return, 1–10. Defaults to the host's `limit`. */;
+  limit?: number;
+};
+/**
+ * One search result. `url` and `title` are always present; the rest only
+ * when the provider returns them (Exa adds `imageUrl` and
+ * `lastModifiedDate`, Linkup adds `faviconUrl`, Ceramic adds neither).
+ */
+type WebSearchResult = {
+  url: string;
+  title: string /** A snippet or extract of the page. Length and style vary by provider. */;
+  description?: string /** ISO 8601 timestamp of the page's last modification. */;
+  lastModifiedDate?: string;
+  imageUrl?: string;
+  faviconUrl?: string;
+};
+/** The Web Search API's response: results plus request metadata. */
+type WebSearchResponse = {
+  items: WebSearchResult[];
+  metadata: {
+    /** The query as the provider saw it. */ query: string /** AI Gateway request id, for the gateway log. */;
+    requestId: string /** Provider latency in milliseconds. */;
+    latencyMs: number;
+  };
+};
+/**
+ * What one `web_search` run produces for the host: the full API response and
+ * which provider served it. The model sees {@link renderWebSearchResults}
+ * of this.
+ */
+type WebSearchToolOutput = WebSearchResponse & {
+  /** The provider that ran the search, when the source knows. */ provider?: string;
+};
+declare const WEB_SEARCH_TOOL_DESCRIPTION: string;
+interface RenderWebSearchResultsOptions {
+  /**
+   * Trim each description to this many characters in the model's view.
+   * Defaults to {@link DEFAULT_WEB_SEARCH_DESCRIPTION_CHARS}; `Infinity`
+   * disables trimming.
+   */
+  maxDescriptionChars?: number;
+}
+/**
+ * Render search results as the text the model reads: one numbered block per
+ * result, descriptions trimmed and whitespace collapsed.
+ */
+declare function renderWebSearchResults(
+  response: WebSearchResponse,
+  options?: RenderWebSearchResultsOptions
+): string;
+//#endregion
+//#region src/web/search/source.d.ts
+/**
+ * Search providers behind the Cloudflare Web Search API. `ceramic` is the
+ * platform default and the cheapest; `exa` and `linkup` cost more and, in our
+ * testing, ranked announcement-style queries noticeably better. Pricing and
+ * data-retention terms are in the Web Search docs.
+ */
+type WebSearchProvider = "ceramic" | "exa" | "linkup";
+/** One search request as a source receives it. */
+interface WebSearchRequest {
+  /** 1–1024 characters. */
+  query: string;
+  /** 1–10. Defaults to 5. */
+  limit?: number;
+}
+/** Per-call options a source receives alongside the request. */
+interface WebSearchCallOptions {
+  /** Abort the search. A source should reject with the signal's reason. */
+  signal?: AbortSignal;
+}
+/**
+ * Runs searches. The tool core calls `search` and renders what comes back.
+ * An object rather than a bare function so a wrapper (caching, logging)
+ * keeps `provider` by spreading the source it wraps.
+ */
+interface WebSearchSource {
+  search(
+    request: WebSearchRequest,
+    options?: WebSearchCallOptions
+  ): Promise<WebSearchResponse>;
+  /**
+   * The provider this source searches with, when known. Informational:
+   * recorded on the tool's host output.
+   */
+  readonly provider?: WebSearchProvider;
+}
+/** Options shared by the AI-binding and HTTP sources. */
+interface WebSearchGatewayOptions {
+  /** AI Gateway id. Defaults to `"default"`, which Cloudflare creates on first use. */
+  gateway?: string;
+  /**
+   * Which provider runs the search. Host-chosen; the model never picks.
+   * Defaults to the platform default (`ceramic`).
+   */
+  provider?: WebSearchProvider;
+  /**
+   * The BYOK key alias on the gateway to bill the provider with. When set
+   * and no such key exists the request fails rather than falling back to
+   * AI Gateway credits. When omitted, a key under the `default` alias is
+   * used if one exists, otherwise credits.
+   */
+  byokAlias?: string;
+}
+/** A search over the Workers AI binding (`env.AI.websearch`). */
+interface AIWebSearchOptions extends WebSearchGatewayOptions {
+  /** The Workers AI binding. Requires `"ai": { "binding": "AI" }` in wrangler.jsonc. */
+  binding: Ai;
+}
+/**
+ * Search through the Workers AI binding. The Worker's own account and the
+ * named gateway are billed.
+ */
+declare function createAIWebSearch(
+  options: AIWebSearchOptions
+): WebSearchSource;
+/** A search over the HTTP API, from any runtime with `fetch`. */
+interface HTTPWebSearchOptions extends WebSearchGatewayOptions {
+  /** The Cloudflare account the gateway belongs to. */
+  accountId: string;
+  /** An API token with `Workers AI: Read` and `AI Gateway: Read` on that account. */
+  apiToken: string;
+  /** Override for tests. Defaults to the global `fetch`. */
+  fetch?: typeof fetch;
+  /** API origin. Defaults to `https://api.cloudflare.com`. */
+  baseUrl?: string;
+}
+/**
+ * Search through `POST /accounts/{account_id}/ai/websearch`. Use this
+ * outside Workers, or to search through a gateway in another account.
+ */
+declare function createHTTPWebSearch(
+  options: HTTPWebSearchOptions
+): WebSearchSource;
+/**
+ * Error codes a {@link WebSearchError} carries. The `web_search_*` codes the
+ * API returns pass through as-is; failures without one get a code from the
+ * HTTP status, so every error has a code to branch on.
+ */
+type WebSearchErrorCode =
+  /** No AI Gateway credits and no provider key for the search. */ | "web_search_payment_required" /** `byokAlias` names a key the gateway does not have. */
+    | "web_search_byok_not_configured" /** The query, limit, or provider was rejected. */
+    | "invalid_web_search_input" /** The gateway does not exist or is not set up. */
+    | "web_search_gateway_not_configured" /** The API token or binding is not allowed to search. */
+    | "web_search_unauthorized" /** Too many searches; retry later. */
+    | "web_search_rate_limited" /** The search took longer than the tool's `timeoutMs`. */
+    | "web_search_timeout" /** The API or the provider failed. */
+    | "web_search_unavailable" /** The Workers runtime has no `env.AI.websearch()`. */
+    | "web_search_unsupported_runtime" /** A code the API added after this release. */
+    | (string & {});
+/** Why a search failed, with what the API said. */
+declare class WebSearchError extends Error {
+  readonly name = "WebSearchError";
+  readonly status: number;
+  readonly code: WebSearchErrorCode;
+  /** Whether retrying the same search might succeed. */
+  readonly retryable: boolean;
+  /** AI Gateway's id for the failed request, for the gateway log. */
+  readonly requestId?: string;
+  /** The Cloudflare API's numeric error code, when it gave one. */
+  readonly apiCode?: number;
+  constructor(
+    message: string,
+    details: {
+      status: number;
+      code: WebSearchErrorCode;
+      retryable?: boolean;
+      requestId?: string;
+      apiCode?: number;
+      cause?: unknown;
+    }
+  );
+}
+//#endregion
+//#region src/web/search/tool.d.ts
+/** Search through the Workers AI binding; the tool builds the source. */
+type WebSearchToolBindingOptions = AIWebSearchOptions & {
+  source?: never;
+};
+/**
+ * Search through a source you built. Gateway, provider, and billing belong
+ * to the source, so the binding options are not accepted here.
+ */
+type WebSearchToolSourceOptions = {
+  /** Where searches run, instead of the Workers AI binding. */ source: WebSearchSource;
+  binding?: never;
+  gateway?: never;
+  provider?: never;
+  byokAlias?: never;
+};
+/**
+ * Options every `web_search` tool adapter accepts. Invalid values throw a
+ * `RangeError` when the tool is created.
+ */
+type WebSearchToolOptions = (
+  | WebSearchToolBindingOptions
+  | WebSearchToolSourceOptions
+) & {
+  /**
+   * Results per search when the model doesn't ask for a count, and the most
+   * it gets when it asks for more. An integer from 1 to 10; defaults to 5.
+   */
+  limit?: number /** Replaces the default tool description. */;
+  description?: string;
+  /**
+   * Per-result description length in the model's view. A positive integer;
+   * defaults to 600 characters. `Infinity` passes descriptions through whole.
+   */
+  maxDescriptionChars?: number;
+  /**
+   * Give up on a search after this many milliseconds, as a retryable
+   * `web_search_timeout` failure. A positive integer; defaults to 30 seconds.
+   */
+  timeoutMs?: number;
+};
+/** The default for {@link WebSearchToolOptions.timeoutMs}. */
+declare const DEFAULT_WEB_SEARCH_TIMEOUT_MS = 30000;
+//#endregion
+export {
+  WebSearchResponse as C,
+  renderWebSearchResults as D,
+  WebSearchToolOutput as E,
+  WEB_SEARCH_TOOL_NAME as S,
+  WebSearchToolInput as T,
+  DEFAULT_WEB_SEARCH_LIMIT as _,
+  AIWebSearchOptions as a,
+  RenderWebSearchResultsOptions as b,
+  WebSearchError as c,
+  WebSearchProvider as d,
+  WebSearchRequest as f,
+  DEFAULT_WEB_SEARCH_DESCRIPTION_CHARS as g,
+  createHTTPWebSearch as h,
+  WebSearchToolSourceOptions as i,
+  WebSearchErrorCode as l,
+  createAIWebSearch as m,
+  WebSearchToolBindingOptions as n,
+  HTTPWebSearchOptions as o,
+  WebSearchSource as p,
+  WebSearchToolOptions as r,
+  WebSearchCallOptions as s,
+  DEFAULT_WEB_SEARCH_TIMEOUT_MS as t,
+  WebSearchGatewayOptions as u,
+  MAX_WEB_SEARCH_LIMIT as v,
+  WebSearchResult as w,
+  WEB_SEARCH_TOOL_DESCRIPTION as x,
+  MAX_WEB_SEARCH_QUERY_LENGTH as y
+};
+//# sourceMappingURL=tool-CTp72Jb_.d.ts.map