Toolkit
The Toolkit module allows for creating and implementing a collection of Tools which can be used to enhance the capabilities of a large language model beyond simple text generation.
Constructors
Signature
declare const empty: Toolkit<{}>;Creates a new toolkit from the specified tools.
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. Tools can be either Tool instances or TaggedRequest schemas.
Signature
declare function make<Tools extends readonly Array<Any>>(...tools: Tools): Toolkit<ToolsByName<Tools>>Merges multiple toolkits into a single toolkit.
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
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>>, Inspectable, Pipeable {
constructor(_: never);
readonly "~@effect/ai/Toolkit": "~@effect/ai/Toolkit";
readonly tools: Tools;
of<Handlers extends HandlersFrom<Tools>>(handlers: Handlers): Handlers;
toContext<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>>;
}Example
import { Toolkit, Tool } from "@effect/ai"
import { Effect, Schema } from "effect"
// Create individual tools
const GetCurrentTime = Tool.make("GetCurrentTime", {
description: "Get the current timestamp",
success: Schema.Number,
})
const GetWeather = Tool.make("GetWeather", {
description: "Get weather for a location",
parameters: { location: Schema.String },
success: Schema.Struct({
temperature: Schema.Number,
condition: Schema.String,
}),
})
// Create a toolkit with multiple tools
const MyToolkit = Toolkit.make(GetCurrentTime, GetWeather)
const MyToolkitLayer = MyToolkit.toLayer({
GetCurrentTime: () => Effect.succeed(Date.now()),
GetWeather: ({ location }) =>
Effect.succeed({
temperature: 72,
condition: "sunny",
}),
})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]>,
) => Effect<HandlerResult<Tools[Name]>, Failure<Tools[Name]>, Requirements<Tools[Name]>>;
readonly tools: Tools;
}Type Ids
Utility Types
A utility type which structurally represents any toolkit instance.
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.
Signature
type HandlersFrom<Tools extends Record<string, Tool.Any>> = {
[Name in keyof Tools]: (
params: Tool.Parameters<Tools[Name]>,
) => Effect.Effect<
Tool.Success<Tools[Name]>,
Tool.Failure<Tools[Name]>,
Tool.Requirements<Tools[Name]>
>;
};MergedTools type
A utility type which merges the tool calls of two toolkits into a single toolkit.
Signature
type MergedTools<Toolkits extends ReadonlyArray<Any>> = SimplifyRecord<
MergeRecords<Tools<Toolkits[number]>>
>;MergeRecords type
A utility type which merges two records of tools together.
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 simplifies a record type.
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 can 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.
Useful as a starting point for building toolkits or as a default value. Can be extended using the merge function to add tools.