@warlock.js/ai

Provider-agnostic core for building AI agents, tools, workflows, and supervisors in TypeScript.

yarn add @warlock.js/ai @warlock.js/ai-openai @warlock.js/seal

@warlock.js/seal is the recommended schema library — it provides Standard Schema V1 interop and JSON Schema export used by the OpenAI adapter for native structured output. Any other Standard Schema library (Zod, Valibot, …) works too.

What it gives you

• Agents — bounded trip loop, automatic tool dispatch, capability-aware (vision, structured output)
• Tools — thin wrapper around an async function with schema-validated input
• System prompts — composable, immutable builder with mustache placeholders
• Structured output — Standard Schema V1 validation; native enforcement on capable providers, soft fallback elsewhere
• Self-repair — opt-in re-ask when the model produces invalid JSON
• Image attachments — typed ContentPart[] plumbing; capability-gated so unsupported models fail loudly
• Streaming — async iterable + stream.result promise + handler map
• Pluggable adapters — all five first-party adapters ship: @warlock.js/ai-openai, -anthropic, -bedrock, -google, -ollama

30-line example

import { ai } from "@warlock.js/ai";
import { OpenAISDK } from "@warlock.js/ai-openai";
import { v } from "@warlock.js/seal";

const openai = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });

const weatherInput = v.object({
  city: v.string().required(),
});

const weatherTool = ai.tool({
  name: "getWeather",
  description: "Get the current weather for a city",
  input: weatherInput,
  execute: async ({ city }) => fetchWeather(city),
});

const myAgent = ai.agent({
  model: openai.model({ name: "gpt-4o-mini" }),
  systemPrompt: ai.systemPrompt()
    .persona("You are a concise weather assistant.")
    .instruction("Always respond in {{language|English}}."),
  tools: [weatherTool],
});

const result = await myAgent.execute("What's the weather in Cairo?", {
  placeholders: { language: "Arabic" },
  on: { "agent.tool.called": ({ name, output }) => console.log(`${name} →`, output) },
});

console.log(result.text);
console.log("Tokens:", result.usage.total);

Documentation

Full docs live on the Warlock site: https://warlock.js.org/v/latest/ai/

• Your first agent — five-minute walkthrough
• Run agent — execute, stream, attachments, structured output, repair
• Define tools — typed validated functions the model can call
• Run a workflow — durable, resumable pipelines
• Run a supervisor — multi-intent routing
• Reference — every public export

License

MIT