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 unwind functions.

Signature

Agent(
  run_function: Callable[[AgentContext], None],
  unwind_function: Callable[[AgentContext, list[CurrentPosition]], 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
unwind_function?	Callable[[AgentContext, list[CurrentPosition]], None]	The cleanup function called when the agent unwinds
config?	AgentConfig	Agent configuration (title, description, version)

Examples

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

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

def unwind(agent: AgentContext, positions: list[CurrentPosition]) -> None:
    agent.log("Unwinding execution")

agent = Agent(
    run_function=run,
    unwind_function=unwind
    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 unwind_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)

Core Methods

Method	Description
agent.log()	Send messages to users and log locally
agent.sign_and_send()	Sign and broadcast blockchain transactions
agent.sign_message()	Sign messages (EVM only)

Namespace

Namespace	Description
agent.memory.*	Persist data across executions ( .set(), .get(), .list(), .delete() )
agent.swidge.*	Cross-chain swaps and bridges ( .quote(), .execute() )
agent.platforms.polymarket.*	Trade prediction markets ( .market_order(), .redeem_positions() )