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 as a tagged request using Schema.TaggedRequest. This describes what parameters the tool accepts (its payload) and what it returns (either success or failure):

Example (Defining a Tool Call Request)

1
import { 
import Schema
Schema } from "effect"
2

3
class 
class GetDadJoke
GetDadJoke extends 
import Schema
Schema.
const TaggedRequest: <GetDadJoke>(identifier?: string) => <Tag, Payload, Success, Failure>(tag: Tag, options: {
    failure: Failure;
    success: Success;
    payload: Payload;
}, annotations?: ClassAnnotations<...> | undefined) => Schema.TaggedRequestClass<...>@example 
import { Schema } from "effect"

class MyRequest extends Schema.TaggedRequest<MyRequest>("MyRequest")("MyRequest", {
 failure: Schema.String,
 success: Schema.Number,
 payload: { id: Schema.String }
}) {}
@since ― 3.10.0
TaggedRequest<
class GetDadJoke
GetDadJoke>()("GetDadJoke", {
4
  
payload: {
    searchTerm: Schema.SchemaClass<string, string, never>;
}
payload: {
5
    
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({
6
      
Annotations.Doc<string>.description?: string
description: "The search term to use to find dad jokes"
7
    })
8
  },
9
  
success: typeof Schema.String
success: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String,
10
  
failure: typeof Schema.Never
failure: 
import Schema
Schema.
class Never@since ― 3.10.0
Never
11
}, {
12
  
Annotations.Doc<A>.description?: string
description: "Get a hilarious dad joke from the icanhazdadjoke API"
13
}) {}

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

Takes a single searchTerm parameter
Succeeds with a string (i.e. the joke)
Never fails

2. Create a Toolkit

Once we have a tool request defined, we can use AiToolkit.empty to create an empty AiToolkit and then .add(...) our GetDadJoke tool request to it:

Example (Creating an AiToolkit)


14 collapsed lines
1
import { 
import Schema
Schema } from "effect"
2

3
class 
class GetDadJoke
GetDadJoke extends 
import Schema
Schema.
const TaggedRequest: <GetDadJoke>(identifier?: string) => <Tag, Payload, Success, Failure>(tag: Tag, options: {
    failure: Failure;
    success: Success;
    payload: Payload;
}, annotations?: ClassAnnotations<...> | undefined) => Schema.TaggedRequestClass<...>@example 
import { Schema } from "effect"

class MyRequest extends Schema.TaggedRequest<MyRequest>("MyRequest")("MyRequest", {
 failure: Schema.String,
 success: Schema.Number,
 payload: { id: Schema.String }
}) {}
@since ― 3.10.0
TaggedRequest<
class GetDadJoke
GetDadJoke>()("GetDadJoke", {
4
  
payload: {
    searchTerm: Schema.SchemaClass<string, string, never>;
}
payload: {
5
    
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({
6
      
Annotations.Doc<string>.description?: string
description: "The search term to use to find dad jokes"
7
    })
8
  },
9
  
success: typeof Schema.String
success: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String,
10
  
failure: typeof Schema.Never
failure: 
import Schema
Schema.
class Never@since ― 3.10.0
Never
11
}, {
12
  
Annotations.Doc<A>.description?: string
description: "Get a hilarious dad joke from the icanhazdadjoke API"
13
}) {}
14

15
import { 
import AiToolkit
AiToolkit } from "@effect/ai"
16

17
const 
const DadJokeTools: AiToolkit.AiToolkit<typeof GetDadJoke>
DadJokeTools = 
import AiToolkit
AiToolkit.
const empty: AiToolkit.AiToolkit<never>@since ― 1.0.0
empty.
AiToolkit<never>.add: <typeof GetDadJoke>(tool: typeof GetDadJoke) => AiToolkit.AiToolkit<typeof GetDadJoke>
add(
class GetDadJoke
GetDadJoke)

3. Implement the Logic

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

Example (Implementing an AiToolkit)


