Documentation
Why Shirube
A TypeScript agent SDK for people who ship agents into products — not one-off ChatGPT scripts.
Shirube is a TypeScript agent SDK: you describe an agent, give it tools and a model, and it runs a loop until it can answer — with guardrails, memory, and a knowledge graph around that loop.
It is aimed at people who ship agents into products (support, internal ops, coding assistants), not at one-off ChatGPT scripts. It is named after its author. The core loop is written in this repo — it is not a wrapper around the OpenAI or Claude agent frameworks.
The problem it solves
A model API gives you one completion. An agent needs many: call a tool, read the result, maybe call another tool, maybe hand off to a specialist, then answer. Around that loop you also need:
- A place to put tools with validated inputs
- Memory that is not “paste the last 200 messages”
- Security that does not depend on the prompt saying “please be safe”
- Observability (what model, which tools, how long, why it failed)
- MCP so the same tools work in Cursor and in your backend
Shirube is that kernel. The loop is implemented here. It does not wrap @openai/agents or similar.
When to use it
Good fit
- A support bot that refunds, searches docs, and remembers the customer
- An ops agent that talks to GitHub/Linear over MCP
- A classifier that must return JSON your backend can store
- Several specialists behind a triage agent
Poor fit
- A single
chat.completions.createwith no tools — use the vendor SDK - You already standardized on another agent framework and only need a thin helper
What you get
| Capability | In one sentence |
|---|---|
| Agent runtime | User input → model → tools → model → final answer, with turn/time limits |
| Tools | Named functions + Zod schemas + async execute + optional human approval |
| Guardrails | Input / output / tool checks; jailbreak and PII on by default |
| Handoffs | Transfer a run to another agent without looping forever |
| Memory & sessions | Chat history vs long-term notes vs graph facts, kept apart |
| Graph + workers | Background extract / relate / maintain so the graph stays useful |
| Structured output | Zod-validated JSON with repair retries |
| Streaming | Events for UI: text, tools, handoffs, graph updates |
| Providers | OpenAI, Anthropic, Gemini, fallback chain, complexity routing |
| MCP | Consume servers and expose your tools |
Who it is for
| Use case | What Shirube gives you |
|---|---|
| Customer support | Tools for tickets/refunds, sessions per chat, graph memory of the customer, handoff to billing |
| Internal ops | MCP tools from GitHub/Linear, approval on risky actions, traces for audit |
| Coding / research assistants | Model routing (cheap model for easy questions), streaming UI events, structured JSON output |
| Multi-agent products | One triage agent that transfers to specialists without looping |
Why it exists
Vendor agent kits give you a loop. Production still needs: which model to call for this prompt (and a fallback if that provider is down); how to remember a user across weeks without stuffing the whole history into every request; how to stop jailbreaks, leaks, and unapproved refunds; how to share tools with Cursor via MCP; how to keep a knowledge graph from filling with duplicates.
Shirube implements those in-process, with security on by default.
Install the package and run your first agent in Installation and quick start.