ExuluDefaultTools

ExuluDefaultTools is an object that groups the tool factories bundled with IMP. Each factory returns an ExuluTool instance (or undefined when the required license entitlement is absent), ready to pass to ExuluApp.create() or an agent’s tool list. The namespace is intentionally structured so new built-in tools can be added without breaking existing imports.

ExuluDefaultTools.agentic.retrieval.create.pipeline requires the agentic-retrieval EE entitlement. When the entitlement is absent the factory returns undefined and logs a warning — filter undefined before passing to the tool list.

For a product-side guide to configuring the pipeline in the agent editor — including the full options table with UI labels and when-to-change guidance — see Knowledge search.

API surface

ExuluDefaultTools.agentic.retrieval.create.pipeline

ExuluDefaultTools.agentic.retrieval.create.pipeline(opts: {
  contexts: ExuluContext[];
  memoryContext?: ExuluContext;
  user?: User;
  role?: string;
  model?: LanguageModel;
  instructions?: string;
  preselected?: string[];
  memoryItems?: VectorSearchChunkResult[];
  projectScope?: ProjectScope;
}): ExuluTool | undefined

Creates the agentic knowledge-search tool (agentic_context_search). The tool routes a user question across the supplied contexts, expands it into sub-queries, searches and reranks, and returns deduplicated passages. It integrates with memory and project-scoped items when those options are provided.

ExuluContext[]

required

The knowledge contexts the tool may search. Their names appear in the tool description shown to the model.

ExuluContext

Optional context used for memory retrieval (prior conversation summaries or user facts).

User

Authenticated user record. Forwarded to access-control and budget attribution.

string

Role ID for RBAC filtering within searched contexts.

LanguageModel

AI SDK LanguageModel used by the routing and query-expansion phases.

string

Additional instructions prepended to the tool description (admin-supplied guidance on when to use the tool).

string[]

Global item IDs that are pinned into the result set regardless of semantic relevance.

VectorSearchChunkResult[]

Pre-fetched memory chunks to include in the initial result set.

ProjectScope

When set, the tool also searches knowledge items attached to the named project.

ExuluTool | undefined

An ExuluTool ready for registration, or undefined when agentic-retrieval is not licensed.

Example

import { ExuluDefaultTools } from "@exulu/backend";

// Inside your ExuluApp setup:
const agenticSearch = ExuluDefaultTools.agentic.retrieval.create.pipeline({
  contexts: [productDocsContext, faqContext],
  user: req.user,
  role: req.user.role?.id,
  model: resolvedModel,
});

const tools = [
  ...(agenticSearch ? [agenticSearch] : []),
  myCustomTool,
];

Retrieval pipeline saved config options

When a session is configured with an agentic_context_search tool, the following options can be saved on the session’s saved knowledge-search configuration. All options are optional; omitted options fall back to their defaults.

Option key	Type	Default	Effect
`instructions`	`string`	`""`	Extra instructions prepended to the tool description shown to the model.
`reranker`	`string`	`"none"`	Reranker backend to apply after retrieval (`"none"` disables reranking).
`managed_context`	`boolean`	`false`	When `true`, users must preselect items before the tool will search. If no items are preselected the tool returns an instruction asking the user to pin items first.
`require_preselected_contexts`	`boolean`	`false`	When `true`, users must explicitly confirm which knowledge bases to search before the tool runs; the model prompts the user to choose from the available contexts.
`logging`	`boolean`	`false`	Enables verbose pipeline trace logging.
`project_search`	`boolean`	`true`	Includes knowledge items attached to the chat’s project as an additional source.
`utility_model`	`string`	`""`	LiteLLM model name used by routing and query-expansion phases; falls back to the session model when empty.
`max_steps`	`number`	`0`	Maximum number of knowledge searches allowed per agent turn. `0` = no search-specific cap (the agent’s overall tool-step budget still applies).
`knowledge_bases`	`object (JSON)`	`{}`	Per-context KB profiles — a JSON map of context ID to a `KbProfile` object with `enabled`, `kind`, `instructions`, and `overrides`.
`routing`	`object (JSON)`	`{ rules: [] }`	Routing rules that direct queries to different context subsets based on content.
`vocabulary`	`object (JSON)`	`{ glossary: [], identifiers: [], rewrites: [], styleHint: "" }`	Domain vocabulary: glossary terms, identifier sets, text rewrites, and a style hint for query expansion.
`memory`	`object (JSON)`	`{}` (parsed to full defaults at read time)	Memory behaviour: `enabled`, `override`, `filePrioritization`, `queryAugmentation`.
`tuning`	`object (JSON)`	`{}`	Retrieval tuning knobs: `topK`, `fallbackThreshold`, `pinBoost`, `identifierBoost`, `pageWindow`, `maxQueriesPerContext`.

JSON-typed options (knowledge_bases, routing, vocabulary, memory, tuning) accept either a pre-parsed object or a JSON string; invalid JSON or schema failures silently fall back to defaults.

Auto-registered session tools

The following tools are registered automatically for every session that has an active session ID and file storage configured (fileUploads.s3Bucket present). Both conditions must be met — a session without an ID or without a configured S3 bucket will not receive these tools. They run without approval (needsApproval: false) and do not require an EE entitlement.

read_session_file

read_session_file(filename, offset?, limit?)

Pages through any file stored in the session’s S3 folder by line range — including offloaded tool outputs (tool-output-*.txt) and user-uploaded documents. Supports offset (1-based) and limit to avoid loading the whole file at once. Maximum 16 000 characters returned per call. Registration site: src/templates/tools/session-file-read-tool.ts.

parse_document

parse_document(filename, pages?, offset?, limit?)

Extracts the text layer of an uploaded PDF or Office document (.docx, .xlsx, .pptx, and more). PDFs are returned with --- page N --- markers so the model can locate content by page. Scanned or image-only PDFs are detected and rejected with a hint to use view_document_page or a knowledge-base processor instead. Registration site: src/templates/tools/parse-document-tool.ts.

view_document_page

view_document_page(filename, page?)

Renders a single page of a PDF or Office document — or an uploaded image file — and attaches it as a vision input to the next model turn. Requires a vision-capable model; returns an error when the active model’s supports_vision flag is false. Office documents are converted to PDF via a preview cache before rendering. Registration site: src/templates/tools/view-document-page-tool.ts.

ExuluTool — introduction: how tools are defined and registered.
ExuluContext — introduction: build the knowledge contexts passed here.

Start

Tutorials

Recipes

Core classes

Reference

ExuluDefaultTools

API surface

ExuluDefaultTools.agentic.retrieval.create.pipeline

Example

Retrieval pipeline saved config options

Auto-registered session tools

read_session_file

parse_document

view_document_page

​API surface

​ExuluDefaultTools.agentic.retrieval.create.pipeline

​Example

​Retrieval pipeline saved config options

​Auto-registered session tools

​read_session_file

​parse_document

​view_document_page

​Related

API surface

ExuluDefaultTools.agentic.retrieval.create.pipeline

Example

Retrieval pipeline saved config options

Auto-registered session tools

read_session_file

parse_document

view_document_page

Related