Tool Use

Language models are great at generating text, but often we need them to take real-world actions, such as querying an API, accessing a database, or calling a service. Most LLM providers support this through tool use (also known as function calling), where you expose specific operations in your application that the model can invoke.

Based on the input it receives, a model may choose to invoke (or call) one or more tools to augment its response. Your application then runs the corresponding logic for the tool using the parameters provided by the model. You then return the result to the model, allowing it to include the output in its final response.

The AiToolkit simplifies tool integration by offering a structured, type-safe approach to defining tools. It takes care of all the wiring between the model and your application - all you have to do is define the tool and implement its behavior.

Defining a Tool

Let’s walk through a complete example of how to define, implement, and use a tool that fetches a dad joke from the icanhazdadjoke.com API.

1. Define the Tool

We start by defining a tool that the language model will have access to using the AiTool.make constructor.

This constructor accepts several parameters that allow us to fully describe the tool to the language model:

description: Provides an optional description of the tool
success: The type of value the tool will return if it succeeds
failure: The type of value the tool will return if it fails
parameters: The parameters that the tool should be called with

Example (Defining a Tool)

1
import { 
import AiTool
AiTool } from "@effect/ai"
2
import { 
import Schema
Schema } from "effect"
3

4
const 
const GetDadJoke: AiTool.AiTool<"GetDadJoke", Schema.Struct<{
    searchTerm: Schema.SchemaClass<string, string, never>;
}>, typeof Schema.String, typeof Schema.Never, never>
GetDadJoke = 
import AiTool
AiTool.
const make: <"GetDadJoke", {
    searchTerm: Schema.SchemaClass<string, string, never>;
}, typeof Schema.String, typeof Schema.Never>(name: "GetDadJoke", options?: {
    readonly description?: string | undefined;
    readonly parameters?: {
        ...;
    };
    readonly success?: typeof Schema.String;
    readonly failure?: typeof Schema.Never;
} | undefined) => AiTool.AiTool<...>
Constructs an AiTool from a name and, optionally, a specification for the
tool call's protocol.
@since ― 1.0.0
make("GetDadJoke", {
5
  
description?: string | undefined
An optional description of the tool.
description: "Get a hilarious dad joke from the ICanHazDadJoke API",
6
  
success?: typeof Schema.String
A Schema representing the type that a tool returns from its handler if
successful.
success: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String,
7
  
failure?: typeof Schema.Never
A Schema representing the type that a tool returns from its handler if
it fails.
failure: 
import Schema
Schema.
class Never@since ― 3.10.0
Never,
8
  
parameters?: {
    searchTerm: Schema.SchemaClass<string, string, never>;
}
A Schema representing the type of the parameters that a tool call
handler must be provided with.
parameters: {
9
    
searchTerm: Schema.SchemaClass<string, string, never>
searchTerm: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String.
Annotable<SchemaClass<string, string, never>, string, string, never>.annotations(annotations: Schema.Annotations.GenericSchema<string>): Schema.SchemaClass<string, string, never>
Merges a set of new annotations with existing ones, potentially overwriting
any duplicates.
annotations({
10
      
Annotations.Doc<string>.description?: string
description: "The search term to use to find dad jokes"
11
    })
12
  }
13
})

Based on the above, a request to call the GetDadJoke tool:

Takes a single searchTerm parameter
Will return a string if it succeeds (i.e. the joke)
Does not have any expected failure scenarios

2. Create a Toolkit

Once we have a tool request defined, we can create an AiToolkit, which is a collection of tools that the model will have access to.

Example (Creating an AiToolkit)

1
import { 
import AiTool
AiTool, 
import AiToolkit
AiToolkit } from "@effect/ai"
2
import { 
import Schema
Schema } from "effect"
3

4
class 
class DadJokeTools
DadJokeTools extends 
import AiToolkit
AiToolkit.
const make: <readonly [AiTool.AiTool<"GetDadJoke", Schema.Struct<{
    searchTerm: Schema.SchemaClass<string, string, never>;
}>, typeof Schema.String, typeof Schema.Never, never>]>(tools_0: AiTool.AiTool<...>) => AiToolkit.AiToolkit<...>
Constructs a new AiToolkit from the specified tools.
@since ― 1.0.0
make(
5
  
import AiTool
AiTool.
const make: <"GetDadJoke", {
    searchTerm: Schema.SchemaClass<string, string, never>;
}, typeof Schema.String, typeof Schema.Never>(name: "GetDadJoke", options?: {
    readonly description?: string | undefined;
    readonly parameters?: {
        ...;
    };
    readonly success?: typeof Schema.String;
    readonly failure?: typeof Schema.Never;
} | undefined) => AiTool.AiTool<...>
Constructs an AiTool from a name and, optionally, a specification for the
tool call's protocol.
@since ― 1.0.0
make("GetDadJoke", {
6
    
description?: string | undefined
An optional description of the tool.
description: "Get a hilarious dad joke from the ICanHazDadJoke API",
7
    
success?: typeof Schema.String
A Schema representing the type that a tool returns from its handler if
successful.
success: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String,
8
    
failure?: typeof Schema.Never
A Schema representing the type that a tool returns from its handler if
it fails.
failure: 
import Schema
Schema.
class Never@since ― 3.10.0
Never,
9
    
parameters?: {
    searchTerm: Schema.SchemaClass<string, string, never>;
}
A Schema representing the type of the parameters that a tool call
handler must be provided with.
parameters: {
10
      
searchTerm: Schema.SchemaClass<string, string, never>
searchTerm: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String.
Annotable<SchemaClass<string, string, never>, string, string, never>.annotations(annotations: Schema.Annotations.GenericSchema<string>): Schema.SchemaClass<string, string, never>
Merges a set of new annotations with existing ones, potentially overwriting
any duplicates.
annotations({
11
        
Annotations.Doc<string>.description?: string
description: "The search term to use to find dad jokes"
12
      })
13
    }
14
  })
15
) {}

3. Implement the Logic

The .toLayer(...) method on an AiToolkit allows you to define the handlers for each tool in the toolkit. Because .toLayer(...) takes an Effect, we can access services from our application to implement the tool call handlers.

Example (Implementing an AiToolkit)

1
import { 
import AiTool
AiTool, 
import AiToolkit
AiToolkit } from "@effect/ai"
2
import {
3
  
import HttpClient
HttpClient,
4
  
import HttpClientRequest
HttpClientRequest,
5
  
import HttpClientResponse
HttpClientResponse
6
} from "@effect/platform"
7
import { 
import NodeHttpClient
NodeHttpClient } from "@effect/platform-node"
8
import { 
import Array
Array, 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect, 
import Schema
Schema } from "effect"
9

38 collapsed lines
10
class 
class DadJoke
DadJoke extends 
import Schema
Schema.
const Class: <DadJoke>(identifier: string) => <Fields>(fieldsOr: Fields | HasFields<Fields>, annotations?: ClassAnnotations<DadJoke, { [K in keyof Schema.Struct<Fields extends Schema.Struct.Fields>.Type<Fields>]: Schema.Struct.Type<...>[K]; }> | undefined) => Schema.Class<...>@example 
import { Schema } from "effect"

class MyClass extends Schema.Class<MyClass>("MyClass")({
 someField: Schema.String
}) {
 someMethod() {
   return this.someField + "bar"
 }
}
@since ― 3.10.0
Class<
class DadJoke
DadJoke>("DadJoke")({
11
  
id: typeof Schema.String
id: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String,
12
  
joke: typeof Schema.String
joke: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String
13
}) {}
14

15
class 
class SearchResponse
SearchResponse extends 
import Schema
Schema.
const Class: <SearchResponse>(identifier: string) => <Fields>(fieldsOr: Fields | HasFields<Fields>, annotations?: ClassAnnotations<SearchResponse, { [K in keyof Schema.Struct<Fields extends Schema.Struct.Fields>.Type<...>]: Schema.Struct.Type<...>[K]; }> | undefined) => Schema.Class<...>@example 
import { Schema } from "effect"

class MyClass extends Schema.Class<MyClass>("MyClass")({
 someField: Schema.String
}) {
 someMethod() {
   return this.someField + "bar"
 }
}
@since ― 3.10.0
Class<
class SearchResponse
SearchResponse>("SearchResponse")({
16
  
results: Schema.Array$<typeof DadJoke>
results: 
import Schema
Schema.
Array<typeof DadJoke>(value: typeof DadJoke): Schema.Array$<typeof DadJoke>
export Array@since ― 3.10.0
Array(
class DadJoke
DadJoke)
17
}) {}
18

