4.2 — Models and Messages

1. What is it?

LangChain's model abstraction (BaseChatModel and its provider-specific subclasses like ChatAnthropic, ChatOpenAI) and message types (SystemMessage, HumanMessage, AIMessage, ToolMessage) are the standardized representation of "a conversation with an LLM" that every other LangChain component (agents, chains, retrievers) is built around. This chapter goes into what these abstractions are actually normalizing across providers, and what's lost or gained by using them versus a provider's raw SDK.

2. Why does it exist?

Part 2.6/3.1 established that chat-style LLM interaction is structured as role-tagged messages — but every provider's raw API represents this slightly differently (different field names, different ways of representing tool calls, different content-block structures for multimodal input, Part 3.10). LangChain's message types exist to give you one consistent Python object model for "a message in a conversation," regardless of which provider ultimately sends and receives it — so your application logic (building conversation history, inspecting tool calls, handling multimodal content) is written once, against one consistent interface.

3. What problem does it solve?

It solves "how do I write model-agnostic application logic when every provider's underlying message/API format differs." Without this abstraction, switching providers (or supporting multiple providers, Part 3.11's fallback routing) means rewriting the message-construction and response-parsing code for each provider's specific format — LangChain's message types are the shared vocabulary that makes that switch a configuration change rather than a rewrite.

4. How does it work internally?

The message type hierarchy

BaseMessage

SystemMessagepersistent instructions (Part 3.1)

HumanMessageuser turns

AIMessagemodel-generated turns, including tool calls

ToolMessageresults returned from tool execution (Part 3.3 step 6)

Each of these wraps a content field (which can be a plain string, or — for multimodal/structured content, Part 3.10 — a list of typed content blocks) plus metadata like response_metadata (token usage, model identifier, provider-specific extra fields) and, for AIMessage, a tool_calls field structured consistently regardless of provider, even though the underlying providers represent tool-call requests differently in their raw API responses.

BaseChatModel — the provider-normalizing layer

Every provider integration (ChatAnthropic, ChatOpenAI, etc.) implements the same BaseChatModel interface — meaning it exposes the same .invoke(), .stream(), .bind_tools() methods regardless of provider, translating your standardized list[BaseMessage] input into that specific provider's raw API request format internally, and translating that provider's raw response back into a standardized AIMessage on the way out.

Your codelist[BaseMessage] in / AIMessage out

ChatAnthropic.invoke()internal translation, hidden from your code

Anthropic's raw API

Swapping ChatAnthropic(...) for ChatOpenAI(...) in this picture, with the same list[BaseMessage] input, should (for the common, well-covered cases) produce a functionally equivalent AIMessage output — that's the concrete value of the abstraction, and it's genuinely useful for Part 3.11's fallback-routing pattern, since your message-handling code doesn't need a provider-specific branch.

.content_blocks — where the abstraction gets more nuanced

Section 4's research (Part 4.1) noted LangChain 1.0's .content_blocks property, giving a provider-agnostic view of reasoning traces, citations, and tool calls on a message. This exists precisely because the plain content string field alone doesn't capture everything a modern model's response can contain — a response might include an internal reasoning trace, one or more tool calls, and citation metadata, all as part of one message, and different providers structure this differently in their raw responses. .content_blocks is the standardized way to inspect these regardless of provider, which matters directly if your application needs to display or log reasoning/citations without writing per-provider parsing logic.

.bind_tools() — attaching Part 3.3's tool definitions

model_with_tools = model.bind_tools([get_order_status_tool])

.bind_tools() returns a new Runnable that, when invoked, automatically includes the bound tool definitions in the underlying API request — internally, this is doing exactly the structured-output/tool-schema translation from Part 3.2/3.3 (converting your tool's schema into whatever format the specific provider's API expects for tool definitions), so your code specifies tools once, in one format, regardless of provider.

Setting cache_control on LangChain message content blocks

Part 3.3's prompt-caching mechanics (a cache breakpoint marked on a stable content block, so a subsequent request sharing that exact prefix is billed a fraction of the normal input-token price for it) apply identically when going through LangChain — the framework passes this provider-specific field through rather than hiding or replacing it. Because content can be either a plain string or a list of typed content blocks, you cache by giving content the list form and adding cache_control to whichever block you want the breakpoint on:

from langchain_core.messages import SystemMessage, HumanMessage

messages = [
    SystemMessage(
        content=[
            {
                "type": "text",
                "text": LONG_STABLE_SYSTEM_PROMPT,
                "cache_control": {"type": "ephemeral"},  # cache breakpoint
            }
        ]
    ),
    HumanMessage(content="How do I reset my password?"),
]

response = await model.ainvoke(messages)

Verify the exact current syntax (field name, nesting, and which provider packages support it) against langchain-anthropic's current documentation before shipping — this is a provider-specific passthrough field, not a normalized part of BaseMessage, so it's more exposed to upstream API changes than the rest of this chapter's abstractions. As in Part 3.3, caching only pays off when the marked content is genuinely stable and byte-identical across calls — a .bind_tools()-attached tool list or a large SystemMessage reused across every turn of a conversation are the natural candidates, not a message whose content changes per request. Verify actual cache hits via response.response_metadata's usage fields (section 8's guidance on inspecting response_metadata) rather than assuming the marker alone guarantees a hit.

5. Simple mental model

LangChain's message types and BaseChatModel interface are a universal power adapter for a conversation with an LLM: you plug in your message list (the same shape regardless of destination country/provider), and the adapter (the provider-specific ChatXxx class) handles translating to and from whatever plug shape (raw API format) the actual wall socket (the provider's API) requires — you never need to learn the destination country's exact socket shape yourself.

6. Real-world example

A team building a customer support system initially ships with ChatAnthropic as their model provider. Three months in, they want to add Part 3.11's fallback-routing pattern using a different provider as backup during outages. Because their application logic is written against list[BaseMessage] and the standardized AIMessage/ToolMessage types rather than any provider-specific raw format, adding the fallback model is a configuration change (instantiate a second ChatXxx object) rather than a parallel, separately-maintained code path for handling that provider's different raw response format.

7. Architecture diagram

Your application codeprovider-agnostic · list[BaseMessage] in → AIMessage out

ChatAnthropictranslates to/from Anthropic's raw API format

ChatOpenAItranslates to/from OpenAI's raw API format

The interface is unified — the underlying model behavior is not.

8. Production considerations

• Don't assume 100% behavioral parity across providers just because the message interface is unified — the underlying models themselves still behave differently (Part 3.1's warning that prompting techniques don't transfer identically applies here too); the abstraction unifies the interface, not the model behavior.
• Inspect response_metadata for token usage and provider-specific details you need for cost tracking (Part 3.11, Part 7.10) — this is where usage information surfaces in the standardized message object, and it's worth logging explicitly for the audit-trail pattern from Part 2.6, section 17.
• Use .content_blocks rather than raw content string parsing when you need to inspect reasoning traces, citations, or tool calls reliably across providers — hand-parsing the raw content field for this is fragile and provider-specific.

9. Common mistakes

• Writing code that assumes a specific provider's raw response quirks (e.g., a specific field only present in one provider's format) instead of using the standardized message/.content_blocks interface, quietly breaking provider-agnosticism you thought you had.
• Assuming that because the interface is unified, prompts and behavior will transfer identically when switching providers, without re-evaluating (Part 8) after a provider switch.
• Not checking response_metadata for token usage, then having no data for the cost-tracking and model-routing decisions from Part 3.11.

