Autonomys Auto Agents SDK

Overview

The @autonomys/auto-agents package provides utilities for managing the state or "experiences" of autonomous agents built on the Autonomys Network. It facilitates saving agent state to AutoDrive and tracking the latest state via an on-chain reference (using EVM).

Key Features

• Save Agent Experiences: Persist agent state (arbitrary data) along with metadata (agent name, version, timestamp, previous state CID) to AutoDrive.
• Retrieve Agent Experiences: Download agent state from AutoDrive using its Content Identifier (CID).
• On-Chain State Tracking: Store and update the CID of the latest agent experience on an EVM-compatible chain.
• Local Caching: Maintain a local cache of the latest known experience CID for faster lookups and offline support.
• Resilience: Includes retry logic for network operations.

Installation

yarn add @autonomys/auto-agents
# or
npm install @autonomys/auto-agents

How to Use

The primary entry point is the createExperienceManager function.

Setup Options

You need to provide configuration options:

import type { ExperienceManagerOptions } from '@autonomys/auto-agents'

const options: ExperienceManagerOptions = {
  // AutoDrive API configuration
  autoDriveApiOptions: {
    apiKey: 'YOUR_AUTO_DRIVE_API_KEY', // Get from https://ai3.storage
    network: 'taurus', // or 'mainnet'
  },
  // Options for uploading experiences (compression, encryption)
  uploadOptions: {
    compression: true,
    // password: 'OPTIONAL_ENCRYPTION_PASSWORD'
  },
  // EVM wallet and contract details for on-chain CID tracking
  walletOptions: {
    privateKey: 'YOUR_AGENT_EVM_PRIVATE_KEY',
    // Omit contractInfo to track the last CID in local storage only
    contractInfo: {
      rpcUrl: 'YOUR_EVM_RPC_URL', // e.g., Polygon Amoy RPC
      contractAddress: 'YOUR_AUTONOMYS_MEMORY_CONTRACT_ADDRESS', // Address of the deployed Memory contract
    },
  },
  // Agent identification and local storage path
  agentOptions: {
    agentName: 'MyCoolAgent',
    agentPath: '/path/to/agent/storage', // Directory to store local cache (e.g., './agent-data')
    memoriesDirectory: 'memories', // Directory to store memories (e.g., './memories')
    lastMemoryCidFilename: 'last-memory-cid.json', // Filename to store the last memory CID (e.g., './last-memory-cid.json')
    agentVersion: '1.0.0',
  },
}

Creating the Manager

import { createExperienceManager } from '@autonomys/auto-agents'

const initializeManager = async () => {
  try {
    const experienceManager = await createExperienceManager(options)
    console.log('Experience Manager created!')
    // Use the manager...
  } catch (error) {
    console.error('Failed to initialize Experience Manager:', error)
  }
}

initializeManager()

Saving an Experience

// Assuming 'experienceManager' is initialized as above

const currentAgentExperience = {
  coolActionTaken:
    'calculated optimal route to the moon, mars, and jupiter including a stop at saturn',
  interestingThoughts: [
    'I should probably check the weather on the moon before I go',
    'I wonder if the moon is made of cheese',
  ],
  usefulData: {
    moonTemperature: 100,
    marsTemperature: 200,
    jupiterTemperature: 300,
    saturnTemperature: 400,
  },
  intelligentReasoning: 'The moon is made of cheese because it is a delicious food.',
}

const saveExperience = async () => {
  try {
    const result = await experienceManager.saveExperience(currentAgentExperience)
    console.log('Experience saved successfully!')
    console.log('New CID:', result.cid)
    console.log('Previous CID:', result.previousCid)
    console.log('EVM Tx Hash:', result.evmHash)
  } catch (error) {
    console.error('Failed to save experience:', error)
  }
}

saveExperience()

Retrieving an Experience

You can retrieve the latest experience by first getting its CID from the CidManager provided by the ExperienceManager.

// Assuming 'experienceManager' is initialized

const retrieveLatestExperience = async () => {
  try {
    // Get the CID of the latest saved experience
    const latestCid = await experienceManager.cidManager.getLastMemoryCid()

    if (!latestCid) {
      console.log('No previous experience found for this agent.')
      return
    }

    console.log(`Retrieving experience with CID: ${latestCid}`)
    const experience = await experienceManager.retrieveExperience(latestCid)

    console.log('Experience retrieved successfully:')
    console.log('Header:', experience.header)
    console.log('Previous Experience CID:', experience.header.previousCid) // This could be used to create a chain of experiences
    console.log('Data:', experience.data)

    // TODO: Verify signature: experience.signature
  } catch (error) {
    console.error('Failed to retrieve experience:', error)
  }
}

retrieveLatestExperience()

You can also retrieve any specific experience if you know its CID.

CidManager

The experienceManager exposes the underlying cidManager instance. This allows more direct interaction with the latest experience CID management, such as checking the status of the local hash cache (cidManager.localHashStatus).

License

This project is licensed under the MIT License. See the LICENSE file for details.

Additional Resources

• Autonomys Academy: Learn more at Autonomys Academy.

Contact

If you have any questions or need support, feel free to reach out:

• GitHub Issues: GitHub Issues Page

We appreciate your feedback and contributions!