model initialization & messages

86 notes in this subject, read out of this brain and free to use. This is page 1 of 2.

Standard message types in LangChain

LangChain provides four standard message types: SystemMessage identifies the message type and sets model behavior; HumanMessage represents user input; AIMessage represents model output including text, tool calls, and metadata; ToolMessage represents tool call outputs.

Message structure: Role, Content, Metadata

Messages are objects containing three components: Role identifies the message type (e.g., system, user); Content represents the actual message payload (text, images, audio, documents, etc.); Metadata includes optional fields such as response information, message IDs, and token usage.

init_chat_model function basic usage

The init_chat_model function creates a chat model instance. Minimal usage: init_chat_model("gpt-5-nano") in Python or await initChatModel("gpt-5-nano") in JavaScript. Returns a model ready to invoke with messages.

Basic agent message invocation example

Create messages list with SystemMessage, HumanMessage, and optionally AIMessage. Pass to model.invoke(messages) which returns an AIMessage. Example: model.invoke([SystemMessage("You are helpful"), HumanMessage("Hello")])

Text prompts vs message prompts

Text prompts are strings ideal for single standalone requests without conversation history. Message prompts are lists of message objects used for multi-turn conversations, multimodal content, and system instructions.

HumanMessage metadata fields

HumanMessage supports optional metadata: name field identifies different users (behavior varies by provider); id field provides unique identifier for tracing.

AIMessage attributes structure

AIMessage objects contain: text (string) - text content; content (string or dict[]) - raw content; content_blocks (ContentBlock[]) - standardized content blocks; tool_calls (dict[] or None) - tool calls made by model; id (string) - unique identifier; usage_metadata (dict or None) - token counts; response_metadata (ResponseMetadata or None) - provider response metadata.

Message content types

Message content can be: a string; a list of provider-native content blocks (e.g., OpenAI format); a list of LangChain standard content blocks. Use content_blocks/contentBlocks property to access standardized representation.

Standard content block types

TextContentBlock (type: 'text') - standard text output; ReasoningContentBlock (type: 'reasoning') - model reasoning steps; ImageContentBlock (type: 'image') - image data; AudioContentBlock (type: 'audio') - audio data; VideoContentBlock (type: 'video') - video data; FileContentBlock (type: 'file') - generic files like PDF; PlainTextContentBlock (type: 'text-plain') - document text (.txt, .md).

Multimodal input image formats

Images can be provided as: URL with type 'image' and url field; base64 data with type 'image', base64 field, and required mime_type; provider-managed File ID with type 'image' and file_id field.

Multimodal input PDF formats

PDFs can be provided as: URL with type 'file' and url field; base64 data with type 'file', base64 field, and required mime_type; provider-managed File ID with type 'file' and file_id field.

Multimodal input audio formats

Audio can be provided as: base64 data with type 'audio', base64 field, and required mime_type; provider-managed File ID with type 'audio' and file_id field.

Multimodal input video formats

Video can be provided as: base64 data with type 'video', base64 field, and required mime_type; provider-managed File ID with type 'video' and file_id field.

AIMessage token usage metadata

AIMessage.usage_metadata contains: input_tokens (count); output_tokens (count); total_tokens (count); input_token_details (object with audio, cache_read counts); output_token_details (object with audio, reasoning counts).

init_chat_model with output_version parameter

init_chat_model accepts output_version parameter set to 'v1' to store standardized content blocks in message content. Usage: init_chat_model("gpt-5-nano", output_version="v1") in Python or initChatModel("gpt-5-nano", { outputVersion: "v1" }) in JavaScript. Can also set LC_OUTPUT_VERSION environment variable.

ImageContentBlock attributes in Python

ImageContentBlock contains: type (required, always 'image'); url (URL to image location); base64 (base64-encoded image data); id (unique identifier); mime_type (image MIME type like image/jpeg, image/png, required for base64 data).

AudioContentBlock attributes in Python

AudioContentBlock contains: type (required, always 'audio'); url (URL to audio location); base64 (base64-encoded audio data); id (unique identifier); mime_type (audio MIME type like audio/mpeg, audio/wav, required for base64 data).

