Python SDK

Use Circuit CLI to create and deploy agents using this SDK

Install the SDK

# Using pip
pip install circuit-agent-sdk

# or using uv (recommended)
uv add circuit-agent-sdk

Requires Python ≥ 3.12. Works seamlessly with the Circuit CLI for local testing and publishing.

`Agent` Constructor

Create a Circuit Agent instance by passing in run and stop functions.

Signature

Agent(
  run_function: Callable[[AgentContext], None],
  stop_function: Callable[[AgentContext], None] | None = None,
  config: AgentConfig | None = None
)

class AgentConfig:
    title: str = "Circuit Agent"          # Agent display name
    description: str = "A Circuit Agent"  # Agent description
    version: str = "1.0.0"                # Agent version

Parameters

Param

Type

Description

run_function

Callable[[AgentContext], None]

The execution function that runs your agent's logic

stop_function?

Callable[[AgentContext], None]

The cleanup function called when the agent stops.

config?

AgentConfig

Agent configuration (title, description, version)

Examples

from agent_sdk import Agent, AgentContext, AgentConfig

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

def stop(agent: AgentContext) -> None:
    agent.log("Stopping execution")

agent = Agent(
    run_function=run,
    stop_function=stop
    config=AgentConfig(
        title="My Trading Bot",
        description="Automated ETH/USDC trading agent",
        version="2.1.0"
    )
)

# For local development
if __name__ == "__main__":
    agent.run()

# For Circuit deployment
handler = agent.get_handler()

`AgentContext` interface

Main interface for interacting with the Circuit platform. This object is passed to your run_function and stop_function and contains the following.

Session Data

Property

Type

Description

agent.sessionId

int

Unique session identifier

agent.sessionWalletAddress

str

Wallet address for this session

agent.currentPositions

list[CurrentPosition]

Positions allocated to agent at start of execution

class CurrentPosition:
    network: str            # e.g., "ethereum:1", "ethereum:137", "solana"
    assetAddress: str       # Token contract address
    tokenId: str | None     # For NFTs/ERC-1155, None for fungible tokens
    avgUnitCost: str        # Average cost per unit (as string for precision)
    currentQty: str         # Current quantity held (as string for precision)