Agent Structure & Configuration

Directory Structure

Python
TypeScript

<agent-name>/
├── main.py               # Agent code (run/unwind functions)
├── DESCRIPTION.md        # Agent description (shown in Circuit UI)
├── circuit.toml         # Agent configuration
├── pyproject.toml        # Dependencies
├── AGENTS.md             # AI coding assistant context
└── CLAUDE.md             # Claude compatibility pointer

<agent-name>/
├── index.ts              # Agent code (run/unwind functions)
├── DESCRIPTION.md        # Agent description (shown in Circuit UI)
├── circuit.toml         # Agent configuration
├── package.json          # Dependencies
├── tsconfig.json         # TypeScript compiler settings
├── AGENTS.md             # AI coding assistant context
└── CLAUDE.md             # Claude compatibility pointer

Agent Code

from circuit_sdk import AgentContext

def run(agent: AgentContext) -> None:
    agent.log("Hello from my agent!")
    # Your agent logic here

def unwind(agent: AgentContext) -> None:
    allocation = agent.allocation
    agent.log(f"Unwind requested for {len(allocation.balances)} balances")
    # Optional unwind logic

import type { AgentContext } from "circuit:sdk";

export async function run(agent: AgentContext): Promise<void> {
  await agent.log("Hello from my agent!");
  // Your agent logic here
}

export async function unwind(agent: AgentContext): Promise<void> {
  const allocation = agent.allocation;
  await agent.log(`Unwind requested for ${allocation.balances.length} balances`);
  // Optional unwind logic
}

`run` Function

Python
TypeScript

Signature: def run(agent: AgentContext) -> None:
Called when a [[triggers]] entry fires (the schedule trigger, or a reactive trigger)
Receives AgentContext with session data and SDK methods
Returns void (no return value)

Signature: async function run(agent: AgentContext): Promise<void>
Called when a [[triggers]] entry fires (the schedule trigger, or a reactive trigger)
Receives AgentContext with session data and SDK methods
Returns void (no return value)

`unwind` Function

Python
TypeScript

Signature: def unwind(agent: AgentContext) -> None:
Called when you ask the agent to unwind positions
Optional unwind logic using agent.allocation
Returns void (no return value)

Signature: async function unwind(agent: AgentContext): Promise<void>
Called when the agent is unwound
Optional unwind logic using agent.allocation
Returns void (no return value)

The plan: `DESCRIPTION.md`

Every agent must include a DESCRIPTION.md file alongside circuit.toml. It is the agent’s plan - the short prose a user reads to decide whether to deploy, rendered as a card on the agent’s page in Circuit. Write all five sections below; keep each line plain, concrete, and present-tense, with real asset/protocol names and no filler.

## Summary

One or two sentences: what the agent does and why it works.

## What it is

**Long:** Gold
**Short:** Bitcoin

## How it works

- Holds a long-gold, short-BTC pair at equal notional.
- Rebalances daily to keep the legs matched.

## Strategy

- Long GOLD, short BTC at equal notional.
- Rebalance when either leg drifts past 5%.
- Exit the pair if drawdown hits the 10% kill-switch.

## Risks

- Both legs can move against you - capped by a 10% drawdown kill-switch.
- Funding/borrow costs erode returns in choppy markets.

## What it is renders as labeled chips, so its rows must use exactly the labels for your circuit.toml category - a missing or mislabeled row is silently dropped from the card. Each value is an ultra-short noun phrase (plain names, no tickers or parentheticals):

`category`	Labels
`spread`	`Long`, `Short`
`yield`	`Source`, `Strategy`, `Target`, `Destination`
`quant`	`Model`, `Trigger`, `Execution`
`prediction`	`Signal`, `Action`, `Reason`
`index`	`Model`, `Trigger`, `Execution` (reuses the quant template)
`experimental`	`Signal`, `Action`, `Reason` (reuses the prediction template)

circuit.toml

The circuit.toml file defines your agent’s metadata, asset requirements, execution settings, and deployment configuration. It must be in the root of your agent directory.

Full Example

agentId = "8b0d9e66-3c0f-4f59-b39e-8b5c6d7b6f9a"  # generated by `circuit new`; the agent's permanent identity
name = "My Agent"                        # max 32 characters
slug = "my-agent"                        # public handle; unique among your agents
tagline = "Short subtitle for cards"     # max 32 characters
category = "experimental"
imageUrl = "https://api.circuit.org/assets/agents/default"
walletVmFamily = "evm"
allowedExecutionModes = ["auto", "manual"]
filesToExclude = []

