Settings
ControlFlow provides a variety of settings to configure its behavior. These can be configured via environment variables or programmatically.
Environment variables
All settings can be set via environment variables using the format CONTROLFLOW_<setting name>
.
For example, to set the default LLM model to gpt-4o-mini
and the log level to DEBUG
, you could set the following environment variables:
export CONTROLFLOW_LLM_MODEL=openai/gpt-4o-mini
export CONTROLFLOW_LOG_LEVEL=DEBUG
You can also set these values in a .env
file. By default, ControlFlow will look for a .env
file at ~/.controlflow/.env
, but you can change this behavior by setting the CONTROLFLOW_ENV_FILE
environment variable.
export CONTROLFLOW_ENV_FILE="~/path/to/.env"
Runtime settings
You can examine and modify ControlFlow’s settings at runtime by inspecting or updating the controlflow.settings
object. Most — though not all — changes to settings will take effect immediately. Here is the above example, but set programmatically:
import controlflow as cf
cf.settings.llm_model = 'openai/gpt-4o-mini'
cf.settings.log_level = 'DEBUG'
Available settings
Home settings
home_path
: The path to the ControlFlow home directory. Default:~/.controlflow
Display and logging settings
log_level
: The log level for ControlFlow. Options:DEBUG
,INFO
,WARNING
,ERROR
,CRITICAL
. Default:INFO
log_prints
: Whether to log workflow prints to the Prefect logger by default. Default:False
log_all_messages
: If True, all LLM messages will be logged at the debug level. Default:False
pretty_print_agent_events
: If True, a PrintHandler will be enabled and automatically pretty-print agent events. Note that this may interfere with logging. Default:True
Orchestration settings
orchestrator_max_agent_turns
: The default maximum number of agent turns per orchestration session. If None, orchestration may run indefinitely. This setting can be overridden on a per-call basis. Default:100
orchestrator_max_llm_calls
: The default maximum number of LLM calls per orchestrating session. If None, orchestration may run indefinitely. This setting can be overridden on a per-call basis. Default:1000
task_max_llm_calls
: The default maximum number of LLM calls over a task’s lifetime. If None, the task may run indefinitely. This setting can be overridden on a per-task basis. Default:None
LLM settings
llm_model
: The default LLM model for agents. Default:openai/gpt-4o
llm_temperature
: The temperature for LLM sampling. Default:0.7
max_input_tokens
: The maximum number of tokens to send to an LLM. Default:100000
Debug settings
debug_messages
: If True, all messages will be logged at the debug level. Default:False
tools_raise_on_error
: If True, an error in a tool call will raise an exception. Default:False
tools_verbose
: If True, tools will log additional information. Default:True
Experimental settings
enable_experimental_tui
: If True, the experimental TUI will be enabled. If False, the TUI will be disabled. Default:False
run_tui_headless
: If True, the experimental TUI will run in headless mode, which is useful for debugging. Default:False
Prefect settings
These are default settings for Prefect when used with ControlFlow. They can be overridden by setting standard Prefect environment variables.
prefect_log_level
: The log level for Prefect. Options:DEBUG
,INFO
,WARNING
,ERROR
,CRITICAL
. Default:WARNING