VideoContentBlock attributes in Python

VideoContentBlock contains: type (required, always 'video'); url (URL to video location); base64 (base64-encoded video data); id (unique identifier); mime_type (video MIME type like video/mp4, video/webm, required for base64 data).

FileContentBlock attributes in Python

FileContentBlock contains: type (required, always 'file'); url (URL to file location); base64 (base64-encoded file data); id (unique identifier); mime_type (file MIME type like application/pdf, required for base64 data).

TextContentBlock structure

TextContentBlock contains: type (required, always 'text'); text (required, the text content); annotations (list of annotations for text); extras (additional provider-specific data).

ReasoningContentBlock structure

ReasoningContentBlock contains: type (required, always 'reasoning'); reasoning (the reasoning content); extras (additional provider-specific data like provider signature).

ContentBlock.Multimodal.Image in TypeScript

ContentBlock.Multimodal.Image contains: type (required, always 'image'); url (URL to image); data (base64-encoded image data); fileId (reference to image in file storage system); mimeType (image MIME type, required for base64 data).

ContentBlock.Multimodal.Audio in TypeScript

ContentBlock.Multimodal.Audio contains: type (required, always 'audio'); url (URL to audio); data (base64-encoded audio data); fileId (reference to audio file in external storage); mimeType (audio MIME type, required for base64 data).

ContentBlock.Multimodal.File in TypeScript

ContentBlock.Multimodal.File contains: type (required, always 'file'); url (URL to file); data (base64-encoded file data); fileId (reference to file in external file storage system); mimeType (file MIME type, required for base64 data).

ContentBlock.Multimodal.PlainText in TypeScript

ContentBlock.Multimodal.PlainText contains: type (required, always 'text-plain'); text (required, the text content); title (optional, title of text content); mimeType (MIME type of text like text/plain, text/markdown).

NonStandardContentBlock for provider-specific features

NonStandardContentBlock contains: type (required, always 'non_standard'); value (required, provider-specific data structure). Used as escape hatch for experimental or provider-unique features.

Message history with manually created AIMessage

AIMessage objects can be manually created and inserted into message history as if they came from the model. This is useful for managing multi-turn conversations or simulating previous model responses. Example: messages = [SystemMessage(...), HumanMessage(...), AIMessage(manually_created), HumanMessage(...)]

Dictionary format for messages OpenAI-compatible

