This page documents the configuration system that controls Runnable execution behavior and enables runtime modification of runnable properties. The system covers:
configurable_fields and configurable_alternatives for runtime switchingwith_retry for transient failure handling, with_fallbacks for provider-level fallbackvar_child_runnable_config for implicit config inheritanceFor information about callbacks and observability hooks, see page 4.3. For agent-specific configuration and middleware, see page 4.1.
The RunnableConfig TypedDict defines the configuration options available for all Runnable objects. Configuration is passed through the optional config parameter in methods like invoke, ainvoke, stream, astream, batch, and abatch.
Key Fields:
| Field | Type | Purpose | Inherited by Children |
|---|---|---|---|
tags | list[str] | Categorize and filter runs in traces | Yes |
metadata | dict[str, Any] | Attach JSON-serializable context to runs | Yes |
callbacks | Callbacks | List of handlers or callback manager | Yes |
run_name | str | Override default name in tracer | No |
max_concurrency | int | None | Control parallel execution in batch operations | Yes |
recursion_limit | int | Maximum recursive call depth | Yes |
configurable | dict[str, Any] | Values for dynamically configurable fields | Yes |
run_id | UUID | None | Unique identifier for this specific run | No |
Sources: libs/core/langchain_core/runnables/config.py51-123
The ensure_config function normalizes partial configurations into complete RunnableConfig objects with default values. It merges user-provided config with context-propagated config from var_child_runnable_config.
Key Behavior:
tags, metadata, callbacks, configurable)Sources: libs/core/langchain_core/runnables/config.py216-266
The merge_configs function combines multiple configurations intelligently, handling special merge logic for collections and callback managers.
Merge Rules:
| Field | Merge Strategy |
|---|---|
tags | Concatenate and deduplicate (sorted) |
metadata | Shallow merge (later values override) |
callbacks | Combine handlers or merge managers |
configurable | Shallow merge (later values override) |
recursion_limit | Use last non-default value |
| Other fields | Use last non-None value |
Sources: libs/core/langchain_core/runnables/config.py357-420
The patch_config function creates a new config by selectively updating specific fields. When replacing callbacks, it automatically removes run_name and run_id since they should apply only to the original callbacks.
Sources: libs/core/langchain_core/runnables/config.py315-354
The get_config_list function generates a list of configs from a single config or sequence, used for batch operations. It warns if a run_id is provided for multiple inputs (will only use for first element).
Sources: libs/core/langchain_core/runnables/config.py269-312
The configurable_fields method makes specific fields of a Runnable dynamically configurable at runtime without modifying the original instance. This returns a RunnableConfigurableFields wrapper that reads values from config["configurable"].
Field Types:
ConfigurableField: Simple field with id and optional metadataConfigurableFieldSingleOption: Field with predefined options (single selection)ConfigurableFieldMultiOption: Field with predefined options (multiple selection)The test cases show configurable fields in action:
Sources: libs/core/tests/unit_tests/runnables/test_runnable.py742-826 libs/core/langchain_core/runnables/configurable.py318-534
The configurable_alternatives method enables switching between entirely different Runnable implementations at runtime based on a configuration key.
prefix_keys Option: When True, alternative-specific configurable fields are prefixed with the alternative name to avoid conflicts.
Alternatives can be specified as:
Runnable instancesfunctools.partialSources: libs/core/tests/unit_tests/runnables/test_runnable.py872-881 libs/core/langchain_core/runnables/configurable.py536-908
The with_config method creates a new Runnable instance with bound configuration that will be merged with any config provided at invocation time.
Common Patterns:
Sources: libs/core/langchain_core/runnables/base.py2034-2061
The with_retry method wraps a Runnable in a RunnableRetry that automatically retries on failure using configurable backoff logic. It is defined on the base Runnable class and delegates retry behavior to the tenacity library.
with_retry parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
retry_if_exception_type | tuple[type[BaseException], ...] | (Exception,) | Exception types that trigger a retry |
wait_exponential_jitter | bool | True | Add random jitter to exponential backoff delays |
stop_after_attempt | int | 3 | Maximum number of total attempts |
Configuration flow:
Sources: libs/core/langchain_core/runnables/base.py1-100
Example from the Runnable docstring:
The ExponentialJitterParams type, imported in libs/core/langchain_core/runnables/base.py, defines the parameter schema for retry configuration. The RunnableRetry class itself lives in libs/core/langchain_core/runnables/retry.py.
Sources: libs/core/langchain_core/runnables/base.py1-120
The with_fallbacks method wraps a Runnable in a RunnableWithFallbacks. If the primary runnable raises an exception, each fallback is attempted in order until one succeeds or all fail.
Class: RunnableWithFallbacks — defined in libs/core/langchain_core/runnables/fallbacks.py36-100
Key fields on RunnableWithFallbacks:
| Field | Type | Description |
|---|---|---|
runnable | Runnable[Input, Output] | The primary runnable to attempt first |
fallbacks | Sequence[Runnable[Input, Output]] | Ordered list of fallback runnables |
exceptions_to_handle | tuple[type[BaseException], ...] | Exception types that trigger a fallback (default: (Exception,)) |
exception_key | str | None | If set, passes the caught exception into the fallback's input dict under this key |
Execution model:
Usage:
Chain-level fallback: Fallbacks can be applied to full chains, not just individual models:
exception_key usage: When set, the caught exception object is passed into the fallback runnable's input dict, allowing the fallback to inspect the failure reason.
Sources: libs/core/langchain_core/runnables/fallbacks.py36-110 libs/core/tests/unit_tests/runnables/test_fallbacks.py33-48
Configuration automatically propagates from parent to child runnables through the var_child_runnable_config context variable. This enables implicit context passing without explicit parameter threading.
The set_config_context function establishes a context for child runnables:
var_child_runnable_config context variableContext object for executionKey Functions:
var_child_runnable_config: ContextVar storing current configset_config_context(config): Context manager for config propagationensure_config(config): Reads from context var and merges with provided configSources: libs/core/langchain_core/runnables/config.py146-214
The configuration system provides concurrency control through max_concurrency and executor management.
The ContextThreadPoolExecutor extends ThreadPoolExecutor to preserve context variables when submitting tasks to worker threads.
For async operations, concurrency is controlled via semaphores in gather_with_concurrency:
Sources: libs/core/langchain_core/runnables/config.py527-596 libs/core/langchain_core/runnables/utils.py49-78
Configuration enables callback attachment and propagation through the execution hierarchy.
When a Runnable invokes a child, callbacks are propagated:
get_child()Functions:
get_callback_manager_for_config(config): Creates sync callback managerget_async_callback_manager_for_config(config): Creates async callback managerpatch_config(config, callbacks=run_manager.get_child()): Updates config with child callbacksSources: libs/core/langchain_core/runnables/config.py489-520 libs/core/langchain_core/callbacks/manager.py489-503
Runnables expose their configurable fields through schema methods for introspection and validation.
The config_specs property returns a list of ConfigurableFieldSpec objects describing available configuration options:
The config_schema method generates a Pydantic model representing valid configuration structure:
The get_config_jsonschema method produces a JSON Schema representation for API documentation and validation:
Sources: libs/core/langchain_core/runnables/base.py520-582 libs/core/langchain_core/runnables/utils.py448-620
Configuration techniques can be combined for sophisticated runtime control:
Sources: libs/core/tests/unit_tests/runnables/test_runnable.py742-869
Configuration plays a crucial role in session management for conversational applications:
The history_factory_config specifies which configurable fields should be passed to the session history factory function.
Sources: libs/core/langchain_core/runnables/history.py169-222 libs/core/tests/unit_tests/runnables/test_history.py169-196
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.