Execution Model

Agents execute by implementing run and unwind functions.

Execution Flow

1. Circuit infrastructure sends either a run or a unwind command to your agent

2. SDK receives the request and creates an AgentContext

3. SDK calls your run function with the AgentContext as the agent variable

4. Your code executes using SDK methods

5. SDK returns execution results to Circuit

6. (Manual Mode) If your agent operates in manual mode, all transactions will be submitted to the user to approve in the Circuit UI.

Modes

There are 2 modes that are available for agents to operate in: auto and manual. The agent developer will decide which modes are available to the user via the allowedExecutionModes property in the agent's .circuit.toml file. The selected executionMode will be available in the agent context.

• auto - Transactions are executed automatically

• manual - Transactions will be submitted for the user to approve on the circuit UI.

From the agent's perspective, there is no difference in submitting a request to either execute automatically, or suggest a transaction. Circuit's API will correctly execute a transaction or log a suggestion based on the session's selected execution mode. The only difference for the agent will be in the response data, which will include the below properties:

• suggested: bool

• suggestionId: int

Important: All suggested transactions will be soft deleted at the beginning of all agent run executions automatically. If you need a shorter expiry time than the sleep interval defined in the .circuit.toml file, you can set that when submitting the transaction with the expiresAt field.

Asset Allocation

Every agent execution starts with agent.currentPositions - the assets allocated to this session. This is the foundation for agent decision-making:

See the Agent Context session for more details on what is available in the agent's execution context

• Check what assets are available

• Decide what actions to take based on holdings

• Execute trades, swaps, or other operations

General pattern you should follow:

1. Read currentPositions to understand current holdings

2. Apply strategy logic to determine desired state

3. Use SDK methods (Swidge, platforms) to reach desired state

Run Function

The run function is called periodically for all active sessions based on the defined defaultSleepIntervalMinutes in .circuit.toml.

TypeScript

async function run(agent: AgentContext): Promise<void> {
  // Your logic here
}

Python

Unwind Function

The unwind function is called when a user unwinds the agent. It receives a list of positions to unwind, which may be a subset of the agent’s current positions.

TypeScript

async function unwind(agent: AgentContext, positions: CurrentPosition[]): Promise<void> {
  // Unwind logic for the provided positions
}

Python

Execution Interval

Set defaultSleepIntervalMinutes in .circuit.toml:

defaultSleepIntervalMinutes = 15

This determines how often run is called. The interval starts after the previous run completes.