@arcaelas/agent

Advanced AI agent library with multi-provider support, reactive contexts, and intelligent tool orchestration.

Modern AI Agent Architecture for Enterprise Applications

@arcaelas/agent is a production-ready TypeScript library that enables developers to build sophisticated conversational AI agents with enterprise-grade features. Our architecture combines reactive context inheritance, intelligent multi-provider failover, and extensible tool orchestration to create agents that scale from simple chatbots to complex organizational workflows.

Why Choose @arcaelas/agent?

🔄 Intelligent Failover: Automatic provider switching ensures 99.9% uptime across OpenAI, Anthropic, Groq, and custom APIs
🏗️ Reactive Architecture: Context inheritance system that scales from individual agents to enterprise-wide organizational hierarchies
🛠️ Tool Ecosystem: Built-in HTTP tools, time utilities, and seamless custom function integration with parallel execution
💎 Type Safety: Full TypeScript support with discriminated unions, generics, and comprehensive IDE integration
⚡ Performance First: Optimized for high-throughput applications with intelligent load balancing and memory management
🎯 Developer Experience: Intuitive API design that reduces complexity while maintaining full control over agent behavior

📖 Table of Contents

🚀 Get Started

Installation

@arcaelas/agent supports multiple installation methods for different environments:

Package Managers

# npm (recommended)
npm install @arcaelas/agent

# yarn
yarn add @arcaelas/agent

# pnpm
pnpm add @arcaelas/agent

# bun
bun add @arcaelas/agent

CDN (Browser)

<!-- ES Modules -->
<script type="module">
  import { Agent, Tool } from 'https://cdn.skypack.dev/@arcaelas/agent';
</script>

<!-- UMD (Global) -->
<script src="https://unpkg.com/@arcaelas/agent/dist/index.umd.js"></script>
<script>
  const { Agent, Tool } = ArcaelasAgent;
</script>

Requirements

Node.js ≥ 16.0.0
TypeScript ≥ 4.5.0 (for TypeScript projects)
Modern Browser (ES2020+ support for browser usage)

Basic Setup

Environment Configuration

Create a .env file in your project root:

# OpenAI
OPENAI_API_KEY=your_openai_api_key

# Anthropic (optional)
ANTHROPIC_API_KEY=your_anthropic_api_key

# Groq (optional)
GROQ_API_KEY=your_groq_api_key

TypeScript Configuration

Ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

First Agent

Create your first AI agent in 3 simple steps:

Step 1: Import and Setup

import { Agent } from '@arcaelas/agent';
import OpenAI from 'openai';

// Initialize your AI provider
const openai = new OpenAI({
  baseURL: "https://api.openai.com/v1",
  apiKey: process.env.OPENAI_API_KEY
});

Step 2: Create Agent

const assistant = new Agent({
  name: "Personal_Assistant",
  description: "Helpful assistant for daily tasks and questions",
  providers: [
    async (ctx) => {
      return await openai.chat.completions.create({
        model: "gpt-4",
        messages: ctx.messages.map(m => ({
          role: m.role,
          content: m.content
        }))
      });
    }
  ]
});

Step 3: Start Conversation

// Simple interaction
const [messages, success] = await assistant.call("What's the weather like today?");

if (success) {
  const response = messages[messages.length - 1].content;
  console.log("Assistant:", response);
} else {
  console.log("Failed to get response");
}

Verification

Test your installation with this complete example:

import { Agent, Tool } from '@arcaelas/agent';
import OpenAI from 'openai';

// Create a simple time tool
const time_tool = new Tool("get_current_time", async (agent) => {
  return new Date().toLocaleString();
});

// Create agent with tool
const agent = new Agent({
  name: "Time_Assistant",
  description: "Assistant that can tell the current time",
  tools: [time_tool],
  providers: [
    async (ctx) => {
      const openai = new OpenAI({
        baseURL: "https://api.openai.com/v1",
        apiKey: process.env.OPENAI_API_KEY
      });

      return await openai.chat.completions.create({
        model: "gpt-4",
        messages: ctx.messages.map(m => ({ role: m.role, content: m.content })),
        tools: ctx.tools?.map(tool => ({
          type: "function",
          function: {
            name: tool.name,
            description: tool.description,
            parameters: {
              type: "object",
              properties: tool.parameters
            }
          }
        }))
      });
    }
  ]
});