10. Security considerations

• SystemMessage content still carries the same trust-boundary considerations from Part 3.1/9.1 — using LangChain's message types doesn't change the underlying fact that a SystemMessage's elevated instruction-following priority is a trained tendency, not an absolute security guarantee.
• ToolMessage content (tool results fed back to the model) is still untrusted-input territory exactly as in Part 3.3 — the standardized message type doesn't add any implicit sanitization.

11. Performance considerations

• .stream() on a BaseChatModel gives token-by-token output using the same underlying interface as .invoke() — no separate code path needed, directly benefiting from the Runnable interface's uniformity discussed in Part 4.1.

12. Cost considerations

• response_metadata's token usage fields are your primary, provider-normalized data source for the per-call cost tracking that Part 3.11's routing and Part 7.10's cost-optimization framework depend on — build logging around this from the start rather than retrofitting it later.

13. When to use it

Whenever you want your message-handling and model-invocation code to remain provider-agnostic — essentially always, for any LangChain-based application, given the low cost and real future flexibility this buys you (provider fallback, provider comparison/evaluation, migration).

14. When NOT to use it

If you need a provider-specific feature not yet exposed through LangChain's standardized interface (a very new, provider-specific capability the abstraction hasn't caught up to yet), dropping to that provider's raw SDK for that specific call, while keeping the rest of your application on the standardized interface, is a legitimate, pragmatic choice — don't contort your architecture to force everything through an abstraction that doesn't yet support what you need.

