Skip to content

Deploy and operate

In-memory

InMemory.layer keeps conversations and attached-subagent reservations in one application Scope. It is useful for trying an agent, local sessions, and work that can end with the process. No storage package is required.

import {
import AgentRuntime
AgentRuntime
,
import InMemory
InMemory
} from "@yielded/agent";
import {
import Effect
Effect
} from "effect";
import {
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
} from "./node-agent.ts";
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> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "trip-planner";
}, never, never>, ModelServices>
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 trip to 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<...>>(this: Effect.Effect<...>, ab: (_: Effect.Effect<...>) => Effect.Effect<...>): Effect.Effect<...> (+21 overloads)
pipe
(
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
));

Supply the agent’s model and tool services around this program. The runnable planner contains the complete setup.

Provide the Layer once around the conversation, or acquire it in one ManagedRuntime shared by your request handlers. Rebuilding it creates separate state. Save the returned Thread ID for follow-ups; omitting it starts a new Thread.

Complete history updates remain available if a later step fails or is interrupted. Closing the Scope or losing the process discards everything. No interrupted Run can recover after process loss.

Built-in conversation limit Maximum
Threads per store 256
Encoded content per message 4 MiB
Encoded content across the store 64 MiB

These bounds protect individual messages and host memory; a Thread has no quota on message count or total content. Exceeding one fails with ThreadLimitExceeded.

@yielded/agent-storage-memory implements canonical Thread, Submission, and settlement ports for tests and custom runtimes. Its ledger is explicitly non-durable. These ports are separate from the conversation store supplied by InMemory.layer and must share one storage owner when composed.

Choose persistent history to retain completed Runs after restart, or a durable platform to recover accepted work as well.