// Test the agent
console.log("Testing agent...");
const [conversation, success] = await agent.call("What time is it?");

if (success) {
  console.log("✅ Installation successful!");
  console.log("Response:", conversation[conversation.length - 1].content);
} else {
  console.log("❌ Installation failed. Check your API key.");
}

Expected Output:

Testing agent...
✅ Installation successful!
Response: The current time is [current date and time].

💡 Use Cases & Examples

Simple Agent

Perfect for getting started with basic conversational AI:

import { Agent } from '@arcaelas/agent';
import OpenAI from 'openai';

// Create a simple chatbot
const chatbot = new Agent({
  name: "Simple_Chatbot",
  description: "Friendly assistant for basic questions and conversations",
  providers: [
    async (ctx) => {
      const openai = new OpenAI({
        baseURL: "https://api.openai.com/v1",
        apiKey: process.env.OPENAI_API_KEY
      });

      return await openai.chat.completions.create({
        model: "gpt-3.5-turbo",
        messages: ctx.messages.map(m => ({
          role: m.role,
          content: m.content
        }))
      });
    }
  ]
});

// Use the chatbot
const [conversation, success] = await chatbot.call("Tell me a joke about programming");
console.log("Bot:", conversation[conversation.length - 1].content);

Advanced Multi-Provider

Production-ready setup with automatic failover and tools:

import { Agent, Tool, TimeTool } from '@arcaelas/agent';
import OpenAI from 'openai';
import Anthropic from '@anthropic-ai/sdk';

// Create utility tools
const weather_tool = new Tool("get_weather", {
  description: "Get current weather for any city",
  parameters: {
    city: "City name (e.g., 'London', 'New York')",
    units: "Temperature units: 'celsius' or 'fahrenheit'"
  },
  func: async (agent, params) => {
    // Mock weather API call
    const temp = params.units === 'celsius' ? '22°C' : '72°F';
    return `Weather in ${params.city}: Sunny, ${temp}`;
  }
});

const time_tool = new TimeTool({ time_zone: "America/New_York" });

// Multi-provider agent with tools
const advanced_agent = new Agent({
  name: "Advanced_Assistant",
  description: "Intelligent assistant with weather and time capabilities",
  tools: [weather_tool, time_tool],
  providers: [
    // Primary: OpenAI GPT-4
    async (ctx) => {
      const openai = new OpenAI({
        baseURL: "https://api.openai.com/v1",
        apiKey: process.env.OPENAI_API_KEY
      });

      return await openai.chat.completions.create({
        model: "gpt-4",
        messages: ctx.messages.map(m => ({ role: m.role, content: m.content })),
        tools: ctx.tools?.map(tool => ({
          type: "function",
          function: {
            name: tool.name,
            description: tool.description,
            parameters: {
              type: "object",
              properties: tool.parameters
            }
          }
        }))
      });
    },

    // Backup: Anthropic Claude
    async (ctx) => {
      const anthropic = new Anthropic({
        apiKey: process.env.ANTHROPIC_API_KEY
      });

      return await anthropic.messages.create({
        model: "claude-3-sonnet-20240229",
        max_tokens: 4000,
        messages: ctx.messages.map(m => ({
          role: m.role === "system" ? "user" : m.role,
          content: m.content
        }))
      });
    }
  ]
});

// Test with tool usage
const [messages, success] = await advanced_agent.call(
  "What's the weather like in Tokyo and what time is it in New York?"
);

Enterprise Architecture

Scalable setup for organizational use with context inheritance:

import { Agent, Context, Metadata, Rule, Tool } from '@arcaelas/agent';

// Organization-wide base context
const company_context = new Context({
  metadata: new Metadata()
    .set("organization", "Acme Corp")
    .set("compliance_level", "enterprise")
    .set("data_retention", "7_years"),
  rules: [
    new Rule("Maintain professional communication"),
    new Rule("Protect confidential information"),
    new Rule("Log all interactions for audit purposes")
  ]
});

