agentis

Agentis Framework v0.2

Current Architecture Overview

Core Components

Agentis Framework

A TypeScript framework for building sophisticated multi-agent systems with LLM integration, specializing in crypto market analysis and research.

Features

• 🤖 Multi-agent Collaboration System

  • Agent-to-agent communication
  • Specialized agent roles (Market Research, Technical Analysis)
  • Task sharing and delegation

• 🧠 Advanced Memory Management

  • Vector-based memory storage using Supabase
  • Short-term and long-term memory systems
  • Context-aware responses

• 🛠️ Modular Tool Architecture

  • WebSearchTool with Tavily API integration
  • OpenRouterTool with Claude-3 integration
  • AnthropicTool with Claude-3.7 integration
  • Advanced tool orchestration with sequential and parallel execution
  • Extensible tool registry system

• 🔄 Real-time Market Analysis

  • Live web search capabilities
  • Market trend analysis
  • Fundamental and technical analysis

• 💾 Persistent Storage

  • Supabase integration
  • Message history tracking
  • Agent state persistence
  • Vector-based memory storage

🚀 Quick Start

1. Installation

npm install agentis

2. Environment Setup

Create a .env file in your project root:

OPENROUTER_API_KEY=your_openrouter_key
SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_supabase_anon_key

3. Supabase Setup

• Create a new Supabase project at supabase.com
• Enable Vector extension in your Supabase database
• Run this SQL in your Supabase SQL editor:

-- Enable vector extension
create extension if not exists vector;

-- Create memory entries table
create table memory_entries (
  id bigint primary key generated always as identity,
  agent_id text not null,
  content text not null,
  type text not null,
  metadata jsonb,
  embedding vector(1536),
  created_at timestamp with time zone default timezone('utc'::text, now())
);

-- Create messages table
create table messages (
  id text primary key,
  sender_id text not null,
  recipient_id text not null,
  content text not null,
  timestamp timestamp with time zone default timezone('utc'::text, now())
);

4. Basic Usage

import { Agent, AgentRuntime, WebSearchTool, OpenRouterTool } from 'agentis';

// Create an agent
const agent = new Agent(
  'market-analyst-1',
  'MarketAnalyst',
  'I am a crypto market analyst specialized in trend analysis',
  'Market Analyst',
  ['Analyze market trends', 'Provide trading insights'],
  [new WebSearchTool(), new OpenRouterTool()]
);

// Initialize runtime
const runtime = new AgentRuntime();
runtime.registerAgent(agent);
await runtime.start();

// Send a message to the agent
const response = await agent.receiveMessage({
  id: `msg-${Date.now()}`,
  sender_id: 'user',
  recipient_id: agent.id,
  content: 'Analyze the current BTC market trends',
  timestamp: Date.now()
});

console.log(response.content);

5. Creating a Team of Agents

import { Agent, AgentRuntime, WebSearchTool, OpenRouterTool } from 'agentis';

// Create specialized agents
const researchAgent = new Agent(
  'research-1',
  'MarketResearcher',
  'I gather and analyze market data',
  'Researcher',
  ['Gather market information'],
  [new WebSearchTool()]
);

const strategyAgent = new Agent(
  'strategy-1',
  'StrategyMaster',
  'I create trading strategies',
  'Strategist',
  ['Create trading strategies'],
  [new OpenRouterTool()]
);

// Initialize runtime with multiple agents
const runtime = new AgentRuntime();
runtime.registerAgent(researchAgent);
runtime.registerAgent(strategyAgent);
await runtime.start();

📚 Features

• 🤖 Multi-agent System
• 🧠 Advanced Memory Management
• 🛠️ Modular Tool Architecture
• 🔄 Real-time Processing
• 💾 Persistent Storage

🔧 Available Tools

• WebSearchTool: Real-time web search capabilities
• OpenRouterTool: LLM integration via OpenRouter

📖 Documentation

For more detailed documentation, visit our documentation site

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines.

📝 License

MIT License - see the LICENSE file for details

Roadmap

• Add sophisticated tool orchestration system with parallel execution
• Add more specialized market analysis tools
• Implement sophisticated inter-agent communication patterns
• Add automated trading capabilities
• Enhance memory management with better context handling
• Add monitoring and observability features

