@stick-ai/runtime

Agent runtime engine for the stick.ai framework - build and execute AI agents with built-in tools.

Installation

npm install @stick-ai/runtime

Quick Start

import { Agent, createTool } from '@stick-ai/runtime';

// Create an agent
const agent = new Agent({
  name: 'my-agent',
  version: '1.0.0',
  description: 'My AI agent',
  capabilities: ['chat', 'task-execution'],
  tools: ['bash', 'http', 'file-ops', 'json'],
  instructions: 'You are a helpful AI agent.',
  environment: {
    maxTokens: 4000,
    temperature: 0.7
  }
});

// Register tools
const bashTool = createTool('bash');
agent.registerTool('bash', bashTool);

// Run the agent
const response = await agent.run('Hello, what can you do?');
console.log(response);

Features

• 🤖 Agent Class - Complete agent lifecycle management
• 🛠️ Built-in Tools - 14 production-ready tools
• 💾 Memory - Conversation history tracking
• 🔧 Extensible - Easy custom tool creation
• 📦 TypeScript - Full type safety
• ⚡ Fast - Lightweight and performant

Built-in Tools

BashTool (bash)

Execute shell commands safely:

const bashTool = createTool('bash');
const result = await bashTool.execute({
  command: 'ls -la',
  timeout: 30000
});

HttpTool (http)

Make HTTP requests:

const httpTool = createTool('http');
const result = await httpTool.execute({
  url: 'https://api.example.com/data',
  method: 'GET',
  headers: { 'Authorization': 'Bearer token' }
});

FileOpsTool (file-ops)

File system operations:

const fileTool = createTool('file-ops');

// Read file
const content = await fileTool.execute({
  operation: 'read',
  path: './data.txt'
});

// Write file
await fileTool.execute({
  operation: 'write',
  path: './output.txt',
  content: 'Hello World'
});

JsonTool (json)

JSON manipulation:

const jsonTool = createTool('json');

// Parse JSON
const parsed = await jsonTool.execute({
  operation: 'parse',
  data: '{"name": "John"}'
});

// Query JSON
const result = await jsonTool.execute({
  operation: 'query',
  data: { user: { name: 'John' } },
  query: 'user.name'
});

PythonTool (python)

Execute Python code:

const pythonTool = createTool('python');
const result = await pythonTool.execute({
  code: 'print("Hello from Python!")',
  timeout: 30000
});

DatabaseTool (database)

Database operations:

const dbTool = createTool('database');

// Connect
const conn = await dbTool.execute({
  operation: 'connect',
  type: 'postgres',
  connectionString: 'postgresql://...'
});

// Query
const result = await dbTool.execute({
  operation: 'query',
  connectionId: conn.connectionId,
  query: 'SELECT * FROM users'
});

EmailTool (email)

Send emails:

const emailTool = createTool('email');
await emailTool.execute({
  to: '[email protected]',
  subject: 'Hello',
  body: 'Message content'
});

WebScraperTool (web-scraper)

Scrape web pages:

const scraperTool = createTool('web-scraper');
const result = await scraperTool.execute({
  url: 'https://example.com',
  selector: 'h1'
});

CsvTool (csv)

CSV operations:

const csvTool = createTool('csv');

// Parse CSV file
const data = await csvTool.execute({
  operation: 'parse',
  path: './data.csv'
});

// Convert to CSV
const csv = await csvTool.execute({
  operation: 'stringify',
  data: [{ name: 'John', age: 30 }]
});

GitHubTool (github)

GitHub API integration:

const githubTool = createTool('github');

// Get repository info
const repo = await githubTool.execute({
  operation: 'get-repo',
  owner: 'microsoft',
  repo: 'vscode'
});

// List issues
const issues = await githubTool.execute({
  operation: 'list-issues',
  owner: 'microsoft',
  repo: 'vscode'
});

SlackTool (slack)

Slack integration:

