Skip to content

Reference

Decision models

Effect’s DecisionModel evaluates schema-defined input and returns evidence. Your application owns confidence thresholds, routing, and side effects. @yielded/agent-ai-decision adds AutoModel for Thread model selection and a language-model adapter for native decisions.

Create a definition with Decision.make({ input, decisions }), then call DecisionModel.decide(definition, { input }). Only include input the decision provider is allowed to receive.

Constructor Criteria Answer
Decision.classify At least two named labels label, probabilities, optional confidence
Decision.rate At least two ordered levels Numeric rating, label, probabilities, optional confidence
Decision.probability Optional descriptions for true and false Probability from 0 to 1

Responses contain answers and optional input/output token usage. Confidence is provider-defined evidence, not an authorization decision or correctness guarantee.

Describe at least two approved native model Layers and give the catalog a version:

auto-model.ts
export const
const ThreadModels: AutoModel.AutoModel<OpenAiClient.OpenAiClient>
ThreadModels
=
import AutoModel
AutoModel
.
const make: <{
routine: OpenAiClient.OpenAiClient;
complex: OpenAiClient.OpenAiClient;
}>(options: {
readonly models: {
readonly routine: AutoModel.Candidate<OpenAiClient.OpenAiClient>;
readonly complex: AutoModel.Candidate<OpenAiClient.OpenAiClient>;
};
readonly version: string;
readonly instructions?: string;
}) => AutoModel.AutoModel<OpenAiClient.OpenAiClient>

Describe at least two approved native models and evaluate them through DecisionModel. Supply Jev with TypeSafeDecisionModel.model("jev-latest") from

@effect ―

/ai-typesafe. Increment version whenever a profile's model, effort, or other settings change; retain old catalogs while their threads remain active.

State should describe the whole task, relevant context, constraints, and tools; only include information the decision provider may receive. The application must filter candidates for authorization and required capabilities first.

Call resolve at host admission, then bind or provide its returned native Layer. Supply DecisionModel, native provider clients, and a shared SelectionStore. Keep selection and execution under the caller's Scope and deadline: the agent's generation budget does not bound the preceding selection request.

For manual select/restore composition, persist the full record before generation and reuse selection.model for all turns and later runs. Restore rejects a different thread, catalog version, or missing profile; it never silently reselects. Store ownership, authorization, atomic creation, and recovery belong to the host's SelectionStore.

There are no implicit retries, deadlines, fallbacks, confidence thresholds, or mid-thread switches. Defects and interruption propagate. Selection annotates the current span with the selected profile ID, not task content.

@category ― constructors

@since ― 0.1.0

