Skip to content

Arcaelas Agent Documentation

Welcome to @arcaelas/agent - a production-ready TypeScript library for building sophisticated AI agents with multi-provider support, reactive contexts, and intelligent tool orchestration.

What is Arcaelas Agent?

@arcaelas/agent enables you to create AI agents that scale from simple chatbots to complex organizational workflows through:

  • 🔄 Multi-Provider Support - Automatic failover between OpenAI, Anthropic, Groq, Ollama, and custom APIs
  • 🏗️ Reactive Architecture - Hierarchical context inheritance with automatic state management
  • 🛠️ Tool Ecosystem - Built-in HTTP tools and seamless custom function integration
  • 💎 Full TypeScript - Complete type safety with discriminated unions and generics

Quick Start

Installation

npm install @arcaelas/agent

Your First Agent

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

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

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

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

Continue with the full tutorial →

Core Architecture

Agent

Central orchestrator combining identity, behavior, tools, and AI providers.

const agent = new Agent({
  rules: [
    new Rule("Customer support specialist."),
    professional_rule,
  ],
  tools: [search_tool, database_tool],
  providers: [openai_provider]
});

Learn more →

Context

Hierarchical state management with automatic inheritance.

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

const child_context = new Context({
  context: parent_context,  // Inherits from parent
  metadata: new Metadata().set("department", "Sales")
});

Learn more →

Tools

Extensible functions for external integrations.

const weather_tool = new Tool("get_weather", {
  description: "Get current weather for any city",
  parameters: {
    city: "City name",
    units: "Temperature units (celsius/fahrenheit)"
  },
  func: async (agent, { city, units }) => {
    return `Weather in ${city}: Sunny, 24°C`;
  }
});

Learn more →

Documentation

📚 Guides

🔧 API Reference

💡 Examples

🎓 Advanced

Requirements

  • Node.js ≥ 16.0.0
  • TypeScript ≥ 4.5.0 (optional)

Ready to build intelligent AI agents? Start with the Getting Started Guide →