Skip to main content

​
Directory Structure

<agent-name>/
├── main.py               # Agent code (run/unwind functions)
├── DESCRIPTION.md        # Agent description (shown in Circuit UI)
├── circuit.toml         # Agent configuration
└── pyproject.toml        # Dependencies

​
Agent Code

from agent_sdk import Agent, AgentContext
from agent_sdk.agent_context import CurrentPosition

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

def unwind(agent: AgentContext, positions: list[CurrentPosition]) -> None:
    agent.log(f"Unwind requested for {len(positions)} positions")
    # Optional unwind logic

agent = Agent(run_function=run, unwind_function=unwind)

handler = agent.get_handler()

if __name__ == "__main__":
    agent.run()

​
run Function

  • Signature: def run(agent: AgentContext) -> None:
  • Called periodically based on runtimeIntervalMinutes
  • Receives AgentContext with session data and SDK methods
  • Returns void (no return value)

​
unwind Function

  • Signature: def unwind(agent: AgentContext, positions: list[CurrentPosition]) -> None:
  • Called when you ask the agent to unwind positions
  • Optional unwind logic for the provided positions
  • Returns void (no return value)

​
DESCRIPTION.md

Every agent must include a DESCRIPTION.md file alongside circuit.toml. This Markdown file is displayed to users in the Circuit UI. 
## Summary

A brief description of what your agent does and the value it provides to users.

## Strategy

Explain the core logic and decision-making process your agent follows. Include details on which protocols it interacts with, what conditions trigger actions, and how it manages positions.

## Risks

Outline the key risks users should understand before starting a session. Consider market risk, smart contract risk, liquidity risk, and any other factors that could result in loss of funds.

## Changelog

- **0.0.1** — Initial release.

​
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

name = "My Agent"                        # max 32 characters
tagline = "Short subtitle for cards"     # max 32 characters
walletType = "ethereum"
allowedExecutionModes = ["manual", "auto"]
runtimeIntervalMinutes = 15
filesToInclude = []
filesToExclude = []
imageUrl = "https://cdn.circuit.org/agents/default"
version = "0.0.1"

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

​
Field Reference

FieldTypeRequiredDescription
namestringYesDisplay name shown in the Circuit UI (32 characters or less). Cannot be changed after first publish — see Agent Identity below.
taglinestringYesBrief subtitle shown on agent cards (32 characters or less)
walletTypestringYes"ethereum" or "solana"
allowedExecutionModesstring[]YesArray of "auto" and/or "manual". First entry is the default for circuit run.
runtimeIntervalMinutesnumberYesHow often run() is called (in minutes). Interval starts after previous run completes.
versionstringYesSemver version (major.minor.patch). Must be incremented before each circuit publish.
filesToIncludestring[]NoExtra files/directories to upload (for monorepo setups). Relative paths from agent directory.
filesToExcludestring[]NoFiles in agent directory to exclude from upload.
imageUrlstringNoAgent icon URL. Defaults to "https://cdn.circuit.org/agents/default".
deploymentRegionOverridestringNoOverride deployment region. Allowed values: "us-east-1" or "eu-central-1". Defaults to "us-east-1".

​
Deployment Regions

Allowed valuesDefault when omitted
us-east-1, eu-central-1us-east-1

​
[startingAsset] Section

Defines the token a user must hold to start a session.
FieldTypeRequiredDescription
networkstringYesNetwork identifier (e.g., "ethereum:1", "solana", "hypercore:perp")
addressstringYesToken contract address. For native tokens: "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" (EVM) or "11111111111111111111111111111111" (Solana). For Hyperliquid perps: "USDC".
minimumAmountstringYesMinimum 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: 
walletType = "ethereum"

[startingAsset]
network = "ethereum:1"
address = "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
minimumAmount = "10000000000000000"  # 0.01 ETH
EVM agent with USDC on Polygon: 
walletType = "ethereum"

[startingAsset]
network = "ethereum:137"
address = "0x2791bca1f2de4661ed88a30c99a7a9449aa84174"
minimumAmount = "10000000"  # 10 USDC (6 decimals)
Solana agent with SOL: 
walletType = "solana"

[startingAsset]
network = "solana"
address = "11111111111111111111111111111111"
minimumAmount = "100000000"  # 0.1 SOL (9 decimals)
Hyperliquid perps agent: 
walletType = "ethereum"

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

​
Agent Identity

Your agent’s identity on Circuit is derived from its name. Once you run circuit publish, the name is used to generate a permanent slug that links all future publishes, version history, sessions, and state to that agent. Changing the name after publishing will create a brand-new agent — the original agent and all its history will remain under the old name. If you need to rename a published agent, create a new agent with the desired name and re-publish. The old agent can be left as-is or removed from the dashboard.

​
Notes

  • The version field follows semver. You must increment it before each circuit publish — publishing will fail if the version is not greater than the previously published version.
  • filesToInclude paths are relative to the agent directory. Use ../../utils to include shared code from a monorepo root. See Multi-Agent Monorepo.
  • allowedExecutionModes order matters — the first entry is used as the execution mode when running locally with circuit run.

​
Next Steps