make
({
version: string
version
: "profiles-v1",
models: {
readonly routine: AutoModel.Candidate<OpenAiClient.OpenAiClient>;
readonly complex: AutoModel.Candidate<OpenAiClient.OpenAiClient>;
}
models
: {
routine: AutoModel.Candidate<OpenAiClient.OpenAiClient>
routine
: {
Candidate<OpenAiClient>.model: Layer.Layer<LanguageModel | ProviderName | ModelName, never, OpenAiClient.OpenAiClient>
model
:
import OpenAiLanguageModel
OpenAiLanguageModel
.
const model: (model: (string & {}) | OpenAiLanguageModel.Model, config?: Omit<{
readonly metadata?: {
readonly [x: string]: string;
} | undefined;
readonly top_logprobs?: number | undefined;
readonly temperature?: number | undefined;
readonly top_p?: number | undefined;
readonly user?: string | undefined;
readonly safety_identifier?: string | undefined;
readonly prompt_cache_key?: string | undefined;
readonly prompt_cache_retention?: "24h" | "in_memory" | undefined;
readonly prompt_cache_options?: {
readonly mode?: "explicit" | "implicit" | undefined;
readonly ttl?: "30m" | undefined;
readonly comparison_response_id?: string | null | undefined;
} | undefined;
... 18 more ...;
readonly reasoningModel?: boolean | undefined;
}, "model">) => Model<"openai", LanguageModel, OpenAiClient.OpenAiClient>

Creates an OpenAI model descriptor that can be provided with Effect.provide.

When to use

Use when you want an OpenAI language model value that carries provider and model metadata and can be supplied directly to an Effect program.

@see ― layer for creating a LanguageModel.LanguageModel layer directly

@see ― make for constructing the language model service effectfully

@stability ― unstable

@category ― constructors

@since ― 4.0.0

model
("gpt-6-luna", {
reasoning?: {
readonly effort?: "high" | "low" | "max" | "medium" | "minimal" | "none" | "xhigh" | undefined;
readonly summary?: "auto" | "concise" | "detailed" | undefined;
readonly generate_summary?: "auto" | "concise" | "detailed" | undefined;
} | undefined
reasoning
: {
effort?: "high" | "low" | "max" | "medium" | "minimal" | "none" | "xhigh" | undefined
effort
: "medium" } }),
Candidate<Requirements = never>.description: string
description
: "Low cost. Extraction, summaries, and well-specified tasks with clear steps.",
},
complex: AutoModel.Candidate<OpenAiClient.OpenAiClient>
complex
: {
Candidate<OpenAiClient>.model: Layer.Layer<LanguageModel | ProviderName | ModelName, never, OpenAiClient.OpenAiClient>
model
:
import OpenAiLanguageModel
OpenAiLanguageModel
.
const model: (model: (string & {}) | OpenAiLanguageModel.Model, config?: Omit<{
readonly metadata?: {
readonly [x: string]: string;
} | undefined;
readonly top_logprobs?: number | undefined;
readonly temperature?: number | undefined;
readonly top_p?: number | undefined;
readonly user?: string | undefined;
readonly safety_identifier?: string | undefined;
readonly prompt_cache_key?: string | undefined;
readonly prompt_cache_retention?: "24h" | "in_memory" | undefined;
readonly prompt_cache_options?: {
readonly mode?: "explicit" | "implicit" | undefined;
readonly ttl?: "30m" | undefined;
readonly comparison_response_id?: string | null | undefined;
} | undefined;
... 18 more ...;
readonly reasoningModel?: boolean | undefined;
}, "model">) => Model<"openai", LanguageModel, OpenAiClient.OpenAiClient>

Creates an OpenAI model descriptor that can be provided with Effect.provide.

When to use

Use when you want an OpenAI language model value that carries provider and model metadata and can be supplied directly to an Effect program.

@see ― layer for creating a LanguageModel.LanguageModel layer directly

@see ― make for constructing the language model service effectfully

@stability ― unstable

@category ― constructors

@since ― 4.0.0

model
("gpt-6-astra", {
reasoning?: {
readonly effort?: "high" | "low" | "max" | "medium" | "minimal" | "none" | "xhigh" | undefined;
readonly summary?: "auto" | "concise" | "detailed" | undefined;
readonly generate_summary?: "auto" | "concise" | "detailed" | undefined;
} | undefined
reasoning
: {
effort?: "high" | "low" | "max" | "medium" | "minimal" | "none" | "xhigh" | undefined
effort
: "medium" } }),
Candidate<Requirements = never>.description: string
description
: "Higher cost. Difficult reasoning, subtle bugs, and ambiguous requirements.",
},
},
});

At host admission, authorize Thread access, validate input, and pass only permitted task context to resolve. Bind its returned native model to the Agent before running:

