Skip to main content
Advanced 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 advancedSettings

​
Accessing Settings

The advancedSettings property is a flat key-value map where each key matches a key 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.advancedSettings
    agent.log(f"Settings: {all_settings}")

    # Get a single setting by key
    risk_level = agent.get_setting("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"
multi_selectstring[] / list[str]["uniswap_v3", "curve"]

​
End-to-End Example

1. Define in circuit.toml: 
[[advancedSettings]]
key = "risk_level"
label = "Risk Level"
description = "How aggressively the agent trades"
type = "single_select"
default = "medium"

  [[advancedSettings.options]]
  key = "low"
  label = "Low"

  [[advancedSettings.options]]
  key = "medium"
  label = "Medium"

  [[advancedSettings.options]]
  key = "high"
  label = "High"

[[advancedSettings]]
key = "max_slippage"
label = "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.get_setting("risk_level")  # "low", "medium", or "high"
    slippage = agent.get_setting("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}%")

​
Backward Compatibility

  • Agents without settings defined: advancedSettings is an empty object {}
  • Old agents receiving new payloads: Extra fields are silently ignored by both SDKs
  • New agents on old payloads: advancedSettings defaults to {}; getSetting() / get_setting() returns undefined / None

​
See Also