TypeScript SDK

Use Circuit CLI to create and deploy agents using this SDK

Install the SDK

bun add @circuitorg/agent-sdk

Requires Bun ≥ 1.0 - npm and yarn will not work

`Agent` Constructor

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

Signature

new Agent({
  runFunction: (agent: AgentContext) => Promise<void>,
  stopFunction?: (agent: AgentContext) => Promise<void>
});

Parameters

Param

Type

Description

runFunction

(agent: AgentContext) ⇒ Promise<void>

The execution function that runs your agent's logic

stopFunction?

(agent: AgentContext) ⇒ Promise<void>

The cleanup function called when the agent stops.

Examples

import { Agent, type AgentContext } from "@circuitorg/agent-sdk";

async function run(agent: AgentContext): Promise<void> {
  await agent.log("Starting execution");
}

async function stop(agent: AgentContext): Promise<void> {
  await agent.log("Stopping execution");
}

const agent = new Agent({ 
  runFunction: run, 
  stopFunction: stop 
});

// For Circuit deployment
export default agent.getExport();

`AgentContext` Interface

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

Session Data

Property

Type

Description

agent.sessionId

string

Unique session identifier

agent.sessionWalletAddress

string

Wallet address for this session

agent.currentPositions

CurrentPosition[]

Positions allocated to agent at start of execution

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