const
const run: Effect.Effect<{
readonly finishReason: "completed" | "model-stop" | "budget-exhausted";
readonly turns: number;
readonly output: {
readonly answer: 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?: Schema.Json | undefined;
readonly usage?: RunTotals | undefined;
readonly delegatedUsage?: RunTotals | undefined;
}, Schema.SchemaError | AgentRuntime.AgentRuntimeFailure<...> | ThreadAccessDenied | TimeoutError, ThreadHistory | ... 3 more ... | ThreadAuthorization>
run
=
import Effect
Effect
.
const gen: <Effect.Effect<string, Schema.SchemaError, never> | Effect.Effect<Layer<LanguageModel | ProviderName | ModelName, never, never>, AiError, OpenAiClient | DecisionModel | SelectionStore> | Effect.Effect<{
readonly finishReason: "completed" | "model-stop" | "budget-exhausted";
readonly turns: number;
readonly output: {
readonly answer: string;
};
readonly threadId: string & Brand<"@effect-agent/core/ThreadId">;
... 4 more ...;
readonly delegatedUsage?: RunTotals | undefined;
}, AgentRuntime.AgentRuntimeFailure<...>, ThreadHistory> | Effect.Effect<...> | Effect.Effect<...>, {
readonly finishReason: "completed" | "model-stop" | "budget-exhausted";
readonly turns: number;
readonly output: {
readonly answer: string;
};
readonly threadId: string & Brand<"@effect-agent/core/ThreadId">;
... 4 more ...;
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 authorization: {
readonly authorize: (threadId: Identifiers.ThreadId) => Effect.Effect<void, ThreadAccessDenied>;
}
authorization
= yield*
class ThreadAuthorization
ThreadAuthorization
;
yield*
const authorization: {
readonly authorize: (threadId: Identifiers.ThreadId) => Effect.Effect<void, ThreadAccessDenied>;
}
authorization
.
authorize: (threadId: Identifiers.ThreadId) => Effect.Effect<void, ThreadAccessDenied>
authorize
(
const threadId: string & Brand<"@effect-agent/core/ThreadId">
threadId
);
const
const input: string
input
= yield*
import Schema
Schema
.
function decodeUnknownEffect<Schema.String>(schema: Schema.String, options?: ParseOptions): (input: unknown, options?: ParseOptions) => Effect.Effect<string, Schema.SchemaError, never>

Decodes an unknown input against a schema, returning an Effect that succeeds with the decoded value or fails with a

SchemaError

.

When to use

Use when you need to decode unknown input in an Effect whose failure channel is SchemaError.

Details

Prefer

decodeEffect

when the input is already typed as the schema's Encoded type. Options may be provided either when creating the decoder or when applying it; application options override creation options.

@see ― SchemaParser.decodeUnknownEffect for the adapter that fails with SchemaIssue.Issue directly

@stability ― stable

@category ― decoding

@since ― 4.0.0

decodeUnknownEffect
(
const Assistant: Agent.Definition<Schema.String, Schema.Struct<{
readonly answer: Schema.String;
}>, "Compare the travel options and answer the user.", Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "assistant";
}
Assistant
.
Definition<String, Struct<{ readonly answer: String; }>, "Compare the travel options and answer the user.", Toolkit<{}>, undefined, undefined, undefined>.input: Schema.String

Canonical schema used to decode and encode run input.

input
)(
const rawInput: unknown
rawInput
);
const
const model: Layer<LanguageModel | ProviderName | ModelName, never, never>
model
= yield*
const ThreadModels: AutoModel<OpenAiClient>
ThreadModels
.
AutoModel<OpenAiClient>.resolve: (options: {
readonly threadId: string;
readonly state: Schema.Json;
}) => Effect.Effect<Layer<LanguageModel | ProviderName | ModelName, never, never>, AiError, OpenAiClient | DecisionModel | SelectionStore>

Return the Thread's retained choice, selecting and committing only when absent. Captures provider requirements; use the returned Layer within the Scope that owns those services.

resolve
({
threadId: string
threadId
,
state: Schema.Json
state
: {
task: string
task
:
const input: string
input
} });
return yield*
import AgentRuntime
AgentRuntime
.
const run: <Agent.Binding<Agent.Definition<Schema.String, Schema.Struct<{
readonly answer: Schema.String;
}>, "Compare the travel options and answer the user.", Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "assistant";
}, Layer<LanguageModel | ProviderName | ModelName, never, never>>, never, never>(agent: Agent.Binding<Agent.Definition<Schema.String, Schema.Struct<{
readonly answer: Schema.String;
}>, ... 4 more ..., undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "assistant";
}, Layer<...>>, input: string, options?: RunOptions<...> | undefined) => Effect.Effect<...>

Accept schema-encoded input, retaining runtime validation.

run
(
import Agent
Agent
.
function withModel<Agent.Definition<Schema.String, Schema.Struct<{
readonly answer: Schema.String;
}>, "Compare the travel options and answer the user.", Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "assistant";
}, Layer<LanguageModel | ProviderName | ModelName, never, never>>(definition: Agent.Definition<Schema.String, Schema.Struct<{
readonly answer: Schema.String;
}>, "Compare the travel options and answer the user.", Toolkit<...>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "assistant";
}, model: Layer<...>): Agent.Binding<...>

Bind a native model Layer without acquiring or hiding its requirements.