19
class 
class ICanHazDadJoke
ICanHazDadJoke extends 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const Service: <ICanHazDadJoke>() => {
    <Key, Make>(key: Key, make: Make): Effect.Service.Class<ICanHazDadJoke, Key, Make>;
    <Key, Make>(key: Key, make: Make): Effect.Service.Class<...>;
    <Key, Make>(key: Key, make: Make): Effect.Service.Class<...>;
    <Key, Make>(key: Key, make: Make): Effect.Service.Class<...>;
    <Key, Make>(key: Key, make: Make): Effect.Service.Class<...>;
}
Simplifies the creation and management of services in Effect by defining both
a Tag and a Layer.
Details
This function allows you to streamline the creation of services by combining
the definition of a Context.Tag and a Layer in a single step. It supports
various ways of providing the service implementation:

Using an effect to define the service dynamically.
Using sync or succeed to define the service statically.
Using scoped to create services with lifecycle management.

It also allows you to specify dependencies for the service, which will be
provided automatically when the service is used. Accessors can be optionally
generated for the service, making it more convenient to use.
Example
import { Effect } from 'effect';

class Prefix extends Effect.Service<Prefix>()("Prefix", {
 sync: () => ({ prefix: "PRE" })
}) {}

class Logger extends Effect.Service<Logger>()("Logger", {
 accessors: true,
 effect: Effect.gen(function* () {
   const { prefix } = yield* Prefix
   return {
     info: (message: string) =>
       Effect.sync(() => {
         console.log(`[${prefix}][${message}]`)
       })
   }
 }),
 dependencies: [Prefix.Default]
}) {}
@since ― 3.9.0
Service<
class ICanHazDadJoke
ICanHazDadJoke>()("ICanHazDadJoke", {
20
  
dependencies: readonly [Layer<HttpClient.HttpClient, never, never>]
dependencies: [
import NodeHttpClient
NodeHttpClient.
const layerUndici: Layer<HttpClient.HttpClient, never, never>@since ― 1.0.0
layerUndici],
21
  
effect: Effect.Effect<{
    readonly search: (this: unknown, searchTerm: string) => Effect.Effect<string, never, never>;
}, never, HttpClient.HttpClient>
effect: 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const gen: <YieldWrap<Tag<HttpClient.HttpClient, HttpClient.HttpClient>>, {
    readonly search: (this: unknown, searchTerm: string) => Effect.Effect<string, never, never>;
}>(f: (resume: Effect.Adapter) => Generator<...>) => Effect.Effect<...> (+1 overload)
Provides a way to write effectful code using generator functions, simplifying
control flow and error handling.
When to Use
Effect.gen allows you to write code that looks and behaves like synchronous
code, but it can handle asynchronous tasks, errors, and complex control flow
(like loops and conditions). It helps make asynchronous code more readable
and easier to manage.
The generator functions work similarly to async/await but with more
explicit control over the execution of effects. You can yield* values from
effects and return the final result at the end.
Example
import { Effect } from "effect"

const addServiceCharge = (amount: number) => amount + 1

const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, Error> =>
  discountRate === 0
    ? Effect.fail(new Error("Discount rate cannot be zero"))
    : Effect.succeed(total - (total * discountRate) / 100)

const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))

