> ## 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

> Access agent-defined settings at runtime via the SDK.

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`](../getting-started/circuit-toml-reference#settings-section) with types, defaults, and options
2. **Upload** — 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.

<CodeGroup>
  ```python Python theme={null}
  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}")
  ```

  ```typescript TypeScript theme={null}
  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}`);
    }
  }
  ```
</CodeGroup>

### 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`:**

```toml theme={null}
[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:**

<CodeGroup>
  ```python Python theme={null}
  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}")
  ```

  ```typescript TypeScript theme={null}
  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}`);
  }
  ```
</CodeGroup>

### 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`:

```bash theme={null}
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](../cli-references/development#settings).

### See Also

* [`circuit.toml` Reference](../getting-started/circuit-toml-reference#settings-section) — Defining settings
* [Agent Context](../concepts/agent-context) — All context properties and methods
* [SDK Quick Reference](./sdk-quick-reference) — SDK methods at a glance