RunConfig is a dataclass in src/agents/run_config.py that defines run-wide settings: model selection, turn limits, input filtering, tool-naming policies, and tracing — applied uniformly across all agents in a single execution. Its hooks (call_model_input_filter, handoff_history_mapper, session_input_callback) let you customize how model inputs are prepared, history is compacted across agent handoffs, and new user messages merge into session state.
RunConfig is defined in src/agents/run_config.py and controls run-wide behavior — model selection, turn limits, tracing, tool policies, and input filtering — that applies across every agent invoked in a single run.[1] DEFAULT_MAX_TURNS is set to 10 in src/agents/run_config.py, making 10 AI invocations the default turn limit for a run.[2]
ModelInputData in src/agents/run_config.py is a dataclass holding input: list[TResponseInputItem] and instructions: str | None — the data container sent to the model each turn.[2] CallModelData in src/agents/run_config.py wraps ModelInputData, the active Agent, and the current context; it is passed to RunConfig.call_model_input_filter before every model call.[2] ReasoningItemIdPolicy in src/agents/run_config.py is a Literal["preserve", "omit"] type alias controlling whether reasoning item IDs are kept or stripped before model calls.[2] ToolNotFoundBehavior in src/agents/run_config.py is a Literal["raise_error", "return_error_to_model"] type alias controlling what happens when a model calls a tool that does not exist.[2] ToolNameCollisionPolicy in src/agents/run_config.py is a Literal["warn", "error"] type alias controlling whether duplicate tool names in a turn produce a warning or raise an error.[2]
RunConfig.call_model_input_filter is a hook to edit the fully prepared model input (instructions and input items) immediately before the model call — for example, to trim history or inject a system prompt.[1] RunConfig.reasoning_item_id_policy controls whether reasoning item IDs are preserved or omitted when the runner converts prior outputs into next-turn model input.[1] RunConfig.tool_not_found_behavior configures how the runner handles model-emitted function tool calls whose name does not match any available tool; the default raises ModelBehaviorError, but it can be set to return a model-visible error output instead.[1]
RunConfig.nest_handoff_history is an opt-in beta (default False) that compacts summarizable history into ordered assistant summary segments while preserving lossless message items; individual handoffs can override it via Handoff.nest_handoff_history.[1] RunConfig.handoff_history_mapper is an optional callable that receives the normalized transcript whenever nest_handoff_history is enabled and must return the exact list of input items to forward to the next agent, replacing the built-in ordered summary segments.[1] A handoff occurs when one agent delegates control to another agent within the same run; RunConfig's handoff history fields govern what context each receiving agent sees.
RunConfig.session_input_callback customizes how new user input is merged with session history before each Runner run when using Sessions; the callback can be sync or async, and the rewritten version of new-turn items is what gets persisted for that turn.[1][3]
RunConfig.workflow_name is recommended to be set on every run; RunConfig.trace_id sets the trace ID; RunConfig.group_id is an optional field that links traces across multiple runs.[1] RunConfig.trace_include_sensitive_data configures whether traces will include potentially sensitive data such as LLM and tool call inputs/outputs.[1]
Sources