Skip to content

Build an agent

Threads

A Thread is an identified conversation shared across Runs. Its lifetime belongs to the application’s history or durable host. Reusing a Thread ID continues that conversation; it does not by itself make execution durable or authorize access.

const
const conversation: Effect.Effect<{
readonly finishReason: "completed" | "model-stop" | "budget-exhausted";
readonly turns: number;
readonly output: {
readonly itinerary: readonly string[];
};
readonly threadId: string & Brand<"@effect-agent/core/ThreadId">;
readonly runId: string & Brand<"@effect-agent/core/RunId">;
readonly exhausted?: "tokens" | "tool-calls" | "turns" | undefined;
readonly runDisposition?: Json | undefined;
readonly usage?: RunTotals | undefined;
readonly delegatedUsage?: RunTotals | undefined;
}, AgentRuntime.AgentRuntimeFailure<Definition<String, ... 5 more ..., undefined> & {
...;
}, never, never> | ConfigError, never>
conversation
=
import Effect
Effect
.
const gen: <Effect.Effect<{
readonly finishReason: "completed" | "model-stop" | "budget-exhausted";
readonly turns: number;
readonly output: {
readonly itinerary: readonly string[];
};
readonly threadId: string & Brand<"@effect-agent/core/ThreadId">;
readonly runId: string & Brand<"@effect-agent/core/RunId">;
readonly exhausted?: "tokens" | "tool-calls" | "turns" | undefined;
readonly runDisposition?: Json | undefined;
readonly usage?: RunTotals | undefined;
readonly delegatedUsage?: RunTotals | undefined;
}, AgentRuntime.AgentRuntimeFailure<Definition<String, ... 5 more ..., undefined> & {
...;
}, never, never>, AgentRuntime.AgentRuntimeRequirements<...>>, {
readonly finishReason: "completed" | "model-stop" | "budget-exhausted";
readonly turns: number;
readonly output: {
readonly itinerary: readonly string[];
};
readonly threadId: string & Brand<"@effect-agent/core/ThreadId">;
readonly runId: string & Brand<"@effect-agent/core/RunId">;
readonly exhausted?: "tokens" | "tool-calls" | "turns" | undefined;
readonly runDisposition?: Json | undefined;
readonly usage?: RunTotals | undefined;
readonly delegatedUsage?: RunTotals | undefined;
}>(f: () => Generator<...>) => Effect.Effect<...> (+1 overload)

Provides a way to write effectful code using generator functions, simplifying control flow and error handling.

When to use

Use when you want to write effectful code that looks and behaves like synchronous code, while still handling asynchronous tasks, errors, and complex control flow such as loops and conditions.

Generator functions work similarly to async/await but keep errors, requirements, and interruption in the Effect type. You can yield* values from effects and return the final result at the end.

Example (Sequencing effects with generators)

