Skip to main content

​
Directory Structure

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

​
Agent Code

import { Agent, type AgentContext, type CurrentPosition } from "@circuitorg/agent-sdk";

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

async function unwind(agent: AgentContext, positions: CurrentPosition[]): Promise<void> {
  await agent.log(`Unwind requested for ${positions.length} positions`);
   // Optional unwind logic
}

const agent = new Agent({
  runFunction: run,
  unwindFunction: unwind
});

export default agent.getExport();

​
run Function

  • Signature: async function run(agent: AgentContext): Promise<void>
  • Called periodically based on runtimeIntervalMinutes
  • Receives AgentContext with session data and SDK methods
  • Returns void (no return value)

​
unwind Function

  • Signature: async function unwind(agent: AgentContext, positions: CurrentPosition[]): Promise<void>
  • Called when the agent is unwound
  • 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"
tagline = "Five-word subtitle goes here"
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)
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). Auto-bumped on circuit publish if not manually incremented.
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: "us-east-1" or "eu-central-1". If omitted, uses default.

​
[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, USDC with 6 decimals for Hyperliquid).

​
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 = "1000000"  # 1 USDC (6 decimals)

​
Notes

  • The version field follows semver. If you don’t increment it before circuit publish, the CLI auto-bumps the patch 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