builtin-tool

To build an agent-callable builtin tool, you define a manifest JSON schema for each ApiName, implement a pure ExecutionRuntime returning BuiltinServerRuntimeOutput, wire a BaseExecutor for dispatch, and register all Inspector and optional UI components in the central registries.

The best way to structure a new builtin tool package is creating a package under builtin-tool-<name>/, defining the manifest and types, implementing the pure service-injected ExecutionRuntime, and wiring the BaseExecutor layer to preserve result-state on failure via a toResult funnel.

You do not need all UI surfaces when adding a builtin tool; only the Inspector component is required, while Render, Placeholder, Streaming, Intervention, and Portal components are optional depending on the specific chat experience you want to render.

A builtin tool not found error typically occurs when stable identifiers like lobe-<domain> are missing, ApiName typing is inconsistent, or the tool lacks proper registry and i18n wiring needed for the agent runtime to discover and validate the manifest.

The BaseExecutor wiring layer handles state preservation on failure by routing all execution paths through a toResult funnel, ensuring the pure ExecutionRuntime returns a BuiltinServerRuntimeOutput that maintains consistent result and state contracts even during errors.

You can extend existing builtin tools with new methods by adding the new ApiName to the manifest JSON schema, implementing the corresponding ExecutionRuntime logic, and updating the BaseExecutor and registry wiring to keep multi-surface UI integration consistent.