// Department-specific context
const sales_context = new Context({
  context: company_context, // Inherits from company
  metadata: new Metadata()
    .set("department", "Sales")
    .set("target_region", "North America"),
  tools: [
    new Tool("get_customer_info", {
      description: "Retrieve customer information from CRM",
      parameters: {
        customer_id: "Customer ID or email address"
      },
      func: async (agent, params) => {
        // Mock CRM integration
        return `Customer ${params.customer_id}: Premium tier, active since 2023`;
      }
    }),

    new Tool("create_quote", {
      description: "Generate sales quote for products",
      parameters: {
        products: "Comma-separated list of product names",
        customer_tier: "Customer tier: 'standard', 'premium', or 'enterprise'"
      },
      func: async (agent, params) => {
        // Mock quote generation
        const discount = params.customer_tier === 'enterprise' ? '15%' : '5%';
        return `Quote generated for ${params.products} with ${discount} discount`;
      }
    })
  ]
});

// Specialized sales agent
const sales_agent = new Agent({
  name: "Sales_Specialist",
  description: "Expert sales representative with CRM access and pricing tools",
  contexts: sales_context, // Inherits complete hierarchy
  providers: [
    async (ctx) => {
      const openai = new OpenAI({
        baseURL: "https://api.openai.com/v1",
        apiKey: process.env.OPENAI_API_KEY
      });

      // Build system message with context
      const system_message = `You are a ${ctx.metadata.get("department")} representative for ${ctx.metadata.get("organization")}.

Rules:
${ctx.rules.map(rule => `- ${rule.description}`).join('\n')}

Available tools: ${ctx.tools?.map(t => t.name).join(', ')}`;

      return await openai.chat.completions.create({
        model: "gpt-4",
        messages: [
          { role: "system", content: system_message },
          ...ctx.messages.map(m => ({ role: m.role, content: m.content }))
        ],
        tools: ctx.tools?.map(tool => ({
          type: "function",
          function: {
            name: tool.name,
            description: tool.description,
            parameters: {
              type: "object",
              properties: tool.parameters
            }
          }
        }))
      });
    }
  ]
});

// Sales interaction example
const [conversation, success] = await sales_agent.call(
  "I need a quote for our enterprise software package for customer john@company.com"
);

// The agent has access to:
// - Company policies and compliance rules
// - Sales department tools and metadata
// - CRM integration and quote generation
// - Professional communication guidelines

🏗️ Core Architecture

@arcaelas/agent is built on four core principles that enable scalable, maintainable AI agent development:

Agent System

The Agent is the central orchestrator that combines identity, behavior, tools, and intelligence providers into a cohesive conversational experience.

Context Inheritance

Reactive Context System provides hierarchical state management where child contexts automatically inherit parent properties while maintaining their own specialized behavior.

Tool Orchestration

Extensible Tool System allows agents to execute custom functions, make HTTP requests, and interact with external services through a unified interface.

Provider Management

Multi-Provider Architecture ensures high availability through automatic failover across OpenAI, Anthropic, Groq, and custom AI endpoints.

📘 API Reference

📌 Agent Class - Main orchestrator for AI conversations

Constructor

new Agent(options: AgentOptions)

AgentOptions Interface

interface AgentOptions {
  name: string;                           // Unique agent identifier
  description: string;                    // Behavioral personality description
  metadata?: Metadata | Metadata[];      // Initial metadata
  tools?: Tool | Tool[];                  // Available tools
  rules?: Rule | Rule[];                  // Behavioral rules
  messages?: Message | Message[];         // Conversation history
  contexts?: Context | Context[];         // Parent contexts for inheritance
  providers?: ProviderFunction[];         // AI model provider functions
}

Properties

readonly name: string - Agent identifier
readonly description: string - Agent behavior description
metadata: Metadata - Reactive metadata with inheritance
rules: Rule[] - Combined inherited and local rules
tools: Tool[] - Deduplicated tools by name (latest wins)
messages: Message[] - Full conversation history
providers: ProviderFunction[] - Configured AI provider functions

Methods

async call(prompt: string): Promise<[Message[], boolean]>

Processes user input with automatic tool execution and provider failover.

Returns: Tuple of [conversation_messages, success_status]

Example

const agent = new Agent({
  name: "Assistant",
  description: "Helpful AI assistant",
  providers: [
    async (ctx) => {
      const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
      return await openai.chat.completions.create({
        model: "gpt-4",
        messages: ctx.messages.map(m => ({ role: m.role, content: m.content }))
      });
    }
  ]
});

