SDK

This document covers the agent-creation contract integration in the Regent SDK.

Overview

The Regent SDK provides TypeScript interfaces and implementations for interacting with the Regent Agent Factory smart contracts. This enables:

• Creating sovereign agents on-chain

• Managing agent lifecycle (pause, resume, transfer)

• Configuring tokenomics (bond, rake, treasury)

• Integrating with ERC-8004 identity

Packages

Package	Description
@regent/contracts	TypeScript interfaces and viem clients for factory contracts
@regent/agents	High-level orchestration (factory + ERC-8004 + wallet)
@regent/regentx	CLI for agent management

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  @regent/regentx│────▶│ @regent/agents  │────▶│ @regent/contracts│
│     (CLI)       │     │   (Manager)     │     │   (Factory)     │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                               │                        │
                               ▼                        ▼
                        ┌─────────────┐          ┌─────────────┐
                        │@regent/erc8004│        │ On-Chain    │
                        │  (Identity) │          │ Contracts   │
                        └─────────────┘          └─────────────┘

Quick Start

Local Development (Mock Mode)

import { InMemoryAgentFactory } from '@regent/contracts';
import { RegentAgentManager } from '@regent/agents';

// Create mock factory for development
const factory = new InMemoryAgentFactory({ chainId: 11155111 });
const manager = new RegentAgentManager(factory);

// Create an agent
const result = await manager.createAgentFromConfig({
  name: 'My Agent',
  ownerConnectorId: 'local-eoa',
  metadata: { uri: 'ipfs://...' },
}, ownerAddress);

console.log('Agent ID:', result.agentId);

On-Chain Mode

import { ViemRegentAgentFactory } from '@regent/contracts';
import { RegentAgentManager } from '@regent/agents';
import { createPublicClient, createWalletClient, http } from 'viem';
import { sepolia } from 'viem/chains';

// Create viem clients
const publicClient = createPublicClient({ chain: sepolia, transport: http() });
const walletClient = createWalletClient({ chain: sepolia, transport: http() });

// Create factory client
const factory = new ViemRegentAgentFactory({
  address: '0x...', // Factory contract address
  chain: sepolia,
  publicClient,
  walletClient,
});

const manager = new RegentAgentManager(factory);

// Create on-chain agent
const result = await manager.createAgentFromConfig({
  name: 'My Agent',
  ownerConnectorId: 'local-eoa',
  metadata: { uri: 'ipfs://...' },
  tokenomics: {
    rakeBps: 500, // 5%
    initialBond: 1000000000000000000n, // 1 token
  },
}, ownerAddress);

Factory Interface

The RegentAgentFactory interface defines the contract between the SDK and on-chain factories:

interface RegentAgentFactory {
  // Create agent
  createAgent(input: CreateAgentInput): Promise<CreatedAgentInfo>;

  // Query state
  getAgent(agentId: string): Promise<AgentOnchainState | null>;
  getAgentsByOwner(owner: Address): Promise<AgentOnchainState[]>;

  // Management (optional)
  updateMetadata?(agentId: string, metadataUri: string): Promise<TxHash>;
  setPaused?(agentId: string, paused: boolean): Promise<TxHash>;
  changeOwner?(agentId: string, newOwner: Address): Promise<TxHash>;
  setTreasury?(agentId: string, treasury: Address, rakeBps: number): Promise<TxHash>;

  // Bond operations (optional)
  depositBond?(agentId: string, amount: bigint): Promise<TxHash>;
  withdrawBond?(agentId: string, to: Address, amount: bigint): Promise<TxHash>;
}

Agent ID Format

Agent IDs are formatted as chainId:localId:

// Examples
"11155111:42"  // Sepolia, agent ID 42
"84532:1"      // Base Sepolia, agent ID 1

This format allows cross-chain agent identification.

Tokenomics Configuration

Rake (Revenue Share)

The rake is specified in basis points (1-10000):

{
  tokenomics: {
    rakeBps: 500,  // 5% rake
    treasury: '0x...', // Treasury address
  }
}

Bond

Initial bond amount in wei:

{
  tokenomics: {
    initialBond: 1000000000000000000n, // 1 token
  }
}

CLI Usage

# Initialize project
regentx agent:init --name "my-agent"

# Create agent (mock mode)
regentx agent:create --mode mock

# Create agent (on-chain)
regentx agent:create --mode onchain --chain sepolia

# Check status
regentx agent:status

# List agents
regentx agent:list

Solidity Interface

The SDK expects contracts implementing IRegentAgentFactory:

interface IRegentAgentFactory {
    struct CreateAgentParams {
        address owner;
        string name;
        string metadataURI;
        address treasury;
        uint16 rakeBps;
        uint256 initialBond;
        address identityRegistry;
        bytes identityData;
    }

    function createAgent(CreateAgentParams calldata params)
        external returns (uint256 agentId);

    function getAgent(uint256 agentId)
        external view returns (Agent memory);

    function getAgentsByOwner(address owner)
        external view returns (uint256[] memory);
}

Full ABI available in @regent/contracts/abi.

Related Documentation

• ERC-8004 Integration Guide

• Tokenomics Concepts

• TEE Infrastructure