Installation

@warlock.js/ai is the orchestration core. It does nothing on its own — you pair it with one of the provider adapters (OpenAI, Anthropic, Bedrock, Google, Ollama) which gives you the actual model and embedder.

The adapter is a peer dependency in spirit: pick the one(s) you need and install alongside.

Standalone

Install the core package plus the provider you want to use. Most apps start with the OpenAI adapter — it’s the only adapter shipped today and also covers OpenAI-compatible gateways like OpenRouter.

yarn

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

npm

npm install @warlock.js/ai @warlock.js/ai-openai

pnpm

pnpm add @warlock.js/ai @warlock.js/ai-openai

If you also need persistence (snapshot resume, semantic cache) or logging, add those too:

yarn

yarn add @warlock.js/cache @warlock.js/logger

npm

npm install @warlock.js/cache @warlock.js/logger

pnpm

pnpm add @warlock.js/cache @warlock.js/logger

Both are optional. The AI package works without them — you just lose snapshot resume, semantic cache, and structured logging.

Now write a smoke test to confirm everything resolves:

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

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

const myAgent = ai.agent({
  model: openai.model({ name: "gpt-4o-mini" }),
  systemPrompt: "You are a concise assistant.",
});

const { text, usage, error } = await myAgent.execute("Say hi in one word.");

if (error) {
  console.error(error.code, error.message);
} else {
  console.log(text, usage.total);
}

Warlock.js

When you’re already inside a Warlock app, use the framework CLI to install and auto-wire:

warlock add ai openai

This installs @warlock.js/ai plus @warlock.js/ai-openai, registers the connector, and scaffolds the config file. Then use the framework-aware setup:

import { ai } from "@warlock.js/ai";
import { OpenAISDK } from "@warlock.js/ai-openai";
import { env } from "@warlock.js/core";

const openai = new OpenAISDK({ apiKey: env("OPENAI_API_KEY") });

export const summarizer = ai.agent({
  model: openai.model({ name: "gpt-4o-mini" }),
  systemPrompt: "Summarize in one sentence.",
});

New to the framework? Start with core / getting-started.

What you just installed

• @warlock.js/ai — the orchestration core: ai.agent, ai.workflow, ai.supervisor, ai.tool, ai.systemPrompt, ai.middleware.
• @warlock.js/ai-openai — the OpenAI adapter: new OpenAISDK({ apiKey }), sdk.model({ name }), sdk.embedder({ name }). Also works against any OpenAI-compatible upstream (OpenRouter, Together.ai, Azure).

You can install multiple adapters side by side — they’re separate packages, no conflicts.

Adapter status

Adapter	Status
@warlock.js/ai-openai	Shipped
@warlock.js/ai-anthropic	Shipped
@warlock.js/ai-bedrock	Shipped
@warlock.js/ai-google	Shipped
@warlock.js/ai-ollama	Shipped

All five first-party adapters ship. OpenAI is the usual default; because it also works against any OpenAI-compatible gateway, you can additionally reach 100+ models through OpenRouter with one key when that’s more convenient than installing a native adapter.

Related

• Pick a provider — comparison across all five adapters.
• Your first agent — a five-minute walkthrough from install to a streaming reply.