Agentium

Build, run, and manage multi-agent systems in Node.js / TypeScript.

Website · Documentation · npm · GitHub · Discord

Agentium is a TypeScript-native agent orchestration framework with zero dependency on meta-frameworks like LangGraph or Vercel AI SDK. It provides a clean, declarative API and a custom model abstraction layer that wraps raw provider SDKs directly.

Install from npm: @agentium/core · full docs at docs.agentium.in

Features

• Model-agnostic — swap between OpenAI, Anthropic, Google Gemini, Ollama, or any OpenAI-compatible API with one line
• Agents — tool-calling loop, session history, memory, guardrails, hooks. Agent.deep() adds project files, skills, workspace, notes, and subagents
• Voice / Realtime Agents — real-time voice conversations over WebSocket
• Sessions & Memory — session history, standing MEMORY.md notes, long-term summaries, vector learnings
• Knowledge Base — vector + BM25 hybrid search with reciprocal rank fusion
• Teams — multi-agent coordination with coordinate, route, broadcast, and collaborate modes
• Workflows — deterministic step execution with typed state, conditions, parallel steps, retry policies
• Toolkit Catalog — 30+ built-in toolkits from @agentium/core/toolkits, with dynamic credential management via Admin API
• Edge & IoT — Raspberry Pi support with GPIO, I2C sensors, camera, BLE, Ollama local LLM
• Transport — Express REST + SSE streaming + Socket.IO real-time + Voice gateway
• Queue — BullMQ-based background job execution with progress tracking
• Storage — pluggable drivers: InMemory, SQLite, PostgreSQL, MongoDB, Redis, DynamoDB
• Observability — OpenTelemetry tracing, Prometheus metrics, Langfuse, structured logs

Packages

Package	npm	Description
@agentium/core		Agents, Teams, Workflows, Models, Tools, Memory, Voice
@agentium/transport		Express router + Socket.IO + Voice/Browser gateways
@agentium/queue		BullMQ background jobs
@agentium/browser		Vision-based browser automation
@agentium/eval		Agent output testing and scoring
@agentium/observability		Tracing, metrics, structured logging
@agentium/admin		Admin CRUD API for runtime agent management
@agentium/edge		IoT toolkits + edge runtime for Raspberry Pi

Quick Start

npm install @agentium/core openai

import { Agent, openai } from "@agentium/core";

const agent = new Agent({
  name: "Assistant",
  model: openai("gpt-4o"),
  instructions: "You are a helpful assistant.",
});

const result = await agent.run("What is the capital of France?");
console.log(result.text);

Agent with Tools

import { Agent, defineTool, openai } from "@agentium/core";
import { z } from "zod";

const weatherTool = defineTool({
  name: "getWeather",
  description: "Get weather for a city",
  parameters: z.object({ city: z.string() }),
  execute: async ({ city }) => `It is sunny in ${city}`,
});

const agent = new Agent({
  name: "WeatherBot",
  model: openai("gpt-4o"),
  tools: [weatherTool],
  instructions: "You help with weather queries.",
});

const result = await agent.run("What's the weather in Tokyo?");

Streaming

for await (const chunk of agent.stream("Tell me a story")) {
  if (chunk.type === "text") process.stdout.write(chunk.text);
}

Teams

import { Agent, Team, TeamMode, openai } from "@agentium/core";

const team = new Team({
  name: "Research Team",
  mode: TeamMode.Coordinate,
  model: openai("gpt-4o"),
  members: [researchAgent, writerAgent, reviewerAgent],
});

const result = await team.run("Write a report on quantum computing.");

Workflows

import { Workflow } from "@agentium/core";

const workflow = new Workflow({
  name: "Pipeline",
  initialState: { topic: "AI", research: "", final: "" },
  steps: [
    { name: "research", agent: searchAgent, inputFrom: (s) => s.topic },
    { name: "write", agent: writerAgent },
    { name: "parallel-review", parallel: [
      { name: "grammar", agent: grammarAgent },
      { name: "fact-check", agent: factAgent },
    ]},
  ],
  retryPolicy: { maxRetries: 2, backoffMs: 1000 },
});

