Settings

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

Define settings in circuit.toml with types, defaults, and options
Upload - settings become the agent’s current settings
Users customize - when starting a session, users can override defaults
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}")

async function run(agent: AgentContext): Promise<void> {
  // Access the full settings map
  const allSettings = agent.settings;
  await agent.log(`Settings: ${JSON.stringify(allSettings)}`);

  // Get a single setting by key
  const riskLevel = agent.settings.risk_level;
  if (riskLevel === undefined) {
    await agent.log("No risk_level setting defined");
  } else if (typeof riskLevel === "string") {
    await agent.log(`Risk level: ${riskLevel}`);
  }
}

Value Types

The value type depends on the setting’s type in circuit.toml:

Setting Type	Runtime Value Type	Example
`text`	`string`	`"hello"`
`boolean`	`boolean`	`true`
`single_select`	`string`	`"conservative"`
`integer`	`number`	`3`
`number`	`number`	`50.5`
`percentage`	`number`	`0.5`
`address`	`string`	`"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}")

async function run(agent: AgentContext): Promise<void> {
  const risk = agent.settings.risk_level; // "low", "medium", or "high"
  const slippage = agent.settings.slippage_tolerance; // e.g. 0.5

  if (risk === "high") {
    await agent.log("Running aggressive strategy");
  }

  const buyAmount = agent.settings.buy_amount_usd; // e.g. 50.0
  const maxOrders = agent.settings.max_orders_per_day; // e.g. 3
  const treasury = agent.settings.treasury; // e.g. "0x1234..."
  const apiKey = agent.settings.api_key; // always present (required setting)
  await agent.log(`Slippage: ${slippage}%, Amount: $${buyAmount}, Max orders: ${maxOrders}`);
}

Testing Locally

circuit run and circuit 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 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.

Getting Started

Core Concepts

Examples

CLI Reference

SDK Reference

Advanced

How It Works

Required Settings

Accessing Settings

Value Types

End-to-End Example

Testing Locally

See Also

​How It Works

​Required Settings

​Accessing Settings

​Value Types

​End-to-End Example

​Testing Locally

​See Also

How It Works

Required Settings

Accessing Settings

Value Types

End-to-End Example

Testing Locally

See Also