Skip to content

Commit 2f32c44

Browse files
authored
docs: add details on message IDs and their assignment process (#32534)
1 parent fe740a9 commit 2f32c44

File tree

1 file changed

+35
-1
lines changed

1 file changed

+35
-1
lines changed

docs/docs/concepts/messages.mdx

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -147,7 +147,7 @@ An `AIMessage` has the following attributes. The attributes which are **standard
147147
| `tool_calls` | Standardized | Tool calls associated with the message. See [tool calling](/docs/concepts/tool_calling) for details. |
148148
| `invalid_tool_calls` | Standardized | Tool calls with parsing errors associated with the message. See [tool calling](/docs/concepts/tool_calling) for details. |
149149
| `usage_metadata` | Standardized | Usage metadata for a message, such as [token counts](/docs/concepts/tokens). See [Usage Metadata API Reference](https://python.langchain.com/api_reference/core/messages/langchain_core.messages.ai.UsageMetadata.html). |
150-
| `id` | Standardized | An optional unique identifier for the message, ideally provided by the provider/model that created the message. |
150+
| `id` | Standardized | An optional unique identifier for the message, ideally provided by the provider/model that created the message. See [Message IDs](#message-ids) for details. |
151151
| `response_metadata` | Raw | Response metadata, e.g., response headers, logprobs, token counts. |
152152

153153
#### content
@@ -243,3 +243,37 @@ At the moment, the output of the model will be in terms of LangChain messages, s
243243
need OpenAI format for the output as well.
244244

245245
The [convert_to_openai_messages](https://python.langchain.com/api_reference/core/messages/langchain_core.messages.utils.convert_to_openai_messages.html) utility function can be used to convert from LangChain messages to OpenAI format.
246+
247+
## Message IDs
248+
249+
LangChain messages include an optional `id` field that serves as a unique identifier. Understanding when and how these IDs are assigned can be helpful for debugging, tracing, and working with message history.
250+
251+
### When Messages Get IDs
252+
253+
Messages receive IDs in the following scenarios:
254+
255+
**Automatically assigned by LangChain:**
256+
- When generated through chat model invocation (`.invoke()`, `.stream()`, `.astream()`) with an active run manager/tracing context
257+
- IDs follow the format:
258+
- `run-$RUN_ID` (e.g., `run-ba48f958-6402-41a5-b461-5e250a4ebd36-0`)
259+
- `run-$RUN_ID-$IDX` (e.g., `run-ba48f958-6402-41a5-b461-5e250a4ebd36-1`) when there are multiple generations from a single chat model invocation.
260+
261+
**Provider-assigned IDs (highest priority):**
262+
- When the model provider assigns its own ID to the message
263+
- These take precedence over LangChain-generated run IDs
264+
- Format varies by provider
265+
266+
### When Messages Don't Get IDs
267+
268+
Messages will **not** receive IDs in these situations:
269+
270+
- **Manual message creation**: Messages created directly (e.g., `AIMessage(content="hello")`) without going through chat models
271+
- **No run manager context**: When there's no active callback/tracing infrastructure
272+
273+
### ID Priority System
274+
275+
LangChain follows a clear precedence system for message IDs:
276+
277+
1. **Provider-assigned IDs** (highest priority): IDs from the model provider
278+
2. **LangChain run IDs** (medium priority): IDs starting with `run-`
279+
3. **Manual IDs** (lowest priority): IDs explicitly set by users

0 commit comments

Comments
 (0)