---
title: experimental_decide
description: Decide answers to typed questions against shared state with a decision model.
url: "https://ai-sdk.dev/docs/reference/ai-sdk-core/decide"
docs_index: /llms.txt
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

```ts
import { experimental_decide } from 'ai';
```

Decides answers to a nonempty map of `choice`, `score`, and `boolean` questions against one
state. See [Decisions](/docs/ai-sdk-core/decisions) for examples and semantics.

## Parameters

| Parameter         | Type                                             | Description                                                                                                                               |
| ----------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `model`           | `Experimental_DecisionModel`                     | Required experimental v4 model instance or a string ID resolved by Gateway or an explicitly configured decision-capable default provider. |
| `state`           | `string \| object \| array`                      | Required JSON-compatible shared state.                                                                                                    |
| `questions`       | `Record<string, Experimental_DecisionQuestion>`  | Required nonempty question map.                                                                                                           |
| `maxRetries`      | `number`                                         | Nonnegative integer; defaults to 2.                                                                                                       |
| `abortSignal`     | `AbortSignal`                                    | Cancels the decisions request.                                                                                                            |
| `headers`         | `Record<string, string>`                         | Additional HTTP headers.                                                                                                                  |
| `providerOptions` | `ProviderOptions`                                | Provider-specific options.                                                                                                                |
| `telemetry`       | `TelemetryOptions`                               | Telemetry configuration, including per-call integrations, input/output recording, and a function ID.                                      |
| `runtimeContext`  | `Record<string, unknown>`                        | Context available to lifecycle callbacks and selectively included in telemetry with `telemetry.includeRuntimeContext`.                    |
| `onStart`         | `(event: Experimental_DecideStartEvent) => void` | Called when the decision operation begins.                                                                                                |
| `onEnd`           | `(event: Experimental_DecideEndEvent) => void`   | Called when the decision operation completes successfully.                                                                                |

See [Lifecycle Callbacks](/docs/ai-sdk-core/lifecycle-callbacks#experimental_decide)
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_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`. Invalid answers 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](/docs/ai-sdk-core/decisions#model-aliases-and-registries).

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)