Sessions and runs
A session ties one agent to one wallet and its virtual allocation. Circuit supplies a fresh AgentContext to eachrun or unwind invocation. Implement run(agent) for the strategy and unwind(agent) to close its positions or convert balances; SDK methods execute the operations. Use Memory to persist strings between invocations; session memory ends with the session.
Only one run executes per session. Start admits its initial run. Top-up commits allocation and another run atomically, even while paused or busy. Pausing preserves allocation, session and memory; an executing run may continue, while queued work waits. Resume clears pause and admits behind earlier queued work. Stop ends the session and queued work, releases its allocation, and admits an unwind attempting to close its historical positions. Account requirements inferred from the starting asset must be ready before agent code executes. Hosted execution requires runtime admission: Stop winning that admission race prevents execution, while an already-admitted run may continue.
Test runs the same public agent once with real funds, then automatically stops and admits an unwind on success or failure. Re-test creates a new session using the latest verified saved code. Test sessions have no triggers and cannot be paused, topped up or run again. The public start route accepts optional runOnce: true for hosted tests; omission starts a recurring session.
Every session pins its code hash, environment revision and setting definitions. Saving code affects new sessions; queued and executing runs keep their admitted revision. Setting overrides affect later admissions. Session details and run status report codeHash; null means no historical revision was recorded.
Triggers
Declare one or more triggers in circuit.toml. Schedules provide recurring wakes; reactive triggers wake on recorded events. SeteveryMs = 900000 and align = "rolling" for a fifteen-minute schedule.
Rolling schedules use the last run’s timestamp; fixed schedules align to clock boundaries (hourly at :00, or every fifteen minutes at :00, :15, :30, :45). Queued admission alone does not advance the rolling schedule. Every invocation receives a fixed agent.allocation; the next invocation gets a fresh snapshot.
Execution limits and failures
Five minutes without a Circuit call stops a run. SDK calls, including logging, reset the silence clock; reading the fixedagent.allocation, local sleep, hangs and computation do not. Return and continue on a later trigger when work requires a longer wait. The outer execution ceilings are two hours for run and fifteen minutes for unwind; queue waiting is excluded. Uncaught exceptions fail the execution and are logged automatically.
Each money operation has its own thirty-second lifecycle deadline. High-level SDK calls may sequence multiple operations, such as approval followed by a newly quoted swap; each is separately admitted, and failure stops the sequence without retrying. Earlier successful transactions remain recorded. Stopping cannot undo provider-accepted effects, and an operation timeout does not silently resume work later.
Multiple different agents can share a wallet; the same agent cannot have two active sessions on it. Hyperliquid agents share account-level liquidation risk because positions net at the account. Size autonomous work from session allocations, which coordinate budgets without creating separate custody or signing authority.