[[triggers]]
type = "schedule"
every = 15
align = "rolling"

[startingAsset]
network = "ethereum:1"
address = "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
minimumAmount = "10000000000000000"

[settings.risk_level]
description = "How aggressively the agent trades"
type = "single_select"
default = "medium"
required = false
options = ["low", "medium", "high"]

Field Reference

Field	Type	Required	Description
`agentId`	string (UUID)	Yes	The agent’s permanent identity. Generated for you by `circuit new` - never edit it. Every upload updates the agent with this id, so `name` and `slug` can change freely without forking. See Agent Identity below.
`name`	string	Yes	Display name shown in the Circuit UI (32 characters or less). Free to change after upload - renaming updates the same agent.
`slug`	string	Yes	Public, human-readable handle (kebab-case, 64 characters or less), unique among your agents. Generated from `name` by `circuit new`; you may change it.
`tagline`	string	Yes	Brief subtitle shown on agent cards (32 characters or less)
`category`	string	No	Catalog category for the explore page. Allowed values: `"spread"`, `"index"`, `"prediction"`, `"quant"`, `"yield"`, `"experimental"`. Defaults to `"experimental"`.
`imageUrl`	string	No	Agent icon URL. Defaults to `"https://api.circuit.org/assets/agents/default"`.
`walletVmFamily`	string	No	`"evm"` or `"svm"` (the wallet’s signing key family). Defaults to `"evm"`.
`allowedExecutionModes`	string[]	No	Array of `"auto"` and/or `"manual"`. The first entry is the default for `circuit run`. Embedded execution accepts only `"auto"`; `--dry-run` accepts `"manual"` but warns that approvals are not simulated. Defaults to `["auto"]`.
`triggers`	array of tables	Yes	The agent’s dispatch configuration: what wakes `run()`. Exactly one `schedule` trigger is required, plus optional reactive triggers. See `[[triggers]]` below.
`startingAsset`	table	Yes	The token a user must hold to start a session. Required to upload. See `[startingAsset]` below.
`filesToExclude`	string[]	No	Files in agent directory to exclude from upload.
`settings`	table	No	Configurable settings users can customize when starting a session. See `[settings]` below.
`exchangeCredentials`	table	No	Exchange credentials users must select when starting a session. See `[exchangeCredentials]` below.

Deployment Regions

Allowed values	Default when omitted
`us-east-1`, `eu-central-1`	`us-east-1`

`[[triggers]]` Section

Triggers are the only dispatch configuration: what the config lists is exactly what wakes your agent, nothing is implied or defaulted. Every agent declares exactly one schedule trigger (the guaranteed periodic wake), and may add reactive triggers that wake run() early when something the agent watches changes.

[[triggers]]
type = "schedule"
every = 60          # minutes between runs (whole number, minimum 1)
align = "rolling"   # "rolling" or "fixed"

[[triggers]]
type = "price"
venue = "hyperliquid"
coin = "ETH"            # must match the venue's price feed symbol exactly (case-sensitive)
condition = "pct_move"  # "cross" | "abs_move" | "pct_move"
threshold = "1%"        # absolute level for cross/abs_move; percent or bps for pct_move
debounce = "120s"       # optional: minimum spacing between wakes
maxFrequency = "5m"     # optional: hard cap; over budget the schedule still runs

[[triggers]]
type = "drawdown"
threshold = "5%"        # percent of peak equity ("5%", "250bps") or USD decline ("100")
debounce = "60s"

Schedule trigger fields:

Field	Type	Required	Description
`every`	number	Yes	Minutes between runs (whole number, minimum 1).
`align`	string	Yes	`"rolling"` starts the interval after the previous run completes. `"fixed"` aligns runs to clock boundaries (for example `:00`, `:15`, `:30`, `:45`) and requires `every` to divide evenly into 60.

Price trigger fields:

Field	Type	Required	Description
`venue`	string	Yes	`"hyperliquid"` or `"polymarket"`.
`coin`	string	Yes	Venue symbol, case-sensitive (for example `"ETH"`, `"kPEPE"`, `"xyz:GOLD"`). Upload fails on an unknown symbol and suggests the canonical casing.
`condition`	string	Yes	`"cross"` (price crosses an absolute level), `"abs_move"` (absolute move since last wake), or `"pct_move"` (percent move since last wake).
`threshold`	string	Yes	An absolute price for `cross`/`abs_move` (for example `"3000"`); a percent (`"0.5%"`) or basis points (`"50bps"`) for `pct_move`.
`debounce`	string	No	Minimum spacing between wakes (for example `"60s"`, `"5m"`).
`maxFrequency`	string	No	Hard cap on wake frequency; omit for no cap.
`mode`	string	No	Restrict the trigger to `"auto"` or `"manual"` sessions; defaults to `"any"`.