import { Data, Effect } from "effect"
class DiscountRateError extends Data.TaggedError("DiscountRateError")<{}> {}
const addServiceCharge = (amount: number) => amount + 1
const applyDiscount = (
total: number,
discountRate: number
): Effect.Effect<number, DiscountRateError> =>
discountRate === 0
? Effect.fail(new DiscountRateError())
: 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}`
})
await Effect.runPromise(program) // => "Final amount to charge: 96"

@stability ― stable

@category ― constructors

@since ― 2.0.0

gen
(function* () {
const
const first: {
readonly finishReason: "completed" | "model-stop" | "budget-exhausted";
readonly turns: number;
readonly output: {
readonly itinerary: readonly string[];
};
readonly threadId: string & Brand<"@effect-agent/core/ThreadId">;
readonly runId: string & Brand<"@effect-agent/core/RunId">;
readonly exhausted?: "tokens" | "tool-calls" | "turns" | undefined;
readonly runDisposition?: Json | undefined;
readonly usage?: RunTotals | undefined;
readonly delegatedUsage?: RunTotals | undefined;
}
first
= yield*
import AgentRuntime
AgentRuntime
.
const run: <Definition<String, Struct<{
readonly itinerary: $Array<String>;
}>, "Plan a trip with one itinerary entry per day.", Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "trip-planner";
}, never, never>(agent: Definition<String, Struct<{
readonly itinerary: $Array<String>;
}>, "Plan a trip with one itinerary entry per day.", Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "trip-planner";
}, input: string, options?: RunOptions<...> | undefined) => Effect.Effect<...>

Accept schema-encoded input, retaining runtime validation.

run
(
const planner: Definition<String, Struct<{
readonly itinerary: $Array<String>;
}>, "Plan a trip with one itinerary entry per day.", Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "trip-planner";
}
planner
, "Plan a weekend in Lisbon.");
return yield*
import AgentRuntime
AgentRuntime
.
const run: <Definition<String, Struct<{
readonly itinerary: $Array<String>;
}>, "Plan a trip with one itinerary entry per day.", Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "trip-planner";
}, never, never>(agent: Definition<String, Struct<{
readonly itinerary: $Array<String>;
}>, "Plan a trip with one itinerary entry per day.", Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "trip-planner";
}, input: string, options?: RunOptions<...> | undefined) => Effect.Effect<...>

Accept schema-encoded input, retaining runtime validation.

run
(
const planner: Definition<String, Struct<{
readonly itinerary: $Array<String>;
}>, "Plan a trip with one itinerary entry per day.", Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "trip-planner";
}
planner
, "Make it cheaper.", {
RunOptions<HookError = never, HookRequirements = never>.threadId?: (string & Brand<"@effect-agent/core/ThreadId">) | undefined

Reuse a Thread identity, including retained history, instead of allocating one.

threadId
:
const first: {
readonly finishReason: "completed" | "model-stop" | "budget-exhausted";
readonly turns: number;
readonly output: {
readonly itinerary: readonly string[];
};
readonly threadId: string & Brand<"@effect-agent/core/ThreadId">;
readonly runId: string & Brand<"@effect-agent/core/RunId">;
readonly exhausted?: "tokens" | "tool-calls" | "turns" | undefined;
readonly runDisposition?: Json | undefined;
readonly usage?: RunTotals | undefined;
readonly delegatedUsage?: RunTotals | undefined;
}
first
.
threadId: string & Brand<"@effect-agent/core/ThreadId">
threadId
,
});
}).
Pipeable.pipe<Effect.Effect<{
readonly finishReason: "completed" | "model-stop" | "budget-exhausted";
readonly turns: number;
readonly output: {
readonly itinerary: readonly string[];
};
readonly threadId: string & Brand<"@effect-agent/core/ThreadId">;
readonly runId: string & Brand<"@effect-agent/core/RunId">;
readonly exhausted?: "tokens" | "tool-calls" | "turns" | undefined;
readonly runDisposition?: Json | undefined;
readonly usage?: RunTotals | undefined;
readonly delegatedUsage?: RunTotals | undefined;
}, AgentRuntime.AgentRuntimeFailure<Definition<String, ... 5 more ..., undefined> & {
...;
}, never, never>, AgentRuntime.AgentRuntimeRequirements<...>>, Effect.Effect<...>, Effect.Effect<...>, Effect.Effect<...>>(this: Effect.Effect<...>, ab: (_: Effect.Effect<...>) => Effect.Effect<...>, bc: (_: Effect.Effect<...>) => Effect.Effect<...>, cd: (_: Effect.Effect<...>) => Effect.Effect<...>): Effect.Effect<...> (+21 overloads)
pipe
(
import Effect
Effect
.
const provide: <LanguageModel | ProviderName | ModelName, never, OpenAiClient>(layer: Layer<LanguageModel | ProviderName | ModelName, never, OpenAiClient>, options?: {
readonly local?: boolean | undefined;
} | undefined) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, OpenAiClient | Exclude<R, LanguageModel | ProviderName | ModelName>> (+5 overloads)

Provides dependencies to an effect using layers or a context. A layer already built by an enclosing provide or runtime is reused. Sibling provide calls build their own copies. Use options.local to build a fresh layer subtree.

Example (Providing dependencies with a layer)

import { Context, Effect, Layer } from "effect"
interface Database {
readonly query: (sql: string) => Effect.Effect<string>
}
const Database = Context.Service<Database>("Database")
const DatabaseLayer = Layer.succeed(Database)({
query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Result for: ${sql}`))
})
const program = Effect.gen(function*() {
const db = yield* Database
return yield* db.query("SELECT * FROM users")
})
const provided = Effect.provide(program, DatabaseLayer)
await Effect.runPromise(provided) // => "Result for: SELECT * FROM users"

@stability ― stable

@category ― providing services

@since ― 2.0.0

provide
(
const ModelLive: Model<"openai", LanguageModel, OpenAiClient>
ModelLive
),
import Effect
Effect
.
const provide: <OpenAiClient, ConfigError, never>(layer: Layer<OpenAiClient, ConfigError, never>, options?: {
readonly local?: boolean | undefined;
} | undefined) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, ConfigError | E, Exclude<R, OpenAiClient>> (+5 overloads)

Provides dependencies to an effect using layers or a context. A layer already built by an enclosing provide or runtime is reused. Sibling provide calls build their own copies. Use options.local to build a fresh layer subtree.