Messages can be specified directly in OpenAI chat completions format using dictionaries with role and content keys: {"role": "system", "content": "..."}, {"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}

TypeScript ContentBlock import and usage

ContentBlock types can be imported: import { ContentBlock } from "langchain". Each content block type is individually addressable as subtypes like ContentBlock.Text, ContentBlock.Multimodal.Image, ContentBlock.Tools.ToolCall.

content_blocks property lazy parsing

Message objects implement content_blocks property (Python) or contentBlocks field (JavaScript) that lazily parses the content attribute into standardized, type-safe representation. Converts provider-native formats like Anthropic 'thinking' blocks into consistent ReasoningContentBlock format.

PlainTextContentBlock for document text

PlainTextContentBlock contains: type (required, always 'text-plain'); text (the text content); mime_type (MIME type like text/plain or text/markdown). Used for document text like .txt and .md files.

Chat models accept message sequences and return AIMessage

Chat models accept a sequence of message objects as input and return an AIMessage as output. Interactions are often stateless, so a simple conversational loop involves invoking a model with a growing list of messages.

AIMessage is the standard output type from chat models

Chat models return an AIMessage object as output when processing a sequence of message objects.

HTTP proxy configuration for ChatOpenAI

For deployments requiring HTTP proxies, ChatOpenAI supports proxy configuration via the openai_proxy parameter. Example: model = ChatOpenAI(model='gpt-5.5', openai_proxy='http://proxy.example.com:8080'). Proxy support varies by integration; check the specific provider's reference for proxy configuration options.

Provider-specific reasoning_effort aliases

Some providers accept native aliases for reasoning_effort. ChatAnthropic accepts 'effort', and ChatGoogleGenerativeAI accepts 'thinking_level'. Check the chat model integrations page for provider-specific details.

Custom base URL with init_chat_model

Many model providers offer OpenAI-compatible APIs (e.g., Together AI, vLLM). You can use init_chat_model with these providers by specifying the base_url parameter. Example: model = init_chat_model(model='MODEL_NAME', model_provider='openai', base_url='BASE_URL', api_key='YOUR_API_KEY').

Custom base URL with initChatModel in TypeScript

In JavaScript/TypeScript, use initChatModel with the baseUrl parameter to connect to OpenAI-compatible APIs. Example: model = await initChatModel('MODEL_NAME', {modelProvider: 'openai', baseUrl: 'BASE_URL', apiKey: 'YOUR_API_KEY'}).

Getting log probabilities from model responses

Certain models can be configured to return token-level log probabilities by setting the logprobs parameter when initializing the model. In Python: model = init_chat_model(model='gpt-5.5', model_provider='openai').bind(logprobs=True); then access response.response_metadata['logprobs']. In TypeScript: const model = new ChatOpenAI({model: 'gpt-5.5', logprobs: true}); then access responseMessage.response_metadata.logprobs.content.

Token usage information in AIMessage objects

Token usage information from model providers is included on AIMessage objects produced by the corresponding model when available. Some provider APIs, notably OpenAI and Azure OpenAI chat completions, require users to opt-in to receiving token usage data in streaming contexts.

Tracking aggregate token counts with UsageMetadataCallbackHandler

Use UsageMetadataCallbackHandler as a callback to track aggregate token counts across models. Example: callback = UsageMetadataCallbackHandler(); result_1 = model_1.invoke('Hello', config={'callbacks': [callback]}); result_2 = model_2.invoke('Hello', config={'callbacks': [callback]}); print(callback.usage_metadata). The usage_metadata dictionary contains per-model token counts with keys like 'input_tokens', 'output_tokens', 'total_tokens', 'input_token_details', and 'output_token_details'.

Tracking aggregate token counts with get_usage_metadata_callback context manager

Use get_usage_metadata_callback() as a context manager to track aggregate token counts across models. Example: with get_usage_metadata_callback() as cb: model_1.invoke('Hello'); model_2.invoke('Hello'); print(cb.usage_metadata). The usage_metadata dictionary contains per-model token counts.

RunnableConfig parameters for model invocation

When invoking a model, pass additional configuration through the config parameter using a RunnableConfig dictionary (Python) or object (JavaScript). Common configuration options are: run_name (string, identifies this specific invocation in logs and traces, not inherited by sub-calls), tags (string array, labels inherited by all sub-calls for filtering and organization), metadata (object, custom key-value pairs inherited by all sub-calls), max_concurrency/maxConcurrency (number, controls maximum parallel calls with batch() or batch_as_completed()), callbacks (array/CallbackHandler[], handlers for monitoring events), and recursion_limit (number, maximum recursion depth for chains).

Example: Model invocation with config in Python

```python response = model.invoke( "Tell me a joke", config={ "run_name": "joke_generation", # Custom name for this run "tags": ["humor", "demo"], # Tags for categorization "metadata": {"user_id": "123"}, # Custom metadata "callbacks": [my_callback_handler], # Callback handlers } ) ```

Example: Model invocation with config in TypeScript

```typescript const response = await model.invoke( "Tell me a joke", { runName: "joke_generation", // Custom name for this run tags: ["humor", "demo"], // Tags for categorization metadata: {"user_id": "123"}, // Custom metadata callbacks: [my_callback_handler], // Callback handlers } ) ```

Creating configurable models with init_chat_model

You can create a runtime-configurable model by specifying configurable_fields when calling init_chat_model. If you don't specify a model value, 'model' and 'model_provider' will be configurable by default. Example: configurable_model = init_chat_model(temperature=0); response = configurable_model.invoke('what\'s your name', config={'configurable': {'model': 'gpt-5-nano'}}).

Configurable model with custom fields and prefix

