Suzi Agent SDK

The Suzi Agent SDK is the runtime and framework for defining autonomous agents. It provides a type-safe DSL (Domain Specific Language) for creating agents that can hold assets, execute transactions, and react to on-chain and off-chain events.

Core Concepts

An Agent in Suzi is a self-contained unit of logic that possesses:

Identity: A cryptographic wallet (EVM or SVM).
Configuration: User-tunable parameters (e.g., "Trading Size", "Risk Level").
Resources: External connections (wallets, API keys).
Triggers: Events that wake the agent up (Time, Price, On-chain Event).
Actions: Capabilities to interact with the world (Swap, Transfer, Tweet).

The `defineAgent` DSL

All agents are defined using the defineAgent function. This function takes a single configuration object that describes every aspect of your agent.

No Imports Rule: In v1, agent files must be self-contained. You cannot use top-level import statements. The runtime provides the necessary globals (defineAgent, on, resource, config, requirement) automatically.

Basic Structure

export default defineAgent({
  meta: {
    name: 'My Agent',
    version: '1.0.0',
    description: 'A simple trading agent',
  },
  config: { ... },
  resources: { ... },
  triggers: { ... },
});

Metadata (`meta`)

Describes your agent for the marketplace and UI.

Field	Type	Description
`name`	string	Display name of the agent.
`version`	string	Semver string (e.g., '1.0.0').
`description`	string	Short summary of what the agent does.
`tags`	string[]	Keywords for discovery (e.g., `['defi', 'arbitrage']`).

Configuration (`config`)

Defines parameters that users can tune when deploying or managing the agent. Use the config global to define schema.

config: {
  maxSlippage: config.number({
    description: 'Maximum slippage tolerance in %',
    default: 1.0,
    min: 0.1,
    max: 5.0,
  }),
  pair: config.string({
    description: 'Trading pair (e.g., SOL/USDC)',
    required: true, // User must provide this
  }),
  dryRun: config.boolean({
    description: 'If true, only log actions without executing',
    default: false,
  }),
}

Resources (`resources`)

Declares external capabilities the agent needs. The most common is a wallet.

resources: {
  // Requests the user's primary SVM (Solana) wallet
  mainWallet: resource.wallet('svm'),
  // Requests the user's primary EVM (Ethereum/Base/Arb) wallet
  ethWallet: resource.wallet('evm'),
}

Activation Requirements (`activationRequirements`)

Pre-flight checks that run before an agent can be activated. If these fail, the agent refuses to start.

activationRequirements: {
  initialCapital: requirement.svmTokenBalance({
    token: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
    minAmount: 100, // or reference config: { $ref: 'config.minCapital' }
    description: 'Agent requires at least 100 USDC to start',
  }),
  gasFees: requirement.svmNativeBalance({
    minAmount: 0.1,
    description: 'Requires 0.1 SOL for gas',
  }),
}

Triggers (`triggers`)

Define when your agent runs. Use the on global builder.

1. Manual Trigger

triggered by the user clicking "Run" in the CLI or UI.

triggers: {
  manual: on.suzi.manual(async (ctx) => {
    // ... logic ...
  }),
}

2. Cron Trigger

Runs on a schedule.

triggers: {
  hourly: on.suzi.cron({ schedule: '0 * * * *' }, async (ctx) => {
    // ... logic ...
  }),
}

3. Event Triggers (Protocol Specific)

React to on-chain events. (Run suzi list-triggers to see all available).

triggers: {
  priceMove: on.polymarket.price_change({ market: '...' }, async (ctx, event) => {
    // ... logic ...
  }),
}

The Context Object (`ctx`)

Every trigger handler receives a ctx object containing the agent's runtime state.

async (ctx) => {
  // 1. Access Config
  const slippage = ctx.config.maxSlippage;

  // 2. Access Actions (The "Toolbox")
  // Run `suzi list-tools` to see all available actions.
  await ctx.actions.suzi.log({ message: 'Analyzing market...' });

  const balance = await ctx.actions.solana.get_balance({
    address: '...'
  });

  // 3. Persistent Storage (Key-Value Store)
  await ctx.actions.suzi.set_to_store({ key: 'last_trade', value: Date.now() });
  const last = await ctx.actions.suzi.get_from_store({ key: 'last_trade' });
}

Lifecycle Hooks

Run logic when the agent is turned on or off.

lifecycle: {
  onActivate: async (ctx) => {
    await ctx.actions.suzi.log({ message: 'Agent starting up!' });
    // Good place to set up initial state or validate complex requirements
  },
  onDeactivate: async (ctx) => {
    await ctx.actions.suzi.log({ message: 'Agent shutting down, closing positions...' });
    // Good place to close open orders or withdraw liquidity
  },
}

Example: Simple Auto-Compounder

export default defineAgent({
  meta: {
    name: 'Auto Compounder',
    description: 'Claims rewards and restakes them daily',
    version: '0.0.1',
  },
  triggers: {
    daily: on.suzi.cron({ schedule: '0 0 * * *' }, async (ctx) => {
      // 1. Claim
      await ctx.actions.protocol.claim_rewards({});
      // 2. Log
      await ctx.actions.suzi.log({ message: 'Rewards claimed' });
      // 3. Restake
      await ctx.actions.protocol.stake({ amount: 'max' });
    }),
  },
});

On this page