const result = await workflow.run();

Express Server

npm install @agentium/transport express

import express from "express";
import { Agent, openai } from "@agentium/core";
import { createAgentRouter } from "@agentium/transport";

new Agent({ name: "assistant", model: openai("gpt-4o") });

const app = express();
app.use(express.json());
app.use("/api", createAgentRouter());
app.listen(3000);

Generated endpoints:

• POST /api/agents/:name/run — JSON response
• POST /api/agents/:name/stream — SSE stream
• POST /api/teams/:name/run
• POST /api/workflows/:name/run
• GET /api/registry

Socket.IO Real-Time

npm install @agentium/transport socket.io

import { Server as SocketIOServer } from "socket.io";
import { createAgentGateway } from "@agentium/transport";

const io = new SocketIOServer(httpServer);
createAgentGateway({ io });

Events: agent.run → agent.chunk → agent.tool.call → agent.done

Background Jobs

npm install @agentium/queue bullmq ioredis

import { AgentQueue, AgentWorker } from "@agentium/queue";

const queue = new AgentQueue({ connection: { host: "localhost", port: 6379 } });
await queue.enqueueAgentRun({ agentName: "report-gen", input: "Generate Q4 report" });

const worker = new AgentWorker({
  connection: { host: "localhost", port: 6379 },
  agentRegistry: { "report-gen": reportAgent },
});
worker.start();

Storage Drivers

import { InMemoryStorage, SqliteStorage, PostgresStorage } from "@agentium/core";

const storage = new InMemoryStorage();
const storage = new SqliteStorage("agentium.db");
const storage = new PostgresStorage("postgresql://...");

Hooks and Guardrails

const agent = new Agent({
  name: "safe-agent",
  model: openai("gpt-4o"),
  hooks: {
    beforeRun: async (ctx) => console.log("Starting run", ctx.runId),
    afterRun: async (ctx, output) => console.log("Done:", output.text.length, "chars"),
    onToolCall: async (ctx, toolName) => console.log("Calling tool:", toolName),
    onError: async (ctx, error) => console.error("Error:", error.message),
  },
  guardrails: {
    input: [{
      name: "no-pii",
      validate: async (input) =>
        input.includes("SSN") ? { pass: false, reason: "PII detected" } : { pass: true },
    }],
  },
});

Browser Agents

npm install @agentium/browser playwright

import { BrowserAgent } from "@agentium/browser";
import { openai } from "@agentium/core";

const agent = new BrowserAgent({
  model: openai("gpt-4o"),
  instructions: "You are a browser automation assistant.",
  headless: false,
});

const result = await agent.run("Go to github.com and find the agentium repo");
await agent.close();

Model Providers

Provider SDKs are optional peer dependencies — install only what you use:

Project Structure

packages/
  core/           @agentium/core           Agents, Teams, Workflows, Models, Tools, Memory, Voice
  transport/      @agentium/transport      Express + Socket.IO + Voice/Browser gateways
  queue/          @agentium/queue          BullMQ background jobs
  browser/        @agentium/browser        Vision-based browser automation
  eval/           @agentium/eval           Agent output evaluation framework
  observability/  @agentium/observability  Tracing, metrics, structured logging
  admin/          @agentium/admin          Admin CRUD API
  edge/           @agentium/edge           IoT toolkits and edge runtime
benchmarks/       Performance benchmarks
scripts/          Release and utility scripts

Examples and docs live in separate repositories under the agentiumOS org.

Community

Join the conversation on Discord — the fastest place to get help, share what you're building, and discuss roadmap.

Contributing

See CONTRIBUTING.md for setup, development workflow, and PR guidelines.

License

MIT