npm - @circuitorg/agent-sdk - Versions diffs - 1.1.8 → 1.2.1 - Mend

@circuitorg/agent-sdk 1.1.8 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md CHANGED Viewed

@@ -1,30 +1,45 @@
-# Circuit Agent SDK - Typescript
+# Circuit Agent SDK - TypeScript
+> **Clean, unified, type-safe TypeScript SDK for building cross-chain agents on Circuit**
-A TypeScript SDK for building automated agents to deploy on Circuit. Features **2 low-level core methods** for maximum flexibility, plus **built-in platform integrations** for common on-chain operations—all with full type safety.
+A simplified TypeScript SDK for building automated agents to deploy on Circuit. Agents receive a single `AgentContext` object containing everything they need - request data, SDK methods, and unified logging. No boilerplate, no return values to manage, just write your logic.
 > **💡 Best used with [Circuit Agents CLI](https://github.com/circuitorg/agents-cli)** - Deploy, manage, and test your agents with ease
 ## 📑 Table of Contents
-- [Features](#-features)
-- [Quick Start](#-quick-start)
-- [Core SDK API](#-core-sdk-api-only-2-methods) - Low-level transaction & event logging methods
-- [Cross-Chain Swaps with Swidge](#-cross-chain-swaps-with-swidge) - Token swaps & bridges
-- [Polymarket Prediction Markets](#-polymarket-prediction-markets) - Trading integration
-- [Session Memory Storage](#-session-memory-storage) - State management
-- [Examples](#-examples)
-## ✨ Features
-- **🎯 Low-Level Core API**: 2 foundational methods (`sendLog()`, `signAndSend()`) for sending custom transactions
-- **🔒 Type Safety**: Network parameter determines valid request shapes automatically
-- **🚀 Cross-Chain**: Unified interface for EVM and Solana networks
-- **🌉 Cross-Chain Swaps**: Built-in Swidge integration for seamless token swaps and bridges
-- **📈 Polymarket Integration**: Trade prediction markets with `sdk.polymarket.*` methods
-- **💾 Session Memory**: Key-value storage with `sdk.memory.*` methods for maintaining state
+- [Circuit Agent SDK - TypeScript](#circuit-agent-sdk---typescript)
+  - [📑 Table of Contents](#-table-of-contents)
+  - [🚀 Quick Start](#-quick-start)
+    - [Install the SDK](#install-the-sdk)
+    - [Create Your First Agent](#create-your-first-agent)
+  - [🎯 Core Concepts](#-core-concepts)
+    - [The AgentContext Object](#the-agentcontext-object)
+    - [Run/Stop Function Requirements](#runstop-function-requirements)
+  - [📝 Unified Logging with agent.log()](#-unified-logging-with-agentlog)
+  - [💾 Session Memory Storage](#-session-memory-storage)
+  - [🌉 Cross-Chain Swaps with Swidge](#-cross-chain-swaps-with-swidge)
+    - [Get and execute a quote](#get-and-execute-a-quote)
+  - [📈 Polymarket Prediction Markets](#-polymarket-prediction-markets)
+    - [Place Market Orders](#place-market-orders)
+    - [Redeem Positions](#redeem-positions)
+  - [🚀 Sign \& Send Transactions](#-sign--send-transactions)
+    - [Ethereum (any EVM chain)](#ethereum-any-evm-chain)
+    - [Solana](#solana)
+  - [⚡ Error Handling](#-error-handling)
+  - [🛠️ Deployment](#️-deployment)
+    - [What You Write](#what-you-write)
+    - [Deploy to Circuit](#deploy-to-circuit)
+    - [Test Locally](#test-locally)
+  - [🧪 Manual Instantiation (Testing)](#-manual-instantiation-testing)
+  - [📚 Working Examples](#-working-examples)
+    - [`demo-agent.ts`](#demo-agentts)
+    - [`examples/kitchen-sink.ts`](#exampleskitchen-sinkts)
+  - [🎯 Key Takeaways](#-key-takeaways)
+  - [📖 Additional Resources](#-additional-resources)
 ## 🚀 Quick Start
 ### Install the SDK
 ```bash
 npm install @circuitorg/agent-sdk
@@ -34,771 +49,448 @@ yarn add @circuitorg/agent-sdk
 bun add @circuitorg/agent-sdk
 ```
-### Sample SDK Usage
->**NOTE:** The fastest, and recommended, way to get started is to setup an agent via the circuit [CLI](https://github.com/circuitorg/agents-cli)'s 'circuit agent init' command. This will setup a sample agent directory with the necessary agent wireframe, and configure the cli to allow you for easy testing and deployment. You just simply need to add in your secret formula to the execution and stop functions.
+### Create Your First Agent
-```typescript
-import { AgentSdk } from "@circuitorg/agent-sdk";
+Every agent receives a single `AgentContext` object that provides:
-// Initialize the sdk
-const sdk = new AgentSdk({
-  sessionId: 123,
-});
-```
-## 🎯 Core SDK API (Only 2 Methods!)
+**Session Data:**
+- `agent.sessionId` - Unique session identifier
+- `agent.sessionWalletAddress` - The wallet address for this session
+- `agent.currentPositions` - Assets allocated to the agent at the start of this execution
-> **Low-level building blocks** for direct blockchain interaction. Use these for maximum flexibility, or leverage our higher-level integrations (Swidge, Polymarket, Memory) for common operations.
+**Available Methods:**
+- `agent.log()` - Send messages to users and log locally
+- `agent.memory` - Persist data across executions (`.set()`, `.get()`, `.list()`, `.delete()`)
+- `agent.platforms.polymarket` - Trade prediction markets (`.marketOrder()`, `.redeemPositions()`)
+- `agent.swidge` - Cross-chain swaps and bridges (`.quote()`, `.execute()`)
+- `agent.signAndSend()` - Execute custom built transactions on any supported chain
+- `agent.signMessage()` - Sign messages (EVM only)
-### 1. Add Logs to Timeline
+**Important:** `currentPositions` reflects your allocated assets at the **start** of each execution. To avoid failed transactions, you should be tracking intra-run position changes based on transactions the agent makes during the execution. Circuit will provide updated positions on the next execution request.
 ```typescript
-await sdk.sendLog({
-  type: "observe",
-  shortMessage: "Starting swap operation"
-});
-```
-### 2. Sign & Send Transactions
+import { Agent, AgentContext } from "@circuitorg/agent-sdk";
+async function run(agent: AgentContext): Promise<void> {
+  /**
+   * Main agent logic - receives AgentContext with everything needed.
+   * No return value - errors are caught automatically.
+   */
+  // Access session data
+  await agent.log(`Starting execution for session ${agent.sessionId}`);
+  await agent.log(`Wallet: ${agent.sessionWalletAddress}`);
+  await agent.log(`Managing ${agent.currentPositions.length} allocated positions`);
+  // Use SDK methods
+  await agent.memory.set("last_run", Date.now().toString());
+  // Your agent logic here - track position changes within this execution
+  // Circuit will provide updated positions on the next run
+}
-#### Ethereum (any EVM chain)
+async function stop(agent: AgentContext): Promise<void> {
+  /**Cleanup when agent is stopped.*/
+  await agent.log("Cleaning up resources");
+  await agent.memory.delete("temp_data");
+}
-```typescript
-// Native ETH transfer
-await sdk.signAndSend({
-  network: "ethereum:1", // Chain ID in network string
-  request: {
-    toAddress: "0x742d35cc6634C0532925a3b8D65e95f32B6b5582" as `0x${string}`,
-    data: "0x" as `0x${string}`,
-    value: "1000000000000000000" // 1 ETH in wei
-  },
-  message: "Sending 1 ETH"
+// Boilerplate - This should never change unless you want to change the names of your run and stop functions
+const agent = new Agent({
+  runFunction: run,
+  stopFunction: stop
 });
-// Contract interaction
-await sdk.signAndSend({
-  network: "ethereum:42161", // Arbitrum
-  request: {
-    toAddress: "0xTokenContract..." as `0x${string}`,
-    data: "0xa9059cbb..." as `0x${string}`, // encoded transfer()
-    value: "0"
-  }
-});
+export default agent.getExport();
 ```
-#### Solana
+## 🎯 Core Concepts
-```typescript
-await sdk.signAndSend({
-  network: "solana",
-  request: {
-    hexTransaction: "010001030a0b..." // serialized VersionedTransaction
-  }
-});
-```
+### The AgentContext Object
+Every agent function receives a single `AgentContext` object that contains:
+**Request Data:**
+- `agent.sessionId` - Unique session identifier
+- `agent.sessionWalletAddress` - Wallet address for this session
+- `agent.currentPositions` - Current positions allocated to this agent
-## 🌉 Cross-Chain Swaps and Bridging with Swidge
+**SDK Methods:**
+- `agent.log()` - Unified logging (console + backend)
+- `agent.memory` - Session-scoped key-value storage
+- `agent.platforms.polymarket` - Prediction market operations
+- `agent.swidge` - Cross-chain swap operations
+- `agent.signAndSend()` - Sign and broadcast transactions
+- `agent.signMessage()` - Sign messages on EVM
-> **High-level abstraction** built on core SDK methods. Simplifies cross-chain token operations with a quote-and-execute pattern.
+### Run/Stop Function Requirements
-The SDK includes built-in Swidge integration for seamless cross-chain token swaps and bridges. Swidge provides a unified interface that handles both **swapping** (exchanging tokens within the same network) and **bridging** (moving tokens across different networks) through a single API. Whether you're doing a simple token swap on Ethereum or bridging assets across chains, the same pattern works for everything.
+1. **Signature**: `async function myFunction(agent: AgentContext): Promise<void>`
+2. **Return**: Always return `void` (or no return statement)
+3. **Errors**: You should surface any relevant errors via `agent.log('error message', { error: true })`. All errors from built-in SDK functions will be caught gracefully and provided in the return data for you to handle as necessary.
-### Cross-Chain Swaps & Bridges
+## 📝 Unified Logging with agent.log()
-#### Get a Quote
+Use `agent.log()` to communicate with your users and debug your agent. Every message appears in your terminal, and by default also shows up in the Circuit UI for your users to see. Simply pass `debug: true` to skip sending the message to the user.
 ```typescript
-// 🌉 Bridge USDC: Polygon → Arbitrum
-const bridgeQuote = await sdk.swidge.quote({
-  from: { network: "ethereum:137", address: request.sessionWalletAddress },
-  to: { network: "ethereum:42161", address: request.sessionWalletAddress },
-  amount: "50000000", // $50 USDC (6 decimals)
-  fromToken: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174", // USDC on Polygon
-  toToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",   // USDC on Arbitrum
-  slippage: "2.0", // 2% slippage for cross-chain (default: 0.5%)
-  priceImpact: "1.0" // 1% max price impact (default: 0.5%)
-});
+async function run(agent: AgentContext): Promise<void> {
+  // Standard log: Shows to user in Circuit UI
+  await agent.log("Processing transaction");
+  // Error log: Shows to user in Circuit UI (as an error)
+  const result = await agent.memory.get("key");
+  if (!result.success) {
+    await agent.log(result.error_message || result.error, { error: true });
+  }
-// 🔄 Swap USDC → ETH on same chain (using defaults)
-const swapQuote = await sdk.swidge.quote({
-  from: { network: "ethereum:42161", address: request.sessionWalletAddress },
-  to: { network: "ethereum:42161", address: request.sessionWalletAddress },
-  amount: "100000000", // $100 USDC (6 decimals)
-  fromToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // USDC
-  // toToken omitted = native ETH (default behavior)
-  // slippage defaults to "0.5", priceImpact defaults to "0.5"
-});
+  // Debug log: Only you see this in your terminal
+  await agent.log("Internal state: processing...", { debug: true });
-if (quote.success) {
-  console.log(`💰 You'll receive: ${quote.data.assetReceive.amountFormatted}`);
-  console.log(`💸 Total fees: ${quote.data.fees.map(f => f.name).join(", ")}`);
-} else if (quote.error) {
-  // Check for specific error types
-  if (quote.error === QUOTE_RESULT.WALLET_NOT_FOUND) {
-    console.log("👛 Wallet not found");
-  } else if (quote.error === QUOTE_RESULT.WALLET_MISMATCH) {
-    console.log("🔐 Wallet address doesn't match session");
-  } else {
-    console.log("❓ Quote not available for this swap");
+  // Logging objects
+  // Objects are pretty-printed to console and serialized/truncated for backend
+  await agent.log({ wallet: agent.sessionWalletAddress, status: "active" });
+  // Check if message reached the user
+  const logResult = await agent.log("Important message");
+  if (!logResult.success) {
+    // Rare - usually means Circuit UI is unreachable
   }
 }
 ```
-#### Execute a Swap
+**What Your Users See:**
-```typescript
-// 1️⃣ Get a quote first
-let quoteRequest = {
-  from: { network: "ethereum:42161", address: request.sessionWalletAddress },
-  to: { network: "ethereum:1", address: request.sessionWalletAddress },
-  amount: "100000000", // $100 USDC
-  fromToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // USDC on Arbitrum
-  priceImpact: "0.1", // Conservative price impact setting
-  slippage: "5.0"
-};
+| Code | You See (Terminal) | User Sees (Circuit UI) |
+|------|-------------------|----------------------|
+| `agent.log("msg")` | ✅ In your terminal | ✅ In Circuit UI |
+| `agent.log("msg", { error: true })` | ✅ As error in terminal | ✅ As error in Circuit UI |
+| `agent.log("msg", { debug: true })` | ✅ In terminal | ❌ Hidden from user |
+| `agent.log("msg", { error: true, debug: true })` | ✅ As error in terminal | ❌ Hidden from user |
-let quote = await sdk.swidge.quote(quoteRequest);
+## 💾 Session Memory Storage
-// 2️⃣ Handle quote failures with retry logic
-if (quote.error === QUOTE_RESULT.NO_QUOTE_PROVIDED) {
-  console.log(`❓ Quote not available, increasing price impact and retrying...`)
-  // Retry with more permissive parameters
-  quoteRequest.priceImpact = "10.0";
-  quoteRequest.slippage = "10.0";
-  quote = await sdk.swidge.quote(quoteRequest);
-}
+Store and retrieve data for your agent's session with simple operations. Memory is **automatically scoped to your session ID**, and for now is simple string storage. You will need to handle serialization of whatever data you want to store here.
-// 3️⃣ Execute the swap if quote succeeded
-if (quote.success && quote.data) {
-  console.log(`💰 Expected to receive: ${quote.data.assetReceive.amountFormatted}`);
-  console.log(`💸 Fees: ${quote.data.fees.map(f => `${f.name}: ${f.amountFormatted}`).join(", ")}`);
-  const result = await sdk.swidge.execute(quote.data);
-  if (result.success && result.data) {
-    console.log(`🎉 Status: ${result.data.status}`);
-    if (result.data.status === "success") {
-      console.log(`📤 Sent: ${result.data.in.txs[0]}`);
-      console.log(`📥 Received: ${result.data.out.txs[0]}`);
-      console.log("✅ Cross-chain swap completed!");
-    } else if (result.data.status === "failure") {
-      console.log("❌ Transaction failed");
-    } else if (result.data.status === "refund") {
-      console.log("↩️ Transaction was refunded");
-    } else if (result.data.status === "delayed") {
-      console.log("⏰ Transaction is delayed");
-    }
+```typescript
+async function run(agent: AgentContext): Promise<void> {
+  // Set a value
+  const result = await agent.memory.set("lastSwapNetwork", "ethereum:42161");
+  if (!result.success) {
+    await agent.log(result.error_message || result.error, { error: true });
+  }
+  // Get a value
+  const getResult = await agent.memory.get("lastSwapNetwork");
+  if (getResult.success && getResult.data) {
+    const network = getResult.data.value;
+    await agent.log(`Using network: ${network}`);
   } else {
-    console.log(`❌ Execute failed: ${result.error}`);
+    await agent.log("No saved network found");
+  }
+  // List all keys
+  const listResult = await agent.memory.list();
+  if (listResult.success && listResult.data) {
+    await agent.log(`Found ${listResult.data.count} keys: ${listResult.data.keys}`);
   }
-} else {
-  console.log(`❌ Quote failed after retry: ${quote.error}`);
-  return { success: false };
+  // Delete a key
+  await agent.memory.delete("tempData");
 }
 ```
-## 📈 Polymarket Prediction Markets
-> **High-level abstraction** built on core SDK methods. Simplifies prediction market trading on Polygon.
+**All memory operations return responses with `.success` and `.error_message`:**
-> **Note:** Due to polymarket accepting buys and sells with different decimal precision, you may end up with dust positions when trying to sell to close out a position.
+```typescript
+const result = await agent.memory.set("key", "value");
+if (!result.success) {
+  await agent.log(`Failed to save: ${result.error_message}`, { error: true });
+}
+```
+## 🌉 Cross-Chain Swaps with Swidge
-The SDK includes built-in Polymarket integration for trading prediction markets on Polygon.
+Built-in Swidge integration for seamless cross-chain token swaps and bridges.
-### Polymarket Trading
+### Get and execute a quote
+> Note: It is important to always validate quotes before executing. Circuit will always do its best to return a quote, and as of now, will only filter out quotes with price impacts exceeding 100% to ensure maximum flexibility. It is on the agent to makes sure a quote is valid, given its own parameters
-#### Get Positions
+```typescript
+async function run(agent: AgentContext): Promise<void> {
+  // 1. Get quote
+  const quote = await agent.swidge.quote({
+    from: { network: "ethereum:8453", address: agent.sessionWalletAddress },
+    to: { network: "ethereum:137", address: agent.sessionWalletAddress },
+    amount: "1000000000000000",  // 0.001 ETH
+    toToken: "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
+    slippage: "2.0",
+  });
-Fetch all current positions for the session wallet:
+  if (!quote.success) {
+    await agent.log(`Quote failed: ${quote.error_message}`, { error: true });
+    return;
+  }
-```typescript
-const positions = await sdk.polymarket.positions();
-if (positions.success && positions.data) {
-  console.log(`Total value: $${positions.data.totalValue}`);
-  for (const position of positions.data.positions) {
-    console.log(`${position.question} (${position.outcome})`);
-    console.log(`  Shares: ${position.formattedShares}`);
-    console.log(`  Value: $${position.valueUsd}`);
-    console.log(`  P&L: $${position.pnlUsd} (${position.pnlPercent}%)`);
+  if (quote.data && Math.abs(parseFloat(quote.data.priceImpact.percentage)) > 10) {
+    await agent.log(`Warning: Price impact is too high: ${quote.data.priceImpact.percentage}%`, { error: true, debug: true });
+  } else if (quote.data) {
+    await agent.log(`You'll receive: ${quote.data.assetReceive.amountFormatted}`);
+    await agent.log(`Fees: ${quote.data.fees.map(f => f.name).join(', ')}`);
+    // 2. Execute the swap
+    const result = await agent.swidge.execute(quote.data);
+    if (result.success && result.data) {
+      await agent.log(`Swap status: ${result.data.status}`);
+      if (result.data.status === "success") {
+        await agent.log("✅ Swap completed!");
+        await agent.log(`In tx: ${result.data.in.txs}`);
+        await agent.log(`Out tx: ${result.data.out.txs}`);
+      } else if (result.data.status === "failure") {
+        await agent.log("❌ Swap failed", { error: true });
+      }
+    } else {
+      await agent.log(result.error_message || result.error, { error: true });
+    }
   }
 }
 ```
-#### Place Market Orders
+## 📈 Polymarket Prediction Markets
+Trade prediction markets on Polygon.
-Execute buy or sell market orders:
+### Place Market Orders
+> Note: Right now, polymarket's API accepts different decimal precision for buys and sells, this will result in dust positions if you are selling out of a position before expiry. Once expired, dust can be cleaned up during the redeem step.
 ```typescript
-// Buy order - size is USD amount to spend
-const buyOrder = await sdk.polymarket.marketOrder({
-  tokenId: "123456789...",  // Market token ID
-  size: 10,                  // Spend $10 to buy shares
-  side: "BUY"
-});
+async function run(agent: AgentContext): Promise<void> {
+  // Buy order - size is USD amount to spend
+  const buyOrder = await agent.platforms.polymarket.marketOrder({
+    tokenId: "86192057611122246511563653509192966169513312957180910360241289053249649036697",
+    size: 3,  // Spend $3
+    side: "BUY"
+  });
-// Sell order - size is number of shares to sell
-const sellOrder = await sdk.polymarket.marketOrder({
-  tokenId: "123456789...",
-  size: 5.5,                 // Sell 5.5 shares
-  side: "SELL"
-});
+  if (buyOrder.success && buyOrder.data) {
+    await agent.log(`Order ID: ${buyOrder.data.orderInfo.orderId}`);
+    await agent.log(`Price: $${buyOrder.data.orderInfo.priceUsd}`);
+    await agent.log(`Total: $${buyOrder.data.orderInfo.totalPriceUsd}`);
+  } else {
+    await agent.log(buyOrder.error_message || buyOrder.error, { error: true });
+  }
-if (buyOrder.success && buyOrder.data) {
-  console.log(`Order Success: ${buyOrder.data.success}`);
-  console.log(`Order ID: ${buyOrder.data.orderInfo.orderId}`);
-  console.log(`Filled at $${buyOrder.data.orderInfo.priceUsd} per share`);
-  console.log(`Total cost: $${buyOrder.data.orderInfo.totalPriceUsd}`);
+  // Sell order - size is number of shares to sell
+  const sellOrder = await agent.platforms.polymarket.marketOrder({
+    tokenId: "86192057611122246511563653509192966169513312957180910360241289053249649036697",
+    size: 5.5,  // Sell 5.5 shares
+    side: "SELL"
+  });
 }
 ```
-#### Redeem Positions
-Claim winnings from settled positions:
+### Redeem Positions
 ```typescript
-// Redeem all redeemable positions
-const redemption = await sdk.polymarket.redeemPositions();
-if (redemption.success && redemption.data) {
-  for (const result of redemption.data) {
-    if (result.success) {
-      if (result.position) {
-        console.log(`✅ Redeemed: ${result.position.question}`);
-      } else {
-        console.log(`✅ Unwrapped collateral`);
-      }
-      console.log(`   TX: ${result.transactionHash}`);
-    }
+async function stop(agent: AgentContext): Promise<void> {
+  /**Redeem all settled positions.*/
+  const redemption = await agent.platforms.polymarket.redeemPositions();
+  if (redemption.success && redemption.data) {
+    const successful = redemption.data.filter(r => r.success);
+    await agent.log(`Redeemed ${successful.length} positions`);
+  } else {
+    await agent.log(redemption.error_message || redemption.error, { error: true });
   }
 }
-// Redeem specific positions by token IDs
-const specificRedemption = await sdk.polymarket.redeemPositions({
-  tokenIds: ["123456", "789012"]
-});
 ```
-### Complete Polymarket Example
+## 🚀 Sign & Send Transactions
+### Ethereum (any EVM chain)
 ```typescript
-const executionFunction: ExecutionFunctionContract = async (request) => {
-  const sdk = new AgentSdk({ sessionId: request.sessionId });
-  try {
-    // Get current positions
-    const positions = await sdk.polymarket.positions();
-    if (!positions.success || !positions.data) {
-      throw new Error(`Failed to get positions: ${positions.error}`);
-    }
+async function run(agent: AgentContext): Promise<void> {
+  // Self-send demo - send a small amount to yourself
+  const response = await agent.signAndSend({
+    network: "ethereum:1",
+    request: {
+      toAddress: agent.sessionWalletAddress,  // Send to self
+      data: "0x",
+      value: "100000000000000"  // 0.0001 ETH
+    },
+    message: "Self-send demo"
+  });
-    // Find specific position
-    const targetPosition = positions.data.positions.find(
-      p => p.tokenId === "YOUR_TOKEN_ID"
-    );
-    if (targetPosition && Number(targetPosition.formattedShares) > 0) {
-      // Sell position
-      const sellOrder = await sdk.polymarket.marketOrder({
-        tokenId: targetPosition.tokenId,
-        size: Number(targetPosition.formattedShares),
-        side: "SELL"
-      });
-      if (sellOrder.success && sellOrder.data?.orderInfo) {
-        await sdk.sendLog({
-          type: "observe",
-          shortMessage: `Sold ${targetPosition.outcome} for $${sellOrder.data.orderInfo.totalPriceUsd}`
-        });
-      }
+  if (response.success) {
+    await agent.log(`Transaction sent: ${response.txHash}`);
+    if (response.transactionUrl) {
+      await agent.log(`View: ${response.transactionUrl}`);
     }
-    return { success: true };
-  } catch (error) {
-    await sdk.sendLog({
-      type: "error",
-      shortMessage: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`
-    });
-    return { success: false, error: error instanceof Error ? error.message : "Unknown error" };
+  } else {
+    await agent.log(response.error_message || response.error, { error: true });
   }
-};
-const stopFunction: StopFunctionContract = async (request) => {
-  const sdk = new AgentSdk({ sessionId: request.sessionId });
+}
+```
-  try {
-    // Redeem all settled positions on stop
-    const redemption = await sdk.polymarket.redeemPositions();
+### Solana
-    if (redemption.success && redemption.data) {
-      const successful = redemption.data.filter(r => r.success);
-      await sdk.sendLog({
-        type: "observe",
-        shortMessage: `✅ Redeemed ${successful.length} positions`
-      });
+```typescript
+async function run(agent: AgentContext): Promise<void> {
+  const response = await agent.signAndSend({
+    network: "solana",
+    request: {
+      hexTransaction: "010001030a0b..."  // serialized VersionedTransaction
     }
+  });
-    return { success: true };
-  } catch (error) {
-    return { success: false, error: error instanceof Error ? error.message : "Unknown error" };
+  if (response.success) {
+    await agent.log(`Transaction: ${response.txHash}`);
+  } else {
+    await agent.log(response.error_message || response.error, { error: true });
   }
-};
+}
 ```
-## 💾 Session Memory Storage
+## ⚡ Error Handling
-> **High-level abstraction** built on core SDK methods. Provides key-value storage for maintaining state across execution cycles without external databases.
+**All SDK methods return response objects with `.success` and `.error_message`:**
-Store and retrieve data for your agent's session with simple get/set/delete/list operations. Memory is **automatically scoped to your session ID** - each session has isolated storage that persists across execution cycles.
-### Memory Operations
+**Uncaught Exceptions:**
-#### Set a Value
+If your function throws an uncaught exception, the Agent SDK automatically:
+1. Logs the error to console (visible in local dev and cloud logs)
+2. Updates the job in the circuit backend with status='failed' and logs the error.
 ```typescript
-// Store user preferences
-const result = await sdk.memory.set("lastSwapNetwork", "ethereum:42161");
+async function run(agent: AgentContext): Promise<void> {
+  // This typo will be caught and logged automatically
+  await agent.memmory.set("key", "value");  // TypeError
-if (result.success && result.data) {
-  console.log(`Stored key: ${result.data.key}`);
-} else {
-  console.error(`Failed to store: ${result.error}`);
+  // No need for try/catch around everything!
 }
 ```
-#### Get a Value
-```typescript
-// Retrieve stored preferences
-const result = await sdk.memory.get("lastSwapNetwork");
+## 🛠️ Deployment
-if (result.success && result.data) {
-  console.log(`Network: ${result.data.value}`);
-} else {
-  console.log(`Key not found: ${result.error}`);
-}
-```
+### What You Write
-#### Delete a Value
+Your agent code should look like this - just define your functions and add the boilerplate at the bottom:
 ```typescript
-// Clean up temporary data
-const result = await sdk.memory.delete("tempSwapQuote");
+import { Agent, AgentContext } from "@circuitorg/agent-sdk";
-if (result.success && result.data) {
-  console.log(`Deleted key: ${result.data.key}`);
+async function run(agent: AgentContext): Promise<void> {
+  await agent.log("Hello from my agent!");
+  // Your agent logic here
 }
-```
-#### List All Keys
-```typescript
-// List all stored keys
-const result = await sdk.memory.list();
-if (result.success && result.data) {
-  console.log(`Found ${result.data.count} keys:`);
-  result.data.keys.forEach(key => console.log(`  - ${key}`));
+async function stop(agent: AgentContext): Promise<void> {
+  await agent.log("Cleaning up...");
+  // Optional cleanup logic
 }
-```
-### Complete Memory Example
-```typescript
-const executionFunction: ExecutionFunctionContract = async (request) => {
-  const sdk = new AgentSdk({ sessionId: request.sessionId });
-  try {
-    // Check if this is a first run by looking for a stored counter
-    const counterResult = await sdk.memory.get("executionCount");
-    let count = 0;
-    if (counterResult.success && counterResult.data) {
-      count = parseInt(counterResult.data.value);
-      await sdk.sendLog({
-        type: "observe",
-        shortMessage: `Execution #${count + 1} - Welcome back!`
-      });
-    } else {
-      await sdk.sendLog({
-        type: "observe",
-        shortMessage: "First execution - initializing..."
-      });
-    }
-    // Store some session data
-    await sdk.memory.set("executionCount", String(count + 1));
-    await sdk.memory.set("lastRunTimestamp", Date.now().toString());
-    await sdk.memory.set("userPreferences", JSON.stringify({
-      network: "ethereum:42161",
-      slippage: "2.0"
-    }));
-    // List all stored keys
-    const listResult = await sdk.memory.list();
-    if (listResult.success && listResult.data) {
-      await sdk.sendLog({
-        type: "observe",
-        shortMessage: `Stored ${listResult.data.count} keys: ${listResult.data.keys.join(", ")}`
-      });
-    }
-    return { success: true };
-  } catch (error) {
-    await sdk.sendLog({
-      type: "error",
-      shortMessage: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`
-    });
-    return { success: false, error: error instanceof Error ? error.message : "Unknown error" };
-  }
-};
-const stopFunction: StopFunctionContract = async (request) => {
-  const sdk = new AgentSdk({ sessionId: request.sessionId });
-  try {
-    // Clean up temporary data on stop
-    const listResult = await sdk.memory.list();
-    if (listResult.success && listResult.data) {
-      // Delete all temp keys
-      for (const key of listResult.data.keys) {
-        if (key.startsWith("temp_")) {
-          await sdk.memory.delete(key);
-        }
-      }
-    }
+// ============================================================================
+// BOILERPLATE - Don't modify, this handles local testing AND Circuit deployment
+// ============================================================================
+const agent = new Agent({
+  runFunction: run,
+  stopFunction: stop
+});
-    return { success: true };
-  } catch (error) {
-    return { success: false, error: error instanceof Error ? error.message : "Unknown error" };
-  }
-};
+export default agent.getExport();
 ```
+That's it! The boilerplate code automatically handles the rest
-## 🔧 Examples
-### Barebones Agent
->This is the wireframe structure all agents need to have (executionFunction, stopFunction, and export default agent.getWorkerExport()). The main thing an agent dev needs to focus on is the execution logic, and any cleanup logic that would need to be ran whenever a user decides to stop an agent session.
+### Deploy to Circuit
-```typescript
-import { Agent, AgentSdk, ExecutionFunctionContract, StopFunctionContract } from "@circuitorg/agent-sdk";
-// Agent execution function using the new AgentSdk v1.0 API
-const executionFunction: ExecutionFunctionContract = async (request) => {
-  console.log(`🚀 Agent execution called for session ${request.sessionId}`);
-  const sdk = new AgentSdk({
-    sessionId: request.sessionId,
-  });
-  try {
-    // Get user's wallet address (use vitalik.eth for demo if no address provided)
-    const userAddress = request.sessionWalletAddress
-    await sdk.sendLog({
-      type: "observe",
-      shortMessage: `🚀 Agent SDK v1.0 demo - Hello ${userAddress}`
-    });
-    return { success: true};
-  } catch (error) {
-    await sdk.sendLog({
-      type: "error",
-      shortMessage: `Agent execution error: ${error instanceof Error ? error.message : 'Unknown error'}`
-    });
-    return { success: false, error: error instanceof Error ? error.message : "Unknown error" };
-  }
-};
-const stopFunction: StopFunctionContract = async (request) => {
-  const sdk = new AgentSdk({
-    sessionId: request.sessionId,
-    testing: true
-  });
-  try {
-    await sdk.sendLog({
-      type: "observe",
-      shortMessage: "🛑 Agent stopping with new SDK v1.0"
-    });
-    return { success: true };
-  } catch (error) {
-    return { success: false, error: error instanceof Error ? error.message : "Unknown error" };
-  }
-};
+```bash
+circuit publish
+```
+> See the circuit cli docs for more details
-// DONT MODIFY BELOW THIS
-const agent = new Agent({ executionFunction, stopFunction });
-// Export the agent for Cloudflare Workers
-export default agent.getWorkerExport();
+### Test Locally
-```
+## 🧪 Manual Instantiation (Testing)
+For testing in scripts or Node.js REPL, you can manually create an `AgentContext`:
-### Sample self sender
->This demonstrates a very basic structure of fetching balances and sending 1% of that amount to yourself. It highlights what stage in the transaction process you will "hand off" the transaction to the circuit infrastructure for signing and sending (broadcasting).
 ```typescript
-import {
-  Agent,
-  AgentSdk,
-  ExecutionFunctionContract,
-  StopFunctionContract,
-} from "@circuitorg/agent-sdk";
-import { encodeFunctionData, parseAbi } from "viem";
-export type BalanceResponse = {
-  /** Raw amount as string (wei, lamports, or token units) */
-  amount: string;
-  /** Number of decimals for the asset */
-  decimals: number;
-  /** Whether this is a token (true) or native asset (false) */
-  isToken: boolean;
+import { AgentContext } from "@circuitorg/agent-sdk";
+// Create agent context with test data
+// Tip: Get a real session ID and wallet from running 'circuit run -m local -x execute'
+const SESSION_ID = 123; // <your-session-id>
+const WALLET_ADDRESS = "your-wallet-address";
+// Create sample position data - helpful for testing your agents treatment of different scenarios
+// for example if you want to test some re-balancing logic, you can build a sample set of positions here
+// In production, or when using the cli, these will be live values for the session
+const SAMPLE_POSITION = {
+  network: "ethereum:137",
+  assetAddress: "0x4d97dcd97ec945f40cf65f87097ace5ea0476045",
+  tokenId: "86192057611122246511563653509192966169513312957180910360241289053249649036697",
+  avgUnitCost: "0.779812797920499100",
+  currentQty: "41282044"
 };
-export async function getEvmTokenBalance(params: {
-  address: string;
-  token: string;
-  rpcUrl: string;
-}): Promise<BalanceResponse> {
-  // balanceOf(address) - ERC-20 standard
-  const data = `0x70a08231${params.address
-    .replace(/^0x/, "")
-    .padStart(64, "0")}`;
-  const balanceCall = {
-    jsonrpc: "2.0",
-    id: 1,
-    method: "eth_call",
-    params: [{ to: params.token, data }, "latest"],
-  } as const;
-  const balanceRes = await fetch(params.rpcUrl, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify(balanceCall),
-  });
-  const balanceJson = (await balanceRes.json()) as { result?: string };
-  const balHex = balanceJson.result || "0x0";
-  const amount = BigInt(balHex);
-  // decimals() - ERC-20 standard
-  const decimalsCall = {
-    jsonrpc: "2.0",
-    id: 2,
-    method: "eth_call",
-    params: [{ to: params.token, data: "0x313ce567" }, "latest"],
-  } as const;
-  const decimalsRes = await fetch(params.rpcUrl, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify(decimalsCall),
-  });
+const agent = new AgentContext({
+  sessionId: SESSION_ID,
+  sessionWalletAddress: WALLET_ADDRESS,
+  currentPositions: [SAMPLE_POSITION]
+});
-  const decimalsJson = (await decimalsRes.json()) as { result?: string };
-  const decimals = decimalsJson.result
-    ? Number(BigInt(decimalsJson.result))
-    : 18;
+// Use it just like in production!
+await agent.log("Testing agent functionality!");
+await agent.memory.set("test_key", "test_value");
-  return {
-    amount: amount.toString(),
-    decimals,
-    isToken: true,
-  };
+const result = await agent.memory.get("test_key");
+if (result.success && result.data) {
+  console.log(`Value: ${result.data.value}`);
 }
+```
-const toSubscript = (num: number): string => {
-  const map: Record<string, string> = {
-    "0": "₀",
-    "1": "₁",
-    "2": "₂",
-    "3": "₃",
-    "4": "₄",
-    "5": "₅",
-    "6": "₆",
-    "7": "₇",
-    "8": "₈",
-    "9": "₉",
-  };
-  return String(num)
-    .split("")
-    .map((c) => map[c] ?? c)
-    .join("");
-};
+**Key Points:**
+- Use real session IDs from the CLI for proper testing
+- All SDK methods work the same way as in production
-const formatTokenAmount = (
-  amount: bigint,
-  decimals: number,
-  subscriptDecimals: number = 4,
-  standardDecimals: number = 6
-): string => {
-  const sign = amount < 0n ? "-" : "";
-  const s = (amount < 0n ? -amount : amount).toString();
-  const hasFraction = decimals > 0;
-  const integerPart =
-    s.length > decimals ? s.slice(0, s.length - decimals) : "0";
-  const fractional = hasFraction
-    ? s.length > decimals
-      ? s.slice(s.length - decimals)
-      : s.padStart(decimals, "0")
-    : "";
-  const groupedInt = integerPart.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
-  if (!hasFraction) return sign + groupedInt;
-  if (/^0+$/.test(fractional)) return sign + groupedInt;
-  const leadingZeros = fractional.match(/^0+/)?.[0].length ?? 0;
-  if (leadingZeros >= 3) {
-    // Use subscript notation for numbers with 3+ leading zeros
-    const rest = fractional.slice(leadingZeros);
-    const truncatedRest = rest.slice(0, subscriptDecimals);
-    const compressedFrac = `0${toSubscript(leadingZeros)}${truncatedRest}`;
-    return `${sign}${groupedInt}.${compressedFrac}`;
-  }
+## 📚 Working Examples
-  // For 0-2 leading zeros, use standard decimal formatting
-  const truncatedFrac = fractional.slice(0, standardDecimals);
-  const trimmedFrac = truncatedFrac.replace(/0+$/, ""); // Remove trailing zeros
+The SDK includes complete working examples to help you get started:
-  if (trimmedFrac === "") return sign + groupedInt;
-  return `${sign}${groupedInt}.${trimmedFrac}`;
-};
+### [`demo-agent.ts`](./examples/demo-agent.ts)
+An agent demonstrating all main features of the sdk:
+- Memory operations (set, get, list, delete)
+- Polymarket integration (market orders, position redemption)
+- Swidge
+- Self sending using sign and send
+- Unified logging patterns
-// Agent execution function using the new AgentSdk v1.0 API
-const executionFunction: ExecutionFunctionContract = async (request) => {
-  console.log(`🚀 Agent execution called for session ${request.sessionId}`);
+This is a great starting point for building your own agent.
-  const sdk = new AgentSdk({
-    sessionId: request.sessionId,
-  });
-  try {
-    await sdk.sendLog({
-      type: "observe",
-      shortMessage:
-        "🚀 Starting Agent SDK v1.0 comprehensive demo -- live test",
-    });
-    const PEPE_ARB = "0x25d887Ce7a35172C62FeBFD67a1856F20FaEbB00" as `0x${string}`;
-    const pepeBalance = await getEvmTokenBalance({
-      rpcUrl: "https://arb-mainnet.g.alchemy.com/v2/<YOUR_API_KEY>",
-      address: request.sessionWalletAddress,
-      token: PEPE_ARB,
-    });
-    const pepeBalanceFormatted = formatTokenAmount(
-      BigInt(pepeBalance.amount),
-      pepeBalance.decimals
-    );
-    await sdk.sendLog({
-      type: "observe",
-      shortMessage: `PEPE Balance (Arbitrum): ${pepeBalanceFormatted} PEPE`,
-    });
-    const abi = parseAbi([
-      "function transfer(address to, uint256 value) returns (bool)",
-    ]);
-    const demoAmount = BigInt(pepeBalance.amount) / 100n;
-    const data = encodeFunctionData({
-      abi,
-      functionName: "transfer",
-      args: [request.sessionWalletAddress as `0x${string}`, demoAmount],
-    });
-    // Demo custom contract call
-    await sdk.signAndSend({
-      network: "ethereum:42161",
-      request: {
-        toAddress: PEPE_ARB,
-        data: data,
-        value: "0", // No ETH value for token transfers
-      },
-      message: "Custom PEPE transfer demo",
-    });
-    await sdk.sendLog({
-      type: "observe",
-      shortMessage:
-        "✅ Agent SDK v1.0 comprehensive demo completed successfully!",
-    });
-    return { success: true };
-  } catch (error) {
-    console.error("💥 Agent execution error:", error);
-    await sdk.sendLog({
-      type: "error",
-      shortMessage: `Agent execution error: ${
-        error instanceof Error ? error.message : "Unknown error"
-      }`,
-    });
-    // Optional - Return detailed error information for the CLI to display
-    return {
-      success: false,
-      error: error instanceof Error ? error.message : "Unknown error",
-      errorDetails: {
-        name: error instanceof Error ? error.name : "Unknown",
-        message: error instanceof Error ? error.message : String(error),
-        stack: error instanceof Error ? error.stack : undefined,
-        timestamp: new Date().toISOString(),
-        sessionId: request.sessionId,
-        agentSlug: (globalThis as any).CIRCUIT_AGENT_SLUG || "unknown",
-        errorType: "AGENT_EXECUTION_ERROR",
-      },
-    };
-  }
-};
+### [`examples/kitchen-sink.ts`](./examples/kitchen-sink.ts)
+A comprehensive script showing all SDK features:
+- Manual AgentContext instantiation for testing
+- All memory operations with examples
+- Cross-chain swaps with Swidge (quotes, execution, price impact checks)
+- Polymarket operations (buy/sell orders, redemptions)
+- Custom transactions with signAndSend
+- Logging patterns (standard, error, debug)
-const stopFunction: StopFunctionContract = async (request) => {
-  const sdk = new AgentSdk({
-    sessionId: request.sessionId,
-    testing: true,
-  });
+Run this script to experiment with the SDK before deploying your agent.
-  try {
-    await sdk.sendLog({
-      type: "observe",
-      shortMessage: "🛑 Agent stopping with new SDK v1.0",
-    });
-    return { success: true };
-  } catch (error) {
-    console.error("💥 Agent stop error:", error);
-    return {
-      success: false,
-      error: error instanceof Error ? error.message : "Unknown error",
-      errorDetails: {
-        name: error instanceof Error ? error.name : "Unknown",
-        message: error instanceof Error ? error.message : String(error),
-        stack: error instanceof Error ? error.stack : undefined,
-        timestamp: new Date().toISOString(),
-        sessionId: request.sessionId,
-        agentSlug: (globalThis as any).CIRCUIT_AGENT_SLUG || "unknown",
-      },
-    };
-  }
-};
+## 🎯 Key Takeaways
-// Create the agent
-const agent = new Agent({ executionFunction, stopFunction });
+1. **Single Interface**: Everything you need is in the `AgentContext` object
+2. **No Return Values**: Functions return `void` - uncaught errors are handled automatically by circuit
+3. **Unified Logging**: `agent.log()` with simple `debug` and `error` flags
+4. **Check `.success`**: All SDK methods return response objects with `.success` and `.error_message`
-// Export the agent for both Bun local development and Cloudflare Workers
-export default agent.getWorkerExport();
+## 📖 Additional Resources
-```
+- [Circuit CLI](https://github.com/circuitorg/agents-cli) - Deploy and manage agents
+- [`demo-agent.ts`](./examples/demo-agent.ts) - Production-ready agent template
+- [`examples/kitchen-sink.ts`](./examples/kitchen-sink.ts) - Comprehensive SDK demo