export const program = Effect.gen(function* () {
  const transactionAmount = yield* fetchTransactionAmount
  const discountRate = yield* fetchDiscountRate
  const discountedAmount = yield* applyDiscount(
    transactionAmount,
    discountRate
  )
  const finalAmount = addServiceCharge(discountedAmount)
  return `Final amount to charge: ${finalAmount}`
})
@since ― 2.0.0
gen(function*() {
22
    const 
const httpClient: HttpClient.HttpClient
httpClient = yield* 
import HttpClient
HttpClient.
const HttpClient: Tag<HttpClient.HttpClient, HttpClient.HttpClient>@since ― 1.0.0
@since ― 1.0.0
@since ― 1.0.0
HttpClient
23
    const 
const httpClientOk: HttpClient.HttpClient.With<HttpClientError, never>
httpClientOk = 
const httpClient: HttpClient.HttpClient
httpClient.
Pipeable.pipe<HttpClient.HttpClient, HttpClient.HttpClient.With<HttpClientError, never>, HttpClient.HttpClient.With<HttpClientError, never>>(this: HttpClient.HttpClient, ab: (_: HttpClient.HttpClient) => HttpClient.HttpClient.With<...>, bc: (_: HttpClient.HttpClient.With<...>) => HttpClient.HttpClient.With<...>): HttpClient.HttpClient.With<...> (+21 overloads)
pipe(
24
      
import HttpClient
HttpClient.
const filterStatusOk: <E, R>(self: HttpClient.HttpClient.With<E, R>) => HttpClient.HttpClient.With<E | ResponseError, R>
Filters responses that return a 2xx status code.
@since ― 1.0.0
filterStatusOk,
25
      
import HttpClient
HttpClient.
const mapRequest: (f: (a: HttpClientRequest.HttpClientRequest) => HttpClientRequest.HttpClientRequest) => <E, R>(self: HttpClient.HttpClient.With<E, R>) => HttpClient.HttpClient.With<E, R> (+1 overload)
Appends a transformation of the request object before sending it.
@since ― 1.0.0
mapRequest(
import HttpClientRequest
HttpClientRequest.
const prependUrl: (path: string) => (self: HttpClientRequest.HttpClientRequest) => HttpClientRequest.HttpClientRequest (+1 overload)@since ― 1.0.0
prependUrl("https://icanhazdadjoke.com"))
26
    )
27

28
    const 
const search: (this: unknown, searchTerm: string) => Effect.Effect<string, never, never>
search = 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fn: (name: string, options?: SpanOptions) => Effect.fn.Gen & Effect.fn.NonGen (+20 overloads)
fn("ICanHazDadJoke.search")(
29
      function*(
searchTerm: string
searchTerm: string) {
30
        return yield* 
const httpClientOk: HttpClient.HttpClient.With<HttpClientError, never>
httpClientOk.
HttpClient.With<HttpClientError, never>.get: (url: string | URL, options?: HttpClientRequest.Options.NoBody) => Effect.Effect<HttpClientResponse.HttpClientResponse, HttpClientError, never>
get("/search", {
31
          
acceptJson?: boolean | undefined
acceptJson: true,
32
          
urlParams?: Input | undefined
urlParams: { 
searchTerm: string
searchTerm }
33
        }).
Pipeable.pipe<Effect.Effect<HttpClientResponse.HttpClientResponse, HttpClientError, never>, Effect.Effect<SearchResponse, HttpClientError | ParseError, never>, Effect.Effect<...>, Effect.Effect<...>, Effect.Effect<...>, Effect.Effect<...>>(this: Effect.Effect<...>, ab: (_: Effect.Effect<...>) => Effect.Effect<...>, bc: (_: Effect.Effect<...>) => Effect.Effect<...>, cd: (_: Effect.Effect<...>) => Effect.Effect<...>, de: (_: Effect.Effect<...>) => Effect.Effect<...>, ef: (_: Effect.Effect<...>) => Effect.Effect<...>): Effect.Effect<...> (+21 overloads)
pipe(
34
          
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const flatMap: <HttpClientResponse.HttpClientResponse, SearchResponse, ResponseError | ParseError, never>(f: (a: HttpClientResponse.HttpClientResponse) => Effect.Effect<...>) => <E, R>(self: Effect.Effect<...>) => Effect.Effect<...> (+1 overload)
Chains effects to produce new Effect instances, useful for combining
operations that depend on previous results.
Syntax
const flatMappedEffect = pipe(myEffect, Effect.flatMap(transformation))
// or
const flatMappedEffect = Effect.flatMap(myEffect, transformation)
// or
const flatMappedEffect = myEffect.pipe(Effect.flatMap(transformation))
Details
flatMap lets you sequence effects so that the result of one effect can be
used in the next step. It is similar to flatMap used with arrays but works
specifically with Effect instances, allowing you to avoid deeply nested
effect structures.
Since effects are immutable, flatMap always returns a new effect instead of
changing the original one.
When to Use
Use flatMap when you need to chain multiple effects, ensuring that each
step produces a new Effect while flattening any nested effects that may
occur.
Example
import { pipe, Effect } from "effect"

// Function to apply a discount safely to a transaction amount
const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, Error> =>
  discountRate === 0
    ? Effect.fail(new Error("Discount rate cannot be zero"))
    : Effect.succeed(total - (total * discountRate) / 100)

// Simulated asynchronous task to fetch a transaction amount from database
const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

// Chaining the fetch and discount application using `flatMap`
const finalAmount = pipe(
  fetchTransactionAmount,
  Effect.flatMap((amount) => applyDiscount(amount, 5))
)

Effect.runPromise(finalAmount).then(console.log)
// Output: 95
@see ― tap for a version that ignores the result of the effect.
@since ― 2.0.0
flatMap(
import HttpClientResponse
HttpClientResponse.
schemaBodyJson<SearchResponse, {
    readonly results: readonly {
        readonly id: string;
        readonly joke: string;
    }[];
}, never>(schema: Schema.Schema<SearchResponse, {
    readonly results: readonly {
        readonly id: string;
        readonly joke: string;
    }[];
}, never>, options?: ParseOptions | undefined): <E>(self: HttpIncomingMessage<...>) => Effect.Effect<...>
export schemaBodyJson@since ― 1.0.0
schemaBodyJson(
class SearchResponse
SearchResponse)),
35
          
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const flatMap: <SearchResponse, DadJoke, NoSuchElementException, never>(f: (a: SearchResponse) => Effect.Effect<DadJoke, NoSuchElementException, never>) => <E, R>(self: Effect.Effect<...>) => Effect.Effect<...> (+1 overload)
Chains effects to produce new Effect instances, useful for combining
operations that depend on previous results.
Syntax
const flatMappedEffect = pipe(myEffect, Effect.flatMap(transformation))
// or
const flatMappedEffect = Effect.flatMap(myEffect, transformation)
// or
const flatMappedEffect = myEffect.pipe(Effect.flatMap(transformation))
Details
flatMap lets you sequence effects so that the result of one effect can be
used in the next step. It is similar to flatMap used with arrays but works
specifically with Effect instances, allowing you to avoid deeply nested
effect structures.
Since effects are immutable, flatMap always returns a new effect instead of
changing the original one.
When to Use
Use flatMap when you need to chain multiple effects, ensuring that each
step produces a new Effect while flattening any nested effects that may
occur.
Example
import { pipe, Effect } from "effect"

// Function to apply a discount safely to a transaction amount
const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, Error> =>
  discountRate === 0
    ? Effect.fail(new Error("Discount rate cannot be zero"))
    : Effect.succeed(total - (total * discountRate) / 100)

// Simulated asynchronous task to fetch a transaction amount from database
const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

// Chaining the fetch and discount application using `flatMap`
const finalAmount = pipe(
  fetchTransactionAmount,
  Effect.flatMap((amount) => applyDiscount(amount, 5))
)

Effect.runPromise(finalAmount).then(console.log)
// Output: 95
@see ― tap for a version that ignores the result of the effect.
@since ― 2.0.0
flatMap(({ 
results: readonly DadJoke[]
results }) => 
import Array
Array.
const head: <DadJoke>(self: readonly DadJoke[]) => Option<DadJoke>
Get the first element of a ReadonlyArray, or None if the ReadonlyArray is empty.
@since ― 2.0.0
head(
results: readonly DadJoke[]
results)),
36
          
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const map: <DadJoke, string>(f: (a: DadJoke) => string) => <E, R>(self: Effect.Effect<DadJoke, E, R>) => Effect.Effect<string, E, R> (+1 overload)
Transforms the value inside an effect by applying a function to it.
Syntax
const mappedEffect = pipe(myEffect, Effect.map(transformation))
// or
const mappedEffect = Effect.map(myEffect, transformation)
// or
const mappedEffect = myEffect.pipe(Effect.map(transformation))
Details
map takes a function and applies it to the value contained within an
effect, creating a new effect with the transformed value.
It's important to note that effects are immutable, meaning that the original
effect is not modified. Instead, a new effect is returned with the updated
value.
Example (Adding a Service Charge)
import { pipe, Effect } from "effect"

const addServiceCharge = (amount: number) => amount + 1

const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

const finalAmount = pipe(
  fetchTransactionAmount,
  Effect.map(addServiceCharge)
)

Effect.runPromise(finalAmount).then(console.log)
// Output: 101
@see ― mapError for a version that operates on the error channel.
@see ― mapBoth for a version that operates on both channels.
@see ― flatMap or andThen for a version that can return a new effect.
@since ― 2.0.0
map((
joke: DadJoke
joke) => 
joke: DadJoke
joke.
joke: string
joke),
37
          
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const scoped: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Scope>>
Scopes all resources used in an effect to the lifetime of the effect.
Details
This function ensures that all resources used within an effect are tied to
its lifetime. Finalizers for these resources are executed automatically when
the effect completes, whether through success, failure, or interruption. This
guarantees proper resource cleanup without requiring explicit management.
@since ― 2.0.0
scoped,
38
          
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const orDie: <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, never, R>
Converts an effect's failure into a fiber termination, removing the error
from the effect's type.
Details
The orDie function is used when you encounter errors that you do not want
to handle or recover from. It removes the error type from the effect and
ensures that any failure will terminate the fiber. This is useful for
propagating failures as defects, signaling that they should not be handled
within the effect.
*When to Use
Use orDie when failures should be treated as unrecoverable defects and no
error handling is required.
Example (Propagating an Error as a Defect)
import { Effect } from "effect"

const divide = (a: number, b: number) =>
  b === 0
    ? Effect.fail(new Error("Cannot divide by zero"))
    : Effect.succeed(a / b)

//      ┌─── Effect<number, never, never>
//      ▼
const program = Effect.orDie(divide(1, 0))

Effect.runPromise(program).catch(console.error)
// Output:
// (FiberFailure) Error: Cannot divide by zero
//   ...stack trace...
@see ― orDieWith if you need to customize the error.
@since ― 2.0.0
orDie
39
        )
40
      }
41
    )
42

43
    return {
44
      
search: (this: unknown, searchTerm: string) => Effect.Effect<string, never, never>
search
45
    } as 
type const = {
    readonly search: (this: unknown, searchTerm: string) => Effect.Effect<string, never, never>;
}
const
46
  })
47
}) {}
48

49
class 
class DadJokeTools
DadJokeTools extends 
import AiToolkit
AiToolkit.
const make: <readonly [AiTool.AiTool<"GetDadJoke", Schema.Struct<{
    searchTerm: Schema.SchemaClass<string, string, never>;
}>, typeof Schema.String, typeof Schema.Never, never>]>(tools_0: AiTool.AiTool<...>) => AiToolkit.AiToolkit<...>
Constructs a new AiToolkit from the specified tools.
@since ― 1.0.0
make(
50
  
import AiTool
AiTool.
const make: <"GetDadJoke", {
    searchTerm: Schema.SchemaClass<string, string, never>;
}, typeof Schema.String, typeof Schema.Never>(name: "GetDadJoke", options?: {
    readonly description?: string | undefined;
    readonly parameters?: {
        ...;
    };
    readonly success?: typeof Schema.String;
    readonly failure?: typeof Schema.Never;
} | undefined) => AiTool.AiTool<...>
Constructs an AiTool from a name and, optionally, a specification for the
tool call's protocol.
@since ― 1.0.0
make("GetDadJoke", {
51
    
description?: string | undefined
An optional description of the tool.
description: "Get a hilarious dad joke from the ICanHazDadJoke API",
52
    
success?: typeof Schema.String
A Schema representing the type that a tool returns from its handler if
successful.
success: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String,
53
    
failure?: typeof Schema.Never
A Schema representing the type that a tool returns from its handler if
it fails.
failure: 
import Schema
Schema.
class Never@since ― 3.10.0
Never,
54
    
parameters?: {
    searchTerm: Schema.SchemaClass<string, string, never>;
}
A Schema representing the type of the parameters that a tool call
handler must be provided with.
parameters: {
55
      
searchTerm: Schema.SchemaClass<string, string, never>
searchTerm: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String.
Annotable<SchemaClass<string, string, never>, string, string, never>.annotations(annotations: Schema.Annotations.GenericSchema<string>): Schema.SchemaClass<string, string, never>
Merges a set of new annotations with existing ones, potentially overwriting
any duplicates.
annotations({
56
        
Annotations.Doc<string>.description?: string
description: "The search term to use to find dad jokes"
57
      })
58
    }
59
  })
60
) {}
61

