TypeSafeClassifier classifies state into typed decisions and probabilities. It accepts strings, structured JSON, and LangChain message objects. Use it for focused decisions such as routing a request, choosing a model, or checking whether a tool call is safe to run.
Setup
Install@langchain/typesafe and its @langchain/core peer dependency:
dangerouslyAllowBrowser: false to reject browser use, as in the quickstart below.
Create an API key in the TypeSafe console and export it:
Optional: Set
TYPESAFE_BASE_URL to use a compatible gateway, test server, or private deployment. The default is https://api.typesafe.ai.Quickstart
ConfigureTypeSafeClassifier with a fixed set of named questions. Questions that share state are evaluated independently and in parallel in one request:
response.answers. The nouls, choices, and scores accessors group answer objects by type. The response also includes model, usage, and an optional requestId. The usage.inputTokens and usage.outputTokens fields are optional.
The grouped accessors are non-enumerable getters. Object spread and JSON serialization omit them; use answers when storing or transmitting the response.
State can be a string, a JSON object or array, or LangChain messages. The classifier converts message objects to transcript text, including when nested inside a larger object.
Configure requests
Constructor options control authentication and request behavior:apiKey: OverridesTYPESAFE_API_KEY.baseUrl: OverridesTYPESAFE_BASE_URL.timeout: Sets the per-request timeout in milliseconds. Defaults to30000.maxRetries: Sets the maximum number of retries. Defaults to2; set it to0to disable retries.fetch: Supplies a custom transport for proxies or tests.
signal, tags, and metadata, as the second argument to invoke. Questions and the model are constructor settings, not per-call overrides.
The classifier also supports batch and pipe. Its stream method yields the complete classification result, not incremental answers.
Handle errors
The package exportsTypeSafeError, TypeSafeAPIError, TypeSafeAuthenticationError, and TypeSafeRateLimitError. Use their isInstance(error) methods to identify failures. Avoid logging API error bodies indiscriminately: they can contain submitted state.
TypeSafe receives the state you submit, including message content and tool-call arguments. Remove secrets or sensitive data before invoking the classifier.
Decision types
Each question uses one of three primitives. Define questions as objects with atype of "noul", "choice", or "score". The package does not export Noul, Choice, or Score constructors:
A
noul answer has no confidence or probabilities. Use score rather than noul for a spectrum: a noul of 0.5 means an even split between yes and no, not “medium.”
Tracing
With LangSmith tracing enabled, TypeSafe classifications appear in LangSmith. You can inspect the input, output, and available token usage alongside the rest of your agent. LangSmith recordsusage in the traced output rather than as a costed LLM metric.
See also
Connect these docs to your agent of choice via MCP for real-time answers.

