Production agents.You own the loop.
Define an agent, give it tools and a model, and Shirube owns the loop — guardrails, memory, graph knowledge, MCP, and observability. Security on by default.
Requires Node 18.18+. Peer: zod. Optional: mem0ai.
import { Agent, tool } from "shirube-ai";
import { z } from "zod";
const weather = tool({
name: "get_weather",
description: "Current weather for a city.",
parameters: z.object({ city: z.string() }),
execute: async ({ input }) => ({ city: input.city, tempC: 21 }),
});
const agent = Agent.builder()
.name("assistant")
.instructions("Be concise. Use tools when you need facts.")
.apiKey(process.env.OPENAI_API_KEY!)
.tools([weather])
.build();
const result = await agent.run("Weather in Paris?");
console.log(result.output);Capabilities
Everything around the loop.
Vendor kits give you a completion cycle. Shirube is the rest of the stack you actually ship.
Agent runtime
User input → model → tools → model → final answer, with turn and time limits you control.
Tools + Zod
Named functions, JSON Schema from Zod, async execute, and human approval that fails closed.
Guardrails on by default
Jailbreak, prompt injection, PII redaction, secret leak, and system-prompt leak — input, tool, and output.
Handoffs
Triage transfers to specialists. Visited-set and maxHandoffs stop A→B→A loops.
Memory & sessions
This chat stays in the session. Lasting notes live in MemoryProvider. They are not the same pile.
Living knowledge graph
Background extract, relate, and maintain workers. Reads are cheap; writes never block the run.
Structured output
Zod-validated JSON with repair retries. result.outputParsed is ready for Postgres.
Streaming events
runStream() and onEvent share one timeline: text, tools, handoffs, rails, memory, graph.
Routing + fallbacks
Omit .model() to pick mini vs full vs reasoning. Chain OpenAI → Claude → Gemini for uptime.
MCP both ways
Consume GitHub and Linear. Serve your tools to Cursor and Claude Desktop from one catalog.
Runtime
How a run works
You always get a RunResult: text, optional parsed JSON, which agent finished, model used, usage, traces, and events.
- 01
Input guardrails
Reject jailbreaks, redact PII, enforce size limits — before a token is billed.
- 02
Load context
Session history, long-term memory hits, and graph facts for this userId.
- 03
Pick a model
The one you pinned, or a routed GPT from simple / moderate / complex / reasoning.
- 04
The loop
Talk to the LLM. Validate tool args. Optional approval. Execute. Repeat until an answer, maxTurns, or timeout.
- 05
Output guardrails
Block leaks. Optionally parse JSON against Zod and repair.
- 06
Persist
Write memory, append the session, queue graph extraction. Workers run in the background.
Quickstart
Three minutes to a real agent.
npm install shirube-ai zod. Set OPENAI_API_KEY. Builder or Agent.create — same fields.
const agent = Agent.builder()
.name("support")
.instructions("You help customers. Prefer tools over guessing.")
.apiKey(process.env.OPENAI_API_KEY!)
.build();
await agent.run("Where is my order?");
await run(agent, "Where is my order?");Memory model
Five layers, kept apart on purpose.
Mixing “this chat”, “this customer”, and “this agent’s personality” into one prompt is how agents get expensive and wrong.
- 01
Agent config
ProcessInstructions, tools, rails — frozen after .build().
- 02
Run state
One run()Messages, usage, handoff hops, runId.
- 03
Session
One conversationChat window / Slack thread. Not six-month facts.
- 04
Long-term memory
User / org“Ada prefers sci-fi.” Search before, add after.
- 05
Knowledge graph
User / orgAda WORKS_ON Shirube. Typed nodes and edges.
Security
On by default. Tune, don’t disable.
Built-in rails cover jailbreak, injection, PII, leaks, and size. Custom rails return allow, redact, or block. Approval-required tools fail closed if you forget to pass approval.
Read the guardrails guide →- Jailbreak / DAN
- Prompt injection
- PII redaction
- Secret leak
- System-prompt leak
- Max input size
Use cases
Built for agents people actually talk to.
Customer support
Tools for tickets and refunds, a session per chat, graph memory of the customer, handoff to billing.
Internal ops
MCP tools from GitHub and Linear, approval on risky actions, traces for audit.
Coding / research
Cheap models for easy questions, streaming UI events, structured JSON for pipelines.
Multi-agent products
One triage agent that transfers to specialists without looping forever.