58 collapsed lines
1
import { 
import AiToolkit
AiToolkit } from "@effect/ai"
2
import { 
import HttpClient
HttpClient, 
import HttpClientRequest
HttpClientRequest, 
import HttpClientResponse
HttpClientResponse } from "@effect/platform"
3
import { 
import NodeHttpClient
NodeHttpClient } from "@effect/platform-node"
4
import { 
import Array
Array, 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect, 
import Schema
Schema } from "effect"
5

6
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")({
7
  
id: typeof Schema.String
id: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String,
8
  
joke: typeof Schema.String
joke: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String
9
}) {}
10

11
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")({
12
  
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)
13
}) {}
14

15
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", {
16
  
dependencies: readonly [Layer<HttpClient.HttpClient, never, never>]
dependencies: [
import NodeHttpClient
NodeHttpClient.
const layerUndici: Layer<HttpClient.HttpClient, never, never>@since ― 1.0.0
layerUndici],
17
  
effect: Effect.Effect<{
    readonly search: (params: GetDadJoke) => 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: (params: GetDadJoke) => 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*() {
18
    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
19
    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(
20
      
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,
21
      
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"))
22
    )
23

24
    const 
const search: (params: GetDadJoke) => 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")(
25
      function*(
params: GetDadJoke
params: typeof 
class GetDadJoke
GetDadJoke.
Schema<GetDadJoke, { readonly _tag: "GetDadJoke"; readonly searchTerm: string; }, never>.Type: GetDadJoke
Type) {
26
        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", {
27
          
acceptJson?: boolean | undefined
acceptJson: true,
28
          
urlParams?: Input | undefined
urlParams: { ...
params: GetDadJoke
params }
29
        }).
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(
30
          
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)),
31
          
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)),
32
          
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),
33
          
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,
34
          
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
35
        )
36
      }
37
    )
38

39
    return {
40
      
search: (params: GetDadJoke) => Effect.Effect<string, never, never>
search
41
    } as 
type const = {
    readonly search: (params: GetDadJoke) => Effect.Effect<string, never, never>;
}
const
42
  })
43
}) {}
44

45
class 
class GetDadJoke
GetDadJoke extends 
import Schema
Schema.
const TaggedRequest: <GetDadJoke>(identifier?: string) => <Tag, Payload, Success, Failure>(tag: Tag, options: {
    failure: Failure;
    success: Success;
    payload: Payload;
}, annotations?: ClassAnnotations<...> | undefined) => Schema.TaggedRequestClass<...>@example 
import { Schema } from "effect"

class MyRequest extends Schema.TaggedRequest<MyRequest>("MyRequest")("MyRequest", {
 failure: Schema.String,
 success: Schema.Number,
 payload: { id: Schema.String }
}) {}
@since ― 3.10.0
TaggedRequest<
class GetDadJoke
GetDadJoke>()("GetDadJoke", {
46
  
payload: {
    searchTerm: Schema.SchemaClass<string, string, never>;
}
payload: {
47
    
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({
48
      
Annotations.Doc<string>.description?: string
description: "The search term to use to find dad jokes"
49
    })
50
  },
51
  
success: typeof Schema.String
success: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String,
52
  
failure: typeof Schema.Never
failure: 
import Schema
Schema.
class Never@since ― 3.10.0
Never
53
}, {
54
  
Annotations.Doc<A>.description?: string
description: "Get a hilarious dad joke from the icanhazdadjoke API"
55
}) {}
56

57
const 
const DadJokeTools: AiToolkit.AiToolkit<typeof GetDadJoke>
DadJokeTools = 
import AiToolkit
AiToolkit.
const empty: AiToolkit.AiToolkit<never>@since ― 1.0.0
empty.
AiToolkit<never>.add: <typeof GetDadJoke>(tool: typeof GetDadJoke) => AiToolkit.AiToolkit<typeof GetDadJoke>
add(
class GetDadJoke
GetDadJoke)
58

