Skip to content

Build an agent

Run & stream

Choose the execution lifetime first. AgentRuntime runs inside your process; a durable host accepts work that can outlive the request and resume after restart. Both use the same agent loop.

const
const program: Effect.Effect<void, AgentRuntime.AgentRuntimeFailure<Definition<Struct<{
readonly city: String;
readonly days: Int;
}>, Struct<{
readonly itinerary: $Array<String>;
}>, ({ city, days }: {
readonly city: string;
readonly days: number;
}) => string, Toolkit<{
readonly search_activities: Tool<"search_activities", {
readonly parameters: Struct<{
readonly city: String;
}>;
readonly success: $Array<String>;
readonly failure: Never;
readonly failureMode: "error";
}, never>;
}>, undefined, undefined, undefined> & {
...;
}, never, never>, AgentRuntime.AgentRuntimeRequirements<...>>
program
=
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<Struct<...>, ... 5 more ..., undefined> & {
...;
}, never, never>, AgentRuntime.AgentRuntimeRequirements<...>> | Effect.Effect<...>, void>(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 result: {
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;
}
result
= yield*
import AgentRuntime
AgentRuntime
.
const run: <Definition<Struct<{
readonly city: String;
readonly days: Int;
}>, Struct<{
readonly itinerary: $Array<String>;
}>, ({ city, days }: {
readonly city: string;
readonly days: number;
}) => string, Toolkit<{
readonly search_activities: Tool<"search_activities", {
readonly parameters: Struct<{
readonly city: String;
}>;
readonly success: $Array<String>;
readonly failure: Never;
readonly failureMode: "error";
}, never>;
}>, undefined, undefined, undefined> & {
...;
}, never, never>(agent: Definition<...> & {
...;
}, input: NoInfer<{
...;
}>, options?: RunOptions<...> | undefined) => Effect.Effect<...>

Accept schema-encoded input, retaining runtime validation.

run
(
const planner: Definition<Struct<{
readonly city: String;
readonly days: Int;
}>, Struct<{
readonly itinerary: $Array<String>;
}>, ({ city, days }: {
readonly city: string;
readonly days: number;
}) => string, Toolkit<{
readonly search_activities: Tool<"search_activities", {
readonly parameters: Struct<{
readonly city: String;
}>;
readonly success: $Array<String>;
readonly failure: Never;
readonly failureMode: "error";
}, never>;
}>, undefined, undefined, undefined> & {
...;
}
planner
, {
city: string
city
: "Lisbon",
days: number
days
: 2 });
yield*
import Effect
Effect
.
const log: (...message: ReadonlyArray<any>) => Effect.Effect<void>

Logs one or more messages using the default log level.

Example (Logging at the default level)

import { Effect, Logger } from "effect"
const output: Array<unknown> = []
const program = Effect.gen(function*() {
const result = 2 + 2
yield* Effect.log("Result:", result)
return result
})
const logger = Logger.make<unknown, void>(({ logLevel, message }) => {
void output.push(`${logLevel}: ${Array.isArray(message) ? message.map(String).join(" ") : String(message)}`)
})
const runnable = Effect.provide(program, Logger.layer([logger]))
void output.push(Effect.runSync(runnable))
output // => ["Info: Result: 4", 4]

@stability ― stable

@category ― logging

@since ― 2.0.0

log
(
const result: {
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;
}
result
.
output: {
readonly itinerary: readonly string[];
}
output
);
});

Provide the model, toolkit handlers, and runtime services around program. The travel-planner example contains the complete setup. output has passed the Agent’s output Schema; finishReason distinguishes ordinary completion from a budget-exhausted answer.

Use AgentRuntime.stream to consume a Stream of RunEvent values: text, tool activity, updates, and lifecycle events. Text deltas are provisional. For structured output, wait for Schema-validated completion before presenting a final answer.

A slow consumer backpressures the bounded event queue. Interrupting an ephemeral stream closes its execution Scope and interrupts the Run. To observe the same local Run more than once, use AgentRuntime.start inside Effect.scoped; its handle exposes await, observe, events, and usageReport. Slow detached observers can fail with a lag error without blocking execution.

  1. Runtime

    Prepare context

  2. Model

    Return a response and proposed calls

  3. Runtime

    Validate the complete batch and apply policy

  4. Your tools

    Execute bounded tool calls

  5. Runtime

    Commit results, then consume steering

  6. Runtime

    Consume follow-up if otherwise finished

Steering enters before the next model request; follow-up enters when the Agent would otherwise stop. Neither rewrites an active tool call. With restartOnJoinedInput, eligible new input can cancel a disposable model request and replace it. Clients must clear the affected draft on ModelRestarted.

run finishes run-local cleanup before returning. stream owns cleanup through consumption; start belongs to its caller’s Scope. Enclosing application Layers can serve many Runs.

For durable work, disconnecting an observer or interrupting a waiter only detaches that caller. Use an authorized, persisted abort command to cancel accepted work. A replacement Attempt receives a fresh duration allowance; cumulative call and usage limits remain separate.

Choose a Node or Cloudflare host for durable execution. See operations for receipts, observation, and cancellation, and budgets for limits and usage accounting.

DurableAgentRuntime.layer composes registrations with a SubmissionLedger, ThreadStore, WakeScheduler, and host authorization. Capture model and tool services when building the Layer. The storage adapter must provide work discovery, streaming verification, worker-capacity reads, and peer-message counts; missing capabilities fail Layer construction with ThreadStoreError. Prompt checkpoints and fresh-admission shortcuts are optional accelerators. Your host must route each Thread to one process owner and drive recovery after lost wake hints. Prefer a platform host unless you need to own that scheduling and resource lifetime yourself.