0.3.1 • Published 5 months ago

@autonomys/agent-core v0.3.1

Weekly downloads
-
License
MIT
Repository
github
Last release
5 months ago

@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.