AI SDK
ReferenceAI SDK Core

experimental_decide

Decide answers to typed questions against shared state with a decision model.

import { experimental_decide } from 'ai';

Decides answers to a nonempty map of choice, score, and boolean questions against one state. See Decisions for examples and semantics.

Parameters

ParameterTypeDescription
modelExperimental_DecisionModelRequired experimental v4 model instance or a string ID resolved by Gateway or an explicitly configured decision-capable default provider.
stateExperimental_DecisionStateRequired string, JSON object, or ordered array of text, file, and JSON parts.
questionsRecord<string, Experimental_DecisionQuestion>Required nonempty question map.
maxRetriesnumberNonnegative integer; defaults to 2.
abortSignalAbortSignalCancels the decisions request.
headersRecord<string, string>Additional HTTP headers.
providerOptionsProviderOptionsProvider-specific options.
telemetryTelemetryOptionsTelemetry configuration, including per-call integrations, input/output recording, and a function ID.
runtimeContextRecord<string, unknown>Context available to lifecycle callbacks and selectively included in telemetry with telemetry.includeRuntimeContext.
onStart(event: Experimental_DecideStartEvent) => voidCalled when the decision operation begins.
onEnd(event: Experimental_DecideEndEvent) => voidCalled when the decision operation completes successfully.

See Lifecycle Callbacks for the complete onStart and onEnd event fields.

Result

Returns Promise<Experimental_DecisionResult<QUESTIONS>>:

  • answers: One typed answer per question ID, with literal Choice option inference.
  • usage: inputTokens, outputTokens, and totalTokens, each possibly undefined.
  • warnings: Provider warnings, also passed to the SDK warning logger.
  • rounding: Optional provider-declared decimal precision for probabilities and scores.
  • providerMetadata: Optional provider-specific metadata.
  • response: Timestamp, model ID, and optional response ID, headers, and body.

Provider specification

Experimental_DecisionModelV4 is exported from @ai-sdk/provider and declares specificationVersion: 'v4', provider, modelId, supportedQuestionTypes, and doDecide(options). Decision models are isolated from stable ProviderV4.

The public core types are Experimental_DecisionModel, Experimental_DecisionState, Experimental_DecisionStatePart, Experimental_DecisionQuestion, Experimental_DecisionAnswer, and Experimental_DecisionResult. All decision-specific classes use the Decision prefix, with Experimental_ aliases at package boundaries.

Errors

Unsupported types throw Experimental_DecisionUnsupportedQuestionTypeError before provider I/O. Invalid inputs throw InvalidArgumentError; malformed answers throw InvalidResponseDataError. Questions the model refuses throw Experimental_DecisionRefusalError. Invalid answers and refusals are not retried. Neither partial results nor missing probability synthesis are supported.

Model resolution

Use registry.decisionModel('provider:model') or customProvider({ decisionModels: { alias: model } }).decisionModel('alias') to resolve models. Strings passed directly to experimental_decide use globalThis.AI_SDK_DEFAULT_PROVIDER.decisionModel(id) when a default provider is configured, or Gateway when no default provider is configured.

Resolution errors use the existing NoSuchModelError and NoSuchProviderError classes with modelType: 'decisionModel'. Model instances and resolved models must implement v4; other versions throw UnsupportedModelVersionError. See model resolution examples.

Previousexperimental_generateVideoNextuploadFile