When creating a configurable model, you can specify which parameters are configurable and add a prefix to configurable parameter names. Example: first_model = init_chat_model(model='gpt-5.4-mini', temperature=0, configurable_fields=('model', 'model_provider', 'temperature', 'max_tokens'), config_prefix='first'). Then invoke with: first_model.invoke('what\'s your name', config={'configurable': {'first_model': 'claude-sonnet-4-6', 'first_temperature': 0.5, 'first_max_tokens': 100}}).

Using configurable models with declarative operations

Configurable models created with init_chat_model can be used with declarative operations like bind_tools, with_structured_output, and with_configurable in the same way as regularly instantiated chat model objects. You can chain configurable models and call operations on them before configuring them at runtime.

init_chat_model factory function for Python

init_chat_model is the main factory function for creating a basic LangChain chat model in Python. It initializes a model from a chat model provider of your choice. The minimal configuration includes passing the model name as the first argument. Additional parameters can be passed as keyword arguments including temperature, timeout, max_tokens, and max_retries.

initChatModel factory function for JavaScript

initChatModel is the main factory function for creating a basic LangChain chat model in JavaScript/TypeScript. It initializes a model from a chat model provider. The model name is passed as the first argument. Additional parameters are passed as an options object including temperature, timeout, maxTokens, and maxRetries.

Model initialization parameters in Python

When using init_chat_model in Python, the following parameters can be passed as keyword arguments: model (string, required) - the name or identifier of the model, api_key (string) - the authentication key, temperature (number) - controls randomness of output, max_tokens (number) - limits total tokens in response, timeout (number) - maximum time in seconds to wait for response, max_retries (number, default 6) - maximum number of retry attempts for failed requests.

Model initialization parameters in JavaScript

When using initChatModel in JavaScript, the following parameters can be passed in the options object: model (string, required) - the name or identifier of the model, apiKey (string) - the authentication key, temperature (number) - controls randomness of output, maxTokens (number) - limits total tokens in response, timeout (number) - maximum time in milliseconds to wait for response, maxRetries (number, default 6) - maximum number of retry attempts for failed requests.

Model parameter format for provider and model specification

The model parameter can specify both the model and its provider in a single argument using the format '{model_provider}:{model}', for example 'openai:o1' to specify OpenAI's o1 model.

max_retries default and retry behavior

The max_retries parameter defaults to 6. Retries use exponential backoff with jitter. Network errors, rate limits (429), and server errors (5xx) are retried automatically. Client errors such as 401 (unauthorized) or 404 are not retried. For long-running agent tasks on unreliable networks, consider increasing max_retries to 10-15.

Standard message types and structure in LangChain

LangChain provides standard message types for conversations. Messages have a role property that indicates who sent the message in the conversation. Two formats are supported: dictionary format with 'role' and 'content' keys, and message objects (SystemMessage, HumanMessage, AIMessage). The role types include 'system', 'user', and 'assistant'.

Message objects available in Python

Python provides message object classes: SystemMessage for system instructions, HumanMessage for user input, and AIMessage for model responses. These can be imported from langchain.messages.

Message objects available in JavaScript

JavaScript provides message object classes: SystemMessage for system instructions, HumanMessage for user input, and AIMessage for model responses. These can be imported from 'langchain'.

invoke() method for chat models

invoke() is the most straightforward way to call a model. It takes a single message (string) or a list of messages as input and returns a single AIMessage after the model has finished generating its complete response.

batch() method for chat models

batch() sends multiple independent requests to a model for more efficient parallel processing. By default it returns final output for the entire batch. The maxConcurrency parameter can be set in RunnableConfig to limit parallel calls.

batch_as_completed() method for chat models in Python

batch_as_completed() yields batch responses upon completion in Python. Results may arrive out of order, and each includes the input index for matching to reconstruct the original order as needed.

Model profile attribute

LangChain chat models expose a profile attribute (dictionary in Python, property in JavaScript) containing supported features and capabilities. Key fields include max_input_tokens, image_inputs, reasoning_output, and tool_calling. Profile data is powered by models.dev project with augmentations in LangChain integration packages.

Give your agent this brain