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
• Voice / Realtime Agents — real-time voice conversations over WebSocket
• Sessions & Memory — session history, long-term summarization, cross-session user memory
• 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 — 18+ built-in 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";constagent=newAgent({name: "Assistant",model: openai("gpt-4o"),instructions: "You are a helpful assistant.",});constresult=awaitagent.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";constweatherTool=defineTool({name: "getWeather",description: "Get weather for a city",parameters: z.object({city: z.string()}),execute: async({ city })=>`It is sunny in ${city}`,});constagent=newAgent({name: "WeatherBot",model: openai("gpt-4o"),tools: [weatherTool],instructions: "You help with weather queries.",});constresult=awaitagent.run("What's the weather in Tokyo?");

Streaming

forawait(constchunkofagent.stream("Tell me a story")){if(chunk.type==="text")process.stdout.write(chunk.text);}

Teams

import{Agent,Team,TeamMode,openai}from"@agentium/core";constteam=newTeam({name: "Research Team",mode: TeamMode.Coordinate,model: openai("gpt-4o"),members: [researchAgent,writerAgent,reviewerAgent],});constresult=awaitteam.run("Write a report on quantum computing.");

Mode	Behavior
Coordinate	Leader decomposes task, delegates to members, synthesizes outputs
Route	Leader picks one member, returns their response directly
Broadcast	All members get the same task in parallel, leader synthesizes
Collaborate	Members respond concurrently, leader checks consensus, iterates

Workflows

import{Workflow}from"@agentium/core";constworkflow=newWorkflow({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},});constresult=awaitworkflow.run();

Express Server

npm install @agentium/transport express

importexpressfrom"express";import{Agent,openai}from"@agentium/core";import{createAgentRouter}from"@agentium/transport";newAgent({name: "assistant",model: openai("gpt-4o")});constapp=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{ServerasSocketIOServer}from"socket.io";import{createAgentGateway}from"@agentium/transport";constio=newSocketIOServer(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";constqueue=newAgentQueue({connection: {host: "localhost",port: 6379}});awaitqueue.enqueueAgentRun({agentName: "report-gen",input: "Generate Q4 report"});constworker=newAgentWorker({connection: {host: "localhost",port: 6379},agentRegistry: {"report-gen": reportAgent},});worker.start();

Storage Drivers

import{InMemoryStorage,SqliteStorage,PostgresStorage}from"@agentium/core";conststorage=newInMemoryStorage();conststorage=newSqliteStorage("agentium.db");conststorage=newPostgresStorage("postgresql://...");

Hooks and Guardrails

constagent=newAgent({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";constagent=newBrowserAgent({model: openai("gpt-4o"),instructions: "You are a browser automation assistant.",headless: false,});constresult=awaitagent.run("Go to github.com and find the agentium repo");awaitagent.close();

Model Providers

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

Provider	Install	Factory
OpenAI	npm i openai	openai("gpt-4o")
Anthropic	npm i @anthropic-ai/sdk	anthropic("claude-sonnet-4-20250514")
Google Gemini	npm i @google/genai	google("gemini-2.0-flash")
Ollama (local)	npm i ollama	ollama("llama3")
Groq / Together / DeepSeek	npm i openai	openai("model-id", { baseURL, apiKey })

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