Basic Agent - Circuit

Scaffold this example locally and test it with the CLI:

circuit new --name my-basic-agent --language python --template basic
cd my-basic-agent
circuit run    # execute a run cycle
circuit unwind # test the unwind logic

circuit.toml

circuit.toml

name = "Example Agent"
tagline = "A minimal Circuit agent"
category = "experimental"
imageUrl = "https://api.circuit.org/assets/agents/default"
walletVmFamily = "evm"
allowedExecutionModes = ["auto", "manual"]

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

[startingAsset]
network = "ethereum:1" # Ethereum Mainnet
address = "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" # Native ETH
minimumAmount = "0"

Example

from circuit_sdk import AgentContext


def run(agent: AgentContext) -> None:
    agent.log("Starting execution")

    # Memory example - persist a counter across run cycles
    run_count_memory = agent.memory.get("run-count")
    if run_count_memory.data and run_count_memory.data.value is not None:
        run_count = int(run_count_memory.data.value)
    else:
        run_count = 0
    run_count += 1

    agent.memory.set("run-count", str(run_count))
    agent.log(f"Session run count: {run_count}")


def unwind(agent: AgentContext) -> None:
    allocation = agent.allocation
    agent.log(f"Unwinding {len(allocation.balances)} balances")

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

export async function run(agent: AgentContext): Promise<void> {
  await agent.log("Starting execution");

  // Memory example - persist a counter across run cycles
  let runCount: number;
  const runCountMemory = await agent.memory.get("run-count");
  if (runCountMemory.success && runCountMemory.data) {
    runCount = parseInt(runCountMemory.data.value || "0", 10);
  } else {
    runCount = 0;
  }
  runCount += 1;

  await agent.memory.set("run-count", runCount.toString());
  await agent.log(`Session run count: ${runCount}`);
}

export async function unwind(agent: AgentContext): Promise<void> {
  const allocation = agent.allocation;
  await agent.log(`Unwinding ${allocation.balances.length} balances`);
}

Sample Output

Agent run started
Starting execution
Session run count: 1
Agent run completed

Agent unwind started
Unwinding 1 positions
Agent unwind completed

How It Works

Log: Logs a starting message
Read memory: Retrieves a persistent counter from agent memory
Increment & store: Bumps the counter and writes it back
Unwind: Logs the number of positions being unwound

Notes

This is the default template used by circuit new. It’s a good starting point for any agent.
Agent memory persists across run cycles - use it for counters, flags, or any state you need between executions.
See CLI + SDK Context for the full AgentContext API.

⌘I