🔗 Context Class - Hierarchical state management

Constructor

new Context(options: ContextOptions)

ContextOptions Interface

interface ContextOptions {
  context?: Context | Context[];         // Parent contexts
  metadata?: Metadata | Metadata[];     // Metadata sources
  rules?: Rule | Rule[];                 // Behavioral rules
  tools?: Tool | Tool[];                 // Available tools
  messages?: Message | Message[];        // Message history
}

Properties

metadata: Metadata - Reactive metadata with inheritance
rules: Rule[] - Combined rules from hierarchy
tools: Tool[] - Deduplicated tools (child overrides parent)
messages: Message[] - Combined message history

Example

const base_context = new Context({
  metadata: new Metadata().set("company", "Acme Corp"),
  rules: [new Rule("Maintain professional tone")]
});

const team_context = new Context({
  context: base_context,  // Inherits from base
  metadata: new Metadata().set("team", "Engineering"),
  tools: [new Tool("deploy", async (agent, env) => `Deployed to ${env}`)]
});

📊 Metadata Class - Key-value state management with inheritance

Constructor

new Metadata(...children: (Metadata | Metadata[])[])

Methods

get(key: string, fallback?: string | null): string | null
has(key: string): boolean
set(key: string, value: string | null | undefined): this
delete(key: string): this
clear(): this
use(...nodes: (Metadata | Metadata[])[]): this
all(): Record<string, string>

Example

const parent_metadata = new Metadata()
  .set("organization", "Acme Corp")
  .set("tier", "enterprise");

const child_metadata = new Metadata(parent_metadata)
  .set("department", "Sales")
  .set("region", "North America");

console.log(child_metadata.get("organization")); // "Acme Corp" (inherited)
console.log(child_metadata.get("department"));   // "Sales" (local)

🛠️ Tool Class - Function execution system

Constructors

// Simple tool
new Tool(name: string, handler: (agent: Agent, input: string) => any)

// Advanced tool
new Tool<T>(name: string, options: ToolOptions<T>)

ToolOptions Interface

interface ToolOptions<T = Record<string, string>> {
  description: string;                          // Tool functionality description
  parameters?: T;                               // Parameter schema object
  func: (agent: Agent, params: T) => string | Promise<string>; // Execution function
}

Properties

readonly name: string - Unique tool identifier
readonly description: string - Functionality description
readonly parameters: T | { input: string } - Parameter schema
readonly func: Function - Execution function

Examples

// Simple tool
const time_tool = new Tool("get_time", async (agent) => {
  return new Date().toLocaleString();
});

// Advanced tool with parameters
const calculator = new Tool("calculate", {
  description: "Perform mathematical calculations",
  parameters: {
    expression: "Mathematical expression to evaluate",
    precision: "Number of decimal places (optional)"
  },
  func: async (agent, params) => {
    const result = eval(params.expression);
    const precision = parseInt(params.precision) || 2;
    return result.toFixed(precision);
  }
});

📨 Message Class - Type-safe conversation handling

Constructor

new Message(options: MessageOptions)

MessageOptions (Union Type)

type MessageOptions =
  | { role: "user"; content: string; }
  | { role: "assistant"; content: string; }
  | { role: "system"; content: string; }
  | { role: "tool"; content: string; tool_call_id: string; };

Properties

readonly role: MessageRole - Message role
readonly content: string - Message content
readonly tool_call_id?: string - Tool ID (for tool messages)
readonly timestamp: Date - Creation timestamp
readonly length: number - Content length

Example

const user_msg = new Message({
  role: "user",
  content: "What's the weather like?"
});

const tool_msg = new Message({
  role: "tool",
  content: "Sunny, 22°C",
  tool_call_id: "weather_123"
});

console.log(user_msg.timestamp); // Date object
console.log(user_msg.length);    // 23

📋 Rule Class - Behavioral constraints and guidelines

Constructors

// Always active rule
new Rule(description: string)

// Conditional rule
new Rule(description: string, options: RuleOptions)

RuleOptions Interface

interface RuleOptions {
  when: (ctx: Agent) => boolean | Promise<boolean>; // Evaluation function
}

