Decisions

Rule

Use decide() to classify or score supplied inputs. It returns a result and never performs, authorizes, or replaces the action selected from that result.

How

Pass an explicit ownerEmail, an input string or array of parts, and named questions to decide() from @agent-native/core/decisions:

import { decide } from "@agent-native/core/decisions";

const result = await decide({
  ownerEmail: "owner@example.com",
  input: [{ type: "text", text: "Please cancel Friday's lunch reservation." }],
  questions: [
    {
      type: "predicate",
      name: "isCancellationRequest",
      instructions: "Does the message ask to cancel a reservation?",
    },
  ],
});

input can be a plain string or contain text, structured JSON, or an image URL. Questions are named and use one of these shapes:

Provider and model capabilities can differ. Treat question support as capability-aware. Only claim a provider/model supports a question type after that combination has been verified. An ok result includes provider, model, and answers keyed by question name; cached and usage are optional. A not_configured result includes the missing_credentials reason and configured provider list. A failed result has a typed reason and may include provider and questionNames. Handle these statuses as distinct outcomes; never turn a failure into an answer.

Provider routing and caches

Provider order is configurable per workspace. New customer workspaces try Builder Jev first, then a personal Jev key, then OpenAI. Within Jev, the Builder gateway is tried before falling back to a direct key. If no provider is configured, decide() returns not_configured.

getDecisionsStatus() reports credential readiness separately from provider capabilities. The Builder Jev proxy is verified for predicate and choice. Jev score remains unverified and disabled by its capability flag, so decide() skips Jev for score questions and continues to the next configured provider. A Jev-only score request returns failed with unverified_capability. The OpenAI Decisions API supports scores with 2–10 ordered levels; its request and response mapping is covered by documented fixtures.

Key any per-provider threshold or cache by both provider and model. cacheKey enables caching only when supplied. Cache identity includes the owner, organization, provider, model, cache key, input, and questions. The in-memory cache has a 60-second TTL and a 256-entry cap.

Related skills

• actions — keep action behavior focused and deterministic.