Example (Providing dependencies with a layer)

import { Context, Effect, Layer } from "effect"
interface Database {
readonly query: (sql: string) => Effect.Effect<string>
}
const Database = Context.Service<Database>("Database")
const DatabaseLayer = Layer.succeed(Database)({
query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Result for: ${sql}`))
})
const program = Effect.gen(function*() {
const db = yield* Database
return yield* db.query("SELECT * FROM users")
})
const provided = Effect.provide(program, DatabaseLayer)
await Effect.runPromise(provided) // => "Result for: SELECT * FROM users"

@stability ― stable

@category ― providing services

@since ― 2.0.0

provide
(
const OpenAiLive: Layer<OpenAiClient, ConfigError, never>
OpenAiLive
),
import Effect
Effect
.
const provide: <ThreadHistory | Store | SubagentReservations, never, never>(layer: Layer<ThreadHistory | Store | SubagentReservations, never, never>, options?: {
readonly local?: boolean | undefined;
} | undefined) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, ThreadHistory | Store | SubagentReservations>> (+5 overloads)

Provides dependencies to an effect using layers or a context. A layer already built by an enclosing provide or runtime is reused. Sibling provide calls build their own copies. Use options.local to build a fresh layer subtree.

Example (Providing dependencies with a layer)

import { Context, Effect, Layer } from "effect"
interface Database {
readonly query: (sql: string) => Effect.Effect<string>
}
const Database = Context.Service<Database>("Database")
const DatabaseLayer = Layer.succeed(Database)({
query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`Result for: ${sql}`))
})
const program = Effect.gen(function*() {
const db = yield* Database
return yield* db.query("SELECT * FROM users")
})
const provided = Effect.provide(program, DatabaseLayer)
await Effect.runPromise(provided) // => "Result for: SELECT * FROM users"

@stability ― stable

@category ― providing services

@since ― 2.0.0

provide
(
import InMemory
InMemory
.
const layer: Layer<ThreadHistory | Store | SubagentReservations, never, never>

Run agents and attached subagents with in-memory conversation history. Provide once around the parent program and all child handler Layers so siblings share history and one reservation ledger. Reuse a Thread ID to continue a conversation. Each parent Run releases its reservation pool after its attached children finish cleanup. Conversations have no per-Thread history quota; individual messages and total host memory are bounded. Use scoped for disposable request workflows within this shared store. Each independent Layer build owns fresh state; state is released when its Scope closes. Process loss loses history and active execution; this Layer provides no crash recovery.

Models, tool handlers, and provider clients remain application-supplied. Default IDs need no Layer; enclosing ID and context-preparation overrides are preserved. For storage-backed history, provide PersistentHistory.layer and a shared SubagentReservationsMemoryLive instead. Durable hosts own their own assembly.

layer
));

One Layer surrounds both Runs. In a server, keep the application Layer in one ManagedRuntime. The runnable Node snippets show the imported definition and services.

Assembly What it retains Who ends it
InMemory.layer Incremental complete messages and tool batches, including before a later failure Application Scope or process loss
InMemory.scoped inside that Layer Conversations created by one owned workflow, including attached children Workflow success, failure, or interruption
PersistentHistory.layer with storage Each successful Run as one atomic history commit Application retention policy
Durable host Committed conversation plus accepted-work and recovery state Explicit lifecycle and retention operations

In-memory storage bounds apply to individual messages and the whole host. Capacity errors leave existing conversations intact. Finishing a Run does not release its history. Use InMemory.scoped for disposable workflows and consume streams or handles before that scope closes.

Persistent history retains successful Runs but cannot resume interrupted execution. A storage error can occur after commit; inspect the retained history before retrying. Serialize callers when repeating external work would be unsafe: a conflicting history append can reject a stale writer after its tools have already run.

The durable host admits a submission, returns a receipt, and owns its execution history and settlement. Keep ordinary persistent-history Threads and durable-admission Threads on separate IDs. Use its API for durable work instead of layering ordinary history hooks around it. See durability and storage choices.

The model reads a selected context window. Recovery reads active Run state and necessary evidence. A history UI reads ordered ranges. Compaction can shorten model context without erasing conversation history; archival can relocate old records without resolving open work. A Thread’s lifetime is unbounded: history, sends and child invocations have no cumulative per-Thread quota. Payloads, individual Runs, live work and host storage have limits.

Thread.Store.snapshot inspects an in-memory conversation; Thread.toPrompt turns it into an Effect AI Prompt. Durable ThreadStore and ThreadReader expose journal reads instead. Authorize tenant and Thread access at the host boundary for both.