Skip to main content
OpenAIClassifier answers typed questions with the OpenAI Decisions API through LangChain’s standard BaseDecisionModel interface. It shares its question and response types with other decision models, such as TypeSafeClassifier, so you can swap providers without changing application code, and pass it to LangChain’s decision-driven agent middleware. OpenAIClassifier is a Runnable, so you can invoke, batch, or compose it with other runnables. It accepts strings, structured JSON, LangChain message objects, and images, and records traces and token usage in LangSmith. OpenAIClassifier adopts the shared BaseDecisionModel interface, which does not cover every Decisions API feature. For example, the Decisions API can refuse individual questions, but when it refuses any question, OpenAIClassifier raises ModelRefusalError and discards the other answers. To use the full OpenAI request and response format, use OpenAIDecisions instead.
OpenAIClassifier is in beta and requires langchain-openai>=1.8.0. Its API may change without notice.

Setup

Create an API key in the OpenAI dashboard and export it:
Optional: Set OPENAI_API_BASE or OPENAI_BASE_URL to use a compatible gateway or test server. The default is the OpenAI API endpoint. OPENAI_API_BASE takes precedence when both are set.

Quickstart

Create an OpenAIClassifier with a decisions model, then pass the state and named questions together in each invocation. Questions that share state are answered in one request:
Answers are keyed by the question names you supplied, and grouped by type on nouls, choices, and scores. All answers are also available on answers. The response carries the model that answered, the OpenAI request_id, and token usage. usage is a dictionary, or None when the API returns no usage. Check for None before reading it:
The question and response types, such as Noul and ClassifierResponse, come from langchain_core.decisions.

Question types

Each question is one of three types:
  • Noul: Sent to the API as a predicate question. A value near 0.5 means uncertainty, not “medium”, so use Score for a spectrum. Predicates have no field for outcome descriptions, so OpenAIClassifier appends any criteria to the instructions as text. Noul answers have no confidence, because the probability is the answer.
  • Choice: Maps each label to a description, or to None when the label needs no description. A Choice needs at least two labels. Include an other label when your options may not cover every input. The answer includes probabilities for every label and a separate confidence score. Use labeled examples from your application to set thresholds.
  • Score: Takes levels ordered from lowest to highest and indexed from 0. The returned score is the probability-weighted average of the level indices, so it may fall between levels, and legend maps each index to the level you supplied. The answer includes per-level probabilities and a separate confidence score.
Instructions can be text, structured JSON, or contain images. Criteria accept text or structured JSON only, and a media block in criteria raises ValueError. langchain_core.decisions also defines a Box question type for locating objects in images. The OpenAI Decisions API does not support it, and OpenAIClassifier raises ValueError for a request that includes one.

State

The state can be a string, a JSON object or array, or LangChain messages:
  • Strings: Sent as-is.
  • LangChain messages: A message or list of messages at the root of the state is sent as native Decisions API input. Human, system, AI, and tool messages keep their roles, and tool calls and tool results are sent as function call items.
  • JSON objects and arrays: Sent as JSON in a single user message. Messages nested inside an object or array are converted to JSON.
To classify an agent conversation, including its tool calls, pass the messages as the state:
Messages accept text and image content. Images can be base64 data or public http or https URLs. File and audio content raise ValueError, and system messages accept text only. To classify an image, pass it in a message at the root of the state:
JSON state cannot carry media. OpenAIClassifier drops media blocks inside an object or array, including blocks in nested messages, and emits a UserWarning. Pass messages as the root state to include their images.

Configuration

An async callable api_key works only with ainvoke and abatch.

Errors

  • ValueError: Raised when no API key is available, and by invoke for a request the API does not support: a Box question, a Choice with fewer than two labels, media in criteria, file or audio content, non-text system message content, or a tool call without an ID.
  • TypeError: Raised by invoke when the state is None, a number, or a boolean.
  • ModelRefusalError: Raised when the API refuses any question in the request. The message names the refused questions, and answers to the other questions are discarded. Import it from langchain_core.exceptions.

Agent middleware

LangChain includes two beta middleware that use a decision model at an agent’s decision points. Pass an OpenAIClassifier as their classifier. Both require langchain>=1.5.0:

Route models

ModelRouterMiddleware picks one of your named models for each agent run, based on the latest human message:

Gate tool calls

AutoModeMiddleware checks each call to the tools you list, and blocks calls the classifier judges risky:
The default instructions treat destructive actions as risky, even when the user asks for them. When the agent calls delete_file, the middleware returns an error ToolMessage instead of running the tool, and the agent reports that the call was blocked.
Do not put secrets in tool arguments or conversation state unless sending them to OpenAI is acceptable. This middleware refuses risky calls. It does not request approval. Pair it with human-in-the-loop middleware when you want a person to approve them.

Tracing

OpenAIClassifier runs are traced in LangSmith with the openai provider and model name, so you can inspect decisions and token usage alongside the rest of your application.

See also

For the native OpenAI Decisions API format, including per-question refusals and OpenAI-specific middleware, see the OpenAI Decisions integration.