kraken-ai

A fully typed, multi-model AI agent framework with a single dependency (zod) plus the provider SDK of your choice. Create simple agents or build sophisticated multi-model orchestrators with team delegation, custom execution loops via kernels, middleware injection, and event hooks.

We built this because we were tired of poor developer experience with existing frameworks, and we wanted to create something very lightweight yet useful.

• Model-agnostic — swap providers without changing agent code
• Zod-native tools — define tools with Zod schemas, get full type inference
• Structured output — constrain model responses to a Zod schema
• Multi-agent teams — agents delegate to team members; the model decides when
• Human-in-the-loop — tools with requiresApproval pause execution for human decision
• Middleware — intercept and transform LLM calls, tool calls, and tool definitions
• Observability — structured events for every LLM call, tool execution, and lifecycle transition
• Mock provider — deterministic testing with pattern-matched responses
• Custom kernels — full control over the execution loop

Install

pnpm add kraken-ai

Quick Start

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

const lookupPrice = tool({
  name: "lookup_price",
  description: "Look up the current price of a product by SKU",
  parameters: z.object({ sku: z.string() }),
  execute: async ({ sku }) => {
    const price = await db.products.getPrice(sku);
    return { sku, price };
  },
});

const agent = new Agent({
  name: "pricing-analyst",
  model: google("gemini-3-flash-preview"),
  instructions: "You are a pricing analyst. Use tools to look up product data.",
  tools: [lookupPrice],
});

const result = await agent.run([{ role: "user", content: "What is the price of SKU-4821?" }]);
if (result.status === "complete") {
  console.log(result.output);
}

Adding skills to a kernel

defineSkillTool and skillDiscoveryMessage give you the Agent Skills progressive-disclosure pattern with no framework lock-in. The SDK stays governance-agnostic — you wire the loader to whatever backend fetches the skill body (an in-memory map for tests, a file walker for a CLI, an authenticated service for production).

import { Agent, defineSkillTool, skillDiscoveryMessage, openai } from "kraken-ai";

const SKILLS = {
  "pdf-processing": "# PDF Processing\n\nUse pdfminer.six to extract …",
  "csv-cleaning": "# CSV Cleaning\n\nNormalize headers via …",
};

const skillTools = Object.keys(SKILLS).map((id) =>
  defineSkillTool({
    skillId: id,
    description: `Load the ${id} skill body`,
    load: async (skillId) => SKILLS[skillId as keyof typeof SKILLS],
  }),
);

const catalog = skillDiscoveryMessage([
  { skillId: "pdf-processing", description: "Extract structured data from PDFs" },
  { skillId: "csv-cleaning", description: "Normalize and dedupe CSVs" },
]);

const agent = new Agent({
  model: openai("gpt-4o"),
  instructions: `You are a data assistant.\n\n${catalog}`,
  tools: skillTools,
});

Only the skill names + descriptions are in the system prompt at startup. The full skill body is loaded only when the model decides to call the matching load_skill_* tool.

Documentation

• Models — providers, lazy resolution, custom providers
• Tools — Zod-native tools, human-in-the-loop approval
• Structured Output — constrain responses to a schema
• Multi-Agent Teams — delegation, parameter propagation
• Middleware — intercept LLM calls, tool calls, and transitions
• Observability — structured event callbacks
• Custom Kernels — async generator kernels
• Testing — mock provider with pattern matching
• API Reference — full API surface

Requirements

• Node.js 18+
• TypeScript 5+ (TypeScript 6 supported; requires tsup patch in monorepos — see egoist/tsup#1388)
• zod 4+ (peer dependency)
• @google/genai 1+ (optional — required for the Google provider)

Enterprise

For full governance, observability, and managed infrastructure, see the Kraken AI platform.

License

Apache-2.0