Properties

readonly description: string - Rule description
readonly when: Function - Evaluation function

Examples

// Always active rule
const professional_rule = new Rule("Maintain professional communication tone");

// Conditional rule
const business_hours_rule = new Rule(
  "Outside business hours, inform customer of support availability",
  {
    when: (agent) => {
      const hour = new Date().getHours();
      return hour < 9 || hour > 17;
    }
  }
);

// Async conditional rule
const premium_rule = new Rule(
  "Offer priority support features",
  {
    when: async (agent) => {
      const tier = agent.metadata.get("customer_tier");
      return tier === "premium" || tier === "enterprise";
    }
  }
);

🌐 RemoteTool Class - HTTP API integration

Constructor

new RemoteTool(name: string, options: RemoteToolOptions)

RemoteToolOptions Interface

interface RemoteToolOptions {
  description: string;
  parameters?: Record<string, string>;
  http: {
    method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
    url: string;
    headers?: Record<string, string>;
  };
}

Features

Automatic JSON serialization of arguments
Support for all HTTP methods
Custom headers and authentication
Returns response as plain text

Example

import { RemoteTool } from '@arcaelas/agent';

const weather_api = new RemoteTool("get_weather", {
  description: "Get current weather for a city",
  parameters: {
    city: "City name (e.g., 'London', 'Tokyo')",
    units: "Temperature units: 'metric' or 'imperial'"
  },
  http: {
    method: "GET",
    url: "https://api.weather.com/v1/current",
    headers: {
      "Authorization": "Bearer your_api_key",
      "Content-Type": "application/json"
    }
  }
});

// Usage in agent
const agent = new Agent({
  name: "Weather_Assistant",
  description: "Assistant with weather capabilities",
  tools: [weather_api]
});

⏰ TimeTool Class - Timezone-aware time utilities

Constructor

new TimeTool(options?: TimeToolOptions)

TimeToolOptions Interface

interface TimeToolOptions {
  time_zone?: string; // IANA timezone (e.g., "America/New_York", "Europe/London")
}

Features

Automatic system timezone detection
IANA timezone support
Consistent "en-US" formatting
ISO date handling

Examples

import { TimeTool } from '@arcaelas/agent';

// System timezone
const local_time = new TimeTool();

// Specific timezones
const tokyo_time = new TimeTool({ time_zone: "Asia/Tokyo" });
const london_time = new TimeTool({ time_zone: "Europe/London" });
const ny_time = new TimeTool({ time_zone: "America/New_York" });

// Usage in agent
const global_agent = new Agent({
  name: "Global_Assistant",
  description: "Assistant with multi-timezone awareness",
  tools: [local_time, tokyo_time, london_time, ny_time]
});

// Agent can now tell time in multiple zones
await global_agent.call("What time is it in Tokyo and London?");

🔧 Provider Function - AI model integration

Type Definition

type ProviderFunction = (
  ctx: Context
) => ChatCompletionResponse | Promise<ChatCompletionResponse>;

ChatCompletionResponse Interface

interface ChatCompletionResponse {
  id: string;
  object: "chat.completion";
  created: number;
  model: string;
  choices: CompletionChoice[];
  usage?: CompletionUsage;
}

interface CompletionChoice {
  index: number;
  message: ResponseMessage;
  finish_reason: "stop" | "length" | "tool_calls" | "content_filter" | null;
}

interface ResponseMessage {
  role: "assistant";
  content: string | null;
  tool_calls?: Array<{
    id: string;
    type: "function";
    function: { name: string; arguments: string; };
  }> | null;
}

Examples

// OpenAI Provider
const openai_provider: ProviderFunction = async (ctx) => {
  const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
  return await openai.chat.completions.create({
    model: "gpt-4",
    messages: ctx.messages.map(m => ({ role: m.role, content: m.content })),
    tools: ctx.tools?.map(tool => ({
      type: "function",
      function: {
        name: tool.name,
        description: tool.description,
        parameters: { type: "object", properties: tool.parameters }
      }
    }))
  });
};