15. Alternatives and trade-offs

Approach	Good for	Weak point
LangChain message/model abstraction	Provider-agnostic code, easy fallback/comparison	Slight abstraction overhead; may lag behind brand-new provider-specific features
Direct provider SDK	Full access to every provider-specific feature immediately	Provider lock-in; more code to change when adding/switching providers

16. Practical Python/code example

from langchain_core.messages import SystemMessage, HumanMessage
from langchain_anthropic import ChatAnthropic

model = ChatAnthropic(model="claude-sonnet-4-5")

messages = [
    SystemMessage(content="You are a concise support assistant."),
    HumanMessage(content="How do I reset my password?"),
]

response = await model.ainvoke(messages)
print(response.content)
print(response.response_metadata.get("usage"))  # verify exact field name against current docs

17. Production-quality example

A provider-agnostic call wrapper with usage logging, directly building on this chapter's abstraction to implement Part 3.11's cost-tracking requirement:

import logging
from langchain_core.messages import BaseMessage, AIMessage

logger = logging.getLogger("model_call")


async def invoke_with_usage_logging(model, messages: list[BaseMessage], request_id: str) -> AIMessage:
    """
    Invokes any BaseChatModel-compatible model and logs token usage in a
    provider-agnostic way, using the standardized response_metadata field.

    Args:
        model: Any LangChain BaseChatModel instance (Anthropic, OpenAI, etc.).
        messages (list[BaseMessage]): The conversation to send.
        request_id (str): Correlation ID for tracing this call.

    Returns:
        AIMessage: The model's response.
    """
    response = await model.ainvoke(messages)
    usage = response.response_metadata.get("usage", {})
    logger.info(
        "request_id=%s model=%s input_tokens=%s output_tokens=%s",
        request_id,
        getattr(model, "model", "unknown"),
        usage.get("input_tokens"),
        usage.get("output_tokens"),
    )
    return response

Because this function only depends on the standardized BaseMessage/AIMessage interface, it works identically regardless of which provider model actually is — exactly the fallback-routing-ready code the real-world example in section 6 needed.

18. Short exercise

Write a small function that takes a list[BaseMessage] conversation and a list of two different BaseChatModel instances (e.g., a primary and a fallback), tries the primary first, and falls back to the second on any exception — using only the standardized interface from this chapter, with no provider-specific branching.

19. Interview questions

• Explain what BaseChatModel actually normalizes across providers, and what it does NOT normalize (i.e., what still differs across providers even when using LangChain).
• Why does .content_blocks exist as a separate concept from a message's plain content field?
• What's the concrete practical benefit of building fallback-provider routing (Part 3.11) against LangChain's message abstraction versus each provider's raw SDK?

20. FDE/customer scenario

Customer: "We're worried about vendor lock-in with a single LLM provider — how hard would it be to switch later?"

Because the application is built against LangChain's standardized message/model interface rather than a specific provider's raw SDK, the honest answer is genuinely reassuring: switching (or adding a fallback) is largely a configuration change for the model-invocation layer, though the customer should understand that prompts may need re-tuning (Part 3.1) and behavior should be re-evaluated (Part 8) after any provider change — the abstraction reduces switching cost, but doesn't eliminate the need to verify behavior after switching.

---

Key takeaways

• LangChain's message types and BaseChatModel interface normalize the shape of provider interaction, not the underlying model's behavior — both matter, and conflating them is a common mistake.
• .content_blocks gives a provider-agnostic view of reasoning, citations, and tool calls that the plain content field doesn't fully capture.
• response_metadata is your standardized source for token usage, feeding directly into Part 3.11's routing and Part 7.10's cost tracking.

Things you should be able to explain

• What BaseChatModel normalizes across providers and what it doesn't.
• Why .bind_tools() lets you specify a tool once, provider-agnostically.

Things you should be able to build

• A provider-agnostic invocation wrapper with usage logging and fallback support.

Common mistakes

• Assuming behavioral parity across providers because the interface is unified.
• Hand-parsing raw content instead of using .content_blocks for reasoning/citations/tool calls.

Recommended next chapter

03-prompts-and-structured-outputs.md