Installation and quick start

Requirements

• Node.js 18.18 or newer
• An API key for at least one model provider (OPENAI_API_KEY is the default path)

npm install shirube-ai zod

Optional: npm install mem0ai for hosted long-term memory. You can also set ANTHROPIC_API_KEY / GEMINI_API_KEY for other providers.

Your first agent

An agent is three things: who it is (name + instructions), how it thinks (model or auto-routing), and what it can do (tools). run() sends a user message through the loop and returns a final string plus metadata.

import { Agent, tool } from "shirube-ai";
import { z } from "zod";

const weather = tool({
  name: "get_weather",
  description: "Current weather for a city. Use when the user asks about temperature or conditions.",
  parameters: z.object({ city: z.string() }),
  execute: async ({ input }) => ({ city: input.city, tempC: 21, condition: "clear" }),
});

const agent = Agent.builder()
  .name("assistant")
  .instructions("You are concise. Call get_weather instead of guessing.")
  .apiKey(process.env.OPENAI_API_KEY!)
  .tools([weather])
  .build();

const result = await agent.run("Weather in Paris?");
console.log(result.output);
console.log(result.model, result.turns, result.runId);

run(agent, input) is the same API in function form, if you prefer that style.

What just happened

1. 1
   Input guardrails

   Shirube ran jailbreak / PII / size checks — on unless you .security(false).

2. 2
   Model + tool

   The model asked for get_weather with { "city": "Paris" }. Zod validated the arguments; execute ran; the JSON result went back to the model.

3. 3
   Final answer

   The model produced a final sentence. Output guardrails ran. You got result.output.

Config object instead of builder

const agent = Agent.create({
  name: "assistant",
  instructions: "Be concise.",
  apiKey: process.env.OPENAI_API_KEY,
  tools: [weather],
});

How an agent run works

1. Input guardrails — reject jailbreaks, redact PII, enforce size limits.
2. Load context — session history, long-term memory hits, graph facts for this user.
3. Pick a model — the one you configured, or a routed GPT based on prompt complexity.
4. Loop — send messages to the LLM. If it requests a tool, validate args, optionally require approval, execute, send the result back. Repeat until a final answer or maxTurns / timeout.
5. Output guardrails — block leaks; optionally validate JSON against a Zod schema (and repair).
6. Persist — write memory, append the session, queue graph extraction. Graph workers run in the background so this step does not wait on them.

You always get a RunResult: text (and optional parsed JSON), which agent finished, model used, token usage, traces, and events.