62
const 
const DadJokeToolHandlers: Layer<AiTool.Handler<"GetDadJoke">, never, ICanHazDadJoke>
DadJokeToolHandlers = 
class DadJokeTools
DadJokeTools.
AiToolkit<AiTool<"GetDadJoke", Struct<{ searchTerm: SchemaClass<string, string, never>; }>, typeof String$, typeof Never, never>>.toLayer<{
    GetDadJoke: ({ searchTerm }: {
        readonly searchTerm: string;
    }) => Effect.Effect<string, never, never>;
}, never, ICanHazDadJoke>(build: {
    GetDadJoke: ({ searchTerm }: {
        readonly searchTerm: string;
    }) => Effect.Effect<string, never, never>;
} | Effect.Effect<...>): Layer<...>
Converts this toolkit into a Layer containing the handlers for all tools
in the toolkit.
toLayer(
63
  
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const gen: <YieldWrap<Tag<ICanHazDadJoke, ICanHazDadJoke>>, {
    GetDadJoke: ({ searchTerm }: {
        readonly searchTerm: string;
    }) => Effect.Effect<string, never, never>;
}>(f: (resume: Effect.Adapter) => Generator<...>) => Effect.Effect<...> (+1 overload)
Provides a way to write effectful code using generator functions, simplifying
control flow and error handling.
When to Use
Effect.gen allows you to write code that looks and behaves like synchronous
code, but it can handle asynchronous tasks, errors, and complex control flow
(like loops and conditions). It helps make asynchronous code more readable
and easier to manage.
The generator functions work similarly to async/await but with more
explicit control over the execution of effects. You can yield* values from
effects and return the final result at the end.
Example
import { Effect } from "effect"

const addServiceCharge = (amount: number) => amount + 1

const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, Error> =>
  discountRate === 0
    ? Effect.fail(new Error("Discount rate cannot be zero"))
    : Effect.succeed(total - (total * discountRate) / 100)

const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))

export const program = Effect.gen(function* () {
  const transactionAmount = yield* fetchTransactionAmount
  const discountRate = yield* fetchDiscountRate
  const discountedAmount = yield* applyDiscount(
    transactionAmount,
    discountRate
  )
  const finalAmount = addServiceCharge(discountedAmount)
  return `Final amount to charge: ${finalAmount}`
})
@since ― 2.0.0
gen(function*() {
64
    // Access the `ICanHazDadJoke` service
65
    const 
const icanhazdadjoke: ICanHazDadJoke
icanhazdadjoke = yield* 
class ICanHazDadJoke
ICanHazDadJoke
66
    return {
67
      // Implement the handler for the `GetDadJoke` tool call request
68
      
type GetDadJoke: ({ searchTerm }: {
    readonly searchTerm: string;
}) => Effect.Effect<string, never, never>
GetDadJoke: ({ 
searchTerm: string
searchTerm }) => 
const icanhazdadjoke: ICanHazDadJoke
icanhazdadjoke.
search: (this: unknown, searchTerm: string) => Effect.Effect<string, never, never>
search(
searchTerm: string
searchTerm)
69
    }
70
  })
71
)

In the code above:

We access the ICanHazDadJoke service from our application
Register a handler for the GetDadJoke tool using .handle("GetDadJoke", ...)
Use the .search method on our ICanHazDadJoke service to search for a dad joke based on the tool call parameters

The result of calling .toLayer on an AiToolkit is a Layer that contains the handlers for all the tools in our toolkit.

Because of this, it is quite simple to test an AiToolkit by using .toLayer to create a separate Layer specifically for testing.

4. Give the Tools to the Model

Once the tools are defined and implemented, you can pass them along to the model at request time. Behind the scenes, the model is given a structured description of each tool and can choose to call one or more of them when responding to input.

Example (Using an AiToolkit in Completions.toolkit)

1
import { 
import AiLanguageModel
AiLanguageModel, 
import AiTool
AiTool, 
import AiToolkit
AiToolkit } from "@effect/ai"
2
import { 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect, 
import Schema
Schema } from "effect"
3

4
class 
class DadJokeTools
DadJokeTools extends 
import AiToolkit
AiToolkit.
const make: <readonly [AiTool.AiTool<"GetDadJoke", Schema.Struct<{
    searchTerm: Schema.SchemaClass<string, string, never>;
}>, typeof Schema.String, typeof Schema.Never, never>]>(tools_0: AiTool.AiTool<...>) => AiToolkit.AiToolkit<...>
Constructs a new AiToolkit from the specified tools.
@since ― 1.0.0
make(
5
  
import AiTool
AiTool.
const make: <"GetDadJoke", {
    searchTerm: Schema.SchemaClass<string, string, never>;
}, typeof Schema.String, typeof Schema.Never>(name: "GetDadJoke", options?: {
    readonly description?: string | undefined;
    readonly parameters?: {
        ...;
    };
    readonly success?: typeof Schema.String;
    readonly failure?: typeof Schema.Never;
} | undefined) => AiTool.AiTool<...>
Constructs an AiTool from a name and, optionally, a specification for the
tool call's protocol.
@since ― 1.0.0
make("GetDadJoke", {
6
    
description?: string | undefined
An optional description of the tool.
description: "Get a hilarious dad joke from the ICanHazDadJoke API",
7
    
success?: typeof Schema.String
A Schema representing the type that a tool returns from its handler if
successful.
success: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String,
8
    
failure?: typeof Schema.Never
A Schema representing the type that a tool returns from its handler if
it fails.
failure: 
import Schema
Schema.
class Never@since ― 3.10.0
Never,
9
    
parameters?: {
    searchTerm: Schema.SchemaClass<string, string, never>;
}
A Schema representing the type of the parameters that a tool call
handler must be provided with.
parameters: {
10
      
searchTerm: Schema.SchemaClass<string, string, never>
searchTerm: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String.
Annotable<SchemaClass<string, string, never>, string, string, never>.annotations(annotations: Schema.Annotations.GenericSchema<string>): Schema.SchemaClass<string, string, never>
Merges a set of new annotations with existing ones, potentially overwriting
any duplicates.
annotations({
11
        
Annotations.Doc<string>.description?: string
description: "The search term to use to find dad jokes"
12
      })
13
    }
14
  })
15
) {}
16

17
const 
const generateDadJoke: Effect.Effect<AiResponse, AiError, AiLanguageModel.AiLanguageModel>
generateDadJoke = 
import AiLanguageModel
AiLanguageModel.
const generateText: <AiTool.Any, {
    prompt: string;
    tools: typeof DadJokeTools;
}>(options: {
    prompt: string;
    tools: typeof DadJokeTools;
} & AiLanguageModel.GenerateTextOptions<AiTool.Any>) => Effect.Effect<...>
Generate text using a large language model for the specified prompt.
If a toolkit is specified, the large language model will additionally
be able to perform tool calls to augment its response.
@since ― 1.0.0
generateText({
18
  
prompt: string & Raw
The prompt input to use to generate text.
prompt: "Generate a dad joke about pirates",
19
  
tools: typeof DadJokeTools
tools: 
class DadJokeTools
DadJokeTools
20
})

5. Bring It All Together

To make the program executable, we must provide the implementation of our tool call handlers:

Example (Providing the Tool Call Handlers to a Program)

1
import { 
import AiLanguageModel
AiLanguageModel, 
import AiTool
AiTool, 
import AiToolkit
AiToolkit } from "@effect/ai"
2
import { 
import OpenAiClient
OpenAiClient, 
import OpenAiLanguageModel
OpenAiLanguageModel } from "@effect/ai-openai"
3
import {
4
  
import HttpClient
HttpClient,
5
  
import HttpClientRequest
HttpClientRequest,
6
  
import HttpClientResponse
HttpClientResponse
7
} from "@effect/platform"
8
import { 
import NodeHttpClient
NodeHttpClient } from "@effect/platform-node"
9
import { 
import Array
Array, 
import Config
Config, 
import Console
Console, 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect, 
import Layer
Layer, 
import Schema
Schema } from "effect"
10

51 collapsed lines
11
class 
class DadJoke
DadJoke extends 
import Schema
Schema.
const Class: <DadJoke>(identifier: string) => <Fields>(fieldsOr: Fields | HasFields<Fields>, annotations?: ClassAnnotations<DadJoke, { [K in keyof Schema.Struct<Fields extends Schema.Struct.Fields>.Type<Fields>]: Schema.Struct.Type<...>[K]; }> | undefined) => Schema.Class<...>@example 
import { Schema } from "effect"

