Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.circuit.org/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Required Settings

Settings marked required = true have no default value. The platform blocks execution until the user provides a value, so your agent code does not need to handle the missing case.

​
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"hello"
booleanbooleantrue
single_selectstring"conservative"
integernumber3
numbernumber50.5
percentagenumber0.5
addressstring"0x1234...abcd"

​
End-to-End Example

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

[settings.slippage_tolerance]
description = "Maximum slippage tolerance"
type = "percentage"
default = 0.5
required = false

[settings.buy_amount_usd]
description = "USD amount per buy order"
type = "number"
default = 50.0
required = false

[settings.max_orders_per_day]
description = "Maximum buy orders per day"
type = "integer"
default = 3
required = false

[settings.treasury]
description = "Fee collection wallet"
type = "address"
default = "0x1234567890abcdef1234567890abcdef12345678"
required = false

[settings.api_key]
description = "Your API key for the external service"
type = "text"
required = true
2. Access at runtime: 
def run(agent: AgentContext) -> None:
    risk = agent.settings.get("risk_level")  # "low", "medium", or "high"
    slippage = agent.settings.get("slippage_tolerance")  # e.g. 0.5

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

    buy_amount = agent.settings.get("buy_amount_usd")  # e.g. 50.0
    max_orders = agent.settings.get("max_orders_per_day")  # e.g. 3
    treasury = agent.settings.get("treasury")  # e.g. "0x1234..."
    api_key = agent.settings.get("api_key")  # always present (required setting)
    agent.log(f"Slippage: {slippage}%, Amount: ${buy_amount}, Max orders: {max_orders}")

​
Testing Locally

circuit dev run and circuit dev unwind inject your circuit.toml setting defaults into the agent context — no extra flags needed. To override individual settings for a single invocation, use --setting KEY=VALUE: 
circuit dev run --setting risk_level=high --setting buy_amount_usd=100
Resolution order: circuit.toml default (for optional settings) → --setting override. Required settings have no default and must be provided via --setting. For full flag documentation, see Development — Settings.

​
See Also