const slackTool = createTool('slack');
await slackTool.execute({
  operation: 'send-message',
  token: 'xoxb-...',
  channel: '#general',
  text: 'Hello from stick.ai!'
});

XmlTool (xml)

XML operations:

const xmlTool = createTool('xml');
const parsed = await xmlTool.execute({
  operation: 'parse',
  data: '<root><name>John</name></root>'
});

DateTimeTool (datetime)

Date/time operations:

const dtTool = createTool('datetime');

// Get current time
const now = await dtTool.execute({ operation: 'now' });

// Add time
const future = await dtTool.execute({
  operation: 'add',
  date: '2024-01-01',
  amount: 7,
  unit: 'days'
});

// Calculate difference
const diff = await dtTool.execute({
  operation: 'diff',
  date: '2024-01-01',
  date2: '2024-12-31'
});

TextTool (text)

Text manipulation:

const textTool = createTool('text');

// Count words
const count = await textTool.execute({
  operation: 'count',
  text: 'Hello world'
});

// Convert case
const converted = await textTool.execute({
  operation: 'case',
  text: 'hello world',
  caseType: 'title'
});

// Search and replace
const replaced = await textTool.execute({
  operation: 'replace',
  text: 'Hello world',
  search: 'world',
  replacement: 'stick.ai'
});

Agent Configuration

interface AgentConfig {
  name: string;
  version: string;
  description: string;
  capabilities: string[];
  tools: string[];
  instructions: string;
  environment: {
    maxTokens?: number;
    temperature?: number;
    topP?: number;
    frequencyPenalty?: number;
    presencePenalty?: number;
  };
  memory?: {
    enabled: boolean;
    maxHistory?: number;
    persistencePath?: string;
    contextWindow?: number;
  };
  security?: {
    sandboxed?: boolean;
    allowedDomains?: string[];
    rateLimiting?: {
      requestsPerMinute?: number;
      requestsPerHour?: number;
    };
  };
}

Creating Custom Tools

import { BaseTool } from '@stick-ai/runtime';

class MyCustomTool extends BaseTool {
  constructor() {
    super({
      name: 'my-tool',
      description: 'My custom tool',
      parameters: { input: 'string' }
    });
  }

  async execute(params: { input: string }): Promise<any> {
    // Your tool logic here
    return {
      success: true,
      result: `Processed: ${params.input}`
    };
  }
}

// Register with agent
const myTool = new MyCustomTool();
agent.registerTool('my-tool', myTool);

Advanced Usage

Conversation History

// Get conversation history
const history = agent.getHistory();
console.log(history);
// [{ role: 'user', content: '...', timestamp: Date },
//  { role: 'assistant', content: '...', timestamp: Date }]

Multiple Agents

const researcher = new Agent({ name: 'researcher', ... });
const writer = new Agent({ name: 'writer', ... });

// Orchestrate multiple agents
const research = await researcher.run('Research AI trends');
const article = await writer.run(`Write article about: ${research}`);

API Reference

Agent Class

new Agent(config: AgentConfig)

Create a new agent instance.

agent.run(input: string): Promise<string>

Run the agent with user input.

agent.registerTool(name: string, tool: BaseTool): void

Register a tool with the agent.

agent.getHistory(): Message[]

Get conversation history.

agent.getConfig(): AgentConfig

Get agent configuration.

Tools

createTool(name: string): BaseTool

Create a built-in tool by name.

Available tools: 'bash', 'http', 'file-ops', 'json', 'python', 'database', 'email', 'web-scraper', 'csv', 'github', 'slack', 'xml', 'datetime', 'text'

TypeScript Support

Full TypeScript definitions included:

import type { Agent, AgentConfig, Message, BaseTool } from '@stick-ai/runtime';

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0 (for development)

License

MIT

Links

• Documentation
• GitHub
• CLI Package
• Website

Support

• 📧 Email: [email protected]
• 💬 Discord: discord.gg/stickai
• 🐛 Issues: github.com/stickai/framework/issues

Built with ❤️ by the stick.ai team