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
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 anOpenAIClassifier with a decisions model, then pass the state and named questions together in each invocation. Questions that share state are answered in one request:
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:
Noul and ClassifierResponse, come from langchain_core.decisions.
Question types
Each question is one of three types:Noul: Sent to the API as apredicatequestion. A value near0.5means uncertainty, not “medium”, so useScorefor a spectrum. Predicates have no field for outcome descriptions, soOpenAIClassifierappends anycriteriato the instructions as text.Noulanswers have noconfidence, because the probability is the answer.Choice: Maps each label to a description, or toNonewhen the label needs no description. AChoiceneeds at least two labels. Include anotherlabel when your options may not cover every input. The answer includesprobabilitiesfor every label and a separateconfidencescore. Use labeled examples from your application to set thresholds.Score: Takes levels ordered from lowest to highest and indexed from0. The returnedscoreis the probability-weighted average of the level indices, so it may fall between levels, andlegendmaps each index to the level you supplied. The answer includes per-levelprobabilitiesand a separateconfidencescore.
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
Thestate 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.
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:
Configuration
An async callable
api_key works only with ainvoke and abatch.
Errors
ValueError: Raised when no API key is available, and byinvokefor a request the API does not support: aBoxquestion, aChoicewith 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 byinvokewhen the state isNone, 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 fromlangchain_core.exceptions.
Agent middleware
LangChain includes two beta middleware that use a decision model at an agent’s decision points. Pass anOpenAIClassifier 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:
delete_file, the middleware returns an error ToolMessage instead of running the tool, and the agent reports that the call was blocked.
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
- OpenAI Decisions guide
- OpenAI provider overview
- TypeSafe integrations
- Prebuilt middleware
- LangChain OpenAI API reference
For the native OpenAI Decisions API format, including per-question refusals and OpenAI-specific middleware, see the OpenAI Decisions integration.
Connect these docs to your agent of choice via MCP for real-time answers.