59
const 
const DadJokeToolsLayer: Layer<AiToolkit.Registry | AiToolkit.Tool.Service<"GetDadJoke">, never, ICanHazDadJoke>
DadJokeToolsLayer = 
const DadJokeTools: AiToolkit.AiToolkit<typeof GetDadJoke>
DadJokeTools.
AiToolkit<typeof GetDadJoke>.implement: <never, never, ICanHazDadJoke>(f: (handlers: AiToolkit.Handlers<typeof GetDadJoke, never>) => AiToolkit.Handlers<never, never> | Effect.Effect<...>) => Layer<...>
implement((
handlers: AiToolkit.Handlers<typeof GetDadJoke, never>
handlers) =>
60
  
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const gen: <YieldWrap<Tag<ICanHazDadJoke, ICanHazDadJoke>>, AiToolkit.Handlers<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*() {
61
    // Extract the `ICanHazDadJoke` service from our application
62
    const 
const icanhazdadjoke: ICanHazDadJoke
icanhazdadjoke = yield* 
class ICanHazDadJoke
ICanHazDadJoke
63
    return 
handlers: AiToolkit.Handlers<typeof GetDadJoke, never>
handlers
64
      // Implement the handler for the `GetDadJoke` tool call request
65
      .
Handlers<typeof GetDadJoke, never>.handle: <"GetDadJoke", never>(tag: "GetDadJoke", f: AiToolkit.Tool.Handler<typeof GetDadJoke, never>) => AiToolkit.Handlers<never, never>
handle("GetDadJoke", (
params: GetDadJoke
params) => 
const icanhazdadjoke: ICanHazDadJoke
icanhazdadjoke.
search: (params: GetDadJoke) => Effect.Effect<string, never, never>
search(
params: GetDadJoke
params))
66
  })
67
)

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 .implement 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 .implement-ing 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)


17 collapsed lines
1
import { 
import AiToolkit
AiToolkit, 
import Completions
Completions } 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 GetDadJoke
GetDadJoke extends 
import Schema
Schema.
const TaggedRequest: <GetDadJoke>(identifier?: string) => <Tag, Payload, Success, Failure>(tag: Tag, options: {
    failure: Failure;
    success: Success;
    payload: Payload;
}, annotations?: ClassAnnotations<...> | undefined) => Schema.TaggedRequestClass<...>@example 
import { Schema } from "effect"

class MyRequest extends Schema.TaggedRequest<MyRequest>("MyRequest")("MyRequest", {
 failure: Schema.String,
 success: Schema.Number,
 payload: { id: Schema.String }
}) {}
@since ― 3.10.0
TaggedRequest<
class GetDadJoke
GetDadJoke>()("GetDadJoke", {
5
  
payload: {
    searchTerm: Schema.SchemaClass<string, string, never>;
}
payload: {
6
    
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({
7
      
Annotations.Doc<string>.description?: string
description: "The search term to use to find dad jokes"
8
    })
9
  },
10
  
success: typeof Schema.String
success: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String,
11
  
failure: typeof Schema.Never
failure: 
import Schema
Schema.
class Never@since ― 3.10.0
Never
12
}, {
13
  
Annotations.Doc<A>.description?: string
description: "Get a hilarious dad joke from the icanhazdadjoke API"
14
}) {}
15

16
const 
const DadJokeTools: AiToolkit.AiToolkit<typeof GetDadJoke>
DadJokeTools = 
import AiToolkit
AiToolkit.
const empty: AiToolkit.AiToolkit<never>@since ― 1.0.0
empty.
AiToolkit<never>.add: <typeof GetDadJoke>(tool: typeof GetDadJoke) => AiToolkit.AiToolkit<typeof GetDadJoke>
add(
class GetDadJoke
GetDadJoke)
17