// Anthropic Provider
const claude_provider: ProviderFunction = async (ctx) => {
  const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
  const response = await anthropic.messages.create({
    model: "claude-3-sonnet-20240229",
    max_tokens: 4000,
    messages: ctx.messages.map(m => ({
      role: m.role === "system" ? "user" : m.role,
      content: m.content
    }))
  });

  // Convert to OpenAI format
  return {
    id: response.id,
    object: "chat.completion",
    created: Date.now(),
    model: "claude-3-sonnet-20240229",
    choices: [{
      index: 0,
      message: {
        role: "assistant",
        content: response.content[0].text
      },
      finish_reason: "stop"
    }]
  };
};

// Multi-provider agent
const resilient_agent = new Agent({
  name: "Resilient_Assistant",
  description: "High-availability assistant with automatic failover",
  providers: [openai_provider, claude_provider]
});

🎯 Performance Tips

Memory Optimization

// Trim conversation history for production
function manage_conversation_memory(agent: Agent, max_messages: number = 100) {
  if (agent.messages.length > max_messages) {
    const system_msgs = agent.messages.filter(m => m.role === "system");
    const recent_msgs = agent.messages.slice(-max_messages + system_msgs.length);
    agent.messages = [...system_msgs, ...recent_msgs];
  }
}

// Use in production environments
setInterval(() => manage_conversation_memory(production_agent), 300000);

Provider Optimization

// Load balancing with health checks
const optimized_providers = [
  async (ctx) => {
    try {
      const openai = new OpenAI({ timeout: 30000, apiKey: process.env.OPENAI_API_KEY });
      return await openai.chat.completions.create({
        model: "gpt-4-turbo",
        messages: ctx.messages.map(m => ({ role: m.role, content: m.content }))
      });
    } catch (error) {
      throw new Error(`OpenAI failed: ${error.message}`);
    }
  },
  // Additional providers...
];

Tool Caching

const cached_tool = new Tool("expensive_computation", {
  description: "Cached computation for better performance",
  parameters: { data: "Input data for processing" },
  func: async (agent, params) => {
    const cache_key = `compute_${JSON.stringify(params.data)}`;
    const cached_result = cache.get(cache_key);

    if (cached_result) return cached_result;

    const result = await heavy_computation(params.data);
    cache.set(cache_key, result, 3600); // 1 hour TTL
    return result;
  }
});

❓ Troubleshooting

Common Issues

Provider Connection Errors

// Check API key validity
const test_provider = async (ctx) => {
  try {
    const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
    const response = await openai.models.list();
    console.log("✅ API connection successful");
    return response;
  } catch (error) {
    console.error("❌ API connection failed:", error.message);
    throw error;
  }
};

Tool Execution Failures

// Debug tool execution
const debug_tool = new Tool("debug_example", {
  description: "Tool with comprehensive error handling",
  parameters: { input: "Test input" },
  func: async (agent, params) => {
    try {
      console.log("Tool input:", params);
      const result = await risky_operation(params.input);
      console.log("Tool output:", result);
      return result;
    } catch (error) {
      console.error("Tool error:", error);
      return `Error: ${error.message}`;
    }
  }
});

Context Inheritance Issues

// Verify context chain
function debug_context_chain(context: Context) {
  console.log("Metadata:", context.metadata.all());
  console.log("Rules:", context.rules.map(r => r.description));
  console.log("Tools:", context.tools.map(t => t.name));
}

Environment Setup

# Verify Node.js version
node --version  # Should be >= 16.0.0

# Check TypeScript installation
tsc --version   # Should be >= 4.5.0

# Validate environment variables
echo $OPENAI_API_KEY | cut -c1-10  # Should show: sk-proj-...

🔧 Migration Guide

v1.x to v2.x Migration

Step-by-step migration process

1. Update Dependencies

npm uninstall @arcaelas/agent@1.x
npm install @arcaelas/agent@latest

2. Update Agent Configuration

// Before (v1.x)
const agent = new Agent({
  name: "Assistant",
  personality: "helpful and professional",
  tools: {
    calculator: calculatorFunction,
    weather: weatherFunction
  },
  providers: [
    {
      base_url: "https://api.openai.com/v1",
      model: "gpt-4",
      api_key: process.env.OPENAI_API_KEY,
      func: openaiFunction
    }
  ]
});

