Skip to main content Link Search Menu Expand Document (external link)
effect

Toolkit.ts overview

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.

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"
    })
})

Since v1.0.0

Exports Grouped by Category

Constructors

empty

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.

Signature

declare const empty: Toolkit<{}>

Source

Since v1.0.0

make

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.

Example

import { Toolkit, Tool } from "@effect/ai"
import { Schema } from "effect"

const GetCurrentTime = Tool.make("GetCurrentTime", {
  description: "Get the current timestamp",
  success: Schema.Number
})

const GetWeather = Tool.make("get_weather", {
  description: "Get weather information",
  parameters: { location: Schema.String },
  success: Schema.Struct({
    temperature: Schema.Number,
    condition: Schema.String
  })
})

const toolkit = Toolkit.make(GetCurrentTime, GetWeather)

Signature

declare const make: <Tools extends ReadonlyArray<Tool.Any>>(...tools: Tools) => Toolkit<ToolsByName<Tools>>

Source

Since v1.0.0

merge

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.

Example

import { Toolkit, Tool } from "@effect/ai"

const mathToolkit = Toolkit.make(Tool.make("add"), Tool.make("subtract"))

const utilityToolkit = Toolkit.make(Tool.make("get_time"), Tool.make("get_weather"))

const combined = Toolkit.merge(mathToolkit, utilityToolkit)
// combined now has: add, subtract, get_time, get_weather

Example

import { Toolkit, Tool } from "@effect/ai"

// Incremental toolkit building
const baseToolkit = Toolkit.make(Tool.make("base_tool"))
const extendedToolkit = Toolkit.merge(
  baseToolkit,
  Toolkit.make(Tool.make("additional_tool")),
  Toolkit.make(Tool.make("another_tool"))
)

Signature

declare const merge: <const Toolkits extends ReadonlyArray<Any>>(
  ...toolkits: Toolkits
) => Toolkit<MergedTools<Toolkits>>

Source

Since v1.0.0

Models

Toolkit (interface)

Represents a collection of tools which can be used to enhance the capabilities of a large language model.

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"
    })
})

Signature

export interface Toolkit<in out Tools extends Record<string, Tool.Any>>
  extends Effect.Effect<WithHandler<Tools>, never, Tool.HandlersFor<Tools>>,
    Inspectable,
    Pipeable {
  readonly [TypeId]: TypeId

  new (_: never): {}

  /**
   * A record containing all tools in this toolkit.
   */
  readonly tools: Tools

  /**
   * A helper method which can be used for type-safe handler declarations.
   */
  of<Handlers extends HandlersFrom<Tools>>(handlers: Handlers): Handlers

  /**
   * Converts a toolkit into an Effect Context containing handlers for each tool
   * in the toolkit.
   */
  toContext<Handlers extends HandlersFrom<Tools>, EX = never, RX = never>(
    build: Handlers | Effect.Effect<Handlers, EX, RX>
  ): Effect.Effect<Context.Context<Tool.HandlersFor<Tools>>, EX, RX>

  /**
   * Converts a toolkit into a Layer containing handlers for each tool in the
   * toolkit.
   */
  toLayer<Handlers extends HandlersFrom<Tools>, EX = never, RX = never>(
    /**
     * Handler functions or Effect that produces handlers.
     */
    build: Handlers | Effect.Effect<Handlers, EX, RX>
  ): Layer.Layer<Tool.HandlersFor<Tools>, EX, Exclude<RX, Scope.Scope>>
}

Source

Since v1.0.0

WithHandler (interface)

A toolkit instance with registered handlers ready for tool execution.

Signature

export interface WithHandler<in out Tools extends Record<string, Tool.Any>> {
  /**
   * The tools available in this toolkit instance.
   */
  readonly tools: Tools

  /**
   * Handler function for executing tool calls.
   *
   * Receives a tool name and parameters, validates the input, executes the
   * corresponding handler, and returns both the typed result and encoded result.
   */
  readonly handle: <Name extends keyof Tools>(
    /**
     * The name of the tool to execute.
     */
    name: Name,
    /**
     * Parameters to pass to the tool handler.
     */
    params: Tool.Parameters<Tools[Name]>
  ) => Effect.Effect<
    {
      readonly result: Tool.Success<Tools[Name]>
      readonly encodedResult: unknown
    },
    Tool.Failure<Tools[Name]>,
    Tool.Requirements<Tools[Name]>
  >
}

Source

Since v1.0.0

Type Ids

TypeId

Unique identifier for toolkit instances.

Signature

declare const TypeId: "~@effect/ai/Toolkit"

Source

Since v1.0.0

TypeId (type alias)

Type-level representation of the toolkit identifier.

Signature

type TypeId = typeof TypeId

Source

Since v1.0.0

Utility Types

Any (interface)

A utility type which structurally represents any toolkit instance.

Signature

export interface Any {
  readonly [TypeId]: TypeId
  readonly tools: Record<string, Tool.Any>
}

Source

Since v1.0.0

HandlersFrom (type alias)

A utility type that maps tool names to their required handler functions.

Signature

type HandlersFrom<Tools> = {
  readonly [Name in keyof Tools as Tool.RequiresHandler<Tools[Name]> extends true ? Name : never]: (
    params: Tool.Parameters<Tools[Name]>
  ) => Effect.Effect<Tool.Success<Tools[Name]>, Tool.Failure<Tools[Name]>, Tool.Requirements<Tools[Name]>>
}

Source

Since v1.0.0

MergeRecords (type alias)

A utility type which merges two records of tools together.

Signature

type MergeRecords<U> = {
  readonly [K in Extract<U extends unknown ? keyof U : never, string>]: Extract<
    U extends Record<K, infer V> ? V : never,
    Tool.Any
  >
}

Source

Since v1.0.0

MergedTools (type alias)

A utility type which merges the tool calls of two toolkits into a single toolkit.

Signature

type { [K in keyof MergeRecords<Tools<Toolkits[number]>>]: MergeRecords<Tools<Toolkits[number]>>[K]; } = SimplifyRecord<
  MergeRecords<Tools<Toolkits[number]>>
>

Source

Since v1.0.0

SimplifyRecord (type alias)

A utility type which simplifies a record type.

Signature

type { [K in keyof T]: T[K]; } = { [K in keyof T]: T[K] } & {}

Source

Since v1.0.0

Tools (type alias)

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

Source

Since v1.0.0

ToolsByName (type alias)

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>
    ? { readonly [Name in keyof Tools]: Tools[Name] }
    : Tools extends ReadonlyArray<Tool.Any>
      ? { readonly [Tool in Tools[number] as Tool["name"]]: Tool }
      : never

Source

Since v1.0.0