Skip to main content
Settings let agent developers define configurable parameters in circuit.toml that users can customize when starting a session. At runtime, the resolved values (defaults merged with any session-level overrides) are available on AgentContext.

​
How It Works

  1. Define settings in circuit.toml with types, defaults, and options
  2. Publish — settings are snapshotted with the agent version
  3. Users customize — when starting a session, users can override defaults
  4. Access at runtime — your agent reads resolved values via settings

​
Accessing Settings

The settings property is a flat key-value map where each key matches the setting name from your circuit.toml definition. Values are resolved in order: session override > default value. 
def run(agent: AgentContext) -> None:
    # Access the full settings map
    all_settings = agent.settings
    agent.log(f"Settings: {all_settings}")

    # Get a single setting by key
    risk_level = agent.settings.get("risk_level")
    if risk_level is None:
        agent.log("No risk_level setting defined")
    elif isinstance(risk_level, str):
        agent.log(f"Risk level: {risk_level}")

​
Value Types

The value type depends on the setting’s type in circuit.toml:
Setting TypeRuntime Value TypeExample
textstring"0.5"
booleanbooleantrue
single_selectstring"conservative"

​
End-to-End Example

1. Define in circuit.toml: 
[settings.risk_level]
description = "How aggressively the agent trades"
type = "single_select"
default = "medium"
options = ["low", "medium", "high"]

[settings.max_slippage]
description = "Maximum slippage tolerance as a percentage"
type = "text"
default = "0.5"
2. Access at runtime: 
def run(agent: AgentContext) -> None:
    risk = agent.settings.get("risk_level")  # "low", "medium", or "high"
    slippage = agent.settings.get("max_slippage")  # e.g. "0.5"

    if risk == "high":
        agent.log("Running aggressive strategy")

    max_slippage = float(slippage) if isinstance(slippage, str) else 0.5
    agent.log(f"Max slippage: {max_slippage}%")

​
See Also