withModel
(
const Assistant: Agent.Definition<Schema.String, Schema.Struct<{
readonly answer: Schema.String;
}>, "Compare the travel options and answer the user.", Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "assistant";
}
Assistant
,
const model: Layer<LanguageModel | ProviderName | ModelName, never, never>
model
),
const input: string
input
, {
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
});
}).
Pipeable.pipe<Effect.Effect<{
readonly finishReason: "completed" | "model-stop" | "budget-exhausted";
readonly turns: number;
readonly output: {
readonly answer: 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?: Schema.Json | undefined;
readonly usage?: RunTotals | undefined;
readonly delegatedUsage?: RunTotals | undefined;
}, Schema.SchemaError | AgentRuntime.AgentRuntimeFailure<...> | ThreadAccessDenied, ThreadHistory | ... 3 more ... | ThreadAuthorization>, Effect.Effect<...>, Effect.Effect<...>>(this: Effect.Effect<...>, ab: (_: Effect.Effect<...>) => Effect.Effect<...>, bc: (_: Effect.Effect<...>) => Effect.Effect<...>): Effect.Effect<...> (+21 overloads)
pipe
(
import Effect
Effect
.
const timeout: (duration: Input) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E | TimeoutError, R> (+1 overload)

Adds a time limit to an effect, triggering a timeout if the effect exceeds the duration.

When to use

Use when you need a timeout of an Effect to be represented as a typed failure.

Details

The timeout function allows you to specify a time limit for an effect's execution. If the effect does not complete within the given time, a TimeoutError is raised. This can be useful for controlling how long your program waits for a task to finish, ensuring that it doesn't hang indefinitely if the task takes too long.

Gotchas

If the timeout wins, the source effect is interrupted.

Example (Failing when work takes too long)

import { Effect } from "effect"
const timedEffect = Effect.never.pipe(Effect.timeout(0))
const error = await Effect.runPromise(Effect.flip(timedEffect))
error._tag // => "TimeoutError"

@see ― timeoutOption for returning Option.none on timeout.

@see ― timeoutOrElse for a version that allows specifying both success and timeout handlers.

@stability ― stable

@category ― delays & timeouts

@since ― 2.0.0

timeout
("30 seconds"),
import Effect
Effect
.
const scoped: <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Scope>>

Runs an effect with a scope that closes when the effect completes.

When to use

Use to acquire scoped resources for the duration of a single workflow.

Details

Finalizers for resources acquired inside the workflow run as soon as the workflow completes, whether by success, failure, or interruption.

Example (Running a scoped acquisition)

import { Effect } from "effect"
const output: Array<unknown> = []
const resource = Effect.acquireRelease(
Effect.sync(() => { output.push("Acquiring resource") }).pipe(Effect.as("resource")),
() => Effect.sync(() => { output.push("Releasing resource") })
)
const program = Effect.scoped(
Effect.gen(function*() {
const res = yield* resource
yield* Effect.sync(() => { output.push(`Using ${res}`) })
return res
})
)
Effect.runSync(program)
output // => ["Acquiring resource", "Using resource", "Releasing resource"]

@stability ― stable

@category ― resource management

@since ― 2.0.0

scoped
);

Supply the host’s ThreadAuthorization, a DecisionModel, native provider clients, and a shared SelectionStore around this workflow. Keep selection and execution in the caller’s Scope and deadline; the Agent’s generation budget starts after selection. Resolving the same Thread reuses its committed choice. Child agents use their configured native model; a separate per-child choice requires explicit host resolution. The complete example includes provider and store wiring shared across two requests.

API or option Behavior/default
make({ models, version, instructions? }) Returns an explicit selector; construction performs no provider work
version Required nonempty catalog identity; change with model settings
instructions Defaults to choosing the least expensive capable profile from descriptions
layerMemory({ capacity? }) 10,000 distinct attempted Thread IDs; no expiry or eviction
resolve({ threadId, state }) Commits or restores a choice and returns a native Layer with captured clients
select({ threadId, state }) Makes a new decision on each execution; returns the model and record
restore(threadId, record) Validates a retained record and returns its model without decision I/O

Provide AutoModel.layerMemory() once around the application’s resolutions and Runs. It loses selections when its Scope closes and fails at capacity instead of evicting a choice. Durable hosts supply an application-owned SelectionStore that atomically commits the winning record before generation and retains it across restarts.

Persist the complete version 2 SelectionRecord: Thread ID, catalog version, profile ID, decision label and probabilities, optional confidence, and token usage. Manual select callers must commit that record before using the returned model. Acquire the returned native Layer during execution.

Keep catalogs needed by active Threads. Invalid records, wrong Thread or catalog identity, and missing profiles fail with an AiError whose reason is InvalidRequestError; they do not silently trigger reselection. Selector usage is retained in the record, separate from generative Run usage. There are no implicit retries, fallback models, thresholds, or mid-Thread switches.

LanguageModelDecisionModel.layer requires a native LanguageModel supporting structured output and provides DecisionModel. All decisions share one generateObject call. Probabilities are model estimates. The provider-neutral example shows the composition.

Upstream @effect/ai-typesafe supplies TypeSafeDecisionModel.model("jev-latest"). Provide TypeSafeClient.layerConfig() and an HTTP client. Configuration reads TYPESAFE_API_KEY; apiUrl and transformClient are optional overrides. This supplies a decision service, not a generative language model.

Native validation checks labels, finite probabilities, and distribution sums within 1e-6 of one. The language-model adapter keeps this strict behavior; TypeSafe allows two-decimal rounding drift and rescales accepted distributions.

Input encoding failures use InvalidUserInputError; invalid answers use InvalidOutputError. Structured-output and provider failures retain their typed errors. Compose retries and timeouts explicitly. Read the decision example for ordinary assessments without model selection.