18
const 
const generateDadJoke: Effect.Effect<WithResolved<string>, AiError, AiToolkit.Registry | Completions.Completions | AiToolkit.Tool.Service<"GetDadJoke">>
generateDadJoke = 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const gen: <YieldWrap<Tag<Completions.Completions, Completions.Completions.Service>> | YieldWrap<Effect.Effect<AiToolkit.Handlers<typeof GetDadJoke, never>, never, AiToolkit.Registry | AiToolkit.Tool.Service<...>>> | YieldWrap<...>, WithResolved<...>>(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*() {
19
  const 
const completions: Completions.Completions.Service
completions = yield* 
import Completions
Completions.
class Completions@since ― 1.0.0
@since ― 1.0.0
Completions
20
  const 
const tools: AiToolkit.Handlers<typeof GetDadJoke, never>
tools = yield* 
const DadJokeTools: AiToolkit.AiToolkit<typeof GetDadJoke>
DadJokeTools
21
  const 
const response: WithResolved<string>
response = yield* 
const completions: Completions.Completions.Service
completions.
Completions.Service.toolkit: <typeof GetDadJoke>(options: {
    readonly input: Input;
    readonly tools: AiToolkit.Handlers<typeof GetDadJoke, never>;
    readonly required?: boolean | "GetDadJoke" | undefined;
    readonly concurrency?: Concurrency | undefined;
}) => Effect.Effect<...>
toolkit({
22
    
input: Input
input: "Generate a dad joke",
23
    
tools: AiToolkit.Handlers<typeof GetDadJoke, never>
tools
24
  })
25
  
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:

A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
See util.format() for more information.
@since ― v0.1.100
log(
const response: WithResolved<string>
response.
WithResolved<string>.value: Option<string>@since ― 1.0.0
value)
26
  return 
const response: WithResolved<string>
response
27
})

In the code above:

We yield* the AiToolkit to gain access to our tools
We use Completions.toolkit to perform text generation supported by our tools (if required)
We log the result to the console

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)


69 collapsed lines
1
import { 
import AiToolkit
AiToolkit, 
import Completions
Completions } from "@effect/ai"
2
import { 
import OpenAiClient
OpenAiClient, 
import OpenAiCompletions
OpenAiCompletions } from "@effect/ai-openai"
3
import { 
import HttpClient
HttpClient, 
import HttpClientRequest
HttpClientRequest, 
import HttpClientResponse
HttpClientResponse } from "@effect/platform"
4
import { 
import NodeHttpClient
NodeHttpClient } from "@effect/platform-node"
5
import { 
import Array
Array, 
import Config
Config, 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect, 
import Layer
Layer, 
import Schema
Schema } from "effect"
6

7
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")({
8
  
id: typeof Schema.String
id: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String,
9
  
joke: typeof Schema.String
joke: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String
10
}) {}
11

12
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")({
13
  
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)
14
}) {}
15

16
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", {
17
  
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],
18
  
effect: Effect.Effect<{
    readonly search: (params: GetDadJoke) => 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: (params: GetDadJoke) => 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*() {
19
    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
20
    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(
21
      
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,
22
      
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"))
23
    )
24

25
    const 
const search: (params: GetDadJoke) => 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")(
26
      function*(
params: GetDadJoke
params: typeof 
class GetDadJoke
GetDadJoke.
Schema<GetDadJoke, { readonly _tag: "GetDadJoke"; readonly searchTerm: string; }, never>.Type: GetDadJoke
Type) {
27
        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", {
28
          
acceptJson?: boolean | undefined
acceptJson: true,
29
          
urlParams?: Input | undefined
urlParams: { ...
params: GetDadJoke
params }
30
        }).
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(
31
          
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)),
32
          
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)),
33
          
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),
34
          
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,
35
          
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
36
        )
37
      }
38
    )
39

40
    return {
41
      
search: (params: GetDadJoke) => Effect.Effect<string, never, never>
search
42
    } as 
type const = {
    readonly search: (params: GetDadJoke) => Effect.Effect<string, never, never>;
}
const
43
  })
44
}) {}
45

46
class 
class GetDadJoke
GetDadJoke extends 
import Schema
Schema.
const TaggedRequest: <GetDadJoke>(identifier?: string) => <Tag, Payload, Success, Failure>(tag: Tag, options: {
    failure: Failure;
    success: Success;
    payload: Payload;
}, annotations?: ClassAnnotations<...> | undefined) => Schema.TaggedRequestClass<...>@example 
import { Schema } from "effect"

