Skip to main content
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://cdn.circuit.org/agents/default"
walletType = "ethereum"
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, VirtualAllocation


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, allocation: VirtualAllocation) -> None:
    agent.log(f"Unwinding {len(allocation.balances)} balances")



import type { AgentContext, VirtualAllocation } 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, allocation: VirtualAllocation): Promise<void> {
  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

  1. Log: Logs a starting message
  2. Read memory: Retrieves a persistent counter from agent memory
  3. Increment & store: Bumps the counter and writes it back
  4. 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.