// After (v2.x)
const agent = new Agent({
  name: "Assistant",
  description: "Helpful and professional assistant",
  tools: [
    new Tool("calculator", {
      description: "Perform mathematical calculations",
      parameters: { expression: "Math expression to evaluate" },
      func: calculatorFunction
    }),
    new Tool("weather", {
      description: "Get weather information",
      parameters: { location: "City name or coordinates" },
      func: weatherFunction
    })
  ],
  providers: [
    async (ctx) => {
      const openai = new OpenAI({
        baseURL: "https://api.openai.com/v1",
        apiKey: process.env.OPENAI_API_KEY
      });
      return await openai.chat.completions.create({
        model: "gpt-4",
        messages: ctx.messages.map(m => ({ role: m.role, content: m.content }))
      });
    }
  ]
});

3. Update Message Handling

// Before (v1.x)
const response = await agent.ask("Hello");

// After (v2.x)
const [messages, success] = await agent.call("Hello");
if (success) {
  const response = messages[messages.length - 1].content;
}

Key Breaking Changes

Property Names: personality → description
Tool Format: Plain objects → Tool class instances
Provider Format: Config objects → Functions returning ChatCompletionResponse
Response Format: String response → [Message[], boolean] tuple
Import Changes: Some built-in tools moved to separate exports

🤝 Contributing

We welcome contributions from the community! Here's how you can help improve @arcaelas/agent:

Quick Start for Contributors

# Fork the repository on GitHub, then:
git clone https://github.com/your-username/agent.git
cd agent

# Install dependencies
npm install

# Create a feature branch
git checkout -b feature/your-feature-name

# Make your changes and test
npm run test
npm run build
npm run lint

# Commit and push
git commit -m "feat: add your feature description"
git push origin feature/your-feature-name

# Create a Pull Request on GitHub

Development Workflow

Local Development

# Watch mode for development
npm run dev

# Run tests with coverage
npm run test:coverage

# Type checking
npm run type-check

# Linting and formatting
npm run lint
npm run format

Testing Guidelines

// Example test structure
import { Agent, Tool } from '../src';

describe('Agent Core Functionality', () => {
  test('should create agent with tools', async () => {
    const test_tool = new Tool("test", async (agent) => "test result");
    const agent = new Agent({
      name: "Test_Agent",
      description: "Test agent",
      tools: [test_tool]
    });

    expect(agent.tools).toHaveLength(1);
    expect(agent.tools[0].name).toBe("test");
  });
});

Code Standards

TypeScript: Strict mode enabled with comprehensive type safety
Testing: Jest with >95% coverage requirement
Linting: ESLint with Arcaelas configuration
Formatting: Prettier with consistent style
Documentation: JSDoc for all public APIs

Pull Request Guidelines

Clear Description: Explain what your PR does and why
Tests: Include tests for new functionality
Documentation: Update README and JSDoc as needed
Breaking Changes: Clearly mark and document any breaking changes
Performance: Consider performance implications of changes

📄 License

Custom License with Commercial Flexibility

This project is licensed under a custom license designed for maximum flexibility. See LICENSE file for complete details.

License Summary

Use Case	Allowed	Requirements
Personal Projects	✅ Free	None
Educational Use	✅ Free	None
Open Source Projects	✅ Free	None
Commercial Applications	✅ Allowed	Attribution required
SaaS/Cloud Services	✅ Allowed	Attribution + notification
Enterprise Solutions	✅ Allowed	Contact for enterprise license

Restrictions

❌ No Redistribution: Cannot redistribute as competing library
❌ No Trademark Use: Cannot use "Arcaelas" trademark without permission
❌ No Warranty: Software provided "as-is" without warranties

Commercial Licensing

For enterprise use, custom licensing, or removing attribution requirements: 📧 Contact: licensing@arcaelas.com

🆘 Support & Community

💬 Community Resources

Platform	Purpose	Link
Discord	Real-time chat, questions, discussions	Join Community
GitHub Issues	Bug reports, feature requests	Open Issue
GitHub Discussions	Architecture discussions, ideas	Join Discussion
Documentation	Comprehensive guides and tutorials	docs.arcaelas.com
Stack Overflow	Technical Q&A	Tag: `arcaelas-agent`

🏢 Enterprise Support

Professional support for production deployments and enterprise use cases.

Support Tiers

