Skip to content

The agent engineering platform.

docs(core): enhance docstring for `RunnableConfig` for clarity on `total=False` (#34756)

Mason Daugherty3899154daf9f
diff --git a/libs/core/langchain_core/runnables/config.py b/libs/core/langchain_core/runnables/config.py
index 13c7aba87c..3079f82d94 100644
--- a/libs/core/langchain_core/runnables/config.py
+++ b/libs/core/langchain_core/runnables/config.py
@@ -51,8 +51,24 @@ class EmptyDict(TypedDict, total=False):
class RunnableConfig(TypedDict, total=False):
"""Configuration for a `Runnable`.
- See the [reference docs](https://reference.langchain.com/python/langchain_core/runnables/#langchain_core.runnables.RunnableConfig)
- for more details.
+ !!! note Custom values
+
+ The `TypedDict` has `total=False` set intentionally to:
+
+ - Allow partial configs to be created and merged together via `merge_configs`
+ - Support config propagation from parent to child runnables via
+ `var_child_runnable_config` (a `ContextVar` that automatically passes
+ config down the call stack without explicit parameter passing), where
+ configs are merged rather than replaced
+
+ !!! example
+
+ ```python
+ # Parent sets tags
+ chain.invoke(input, config={"tags": ["parent"]})
+ # Child automatically inherits and can add:
+ # ensure_config({"tags": ["child"]}) -> {"tags": ["parent", "child"]}
+ ```
"""
tags: list[str]
@@ -92,7 +108,8 @@ class RunnableConfig(TypedDict, total=False):
configurable: dict[str, Any]
"""Runtime values for attributes previously made configurable on this `Runnable`,
- or sub-Runnables, through `configurable_fields` or `configurable_alternatives`.
+ or sub-`Runnable` objects, through `configurable_fields` or
+ `configurable_alternatives`.
Check `output_schema` for a description of the attributes that have been made
configurable.