Toolkit
Groups AI tools together with their handlers.
A toolkit connects Tool schemas to the handler functions an application provides for a language model workflow. It can build a handler context or layer and execute tool calls by name. Execution validates parameters, runs the handler, encodes the result, supports preliminary streamed results, and applies the tool's failure mode.
Constructors
Signature
declare const empty: Toolkit<{}>;Creates a new toolkit from the specified tools.
Details
This is the primary constructor for creating toolkits. It accepts multiple tools and organizes them into a toolkit that can be provided to AI language models.
Signature
declare function make<Tools extends readonly Array<Any>>(...tools: Tools): Toolkit<ToolsByName<Tools>>Merges multiple toolkits into a single toolkit.
Details
Combines all tools from the provided toolkits into one unified toolkit. If there are naming conflicts, tools from later toolkits will override tools from earlier ones.
Signature
declare function merge<Toolkits extends readonly Array<Any>>(...toolkits: Toolkits): Toolkit<{ [K in string]: MergeRecords<Tools<Toolkits[number]>>[K] }>Models
HandlerContext interface
Context provided to tool handlers during execution.
Signature
interface HandlerContext<Tool extends Tool.Any> {
readonly preliminary: (result: Success<Tool>) => Effect<void>;
readonly toolCallId?: string;
}Represents a collection of tools which can be used to enhance the capabilities of a large language model.
Signature
interface Toolkit<in out Tools extends Record<string, Tool.Any>> extends Effect<
WithHandler<Tools>,
never,
Tool.HandlersFor<Tools>
> {
constructor(_: never);
readonly "~effect/ai/Toolkit": "~effect/ai/Toolkit";
readonly tools: Tools;
of<Handlers extends HandlersFrom<Tools>>(handlers: Handlers): Handlers;
toHandlers<Handlers extends HandlersFrom<Tools>, EX = never, RX = never>(
build: Handlers | Effect<Handlers, EX, RX>,
): Effect<Context<HandlersFor<Tools>>, EX, RX>;
toLayer<Handlers extends HandlersFrom<Tools>, EX = never, RX = never>(
build: Handlers | Effect<Handlers, EX, RX>,
): Layer<HandlersFor<Tools>, EX, Exclude<RX, Scope>>;
}WithHandler interface
A toolkit instance with registered handlers ready for tool execution.
Signature
interface WithHandler<in out Tools extends Record<string, Tool.Any>> {
readonly handle: <Name extends string | number | symbol>(
name: Name,
params: Parameters<Tools[Name]>,
toolCallId?: string,
) => Effect<
Stream<HandlerResult<Tools[Name]>, HandlerError<Tools[Name]>, HandlerServices<Tools[Name]>>,
AiError
>;
readonly tools: Tools;
}Utility Types
Represents any Toolkit instance, used for generic constraints.
Signature
interface Any {
readonly "~effect/ai/Toolkit": "~effect/ai/Toolkit";
readonly tools: Record<string, Tool.Any>;
}HandlersFrom type
A utility type that maps tool names to their required handler functions.
Details
Handlers can return either the tool's custom failure type, an AiErrorReason (which will be wrapped in AiError), or a full AiError.
Signature
type HandlersFrom<Tools extends Record<string, Tool.Any>> = {
[Name in keyof Tools]: (
params: Tool.Parameters<Tools[Name]>,
context: HandlerContext<Tools[Name]>,
) => Effect.Effect<
Tool.Success<Tools[Name]>,
Tool.Failure<Tools[Name]> | AiError.AiError | AiError.AiErrorReason,
Tool.HandlerServices<Tools[Name]>
>;
};MergedTools type
A utility type which merges the tools from multiple toolkits into a single record.
Signature
type MergedTools<Toolkits extends ReadonlyArray<Any>> = SimplifyRecord<
MergeRecords<Tools<Toolkits[number]>>
>;MergeRecords type
A utility type which merges a union of tool records into a single record.
Signature
type MergeRecords<U> = {
[K in Extract<U extends unknown ? keyof U : never, string>]: Extract<
U extends Record<K, infer V> ? V : never,
Tool.Any
>;
};SimplifyRecord type
A utility type which flattens a record type for improved IDE display.
Signature
type SimplifyRecord<T> = { [K in keyof T]: T[K] } & {};A utility type which can be used to extract the tool definitions from a toolkit.
Signature
type Tools<T> = T extends Toolkit<infer Tools> ? Tools : never;ToolsByName type
A utility type which transforms either a record or an array of tools into a record where keys are tool names and values are the tool instances.
Signature
type ToolsByName<Tools> =
Tools extends Record<string, Tool.Any>
? { [Name in keyof Tools]: Tools[Name] }
: Tools extends ReadonlyArray<Tool.Any>
? { [Tool in Tools[number]]: Tool }
: never;WithHandlerTools type
A utility type which can be used to extract the tools from a toolkit with handlers.
Signature
type WithHandlerTools<T> = T extends WithHandler<infer Tools> ? Tools : never;
An empty toolkit with no tools.
When to use
Use when you need an empty starting point for building toolkits or a default toolkit value that can be extended with
merge.