Drawdown trigger fields: A drawdown trigger is a session-level breaker: it wakes the agent the moment the session’s PnL falls a full band below its high-water mark, so de-risking doesn’t wait for the next scheduled run. PnL is flow-adjusted (net of deposits, withdrawals, and fees), so moving money in or out never reads as a loss. After a fire the mark re-anchors at the current PnL, so each further band down fires again (staged de-risking).

Field	Type	Required	Description
`threshold`	string	Yes	The drawdown band: a percent of peak equity (`"5%"`, `"250bps"`) or an absolute USD decline in PnL (`"100"`).
`debounce`	string	No	Minimum spacing between wakes (for example `"60s"`, `"5m"`).
`maxFrequency`	string	No	Hard cap on wake frequency; omit for no cap.
`mode`	string	No	Restrict the trigger to `"auto"` or `"manual"` sessions; defaults to `"any"`.

Inside run(), agent.trigger carries the wake cause so the agent can branch on why it woke. A drawdown wake carries pnlUsd, peakPnlUsd, drawdownUsd, and (when peak equity is positive) drawdownPct - display-tier hints; read live state to decide what to de-risk.

`[startingAsset]` Section

Defines the token a user must hold to start a session.

Field	Type	Required	Description
`network`	string	Yes	Network identifier (e.g., `"ethereum:1"`, `"solana"`, `"hypercore:perp"`)
`address`	string	Yes	Token contract address. For native tokens: `"0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"` (EVM) or `"11111111111111111111111111111111"` (Solana). For Hyperliquid perps: `"USDC"`.
`minimumAmount`	string	Yes	Minimum balance in raw units (wei, lamports, etc.). For `hypercore:perp` + `USDC`, use 8 decimal places (Circuit raw units; matches Hyperliquid USDC `weiDecimals`).

Common Configurations

EVM agent with ETH on mainnet:

walletVmFamily = "evm"

[startingAsset]
network = "ethereum:1"
address = "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
minimumAmount = "10000000000000000"  # 0.01 ETH

EVM agent with USDC on Polygon:

walletVmFamily = "evm"

[startingAsset]
network = "ethereum:137"
address = "0x2791bca1f2de4661ed88a30c99a7a9449aa84174"
minimumAmount = "10000000"  # 10 USDC (6 decimals)

Solana agent with SOL:

walletVmFamily = "svm"

[startingAsset]
network = "solana"
address = "11111111111111111111111111111111"
minimumAmount = "100000000"  # 0.1 SOL (9 decimals)

Hyperliquid perps agent:

walletVmFamily = "evm"

[startingAsset]
network = "hypercore:perp"
address = "USDC"
minimumAmount = "100000000"  # 1 USDC (8 decimals)

Agent Identity

Your agent’s identity is its agentId - a UUID that circuit new generates once and writes into circuit.toml. Every circuit upload replaces the runnable content for the agent with that id, so sessions and other state stay attached to it. You can rename the agent (name) or change its slug freely - because identity lives in agentId, renaming updates the same agent in place instead of forking a new one. Two rules the tooling enforces for you:

Never edit agentId. It’s the permanent link to your published agent; changing it points at (or creates) a different agent. To intentionally start a brand-new agent, run circuit new (which mints a fresh agentId).
slug is unique among your agents. circuit new derives it from the name and appends -2, -3, … if you already own that slug; circuit check fails (offline) if two agents in your workspace share an agentId or slug, so a copy-paste mistake can’t silently overwrite another agent on publish.

`[settings]` Section

Define configurable settings that users can customize when starting a session. Each setting is a TOML table under [settings.X] where X is the setting key. The display label is auto-derived from the key (snake_case to Title Case).

[settings.strategy]
description = "Which strategy the agent uses"
type = "single_select"
default = "conservative"
required = false
options = ["conservative", "aggressive"]

[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.auto_compound]
description = "Automatically reinvest rewards"
type = "boolean"
default = true
required = false

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

[settings.api_key]
type = "text"
required = true
description = "Your API key for the external service"

Required settings have no default value. Users must provide a value before the agent runs. The agent will refuse to execute if any required settings are missing.

Setting fields:

Field	Type	Required	Description
`description`	string	No	Help text shown to users (max 200 characters)
`type`	string	Yes	One of `"text"`, `"boolean"`, `"single_select"`, `"integer"`, `"number"`, `"percentage"`, `"address"`
`default`	varies	Conditional	Default value - must match the type (see below). Required when `required = false`; not allowed when `required = true`.
`required`	boolean	Yes	Whether users must provide a value. When `true`, no default is allowed; the agent will not run until a value is set.
`options`	string[]	Conditional	Required for `single_select`; not allowed for other types

Type rules:

Type	Default value	Options
`text`	String (max 1000 characters)	Not allowed
`boolean`	`true` or `false`	Not allowed
`single_select`	String matching one of the options	Required (max 20 options)
`integer`	Whole number	Not allowed
`number`	Any number (decimals allowed)	Not allowed
`percentage`	Number between 0 and 100 (decimals allowed)	Not allowed
`address`	Wallet address string (validated against `walletVmFamily`)	Not allowed

Limits:

Maximum 20 settings per agent
Maximum 20 options per single_select setting
Options must be unique within a setting
Setting keys must be unique across all settings
Setting keys cannot be numeric (e.g. 0, 3.14) - use a descriptive name instead
Default values for single_select must match a valid option

Settings are displayed to users in the order they appear in the file. Settings are snapshotted with each uploaded version - changing settings requires a new upload. At runtime, resolved setting values (defaults merged with session overrides) are available on AgentContext. See Settings SDK Reference for access patterns.

`[exchangeCredentials]` Section

Declare exchange credentials your agent needs. Circuit shows a credential picker when the user starts a session, then seats a runtime permit scoped to that selected credential. Read-only attachments receive wallet.read; trading attachments receive wallet.sign, which includes private reads. For trading credentials, Circuit also asks for the venue allocation. The selected credential belongs to the session; the exact venue allocation is an append-only session allocation fact. Neither appears in agent.settings. An agent version may currently declare one exchange venue, and each session attaches one credential for that venue.

[exchangeCredentials.kraken]
read = true
trade = true
minimumAllocationUsd = 25

Field	Type	Required	Description
`read`	boolean	No	Allows signed Kraken account reads such as balances and open orders. Defaults to `true`.
`trade`	boolean	No	Allows signed Kraken order/cancel calls. Defaults to `false`. Requires `read = true` for balance checks.
`minimumAllocationUsd`	number	Yes when `trade = true`	Minimum Kraken virtual funding allocation, in USD, that users must assign before the agent can start.

At runtime, private agent.platforms.kraken.* calls automatically use the credential selected for the session; its id and secret are not exposed to agent code. For trade = true agents, agent.allocation contains invocation-start available kraken:allocation:USD cash (the user-declared slice minus deployed and pending buys) plus positive base-asset inventory carrying krakenMetadata; size sells from its exact availableBaseVolume.

Notes

circuit.toml has no version field. Each circuit upload hashes the uploaded bundle and the backend assigns the version automatically - there is nothing to bump by hand.
Runtime asset files (data, configs) the agent reads ship automatically when they live inside the agent directory. To share code across agents, use a workspace package - see Multi-Agent Monorepo.
.circuit is reserved for CLI-managed staging during local runs. Do not store agent source files under .circuit.
allowedExecutionModes order matters - the first entry is the execution mode for circuit run commands that omit --mode. Embedded execution accepts only auto; --dry-run accepts manual but warns that approvals are not simulated.

Next Steps

Execution Model - How sessions and the run loop work
Multi-Agent Monorepo - share code across agents with workspace packages

Getting Started

Core Concepts

Examples

CLI Reference

SDK Reference

Advanced

Agent Structure & Configuration

Directory Structure

Agent Code

`run` Function

`unwind` Function

The plan: `DESCRIPTION.md`

circuit.toml

Full Example

Field Reference

Deployment Regions

`[[triggers]]` Section

`[startingAsset]` Section

Common Configurations

Agent Identity

`[settings]` Section

`[exchangeCredentials]` Section

Notes

Next Steps

​Directory Structure

​Agent Code

​run Function

​unwind Function

​The plan: DESCRIPTION.md

​circuit.toml

​Full Example

​Field Reference

​Deployment Regions

​[[triggers]] Section

​[startingAsset] Section

​Common Configurations

​Agent Identity

​[settings] Section

​[exchangeCredentials] Section

​Notes

​Next Steps

Directory Structure

Agent Code

`run` Function

`unwind` Function

The plan: `DESCRIPTION.md`

circuit.toml

Full Example

Field Reference

Deployment Regions

`[[triggers]]` Section

`[startingAsset]` Section

Common Configurations

Agent Identity

`[settings]` Section

`[exchangeCredentials]` Section

Notes

Next Steps