3.3

Messages and content blocks

Every model input and output is a list of four message types, and content_blocks reads any provider's content as the same typed blocks.

You switch an agent from one provider to another, and the code that read the reasoning text of the model breaks. One provider puts it in a thinking block and the other in a reasoning block. Both are still the content of an AIMessage, in two shapes.

When you finish this section, you can build each message type and read a tool call from an AIMessage. You can also read content through standard blocks that stay the same across providers.

The four message types

Message: one entry in the conversation, with a type, a content, and an optional id.

SystemMessage holds instructions, HumanMessage holds the user turn, AIMessage holds the model output, and ToolMessage holds a tool result. This is one conversation in their dict form:

jsonone conversation as message objectsFull log
  {
    "type": "HumanMessage",
    "content": "What is 2 + 3?"
  },
  {
    "type": "AIMessage",
    "content": "",
    "tool_calls": [
      {
        "name": "add",
        "args": {
          "a": 2,
          "b": 3
        },
        "id": "call_1",
        "type": "tool_call"
      }
    ]
  },
  {
    "type": "ToolMessage",
    "content": "5",
    "name": "add",
    "tool_call_id": "call_1",
    "status": "success"
  },
  {
    "type": "AIMessage",
    "content": "The sum is 5.",
    "usage_metadata": {
      "input_tokens": 12,
      "output_tokens": 6,
      "total_tokens": 18
    }
  }
The first section of the file. The SystemMessage is cut.

Tool call: an entry in AIMessage.tool_calls with a name, parsed args, and an id. The ToolMessage that answers it carries the same id in tool_call_id.

The AIMessage that asks for a tool has empty content. Its request is in tool_calls, already parsed from the JSON text of the provider. usage_metadata holds the token counts when the provider reports them. Figure 3.5 shows where each field is.

Fig. 3.5the fields of an AIMessage and its ToolMessagestructure
The fields of an AIMessage and its ToolMessage Three cards read from one agent run. The first is the AIMessage that asks for a tool: content "", id lc_run--<uuid-2>-0, and tool_calls with name add, args {a: 2, b: 3}, and id <uuid-3>. The second is the ToolMessage that answers it: content "5", name add, tool_call_id <uuid-3>, and status success. A dashed line joins the id <uuid-3> in the tool call to tool_call_id <uuid-3>. The third, below, is the final AIMessage with content "2 + 3 = 5." and no tool_calls, which ends the loop. A reply from a real provider also carries usage_metadata, such as 12 input and 6 output tokens in the messages capture. AIMessage content "" id lc_run--<uuid-2>-0 tool_calls .name add .args {a: 2, b: 3} .id <uuid-3> ToolMessage content "5" name add id <uuid-4> tool_call_id <uuid-3> status success same id the next model call reads both AIMessage, the final answer content "2 + 3 = 5." tool_calls none, so the agent stops usage_metadata 12 in, 6 out, when the provider reports it The request for a tool is in tool_calls, already parsed, and its content is empty. The ToolMessage repeats the id of the call it answers.
A tool call lives in AIMessage.tool_calls, not in content, and the ToolMessage that answers it repeats its id in tool_call_id. The left card is the AIMessage that asks for add, and the right card is the ToolMessage that answers it. The line joins the two fields that hold call_1.

You can also pass plain dicts and tuples. create_agent and every chat model turn {"role": "user", "content": "hi"} into a HumanMessage, and ("assistant", "hello") into an AIMessage:

jsondicts and tuples after convert_to_messagesFull log
  {
    "type": "HumanMessage",
    "content": "hi"
  },
  {
    "type": "AIMessage",
    "content": "hello"
  },
  {
    "type": "SystemMessage",
    "content": "be brief"
  }

Content blocks

Content block: one typed part of a message, a dict with a type such as text, reasoning, image, file, or tool_call.

The documentation says that every message has a content_blocks property, which parses content into standard typed blocks when you read it. The same page says that content blocks add to content and do not replace it. So content keeps the shape of the provider, and content_blocks gives you the standard shape.

The kit builds an AIMessage with content in the Anthropic shape: a thinking block with a signature, then a text block. content_blocks reads it as standard blocks:

jsonprovider content read as standard blocksFull log
  {
    "type": "reasoning",
    "reasoning": "Add the numbers.",
    "extras": {
      "signature": "sig"
    }
  },
  {
    "type": "text",
    "text": "The sum is 5."
  }
]

.text -> 'The sum is 5.'

The thinking block became reasoning, and the field of the provider that has no standard name went to extras. .text joins the text blocks into one string. It is a property at the pin. Code that calls .text() still works, and it warns.

On an AIMessage with tool calls and empty content, content_blocks has one tool_call block for each call. So one loop over content_blocks reads text, reasoning, and tool calls in their order.

Multimodal input

A HumanMessage can hold a list of standard blocks in content. The kit sends a text block, an image by URL, and a PDF as base64:

jsona multimodal human messageFull log
      {
        "type": "text",
        "text": "Describe this image."
      },
      {
        "type": "image",
        "url": "https://example.com/cat.png"
      },
      {
        "type": "file",
        "base64": "JVBERi0=",
        "mime_type": "application/pdf"
      }
The content list of the message.

Each provider package converts these blocks to its own request format. The model profile says which inputs a model accepts, such as image_inputs and pdf_inputs. Section 3.2 shows one profile.

Chunks

Chunk: a part of a message that a model streams, such as AIMessageChunk. Chunks add with + into one message.

Tool calls also stream in parts. Each tool_call_chunk holds a piece of the arguments as text. When the chunks are added, the parts join, and the parsed call appears in tool_calls:

jsontool call chunks after they are addedFull log
{
  "tool_call_chunks": [
    {
      "name": "add",
      "args": "{\"a\": 2, \"b\": 3}",
      "id": "call_1",
      "index": 0,
      "type": "tool_call_chunk"
    }
  ],
  "tool_calls": [
    {
      "name": "add",
      "args": {
        "a": 2,
        "b": 3
      },
      "id": "call_1",
      "type": "tool_call"
    }
  ]
}

langchain-core 1.7.0 changed how a stream reports the arguments of a tool call while they arrive. Part 5 shows the stream events of the pin.

Trimming

trim_messages keeps the last messages that fit a token budget. With max_tokens=3 and a counter that counts one per message, it kept the system message and the last two messages. With start_on="human" it kept only the system message, because no kept slice started on a human message:

jsontrim_messages with start_on humanFull log
the same with start_on='human':
[
  {
    "type": "SystemMessage",
    "content": "You are terse."
  }
]

The first result starts with a ToolMessage whose AIMessage was cut. Most providers reject a tool result without its call. So trim on a turn boundary, and test what your trim returns.

LangChain (Python): langchain, langchain-core, langgraph, deepagents, langsmith 1.5.0 · c2f4036 · 2026-11-11 · Edition 2026.11