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.
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 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.
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:
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.
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
Definition<String,Struct<{ readonlyanswer: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.
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.
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.
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.
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.