Agentium

AI Agent framework for Node.js powered by node-llama-cpp

Agent framework to build AI agents with RAG, function calling, MCP, embeddings, memory, and structured output — built on top of node-llama-cpp.

Install

npm install agentium

Quick Start

import { Model, Agent, Tool, z, ConversationMemory } from "agentium";

const model = new Model({
  path: "./models/Qwen2.5-7B-Instruct-Q4_K_M.gguf",
  gpuLayers: 99,
});
await model.init();

const weatherTool = Tool.define({
  name: "get_weather",
  description: "Get current weather in a city",
  parameters: z.object({
    city: z.string().describe("City name"),
    unit: z.enum(["celsius", "fahrenheit"]).optional(),
  }),
  execute: async ({ city, unit }) => {
    return { temperature: 25, city, unit: unit || "celsius" };
  },
});

const agent = new Agent({
  model,
  systemPrompt: "You are a helpful assistant.",
  tools: [weatherTool],
  memory: new ConversationMemory(),
  temperature: 0.7,
});

// Non-stream
const result = await agent.run("What is the weather in São Paulo?");
console.log(result.text);

API

const { Model, Agent, Tool, z, ConversationMemory, VectorMemory, EmbeddingService, StructuredOutput, McpClient, setLogLevel } from "agentium";

Model

const model = new Model({ path, gpuLayers, contextSize });
await model.init();

Agent

const agent = new Agent({ model, systemPrompt, tools, memory, temperature, maxTokens });
const result = await agent.run("message");

for await (const event of agent.stream("message")) {
  if (event.type === "token") process.stdout.write(event.text);
  if (event.type === "done") console.log(event.text);
}

Tool

// Zod schema
const tool = Tool.define({ name, description, parameters: z.object({...}), execute: async (params) => {} });

// JSON Schema
const tool = Tool.fromJsonSchema({ name, description, inputSchema, execute: async (params) => {} });

Embeddings + RAG

const model = new Model({ path: "./models/bge-small-en-v1.5-q8_0.gguf" });
await model.init();
const embedding = new EmbeddingService({ model });
await embedding.init();
const results = await embedding.search("query", documents, topK);

Structured Output

const schema = z.object({ sentiment: z.enum(["positive", "negative", "neutral"]), confidence: z.number() });
const result = await StructuredOutput.prompt(model, "I love this!", schema);
console.log(result.parsed);

MCP

const mcp = new McpClient();
await mcp.connectStdio("npx", ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]);
const mcpTools = await mcp.listTools();
const agent = new Agent({ model, tools: mcpTools });

Dependencies

• node-llama-cpp ^3.18.1
• zod ^3.24.0
• zod-to-json-schema ^3.24.0
• @modelcontextprotocol/sdk ^1.29.0