Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.circuit.org/llms.txt

Use this file to discover all available pages before exploring further.

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 dev run    # execute a run cycle
circuit dev 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"]
runtimeIntervalMinutes = 15

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

​
Example

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


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.success and run_count_memory.data:
        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, positions: list[CurrentPosition]) -> None:
    agent.log(f"Unwinding {len(positions)} positions")


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

​
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.