Overview

AlcorAgent is a TypeScript-first AI agent platform for building intelligent, extensible, and production-ready AI applications. Named after the binary star system Alcor-Mizar, it represents the interconnected nature of multiple subsystems working in harmony.

Rather than being a chatbot or a collection of AI demos, AlcorAgent provides a reusable foundation for creating agents that can reason, use tools, interact with external systems, retrieve knowledge, remember context, and execute complex workflows. The platform follows Clean Architecture principles, ensuring every capability can be replaced, extended, or combined without changing the core engine.

Features

Modular Monorepo Architecture

• pnpm Workspaces: 12 packages with strict dependency rules and no circular dependencies
• Clean Architecture: Business logic never depends on frameworks; interfaces define boundaries
• One Class Per File: Consistent code organization with barrel exports

Pluggable LLM Provider System

• OpenAI: Full support for GPT models with streaming
• Anthropic: Claude model integration via official SDK
• Ollama: Local LLM support for privacy-sensitive workloads
• Provider-Agnostic: Common interface (LLMProvider) allows swapping providers without touching core logic

Extensible Tool System

• Built-in Tools: Calculator, DateTime, Web Search, Web Fetch
• Tool Registry: Central registry with lookup and validation
• Tool Executor: Manages tool lifecycle and error handling
• MCP Adapter: Wraps MCP server tools as native @alcoragent/tools for unified execution

Model Context Protocol Integration

• MCP Client Interface: Abstract MCPClient for connecting to MCP servers
• Tool Adapter: MCPToolAdapter bridges MCP server tools into the native tool system
• Server Management: MCPServerConfig and MCPServerInfo for connection lifecycle

Subsystem Interfaces (Skeleton Implementations)

• Memory: Short-term and long-term memory store interfaces
• Planner: Planning and reasoning interfaces for multi-step execution
• RAG: Knowledge store and retriever interfaces with embedding provider abstraction
• Workflow: Workflow engine interfaces with step definitions and hooks
• Policy: Policy engine for approval workflows and permissions
• Events: Event bus for decoupled communication between subsystems
• Observability: Tracing, logging, and metrics interfaces

Web Chat Interface

• Next.js 16: Server-side rendering with App Router
• React 19: Modern component architecture with Server Components
• Zod: Schema validation for runtime type safety

System Design

Core Components

1. AgentRuntime: Central orchestrator that manages agent lifecycle, session state, and coordinates between the execution engine, tools, and LLM providers.

2. ExecutionEngine: Handles message processing, tool call orchestration, and streaming responses with support for partial results and cancellation.

3. ContextBuilder: Assembles conversation context, system prompts, and tool definitions for LLM requests.

4. Agent: Encapsulates agent configuration, input/output contracts, and session management.

5. ToolRegistry & ToolExecutor: Manage tool registration, lookup, and secure execution with error boundaries.

Provider Layer

• LLM Providers: OpenAI, Anthropic (Claude), Ollama (local) — all implementing the same LLMProvider interface
• Search Provider: Tavily-based web search
• Fetch Provider: HTTP fetching capability

Architecture Layers

┌──────────────────────────────────────┐
│         Web App (Next.js 16)         │
├──────────────────────────────────────┤
│     AgentRuntime + ExecutionEngine   │
├──────────────────────────────────────┤
│   Tool Layer  │  Provider Layer      │
│   Calculator  │  OpenAI / Anthropic  │
│   DateTime    │  Ollama / Tavily     │
│   Web Search  │  HTTP Fetch          │
│   Web Fetch   │                      │
├──────────────────────────────────────┤
│  MCP Adapter  │  Subsystem Interfaces│
│  (Tool Bridge)│  Memory / Planner    │
│               │  RAG / Workflow      │
│               │  Policy / Events     │
│               │  Observability       │
└──────────────────────────────────────┘

Package Architecture

Technology Stack

• Frontend: Next.js 16 with App Router, React 19, Zod
• Runtime: Node.js 24+, TypeScript 6, pnpm 11
• LLM Providers: OpenAI API, Anthropic SDK, Ollama
• Tooling: Vitest for testing, ESLint + Prettier for code quality
• Protocols: Model Context Protocol (MCP) for external tool integration
• Architecture: Clean Architecture, monorepo with pnpm workspaces, strict dependency rules
• Design System: Tailwind CSS (web UI)

Design Philosophy

AlcorAgent is built on the principle that AI is only one component of an intelligent system. An effective AI application also requires reasoning, memory, tools, knowledge retrieval, workflows, planning, observability, and human interaction — each treated as a first-class architectural concept.

The platform prioritizes composition over specialization: new capabilities are created by composing tools, workflows, memories, and planners instead of creating entirely new agents. Every major capability is replaceable — developers can swap LLM providers, embedding providers, vector databases, memory implementations, planners, and MCP servers without affecting unrelated parts of the system.

As a framework, not an application, the same engine powers web applications, CLI tools, background workers, scheduled jobs, bots, APIs, and automation workflows. The chat interface is only one way to interact.