Chat Model Providers
Purpose and Scope
Chat model providers are the integration layer that lets an application talk to hosted model APIs while keeping one LangChain programming model. A chat model accepts a conversation made of role-bearing messages and returns a message, rather than using only plain text strings. That distinction matters because modern agents depend on system instructions, user messages, assistant responses, tool calls, multimodal content, and streaming deltas. Provider packages such as OpenAI, Anthropic, Mistral, Groq, DeepSeek, Fireworks, Ollama, OpenRouter, Perplexity, and xAI fit behind the same core abstractions so application code can compare or replace models with less orchestration churn.
Sources: libs/core/langchain_core/language_models/init.py, libs/core/langchain_core/language_models/base.py
Relevant Source Files
- libs/partners/openai/langchain_openai/chat_models/codex.py — shows a provider-specific chat model wrapper for an experimental OpenAI Codex backend, including provider headers, OAuth token handling, and safety warnings.
- libs/core/langchain_core/language_models/init.py — defines the public language model package surface and documents the distinction between chat models and legacy string-in, string-out LLMs.
- libs/core/langchain_core/language_models/_compat_bridge.py — converts chat model message chunks into protocol events used by newer streaming consumers.
- libs/core/langchain_core/language_models/_utils.py — contains shared language model helpers for tracing filters and OpenAI-style multimodal data block detection.
- libs/core/langchain_core/language_models/base.py — defines shared language model input and output types, tracing metadata, tokenizer helpers, and the base runnable interface.
- libs/core/langchain_core/language_models/chat_model_stream.py — implements per-message streaming objects and accumulated projections for text, reasoning, tool calls, usage, and final output.
Core Primitives
The central contract is the chat model abstraction, implemented by concrete provider integrations. The language model package exposes base chat models, legacy LLMs, fake models for tests, model profiles, tracing parameter types, and utility functions from a single public namespace. The documented input type accepts prompt values, strings, or message-like sequences, while the output is either a message or a string depending on the model family. Provider packages build on this common contract: they handle provider authentication, transport, model names, and special features, but the calling code still treats the result as a LangChain language model.
Sources: libs/core/langchain_core/language_models/init.py, libs/core/langchain_core/language_models/base.py
Provider Selection and API Shape
The official integration guidance presents providers as separate installable packages with their own credentials and model names, but the same invocation pattern. That is the practical meaning of a unified API: once a provider chat model is instantiated, application logic can call it, compose it with tools, stream from it, or put it inside an agent without rewriting the surrounding workflow. Provider-specific capabilities still matter. OpenAI may expose one set of endpoints and content formats, Anthropic or Mistral another, and local or OpenAI-compatible services may differ in authentication and available model names. LangChain keeps those differences at the adapter boundary.
Sources: libs/core/langchain_core/language_models/init.py, libs/core/langchain_core/language_models/base.py
OpenAI Codex as a Provider-Specific Example
The OpenAI Codex implementation illustrates how a provider integration can extend the common model surface while preserving the standard flow for regular users. The Codex class wraps the normal OpenAI chat model but targets a ChatGPT Codex backend, adds refresh-aware authorization, sets a ChatGPT account header, and allows an originator header to be configured by field or environment variable. The file is explicit that this path is experimental and unofficial, and it emits a warning about account permissions, terms, rate limits, and safeguards. This is a useful pattern to remember: provider adapters can expose specialized transports, but they should make unusual operational constraints visible.
Sources: libs/partners/openai/langchain_openai/chat_models/codex.py
Streaming and Content Blocks
Streaming is part of the provider contract, not a separate application architecture. The compatibility bridge converts message chunks into a protocol lifecycle with message start, content block start, repeated content block deltas, content block finish, and message finish. It treats each chunk as a delta slice and accumulates indexed state only when finalization requires a completed block, such as parsed tool call arguments. The stream objects then expose projections for text, reasoning, tool calls, usage, and final output while still allowing raw event iteration. This lets provider integrations emit incremental data in their natural style while clients consume a consistent event stream.
Sources: libs/core/langchain_core/language_models/_compat_bridge.py, libs/core/langchain_core/language_models/chat_model_stream.py
Multimodal Data and Tracing Behavior
Provider integrations also need small shared rules that keep applications predictable. One utility detects OpenAI Chat Completions style data blocks for images, audio, and files, accepting either data-bearing or identifier-bearing file blocks and allowing callers to filter by modality. Another utility removes large or inappropriate fields such as tools, functions, messages, and response format from invocation parameters before tracing. These details are easy to overlook, but they are important for production provider use: multimodal payloads need format checks, and observability systems should avoid recording oversized request internals when concise metadata is enough.
Sources: libs/core/langchain_core/language_models/_utils.py
Compact Reference
Use this page as a map from provider-facing decisions to the core implementation areas that enforce common behavior. If you are choosing a model, start with the provider package and credentials described in the integration docs, then verify that the features your agent needs are supported by the model profile or provider documentation. If you are implementing or debugging an integration, check that the adapter returns LangChain messages, reports tracing metadata, supports expected streaming events, and handles provider-specific payloads at the boundary rather than leaking them throughout the application.
| Concern | Source-backed contract | What to verify |
|---|---|---|
| Common model surface | Base language model input and output types plus exported chat model abstractions | Application code should call the model through the shared LangChain interface |
| Provider metadata | LangSmith parameters include provider, model name, model type, temperature, max tokens, stop words, and integration | Traces should identify the provider and model without including large request payloads |
| Streaming | Chat chunks are bridged to protocol events and accumulated by stream projections | Clients can consume text, reasoning, tool calls, usage, and final output incrementally |
| Multimodal payloads | OpenAI-style image, audio, and file data blocks are recognized by shared utilities | Provider adapters should normalize content blocks before higher-level consumers inspect them |
| Specialized integrations | Codex demonstrates custom endpoint, OAuth headers, account headers, and warning behavior | Experimental or unofficial provider paths should document operational and policy constraints |
Execution Flow
A typical provider-backed chat flow starts when the application instantiates a provider model with a model name and credentials. The model receives a string, prompt value, or message sequence and normalizes it into the language model input contract. During invocation, provider-specific code builds the request, adds authentication, and sends it to the remote service or local endpoint. The response returns as a message, or as chunks when streaming is enabled. If streaming is used, compatibility code converts chunks into protocol events and stream projections accumulate the pieces that the user interface, agent runtime, or observability layer needs.
Sources: libs/core/langchain_core/language_models/base.py, libs/core/langchain_core/language_models/_compat_bridge.py, libs/core/langchain_core/language_models/chat_model_stream.py
Next Steps
For application authors, the next step is to pick the provider package that matches the model you want to use, configure the required environment variables or credentials, and keep the rest of the agent logic provider-neutral where possible. For integration authors, focus on honoring the shared chat model contract first, then add provider-specific features in well-contained options and payload translation code. Continue with the language model API reference for base classes, the messages and content reference for message shapes, and the event streaming page if your product needs live token, reasoning, or tool-call updates.