class MyRequest extends Schema.TaggedRequest<MyRequest>("MyRequest")("MyRequest", {
 failure: Schema.String,
 success: Schema.Number,
 payload: { id: Schema.String }
}) {}
@since ― 3.10.0
TaggedRequest<
class GetDadJoke
GetDadJoke>()("GetDadJoke", {
47
  
payload: {
    searchTerm: Schema.SchemaClass<string, string, never>;
}
payload: {
48
    
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({
49
      
Annotations.Doc<string>.description?: string
description: "The search term to use to find dad jokes"
50
    })
51
  },
52
  
success: typeof Schema.String
success: 
import Schema
Schema.
class String
export String@since ― 3.10.0
String,
53
  
failure: typeof Schema.Never
failure: 
import Schema
Schema.
class Never@since ― 3.10.0
Never
54
}, {
55
  
Annotations.Doc<A>.description?: string
description: "Get a hilarious dad joke from the icanhazdadjoke API"
56
}) {}
57

58
const 
const DadJokeTools: AiToolkit.AiToolkit<typeof GetDadJoke>
DadJokeTools = 
import AiToolkit
AiToolkit.
const empty: AiToolkit.AiToolkit<never>@since ― 1.0.0
empty.
AiToolkit<never>.add: <typeof GetDadJoke>(tool: typeof GetDadJoke) => AiToolkit.AiToolkit<typeof GetDadJoke>
add(
class GetDadJoke
GetDadJoke)
59

60
const 
const DadJokeToolsLayer: Layer.Layer<AiToolkit.Registry | AiToolkit.Tool.Service<"GetDadJoke">, never, never>
DadJokeToolsLayer = 
const DadJokeTools: AiToolkit.AiToolkit<typeof GetDadJoke>
DadJokeTools.
AiToolkit<typeof GetDadJoke>.implement: <never, never, ICanHazDadJoke>(f: (handlers: AiToolkit.Handlers<typeof GetDadJoke, never>) => AiToolkit.Handlers<never, never> | Effect.Effect<...>) => Layer.Layer<...>
implement((
handlers: AiToolkit.Handlers<typeof GetDadJoke, never>
handlers) =>
61
  
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const gen: <YieldWrap<Tag<ICanHazDadJoke, ICanHazDadJoke>>, AiToolkit.Handlers<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*() {
62
    // Extract the `ICanHazDadJoke` service from our application
63
    const 
const icanhazdadjoke: ICanHazDadJoke
icanhazdadjoke = yield* 
class ICanHazDadJoke
ICanHazDadJoke
64
    return 
handlers: AiToolkit.Handlers<typeof GetDadJoke, never>
handlers
65
      // Implement the handler for the `GetDadJoke` tool call request
66
      .
Handlers<typeof GetDadJoke, never>.handle: <"GetDadJoke", never>(tag: "GetDadJoke", f: AiToolkit.Tool.Handler<typeof GetDadJoke, never>) => AiToolkit.Handlers<never, never>
handle("GetDadJoke", (
params: GetDadJoke
params) => 
const icanhazdadjoke: ICanHazDadJoke
icanhazdadjoke.
search: (params: GetDadJoke) => Effect.Effect<string, never, never>
search(
params: GetDadJoke
params))
67
  })
68
).
Pipeable.pipe<Layer.Layer<AiToolkit.Registry | AiToolkit.Tool.Service<"GetDadJoke">, never, ICanHazDadJoke>, Layer.Layer<AiToolkit.Registry | AiToolkit.Tool.Service<...>, 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))
69

70
const 
const generateDadJoke: Effect.Effect<WithResolved<string>, AiError, AiToolkit.Registry | AiToolkit.Tool.Service<"GetDadJoke"> | Completions.Completions>
generateDadJoke = 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const gen: <YieldWrap<Tag<Completions.Completions, Completions.Completions.Service>> | YieldWrap<Effect.Effect<AiToolkit.Handlers<typeof GetDadJoke, never>, never, AiToolkit.Registry | AiToolkit.Tool.Service<...>>> | YieldWrap<...>, WithResolved<...>>(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*() {
71
  const 
const completions: Completions.Completions.Service
completions = yield* 
import Completions
Completions.
class Completions@since ― 1.0.0
@since ― 1.0.0
Completions
72
  const 
const tools: AiToolkit.Handlers<typeof GetDadJoke, never>
tools = yield* 
const DadJokeTools: AiToolkit.AiToolkit<typeof GetDadJoke>
DadJokeTools
73
  const 
const response: WithResolved<string>
response = yield* 
const completions: Completions.Completions.Service
completions.
Completions.Service.toolkit: <typeof GetDadJoke>(options: {
    readonly input: Input;
    readonly tools: AiToolkit.Handlers<typeof GetDadJoke, never>;
    readonly required?: boolean | "GetDadJoke" | undefined;
    readonly concurrency?: Concurrency | undefined;
}) => Effect.Effect<...>
toolkit({
74
    
input: Input
input: "Generate a dad joke",
75
    
tools: AiToolkit.Handlers<typeof GetDadJoke, never>
tools
76
  })
77
  
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:

A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
See util.format() for more information.
@since ― v0.1.100
log(
const response: WithResolved<string>
response.
WithResolved<string>.value: Option<string>@since ― 1.0.0
value)
78
  return 
const response: WithResolved<string>
response
79
})
80