class MyClass extends Schema.Class<MyClass>("MyClass")({
 someField: Schema.String
}) {
 someMethod() {
   return this.someField + "bar"
 }
}
@since ― 3.10.0
Class<
class DadJoke
DadJoke>("DadJoke")({
12
  
id: typeof Schema.String
id: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String,
13
  
joke: typeof Schema.String
joke: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String
14
}) {}
15

16
class 
class SearchResponse
SearchResponse extends 
import Schema
Schema.
const Class: <SearchResponse>(identifier: string) => <Fields>(fieldsOr: Fields | HasFields<Fields>, annotations?: ClassAnnotations<SearchResponse, { [K in keyof Schema.Struct<Fields extends Schema.Struct.Fields>.Type<...>]: Schema.Struct.Type<...>[K]; }> | undefined) => Schema.Class<...>@example 
import { Schema } from "effect"

class MyClass extends Schema.Class<MyClass>("MyClass")({
 someField: Schema.String
}) {
 someMethod() {
   return this.someField + "bar"
 }
}
@since ― 3.10.0
Class<
class SearchResponse
SearchResponse>("SearchResponse")({
17
  
results: Schema.Array$<typeof DadJoke>
results: 
import Schema
Schema.
Array<typeof DadJoke>(value: typeof DadJoke): Schema.Array$<typeof DadJoke>
export Array@since ― 3.10.0
Array(
class DadJoke
DadJoke)
18
}) {}
19

20
class 
class ICanHazDadJoke
ICanHazDadJoke extends 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const Service: <ICanHazDadJoke>() => {
    <Key, Make>(key: Key, make: Make): Effect.Service.Class<ICanHazDadJoke, Key, Make>;
    <Key, Make>(key: Key, make: Make): Effect.Service.Class<...>;
    <Key, Make>(key: Key, make: Make): Effect.Service.Class<...>;
    <Key, Make>(key: Key, make: Make): Effect.Service.Class<...>;
    <Key, Make>(key: Key, make: Make): Effect.Service.Class<...>;
}
Simplifies the creation and management of services in Effect by defining both
a Tag and a Layer.
Details
This function allows you to streamline the creation of services by combining
the definition of a Context.Tag and a Layer in a single step. It supports
various ways of providing the service implementation:

Using an effect to define the service dynamically.
Using sync or succeed to define the service statically.
Using scoped to create services with lifecycle management.

It also allows you to specify dependencies for the service, which will be
provided automatically when the service is used. Accessors can be optionally
generated for the service, making it more convenient to use.
Example
import { Effect } from 'effect';

class Prefix extends Effect.Service<Prefix>()("Prefix", {
 sync: () => ({ prefix: "PRE" })
}) {}

class Logger extends Effect.Service<Logger>()("Logger", {
 accessors: true,
 effect: Effect.gen(function* () {
   const { prefix } = yield* Prefix
   return {
     info: (message: string) =>
       Effect.sync(() => {
         console.log(`[${prefix}][${message}]`)
       })
   }
 }),
 dependencies: [Prefix.Default]
}) {}
@since ― 3.9.0
Service<
class ICanHazDadJoke
ICanHazDadJoke>()("ICanHazDadJoke", {
21
  
dependencies: readonly [Layer.Layer<HttpClient.HttpClient, never, never>]
dependencies: [
import NodeHttpClient
NodeHttpClient.
const layerUndici: Layer.Layer<HttpClient.HttpClient, never, never>@since ― 1.0.0
layerUndici],
22
  
effect: Effect.Effect<{
    readonly search: (this: unknown, searchTerm: string) => Effect.Effect<string, never, never>;
}, never, HttpClient.HttpClient>
effect: 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const gen: <YieldWrap<Tag<HttpClient.HttpClient, HttpClient.HttpClient>>, {
    readonly search: (this: unknown, searchTerm: string) => Effect.Effect<string, never, never>;
}>(f: (resume: Effect.Adapter) => Generator<...>) => Effect.Effect<...> (+1 overload)
Provides a way to write effectful code using generator functions, simplifying
control flow and error handling.
When to Use
Effect.gen allows you to write code that looks and behaves like synchronous
code, but it can handle asynchronous tasks, errors, and complex control flow
(like loops and conditions). It helps make asynchronous code more readable
and easier to manage.
The generator functions work similarly to async/await but with more
explicit control over the execution of effects. You can yield* values from
effects and return the final result at the end.
Example
import { Effect } from "effect"

const addServiceCharge = (amount: number) => amount + 1

const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, Error> =>
  discountRate === 0
    ? Effect.fail(new Error("Discount rate cannot be zero"))
    : Effect.succeed(total - (total * discountRate) / 100)

const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))