Environment Requirements

• Supabase project with vector extension
• OpenRouter API key
• Node.js environment
• TypeScript support

🎯 Creating Custom Agents

Users can fully customize their agents' personalities, roles, and capabilities:

import { Agent, WebSearchTool, OpenRouterTool } from 'agentis';

// Crypto Trading Specialist
const tradingAgent = new Agent(
  'trader-1',
  'CryptoTrader',
  'I am an experienced crypto trader specializing in technical analysis. I focus on identifying trading opportunities using multiple timeframe analysis.',
  'Trading Specialist',
  [
    'Analyze trading patterns',
    'Identify entry and exit points',
    'Monitor market sentiment'
  ],
  [new WebSearchTool(), new OpenRouterTool()]
);

// Market Research Analyst
const researchAgent = new Agent(
  'research-1',
  'MarketResearcher',
  'I specialize in fundamental analysis and market research. I analyze project fundamentals, team backgrounds, and market dynamics.',
  'Research Analyst',
  [
    'Research project fundamentals',
    'Analyze team credentials',
    'Track market developments'
  ],
  [new WebSearchTool()]
);

// News Sentiment Analyzer
const sentimentAgent = new Agent(
  'sentiment-1',
  'SentimentAnalyst',
  'I track and analyze market sentiment across social media, news, and trading platforms. I identify shifts in market psychology.',
  'Sentiment Analyst',
  [
    'Monitor social media sentiment',
    'Track news impact',
    'Analyze market psychology'
  ],
  [new WebSearchTool(), new OpenRouterTool()]
);

Agent Configuration Options

Each agent can be customized with:

• id: Unique identifier for the agent
• name: Display name
• lore: Personality and background description that shapes the agent's responses
• role: Professional role that defines the agent's expertise
• goals: Array of specific objectives the agent works to achieve
• tools: Array of tools the agent can use (WebSearchTool, OpenRouterTool, etc.)
• model (optional): LLM model configuration

// Optional model configuration
const agent = new Agent(
  'custom-agent',
  'CustomAgent',
  'My custom agent lore',
  'Custom Role',
  ['Goal 1', 'Goal 2'],
  [new WebSearchTool()],
  {
    provider: 'anthropic',
    name: 'anthropic/claude-3-sonnet-20240229',
    temperature: 0.7,
    maxTokens: 4096
  }
);

🛠️ Creating Custom Tools

Agents can be enhanced with custom tools. Here's how to create your own:

1. Basic Tool Structure

import { ITool, ToolOutput } from 'agentis';

export class CustomTool implements ITool {
  name = 'CustomTool';
  description = 'Description of what your tool does';

  async execute(input: string): Promise<ToolOutput> {
    // Your tool's logic here
    return {
      result: `Processed: ${input}`
    };
  }
}

Tool Orchestration

Agentis provides a sophisticated tool orchestration system for complex tool execution flows:

import { EnhancedToolOrchestrator, GraphBuilder, ExecutionMode } from 'agentis/tools';

// Create tool orchestrator
const orchestrator = new EnhancedToolOrchestrator({
  defaultTools: [myTool1, myTool2, myTool3]
});

// Build a parallel execution graph
const graph = new GraphBuilder()
  .addTool('search-1', 'WebSearchTool', 'bitcoin price', 0)
  .addTool('search-2', 'WebSearchTool', 'ethereum price', 0)
  // Process results of both searches
  .addDependentTool(
    'analysis',
    'AnthropicTool',
    (context) => {
      const btcData = context.getPreviousResult('search-1')?.result || '';
      const ethData = context.getPreviousResult('search-2')?.result || '';
      return `Compare these prices: BTC: ${btcData}, ETH: ${ethData}`;
    },
    ['search-1', 'search-2'], // dependencies
    1 // priority
  )
  .parallel(2) // max 2 concurrent requests
  .build();

// Execute the graph
const results = await orchestrator.executeGraph(graph, 'my-agent-id');
console.log(results.get('analysis')?.result);

### 2. Example: Creating a Price Feed Tool

