@autonomys/agent-core

The core package for building autonomous AI agents. This package is extracted from the Autonomys Agents framework.

Installation

npm install @autonomys/agent-core
# or
yarn add @autonomys/agent-core

Features

• Agent orchestration and workflow management
• Integration with major LLM providers (OpenAI, Anthropic, etc.)
• Tools for interacting with external services:
  • Slack integration
  • Twitter automation
  • GitHub operations
  • Notion connectivity
  • Web search capabilities
• Vector database integration for agent memory
• Configurable character system for agent personalities
• Blockchain integration for agent experience tracking
• API server for external control and monitoring
• Task scheduling and execution
• Experience management and monitoring

Usage

Here's how to use the core package in your own project:

import {
  // Configuration tools
  getConfig,
  
  // Agent creation
  createOrchestratorRunner,
  createPrompts,
  registerOrchestratorRunner,
  
  // Tool integrations
  createAllSchedulerTools,
  createWebSearchTool,
  createTwitterApi,
  createSlackTools,
  createFirecrawlTools,
  
  // Agent types
  createTwitterAgent,
  
  // Workflow management
  startTaskExecutor,
  
  // API server
  createApiServer,
  withApiLogger,
  
  // Utilities
  createExperienceManager,
  createLogger,
  closeAllVectorDBs
} from '@autonomys/agent-core';

// Your implementation here...

Required Character Structure

When using this package, you'll need to set up a character structure in your project:

characters/
  ├── your-character-name/
  │   ├── config/
  │   │   ├── .env                # Environment variables
  │   │   ├── config.yaml         # Configuration settings
  │   │   └── your-character.yaml # Character personality definition
  │   ├── data/                   # For agent data storage
  │   ├── logs/                   # For agent logs
  │   └── memories/               # For agent memory storage

Note: Example character configurations are available in the Autonomys Agents GitHub repository to help you get started.

API Server Certificate Requirements

Important: When running without the --headless flag, the API server requires SSL certificates. You must create a certs directory in your workspace root with the following files:

• certs/server.cert - SSL certificate
• certs/server.key - SSL private key

You can generate these certificates using OpenSSL with this command:

mkdir -p certs
openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
  -keyout certs/server.key -out certs/server.cert -days 365

Running Agents

The package automatically handles command-line arguments through the getConfig() function.

Supported Command-Line Arguments

When running your agent implementation, these arguments are automatically parsed and processed:

• Character Name: The first positional argument specifies which character to run

  npx tsx your-script.ts my-character-name

• --headless: Run the agent without starting the API server

  npx tsx your-script.ts my-character-name --headless

• --workspace PATH: Specify a custom workspace root directory where the characters folder exists

  npx tsx your-script.ts my-character-name --workspace /path/to/your/project

Example Script

Here's how you might set up a script to run your agent:

// index.ts or agent.ts
import { getConfig /* other imports */ } from '@autonomys/agent-core';

// The getConfig function automatically parses command-line arguments
const main = async (): Promise<void> => {
  const configInstance = await getConfig();
  // ... rest of your agent code
};

main().catch(error => {
  console.error('Error running agent:', error);
  process.exit(1);
});

Then run it with:

npx tsx index.ts my-character-name
npx tsx index.ts my-character-name --headless
npx tsx index.ts my-character-name --workspace /path/to/workspace

Example Implementation

Here's an example of implementing an agent using this package:

import {
  getConfig,
  createOrchestratorRunner,
  createPrompts,
  createAllSchedulerTools,
  createTwitterApi,
  createTwitterAgent,
  startTaskExecutor,
  registerOrchestratorRunner,
  createLogger,
  closeAllVectorDBs
} from '@autonomys/agent-core';

// Get configuration (automatically parses command-line arguments)
const configInstance = await getConfig();
if (!configInstance) {
  throw new Error('Config instance not found');
}
const { config, characterName } = configInstance;
const character = config.characterConfig;

// Define LLM configurations
const modelConfigurations = {
  inputModelConfig: {
    provider: 'anthropic',
    model: 'claude-3-5-sonnet-latest',
    temperature: 0.6,
  },
  messageSummaryModelConfig: {
    provider: 'anthropic',
    model: 'claude-3-5-haiku-latest',
    temperature: 0.6,
  }
};

// Initialize tools
const schedulerTools = createAllSchedulerTools();

// Set up Twitter agent (if configured)
const twitterAgentTool = 
  config.twitterConfig.USERNAME && config.twitterConfig.PASSWORD
    ? [
        createTwitterAgent(
          await createTwitterApi(
            config.twitterConfig.USERNAME,
            config.twitterConfig.PASSWORD,
            config.twitterConfig.COOKIES_PATH,
          ),
          character,
          {
            tools: [...schedulerTools],
            postTweets: config.twitterConfig.POST_TWEETS,
            modelConfigurations: config.twitterConfig.model_configurations,
            characterDataPathConfig: {
              dataPath: character.characterPath,
            },
          },
        ),
      ]
    : [];

// Create orchestrator configuration
const orchestrationConfig = {
  modelConfigurations,
  tools: [
    ...twitterAgentTool,
    ...schedulerTools,
  ],
  prompts: await createPrompts(character),
  characterDataPathConfig: {
    dataPath: character.characterPath,
  },
};

// Create and register the runner
const runner = await createOrchestratorRunner(character, orchestrationConfig);
registerOrchestratorRunner('orchestrator', runner);

// Start task executor
const stopTaskExecutor = startTaskExecutor(runner, 'orchestrator');

// Handle graceful shutdown
process.on('SIGINT', () => {
  const logger = createLogger('app');
  logger.info('Received SIGINT. Shutting down...');
  stopTaskExecutor();
  closeAllVectorDBs();
  process.exit(0);
});

Documentation

For detailed documentation and examples, please refer to our GitHub repository.

License

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