export const program = Effect.gen(function* () {
  const transactionAmount = yield* fetchTransactionAmount
  const discountRate = yield* fetchDiscountRate
  const discountedAmount = yield* applyDiscount(
    transactionAmount,
    discountRate
  )
  const finalAmount = addServiceCharge(discountedAmount)
  return `Final amount to charge: ${finalAmount}`
})
@since ― 2.0.0
gen(function*() {
23
    const 
const httpClient: HttpClient.HttpClient
httpClient = yield* 
import HttpClient
HttpClient.
const HttpClient: Tag<HttpClient.HttpClient, HttpClient.HttpClient>@since ― 1.0.0
@since ― 1.0.0
@since ― 1.0.0
HttpClient
24
    const 
const httpClientOk: HttpClient.HttpClient.With<HttpClientError, never>
httpClientOk = 
const httpClient: HttpClient.HttpClient
httpClient.
Pipeable.pipe<HttpClient.HttpClient, HttpClient.HttpClient.With<HttpClientError, never>, HttpClient.HttpClient.With<HttpClientError, never>>(this: HttpClient.HttpClient, ab: (_: HttpClient.HttpClient) => HttpClient.HttpClient.With<...>, bc: (_: HttpClient.HttpClient.With<...>) => HttpClient.HttpClient.With<...>): HttpClient.HttpClient.With<...> (+21 overloads)
pipe(
25
      
import HttpClient
HttpClient.
const filterStatusOk: <E, R>(self: HttpClient.HttpClient.With<E, R>) => HttpClient.HttpClient.With<E | ResponseError, R>
Filters responses that return a 2xx status code.
@since ― 1.0.0
filterStatusOk,
26
      
import HttpClient
HttpClient.
const mapRequest: (f: (a: HttpClientRequest.HttpClientRequest) => HttpClientRequest.HttpClientRequest) => <E, R>(self: HttpClient.HttpClient.With<E, R>) => HttpClient.HttpClient.With<E, R> (+1 overload)
Appends a transformation of the request object before sending it.
@since ― 1.0.0
mapRequest(
import HttpClientRequest
HttpClientRequest.
const prependUrl: (path: string) => (self: HttpClientRequest.HttpClientRequest) => HttpClientRequest.HttpClientRequest (+1 overload)@since ― 1.0.0
prependUrl("https://icanhazdadjoke.com"))
27
    )
28

29
    const 
const search: (this: unknown, searchTerm: string) => Effect.Effect<string, never, never>
search = 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const fn: (name: string, options?: SpanOptions) => Effect.fn.Gen & Effect.fn.NonGen (+20 overloads)
fn("ICanHazDadJoke.search")(
30
      function*(
searchTerm: string
searchTerm: string) {
31
        return yield* 
const httpClientOk: HttpClient.HttpClient.With<HttpClientError, never>
httpClientOk.
HttpClient.With<HttpClientError, never>.get: (url: string | URL, options?: HttpClientRequest.Options.NoBody) => Effect.Effect<HttpClientResponse.HttpClientResponse, HttpClientError, never>
get("/search", {
32
          
acceptJson?: boolean | undefined
acceptJson: true,
33
          
urlParams?: Input | undefined
urlParams: { 
searchTerm: string
searchTerm }
34
        }).
Pipeable.pipe<Effect.Effect<HttpClientResponse.HttpClientResponse, HttpClientError, never>, Effect.Effect<SearchResponse, HttpClientError | ParseError, never>, Effect.Effect<...>, Effect.Effect<...>, Effect.Effect<...>, Effect.Effect<...>>(this: Effect.Effect<...>, ab: (_: Effect.Effect<...>) => Effect.Effect<...>, bc: (_: Effect.Effect<...>) => Effect.Effect<...>, cd: (_: Effect.Effect<...>) => Effect.Effect<...>, de: (_: Effect.Effect<...>) => Effect.Effect<...>, ef: (_: Effect.Effect<...>) => Effect.Effect<...>): Effect.Effect<...> (+21 overloads)
pipe(
35
          
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const flatMap: <HttpClientResponse.HttpClientResponse, SearchResponse, ResponseError | ParseError, never>(f: (a: HttpClientResponse.HttpClientResponse) => Effect.Effect<...>) => <E, R>(self: Effect.Effect<...>) => Effect.Effect<...> (+1 overload)
Chains effects to produce new Effect instances, useful for combining
operations that depend on previous results.
Syntax
const flatMappedEffect = pipe(myEffect, Effect.flatMap(transformation))
// or
const flatMappedEffect = Effect.flatMap(myEffect, transformation)
// or
const flatMappedEffect = myEffect.pipe(Effect.flatMap(transformation))
Details
flatMap lets you sequence effects so that the result of one effect can be
used in the next step. It is similar to flatMap used with arrays but works
specifically with Effect instances, allowing you to avoid deeply nested
effect structures.
Since effects are immutable, flatMap always returns a new effect instead of
changing the original one.
When to Use
Use flatMap when you need to chain multiple effects, ensuring that each
step produces a new Effect while flattening any nested effects that may
occur.
Example
import { pipe, Effect } from "effect"

// Function to apply a discount safely to a transaction amount
const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, Error> =>
  discountRate === 0
    ? Effect.fail(new Error("Discount rate cannot be zero"))
    : Effect.succeed(total - (total * discountRate) / 100)

// Simulated asynchronous task to fetch a transaction amount from database
const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

// Chaining the fetch and discount application using `flatMap`
const finalAmount = pipe(
  fetchTransactionAmount,
  Effect.flatMap((amount) => applyDiscount(amount, 5))
)

Effect.runPromise(finalAmount).then(console.log)
// Output: 95
@see ― tap for a version that ignores the result of the effect.
@since ― 2.0.0
flatMap(
import HttpClientResponse
HttpClientResponse.
schemaBodyJson<SearchResponse, {
    readonly results: readonly {
        readonly id: string;
        readonly joke: string;
    }[];
}, never>(schema: Schema.Schema<SearchResponse, {
    readonly results: readonly {
        readonly id: string;
        readonly joke: string;
    }[];
}, never>, options?: ParseOptions | undefined): <E>(self: HttpIncomingMessage<...>) => Effect.Effect<...>
export schemaBodyJson@since ― 1.0.0
schemaBodyJson(
class SearchResponse
SearchResponse)),
36
          
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const flatMap: <SearchResponse, DadJoke, NoSuchElementException, never>(f: (a: SearchResponse) => Effect.Effect<DadJoke, NoSuchElementException, never>) => <E, R>(self: Effect.Effect<...>) => Effect.Effect<...> (+1 overload)
Chains effects to produce new Effect instances, useful for combining
operations that depend on previous results.
Syntax
const flatMappedEffect = pipe(myEffect, Effect.flatMap(transformation))
// or
const flatMappedEffect = Effect.flatMap(myEffect, transformation)
// or
const flatMappedEffect = myEffect.pipe(Effect.flatMap(transformation))
Details
flatMap lets you sequence effects so that the result of one effect can be
used in the next step. It is similar to flatMap used with arrays but works
specifically with Effect instances, allowing you to avoid deeply nested
effect structures.
Since effects are immutable, flatMap always returns a new effect instead of
changing the original one.
When to Use
Use flatMap when you need to chain multiple effects, ensuring that each
step produces a new Effect while flattening any nested effects that may
occur.
Example
import { pipe, Effect } from "effect"

// Function to apply a discount safely to a transaction amount
const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, Error> =>
  discountRate === 0
    ? Effect.fail(new Error("Discount rate cannot be zero"))
    : Effect.succeed(total - (total * discountRate) / 100)

// Simulated asynchronous task to fetch a transaction amount from database
const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

// Chaining the fetch and discount application using `flatMap`
const finalAmount = pipe(
  fetchTransactionAmount,
  Effect.flatMap((amount) => applyDiscount(amount, 5))
)

Effect.runPromise(finalAmount).then(console.log)
// Output: 95
@see ― tap for a version that ignores the result of the effect.
@since ― 2.0.0
flatMap(({ 
results: readonly DadJoke[]
results }) => 
import Array
Array.
const head: <DadJoke>(self: readonly DadJoke[]) => Option<DadJoke>
Get the first element of a ReadonlyArray, or None if the ReadonlyArray is empty.
@since ― 2.0.0
head(
results: readonly DadJoke[]
results)),
37
          
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const map: <DadJoke, string>(f: (a: DadJoke) => string) => <E, R>(self: Effect.Effect<DadJoke, E, R>) => Effect.Effect<string, E, R> (+1 overload)
Transforms the value inside an effect by applying a function to it.
Syntax
const mappedEffect = pipe(myEffect, Effect.map(transformation))
// or
const mappedEffect = Effect.map(myEffect, transformation)
// or
const mappedEffect = myEffect.pipe(Effect.map(transformation))
Details
map takes a function and applies it to the value contained within an
effect, creating a new effect with the transformed value.
It's important to note that effects are immutable, meaning that the original
effect is not modified. Instead, a new effect is returned with the updated
value.
Example (Adding a Service Charge)
import { pipe, Effect } from "effect"

const addServiceCharge = (amount: number) => amount + 1

const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

const finalAmount = pipe(
  fetchTransactionAmount,
  Effect.map(addServiceCharge)
)

Effect.runPromise(finalAmount).then(console.log)
// Output: 101
@see ― mapError for a version that operates on the error channel.
@see ― mapBoth for a version that operates on both channels.
@see ― flatMap or andThen for a version that can return a new effect.
@since ― 2.0.0
map((
joke: DadJoke
joke) => 
joke: DadJoke
joke.
joke: string
joke),
38
          
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const scoped: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Scope>>
Scopes all resources used in an effect to the lifetime of the effect.
Details
This function ensures that all resources used within an effect are tied to
its lifetime. Finalizers for these resources are executed automatically when
the effect completes, whether through success, failure, or interruption. This
guarantees proper resource cleanup without requiring explicit management.
@since ― 2.0.0
scoped,
39
          
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const orDie: <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, never, R>
Converts an effect's failure into a fiber termination, removing the error
from the effect's type.
Details
The orDie function is used when you encounter errors that you do not want
to handle or recover from. It removes the error type from the effect and
ensures that any failure will terminate the fiber. This is useful for
propagating failures as defects, signaling that they should not be handled
within the effect.
*When to Use
Use orDie when failures should be treated as unrecoverable defects and no
error handling is required.
Example (Propagating an Error as a Defect)
import { Effect } from "effect"

const divide = (a: number, b: number) =>
  b === 0
    ? Effect.fail(new Error("Cannot divide by zero"))
    : Effect.succeed(a / b)

//      ┌─── Effect<number, never, never>
//      ▼
const program = Effect.orDie(divide(1, 0))

Effect.runPromise(program).catch(console.error)
// Output:
// (FiberFailure) Error: Cannot divide by zero
//   ...stack trace...
@see ― orDieWith if you need to customize the error.
@since ― 2.0.0
orDie
40
        )
41
      }
42
    )
43

44
    return {
45
      
search: (this: unknown, searchTerm: string) => Effect.Effect<string, never, never>
search
46
    } as 
type const = {
    readonly search: (this: unknown, searchTerm: string) => Effect.Effect<string, never, never>;
}
const
47
  })
48
}) {}
49