81
const 
const program: Effect.Effect<void, AiError, AiToolkit.Registry | AiToolkit.Tool.Service<"GetDadJoke"> | OpenAiClient.OpenAiClient | AiModels>
program = 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const gen: <YieldWrap<Effect.Effect<AiPlan<in Error, in out Provides, in out Requires>.Provider<Completions.Completions | Tokenizer>, never, OpenAiClient.OpenAiClient | AiModels>> | YieldWrap<...>, void>(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*() {
82
  const 
const model: AiPlan.Provider<Completions.Completions | Tokenizer>
model = yield* 
import OpenAiCompletions
OpenAiCompletions.
const model: (model: (string & {}) | OpenAiCompletions.Model, config?: Omit<OpenAiCompletions.Config.Service, "model">) => AiModel<Completions.Completions | Tokenizer, OpenAiClient.OpenAiClient>@since ― 1.0.0
model("gpt-4o")
83
  const 
const response: WithResolved<string>
response = yield* 
const model: AiPlan.Provider<Completions.Completions | Tokenizer>
model.
AiPlan<in Error, in out Provides, in out Requires>.Provider<Completions | Tokenizer>.provide: <WithResolved<string>, AiError, AiToolkit.Registry | AiToolkit.Tool.Service<"GetDadJoke"> | Completions.Completions>(effect: Effect.Effect<...>) => Effect.Effect<...>
provide(
const generateDadJoke: Effect.Effect<WithResolved<string>, AiError, AiToolkit.Registry | AiToolkit.Tool.Service<"GetDadJoke"> | Completions.Completions>
generateDadJoke)
84
})
85

86
const 
const OpenAi: Layer.Layer<OpenAiClient.OpenAiClient | AiModels, 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<AiModels | OpenAiClient.OpenAiClient, ConfigError, HttpClient.HttpClient>@since ― 1.0.0
layerConfig({
87
  
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")
88
}).
Pipeable.pipe<Layer.Layer<OpenAiClient.OpenAiClient | AiModels, ConfigError, HttpClient.HttpClient>, Layer.Layer<OpenAiClient.OpenAiClient | AiModels, 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))
89

90
const program: Effect.Effect<void, AiError, AiToolkit.Registry | AiToolkit.Tool.Service<"GetDadJoke"> | OpenAiClient.OpenAiClient | AiModels>
program.
Pipeable.pipe<Effect.Effect<void, AiError, AiToolkit.Registry | AiToolkit.Tool.Service<"GetDadJoke"> | OpenAiClient.OpenAiClient | AiModels>, Effect.Effect<...>, Promise<...>>(this: Effect.Effect<...>, ab: (_: Effect.Effect<...>) => Effect.Effect<...>, bc: (_: Effect.Effect<...>) => Promise<...>): Promise<...> (+21 overloads)
pipe(
91
  
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const provide: <[Layer.Layer<OpenAiClient.OpenAiClient | AiModels, ConfigError, never>, Layer.Layer<AiToolkit.Registry | AiToolkit.Tool.Service<"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 | AiModels, ConfigError, never>
OpenAi, 
const DadJokeToolsLayer: Layer.Layer<AiToolkit.Registry | AiToolkit.Tool.Service<"GetDadJoke">, never, never>
DadJokeToolsLayer]),
92
  
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
93
)

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.