Tier	Response Time	Features	Price
Community	Best effort	Discord, GitHub Issues	Free
Professional	24-48 hours	Email support, architecture review	Contact us
Enterprise	4-8 hours	Phone support, custom development	Contact us
Mission Critical	1-2 hours	Dedicated engineer, SLA guarantees	Contact us

Enterprise Services

🛠️ Custom Development: Tailored features for your specific needs
🏗️ Architecture Review: Expert review of your agent implementation
📚 Training: On-site or remote training for your development team
🔧 Integration Support: Help integrating with your existing systems
📞 Priority Support: Direct access to our engineering team

Contact: enterprise@arcaelas.com

🌟 Contributing to the Community

Help others and improve the ecosystem:

Answer Questions: Help other developers on Discord or GitHub
Share Examples: Submit real-world usage examples
Write Tutorials: Create blog posts or tutorials
Report Issues: Help identify and fix bugs
Suggest Features: Propose new functionality

📈 Changelog & Roadmap

Recent Releases

v1.0.22 (Current)

✨ New: Enhanced provider function typing with better error handling
🔧 Improved: Context inheritance performance optimization
📝 Documentation: Complete README restructure with examples
🐛 Fixed: Tool parameter validation edge cases
🔒 Security: Enhanced input sanitization for tools

v1.0.14

✨ New: TimeTool with comprehensive timezone support
🔧 Improved: RemoteTool error handling and retry logic
📝 Documentation: Expanded API reference with examples
🐛 Fixed: Context metadata inheritance issues

v1.0.13

🚀 New: Multi-provider failover system
⚡ Performance: Optimized memory usage for long conversations
🔒 Security: Enhanced tool execution sandboxing
📊 Monitoring: Better error reporting and logging

Upcoming Features (Roadmap)

v1.1.0 (Q1 2024)

🔌 Plugin System: Extensible plugin architecture
📊 Analytics: Built-in usage analytics and monitoring
🎯 Smart Routing: Intelligent provider selection based on request type
🛡️ Security: Advanced security features and audit logging

v1.2.0 (Q2 2024)

🌐 Multi-Modal: Support for images, audio, and video
🧠 Memory: Long-term memory and knowledge persistence
🔄 Streaming: Real-time streaming responses
📱 Mobile: React Native and mobile platform support

View Complete Changelog

🚀 Ready to Build?

Start creating intelligent AI agents today with @arcaelas/agent

🌟 Star us on GitHub | 🐦 Follow @ArcaelasHQ | 📧 hello@arcaelas.com

Built with ❤️ by Arcaelas Insiders

Empowering developers to create the next generation of AI experiences

Name		Name	Last commit message	Last commit date
Latest commit History 127 Commits
.github/workflows		.github/workflows
docs		docs
overrides		overrides
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
mkdocs.yml		mkdocs.yml
package.json		package.json
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

Uh oh!

License

arcaelas/agent

Folders and files

Latest commit

History

Repository files navigation

@arcaelas/agent

Modern AI Agent Architecture for Enterprise Applications

📖 Table of Contents

Quick Navigation

API Reference

Resources

🚀 Get Started

Installation

Package Managers

CDN (Browser)

Requirements

Basic Setup

Environment Configuration

TypeScript Configuration

First Agent

Step 1: Import and Setup

Step 2: Create Agent

Step 3: Start Conversation

Verification

💡 Use Cases & Examples

Simple Agent

Advanced Multi-Provider

Enterprise Architecture

🏗️ Core Architecture

Agent System

Context Inheritance

Tool Orchestration

Provider Management

📘 API Reference

Constructor

AgentOptions Interface

Properties

Methods

Example

Constructor

ContextOptions Interface

Properties

Example

Constructor

Methods

Example

Constructors

ToolOptions Interface

Properties

Examples

Constructor

MessageOptions (Union Type)

Properties

Example

Constructors

RuleOptions Interface

Properties

Examples

Constructor

RemoteToolOptions Interface

Features

Example

Constructor

TimeToolOptions Interface

Features

Examples

Type Definition

ChatCompletionResponse Interface

Examples

🎯 Performance Tips

Memory Optimization

Provider Optimization

Tool Caching

❓ Troubleshooting

Common Issues

Environment Setup

🔧 Migration Guide

v1.x to v2.x Migration

Packages