50
class 
class DadJokeTools
DadJokeTools extends 
import AiToolkit
AiToolkit.
const make: <readonly [AiTool.AiTool<"GetDadJoke", Schema.Struct<{
    searchTerm: Schema.SchemaClass<string, string, never>;
}>, typeof Schema.String, typeof Schema.Never, never>]>(tools_0: AiTool.AiTool<...>) => AiToolkit.AiToolkit<...>
Constructs a new AiToolkit from the specified tools.
@since ― 1.0.0
make(
51
  
import AiTool
AiTool.
const make: <"GetDadJoke", {
    searchTerm: Schema.SchemaClass<string, string, never>;
}, typeof Schema.String, typeof Schema.Never>(name: "GetDadJoke", options?: {
    readonly description?: string | undefined;
    readonly parameters?: {
        ...;
    };
    readonly success?: typeof Schema.String;
    readonly failure?: typeof Schema.Never;
} | undefined) => AiTool.AiTool<...>
Constructs an AiTool from a name and, optionally, a specification for the
tool call's protocol.
@since ― 1.0.0
make("GetDadJoke", {
52
    
description?: string | undefined
An optional description of the tool.
description: "Get a hilarious dad joke from the ICanHazDadJoke API",
53
    
success?: typeof Schema.String
A Schema representing the type that a tool returns from its handler if
successful.
success: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String,
54
    
failure?: typeof Schema.Never
A Schema representing the type that a tool returns from its handler if
it fails.
failure: 
import Schema
Schema.
class Never@since ― 3.10.0
Never,
55
    
parameters?: {
    searchTerm: Schema.SchemaClass<string, string, never>;
}
A Schema representing the type of the parameters that a tool call
handler must be provided with.
parameters: {
56
      
searchTerm: Schema.SchemaClass<string, string, never>
searchTerm: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String.
Annotable<SchemaClass<string, string, never>, string, string, never>.annotations(annotations: Schema.Annotations.GenericSchema<string>): Schema.SchemaClass<string, string, never>
Merges a set of new annotations with existing ones, potentially overwriting
any duplicates.
annotations({
57
        
Annotations.Doc<string>.description?: string
description: "The search term to use to find dad jokes"
58
      })
59
    }
60
  })
61
) {}
62

63
const 
const DadJokeToolHandlers: Layer.Layer<AiTool.Handler<"GetDadJoke">, never, never>
DadJokeToolHandlers = 
class DadJokeTools
DadJokeTools.
AiToolkit<AiTool<"GetDadJoke", Struct<{ searchTerm: SchemaClass<string, string, never>; }>, typeof String$, typeof Never, never>>.toLayer<{
    GetDadJoke: ({ searchTerm }: {
        readonly searchTerm: string;
    }) => Effect.Effect<string, never, never>;
}, never, ICanHazDadJoke>(build: {
    GetDadJoke: ({ searchTerm }: {
        readonly searchTerm: string;
    }) => Effect.Effect<string, never, never>;
} | Effect.Effect<...>): Layer.Layer<...>
Converts this toolkit into a Layer containing the handlers for all tools
in the toolkit.
toLayer(
64
  
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const gen: <YieldWrap<Tag<ICanHazDadJoke, ICanHazDadJoke>>, {
    GetDadJoke: ({ searchTerm }: {
        readonly searchTerm: string;
    }) => Effect.Effect<string, never, never>;
}>(f: (resume: Effect.Adapter) => Generator<...>) => Effect.Effect<...> (+1 overload)
Provides a way to write effectful code using generator functions, simplifying
control flow and error handling.
When to Use
Effect.gen allows you to write code that looks and behaves like synchronous
code, but it can handle asynchronous tasks, errors, and complex control flow
(like loops and conditions). It helps make asynchronous code more readable
and easier to manage.
The generator functions work similarly to async/await but with more
explicit control over the execution of effects. You can yield* values from
effects and return the final result at the end.
Example
import { Effect } from "effect"

const addServiceCharge = (amount: number) => amount + 1

const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, Error> =>
  discountRate === 0
    ? Effect.fail(new Error("Discount rate cannot be zero"))
    : Effect.succeed(total - (total * discountRate) / 100)

const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))

export const program = Effect.gen(function* () {
  const transactionAmount = yield* fetchTransactionAmount
  const discountRate = yield* fetchDiscountRate
  const discountedAmount = yield* applyDiscount(
    transactionAmount,
    discountRate
  )
  const finalAmount = addServiceCharge(discountedAmount)
  return `Final amount to charge: ${finalAmount}`
})
@since ― 2.0.0
gen(function*() {
65
    const 
const icanhazdadjoke: ICanHazDadJoke
icanhazdadjoke = yield* 
class ICanHazDadJoke
ICanHazDadJoke
66
    return {
67
      
type GetDadJoke: ({ searchTerm }: {
    readonly searchTerm: string;
}) => Effect.Effect<string, never, never>
GetDadJoke: ({ 
searchTerm: string
searchTerm }) => 
const icanhazdadjoke: ICanHazDadJoke
icanhazdadjoke.
search: (this: unknown, searchTerm: string) => Effect.Effect<string, never, never>
search(
searchTerm: string
searchTerm)
68
    }
69
  })
70
).
Pipeable.pipe<Layer.Layer<AiTool.Handler<"GetDadJoke">, never, ICanHazDadJoke>, Layer.Layer<AiTool.Handler<"GetDadJoke">, never, never>>(this: Layer.Layer<...>, ab: (_: Layer.Layer<...>) => Layer.Layer<...>): Layer.Layer<...> (+21 overloads)
pipe(
import Layer
Layer.
const provide: <never, never, ICanHazDadJoke>(that: Layer.Layer<ICanHazDadJoke, never, never>) => <RIn2, E2, ROut2>(self: Layer.Layer<ROut2, E2, RIn2>) => Layer.Layer<...> (+3 overloads)
Feeds the output services of this builder into the input of the specified
builder, resulting in a new builder with the inputs of this builder as
well as any leftover inputs, and the outputs of the specified builder.
@since ― 2.0.0
provide(
class ICanHazDadJoke
ICanHazDadJoke.
type Default: Layer.Layer<ICanHazDadJoke, never, never>
Default))
71

72
const 
const program: Effect.Effect<void, AiError, OpenAiClient.OpenAiClient>
program = 
import AiLanguageModel
AiLanguageModel.
const generateText: <AiTool.Any, {
    prompt: string;
    tools: typeof DadJokeTools;
}>(options: {
    prompt: string;
    tools: typeof DadJokeTools;
} & AiLanguageModel.GenerateTextOptions<AiTool.Any>) => Effect.Effect<...>
Generate text using a large language model for the specified prompt.
If a toolkit is specified, the large language model will additionally
be able to perform tool calls to augment its response.
@since ― 1.0.0
generateText({
73
  
prompt: string & Raw
The prompt input to use to generate text.
prompt: "Generate a dad joke about pirates",
74
  
tools: typeof DadJokeTools
tools: 
class DadJokeTools
DadJokeTools
75
}).
Pipeable.pipe<Effect.Effect<AiResponse, AiError, AiLanguageModel.AiLanguageModel>, Effect.Effect<void, AiError, AiLanguageModel.AiLanguageModel>, Effect.Effect<...>>(this: Effect.Effect<...>, ab: (_: Effect.Effect<...>) => Effect.Effect<...>, bc: (_: Effect.Effect<...>) => Effect.Effect<...>): Effect.Effect<...> (+21 overloads)
pipe(
76
  
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const flatMap: <AiResponse, void, never, never>(f: (a: AiResponse) => Effect.Effect<void, never, never>) => <E, R>(self: Effect.Effect<AiResponse, E, R>) => Effect.Effect<...> (+1 overload)
Chains effects to produce new Effect instances, useful for combining
operations that depend on previous results.
Syntax
const flatMappedEffect = pipe(myEffect, Effect.flatMap(transformation))
// or
const flatMappedEffect = Effect.flatMap(myEffect, transformation)
// or
const flatMappedEffect = myEffect.pipe(Effect.flatMap(transformation))
Details
flatMap lets you sequence effects so that the result of one effect can be
used in the next step. It is similar to flatMap used with arrays but works
specifically with Effect instances, allowing you to avoid deeply nested
effect structures.
Since effects are immutable, flatMap always returns a new effect instead of
changing the original one.
When to Use
Use flatMap when you need to chain multiple effects, ensuring that each
step produces a new Effect while flattening any nested effects that may
occur.
Example
import { pipe, Effect } from "effect"

// Function to apply a discount safely to a transaction amount
const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, Error> =>
  discountRate === 0
    ? Effect.fail(new Error("Discount rate cannot be zero"))
    : Effect.succeed(total - (total * discountRate) / 100)

// Simulated asynchronous task to fetch a transaction amount from database
const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

// Chaining the fetch and discount application using `flatMap`
const finalAmount = pipe(
  fetchTransactionAmount,
  Effect.flatMap((amount) => applyDiscount(amount, 5))
)

Effect.runPromise(finalAmount).then(console.log)
// Output: 95
@see ― tap for a version that ignores the result of the effect.
@since ― 2.0.0
flatMap((
response: AiResponse
response) => 
import Console
Console.
const log: (...args: ReadonlyArray<any>) => Effect.Effect<void>@since ― 2.0.0
log(
response: AiResponse
response.
AiResponse.text: string
Returns the generated text content of the response.
text)),
77
  
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const provide: <AiLanguageModel.AiLanguageModel, never, OpenAiClient.OpenAiClient>(layer: Layer.Layer<AiLanguageModel.AiLanguageModel, never, OpenAiClient.OpenAiClient>) => <A, E, R>(self: Effect.Effect<...>) => Effect.Effect<...> (+9 overloads)
Provides necessary dependencies to an effect, removing its environmental
requirements.
Details
This function allows you to supply the required environment for an effect.
The environment can be provided in the form of one or more Layers, a
Context, a Runtime, or a ManagedRuntime. Once the environment is
provided, the effect can run without requiring external dependencies.
You can compose layers to create a modular and reusable way of setting up the
environment for effects. For example, layers can be used to configure
databases, logging services, or any other required dependencies.
Example
import { Context, Effect, Layer } from "effect"

class Database extends Context.Tag("Database")<
  Database,
  { readonly query: (sql: string) => Effect.Effect<Array<unknown>> }
>() {}

const DatabaseLive = Layer.succeed(
  Database,
  {
    // Simulate a database query
    query: (sql: string) => Effect.log(`Executing query: ${sql}`).pipe(Effect.as([]))
  }
)

//      ┌─── Effect<unknown[], never, Database>
//      ▼
const program = Effect.gen(function*() {
  const database = yield* Database
  const result = yield* database.query("SELECT * FROM users")
  return result
})

//      ┌─── Effect<unknown[], never, never>
//      ▼
const runnable = Effect.provide(program, DatabaseLive)

Effect.runPromise(runnable).then(console.log)
// Output:
// timestamp=... level=INFO fiber=#0 message="Executing query: SELECT * FROM users"
// []
@see ― provideService for providing a service to an effect.
@since ― 2.0.0
provide(
import OpenAiLanguageModel
OpenAiLanguageModel.
const model: (model: (string & {}) | OpenAiLanguageModel.Model, config?: Omit<OpenAiLanguageModel.Config.Service, "model">) => AiModel<AiLanguageModel.AiLanguageModel, OpenAiClient.OpenAiClient>@since ― 1.0.0
model("gpt-4o"))
78
)
79

