Agent Structure

Overview of what makes up the structure of an agent

An agent is a program that implements your custom run and unwind functions. The SDK does all of the heavy lifting exposing the necessary endpoints to the circuit infrastructure and setting the context needed for your agent's logic. All you need to do is define the logic within your run and unwind commands.

.circuit.toml

The .circuit.toml file defines the agent metadata, starting asset, and more.

Important: In TOML, all key-value pairs belong to the table header that precedes them. Top-level properties like filesToInclude and filesToExclude must be placed before any table headers (e.g., [benchmarkCurrency] or [[requiredAssets]]), otherwise they will be parsed as nested properties within that table section.

name = "My Agent"
slug = "my-agent"
description = "Agent description"
shortDescription = ""
defaultSleepIntervalMinutes = 15
allowedWalletTypes = ["ethereum", "solana"]
allowedExecutionModes = [ "manual"] # Accepts ["manual", "auto"]
devRunExecutionMode = "manual"
filesToInclude = []
filesToExclude = []

[benchmarkCurrency]
network = "fiat:usd"
address = ""

[[requiredAssets]]
network = "ethereum:1"
address = "0x0000000000000000000000000000000000000000"
minimumAmount = "10000000000000000"
devRunAmount = "10000000000000000"

Fields:

• name: Display name

• slug: URL-friendly identifier

• description: Useful information for your agent to be shared with the end user in the Circuit UI. This should include information for how your agent works. Use triple quotes if you need multi-line support

• shortDescription: Brief description of your agent to be displayed in agent cards on the UI.

• defaultSleepIntervalMinutes: Execution interval

• allowedWalletTypes: Supported wallet types

• allowedExecutionModes: An array of modes that the user is allowed to deploy your agent with, possible options are 'auto' and 'manual'

• devRunExecutionMode : The mode that will be used when creating a local dev session via

• filesToInclude: Specify any files outside of your agent's directory to be included in the files to upload to Circuit. See the Multi-Agent Monorepo section for more details on how to use this.

• filesToExclude: If you have any files in your agent directory that do not need to be uploaded to circuit, include those here.

• requiredAssets: Assets needed to run the agent (For now, only single asset use is supported)

  • minimumAmount: The user will need to at least have this much of your required asset to start a session.

  • devRunAmount: This will be the allocation amount that will be used for creating a session when using the CLI's circuit run and circuit unwind commands. Helpful for testing different allocation sizing scenarios.

  • network: See Network Identifiers

Basic Directory

TypeScript

<agent-name>/
├── index.ts              # Agent code (run/unwind functions)
├── package.json          # Dependencies
└── .circuit.toml         # Agent configuration

• index.ts - Main entrypoint for the agent

• .circuit.toml - Agent configuration and metadata

• package.json - Requirements

Python

Agent Code

TypeScript

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();

Python

Function Requirements

run Function

TypeScript

• Signature: async function run(agent: AgentContext): Promise<void>

• Called periodically based on defaultSleepIntervalMinutes

• Receives AgentContext with session data and SDK methods

• Returns void (no return value)

Python

unwind Function

TypeScript

• 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)

Python

Multi-Agent Monorepo

Learn how to organize multiple agents in a monorepo structure and share common utility code across them.

Overview

The Circuit CLI supports a monorepo structure that allows you to:

• Organize multiple agents in a single repository

• Share utility code across agents without duplicating files

• Maintain consistent imports across local development and deployed environments

• Selectively include only the utilities each agent needs

Important Note: Each agent's dependency file (pyproject.toml for Python, package.json for TypeScript) should include the dependencies for any shared utils being used.

Monorepo Structure

The recommended structure uses separate directories for agents and shared utilities:

Python

my-circuit-agents/
├── agents/
│   ├── sample-agent-1/
│   │   ├── main.py
│   │   ├── pyproject.toml
│   │   └── .circuit.toml
│   ├── sample-agent-2/
│   │   ├── main.py
│   │   ├── pyproject.toml
│   │   └── .circuit.toml
└── utils/
    ├── __init__.py
    ├── polymarket/
    │   ├── __init__.py
    │   └── trading.py
    ├── hyperliquid/
    │   ├── __init__.py
    │   └── positions.py
    └── analytics/
        ├── __init__.py
        └── metrics.py

TypeScript

Setting Up Shared Utilities

1. Create the Utils Package

Create a utils/ directory at your monorepo root with proper package structure:

Python

# From your monorepo root
mkdir -p utils/polymarket utils/hyperliquid utils/analytics
touch utils/__init__.py
touch utils/polymarket/__init__.py
touch utils/hyperliquid/__init__.py
touch utils/analytics/__init__.py

TypeScript

2. Export Functions in Module Index Files

Make your utility functions easily importable by exporting them:

Python

# utils/polymarket/__init__.py
from .trading import get_positions, place_order

__all__ = [
    "get_positions",
    "place_order",
]

TypeScript

3. Configure filesToInclude

In each agent's .circuit.toml, specify which shared directories to include:

# agents/trading-bot/.circuit.toml
name = "Trading Bot"
slug = "trading-bot"
# ... other config ...
# Include all shared utilities
filesToInclude = ["../../utils"]

# Or include only specific subdirectories
# filesToInclude = ["../../utils/polymarket", "../../utils/analytics"]

Note: The filesToInclude configuration works the same for both Python and TypeScript agents.

4. Configure Module Resolution

Set up module resolution to enable imports in local development:

Python

Add these 3 lines at the top of your agent's main.py:

import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))

# Now you can import shared utilities
from utils.polymarket import get_positions, place_order
from utils.analytics import calculate_sharpe_ratio

Why this is needed: When running locally, Python doesn't automatically know to look in parent directories. This snippet adds your monorepo root to Python's search path.

TypeScript

Import paths remain consistent regardless of what you include:

The deployment structure preserves the path hierarchy, so whether you include ../../utils or ../../utils/polymarket, the imports remain consistent.

Python

# Always works the same way
from utils.polymarket import get_positions

TypeScript

Next Steps

• Execution Model - How agents run

• Agent Context - Available SDK methods