```typescript
import { ITool, ToolOutput } from 'agentis';

export class PriceFeedTool implements ITool {
  name = 'PriceFeedTool';
  description = 'Fetches real-time crypto prices';

  async execute(input: string): Promise<ToolOutput> {
    const symbol = input.toUpperCase();
    const response = await fetch(`https://api.example.com/price/${symbol}`);
    const data = await response.json();
    
    return {
      result: data.price,
      metadata: {
        timestamp: Date.now(),
        symbol: symbol,
        source: 'ExampleAPI'
      }
    };
  }
}

3. Using Custom Tools

import { Agent, PriceFeedTool } from 'agentis';

const agent = new Agent(
  'price-tracker-1',
  'PriceTracker',
  'I track and analyze crypto prices',
  'Price Analyst',
  ['Monitor price movements'],
  [new PriceFeedTool()]
);

4. Best Practices

• Error Handling: Always include proper error handling in your tool
• Rate Limiting: Implement rate limiting if calling external APIs
• Caching: Consider caching results for frequently used queries
• Typing: Use TypeScript interfaces for structured inputs/outputs
• Documentation: Document expected inputs and output formats

5. Advanced Tool Features

Tools can implement additional optional methods:

import { ITool, ToolOutput } from 'agentis';

export class AdvancedTool implements ITool {
  name = 'AdvancedTool';
  description = 'An advanced tool example';

  // Optional initialization
  async initialize(): Promise<void> {
    // Setup code
  }

  // Main execution method
  async execute(input: string): Promise<ToolOutput> {
    return { result: 'processed data' };
  }

  // Optional cleanup
  async cleanup(): Promise<void> {
    // Cleanup code
  }

  // Optional validation
  validateInput(input: string): boolean {
    return input.length > 0;
  }
}

6. Registering Tools Globally

import { ToolRegistry } from 'agentis';

// Register tool for all agents to use
ToolRegistry.registerTool('CustomTool', new CustomTool());

// Create agent with access to all registered tools
const agent = new Agent(
  'agent-1',
  'Agent',
  'Agent description',
  'Role',
  ['Goals'],
  ToolRegistry.getTools()
);

🤝 Team Composition

Agentis is designed for multi-agent collaboration. Agents can work together in specialized teams:

import { Agent, AgentRuntime, WebSearchTool, OpenRouterTool } from 'agentis';

// Create a crypto research team
const researchTeam = {
  // Research Specialist
  researcher: new Agent(
    'researcher-1',
    'ResearchSpecialist',
    'I conduct deep research into crypto projects, analyzing fundamentals, tokenomics, and team backgrounds',
    'Research Analyst',
    ['Research project fundamentals', 'Analyze tokenomics'],
    [new WebSearchTool()]
  ),

  // Technical Analyst
  analyst: new Agent(
    'analyst-1',
    'TechnicalAnalyst',
    'I analyze market structures, price action, and technical indicators',
    'Technical Analyst',
    ['Analyze price trends', 'Identify technical patterns'],
    [new WebSearchTool(), new OpenRouterTool()]
  ),

  // Strategy Coordinator
  coordinator: new Agent(
    'coordinator-1',
    'StrategyMaster',
    'I coordinate research efforts and synthesize findings into actionable strategies',
    'Strategy Coordinator',
    ['Coordinate research', 'Synthesize findings'],
    [new OpenRouterTool()]
  )
};

// Initialize runtime with the team
const runtime = new AgentRuntime();
Object.values(researchTeam).forEach(agent => runtime.registerAgent(agent));
await runtime.start();

// Team can now collaborate on tasks
const response = await researchTeam.coordinator.receiveMessage({
  id: `msg-${Date.now()}`,
  sender_id: 'user',
  recipient_id: researchTeam.coordinator.id,
  content: 'Analyze Bitcoin\'s current market position',
  timestamp: Date.now()
});

Team Benefits

• Specialized Expertise: Each agent focuses on specific aspects of analysis
• Collaborative Intelligence: Agents share findings and build on each other's work
• Coordinated Research: Strategy agents can delegate and synthesize research tasks
• Scalable Analysis: Teams can handle complex research tasks through division of labor

Team Communication

Agents in a team can:

• Share research findings
• Request additional analysis
• Coordinate on complex tasks
• Synthesize collective insights