80
const 
const OpenAi: Layer.Layer<OpenAiClient.OpenAiClient, ConfigError, never>
OpenAi = 
import OpenAiClient
OpenAiClient.
const layerConfig: (options: Config.Config.Wrap<{
    readonly apiKey?: Redacted | undefined;
    readonly apiUrl?: string | undefined;
    readonly organizationId?: Redacted | undefined;
    readonly projectId?: Redacted | undefined;
    readonly transformClient?: (client: HttpClient.HttpClient) => HttpClient.HttpClient;
}>) => Layer.Layer<OpenAiClient.OpenAiClient, ConfigError, HttpClient.HttpClient>@since ― 1.0.0
layerConfig({
81
  
apiKey?: Config.Config<Redacted<string> | undefined>
apiKey: 
import Config
Config.
const redacted: (name?: string) => Config.Config<Redacted> (+1 overload)
Constructs a config for a redacted value.
@since ― 2.0.0
redacted("OPENAI_API_KEY")
82
}).
Pipeable.pipe<Layer.Layer<OpenAiClient.OpenAiClient, ConfigError, HttpClient.HttpClient>, Layer.Layer<OpenAiClient.OpenAiClient, ConfigError, never>>(this: Layer.Layer<...>, ab: (_: Layer.Layer<...>) => Layer.Layer<...>): Layer.Layer<...> (+21 overloads)
pipe(
import Layer
Layer.
const provide: <never, never, HttpClient.HttpClient>(that: Layer.Layer<HttpClient.HttpClient, never, never>) => <RIn2, E2, ROut2>(self: Layer.Layer<ROut2, E2, RIn2>) => Layer.Layer<...> (+3 overloads)
Feeds the output services of this builder into the input of the specified
builder, resulting in a new builder with the inputs of this builder as
well as any leftover inputs, and the outputs of the specified builder.
@since ― 2.0.0
provide(
import NodeHttpClient
NodeHttpClient.
const layerUndici: Layer.Layer<HttpClient.HttpClient, never, never>@since ― 1.0.0
layerUndici))
83

84
const program: Effect.Effect<void, AiError, OpenAiClient.OpenAiClient>
program.
Pipeable.pipe<Effect.Effect<void, AiError, OpenAiClient.OpenAiClient>, Effect.Effect<void, AiError | ConfigError, never>, Promise<...>>(this: Effect.Effect<...>, ab: (_: Effect.Effect<...>) => Effect.Effect<...>, bc: (_: Effect.Effect<...>) => Promise<...>): Promise<...> (+21 overloads)
pipe(
85
  
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const provide: <[Layer.Layer<OpenAiClient.OpenAiClient, ConfigError, never>, Layer.Layer<AiTool.Handler<"GetDadJoke">, never, never>]>(layers: [...]) => <A, E, R>(self: Effect.Effect<...>) => Effect.Effect<...> (+9 overloads)
Provides necessary dependencies to an effect, removing its environmental
requirements.
Details
This function allows you to supply the required environment for an effect.
The environment can be provided in the form of one or more Layers, a
Context, a Runtime, or a ManagedRuntime. Once the environment is
provided, the effect can run without requiring external dependencies.
You can compose layers to create a modular and reusable way of setting up the
environment for effects. For example, layers can be used to configure
databases, logging services, or any other required dependencies.
Example
import { Context, Effect, Layer } from "effect"

class Database extends Context.Tag("Database")<
  Database,
  { readonly query: (sql: string) => Effect.Effect<Array<unknown>> }
>() {}

const DatabaseLive = Layer.succeed(
  Database,
  {
    // Simulate a database query
    query: (sql: string) => Effect.log(`Executing query: ${sql}`).pipe(Effect.as([]))
  }
)

//      ┌─── Effect<unknown[], never, Database>
//      ▼
const program = Effect.gen(function*() {
  const database = yield* Database
  const result = yield* database.query("SELECT * FROM users")
  return result
})

//      ┌─── Effect<unknown[], never, never>
//      ▼
const runnable = Effect.provide(program, DatabaseLive)

Effect.runPromise(runnable).then(console.log)
// Output:
// timestamp=... level=INFO fiber=#0 message="Executing query: SELECT * FROM users"
// []
@see ― provideService for providing a service to an effect.
@since ― 2.0.0
provide([
const OpenAi: Layer.Layer<OpenAiClient.OpenAiClient, ConfigError, never>
OpenAi, 
const DadJokeToolHandlers: Layer.Layer<AiTool.Handler<"GetDadJoke">, never, never>
DadJokeToolHandlers]),
86
  
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const runPromise: <A, E>(effect: Effect.Effect<A, E, never>, options?: {
    readonly signal?: AbortSignal;
} | undefined) => Promise<A>
Executes an effect and returns the result as a Promise.
Details
This function runs an effect and converts its result into a Promise. If the
effect succeeds, the Promise will resolve with the successful result. If
the effect fails, the Promise will reject with an error, which includes the
failure details of the effect.
The optional options parameter allows you to pass an AbortSignal for
cancellation, enabling more fine-grained control over asynchronous tasks.
When to Use
Use this function when you need to execute an effect and work with its result
in a promise-based system, such as when integrating with third-party
libraries that expect Promise results.
Example (Running a Successful Effect as a Promise)
import { Effect } from "effect"

Effect.runPromise(Effect.succeed(1)).then(console.log)
// Output: 1
Example (Handling a Failing Effect as a Rejected Promise)
import { Effect } from "effect"

Effect.runPromise(Effect.fail("my error")).catch(console.error)
// Output:
// (FiberFailure) Error: my error
@see ― runPromiseExit for a version that returns an Exit type instead
of rejecting.
@since ― 2.0.0
runPromise
87
)

Benefits

Type Safe

Every tool is fully described using Effect’s Schema, including inputs, outputs, and descriptions.

Effect Native

Tool call behavior is defined using Effect, so they can leverage all the power of Effect. This is especially useful when you need to access other services to support the implementation of your tool call handlers.

Injectable

Because implementing the handlers for an AiToolkit results in a Layer, providing alternate implementation of tool call handlers in different environments is as simple as providing a different Layer to your program.

Separation of Concerns

The definition of a tool call request is cleanly separated from both the implementation of the tool behavior, as well as the business logic that calls the model.