Overview

AI is how your backend calls a model as a declared effect. Ticket triage, a weekly summary, a planner that tools your own Flows — each ask is a named prompt or agent with budgets, not an SDK call buried in do.

For developers wiring OpenRouter or any OpenAI-compatible /v1 endpoint — bind a model, mint a prompt, ask through fx.

Smallest Example

import { ai } from "okengine";
import { z } from "zod";

export const smart = ai.model("smart", {
  provider: "openrouter",
  model: "openrouter/free",
  apiKey: process.env.OPENROUTER_API_KEY,
});

export const triage = smart.prompt("ticket-triage", {
  version: 1,
  budget: { maxCostPerCall: 0.02 },
  out: z.object({
    category: z.enum(["billing", "technical", "other"]),
    urgency: z.enum(["low", "medium", "high"]),
  }),
});

import { on, flow, http } from "okengine";
import { z } from "zod";
import { triage } from "@/core/ai";

export const classify = on(
  http.post({
    in: z.object({ message: z.string().min(1) }),
  }),
  flow({
    do: async ({ message }, fx) => {
      return await fx.ask(triage, { message });
    },
  }),
);

curl -X POST http://localhost:6530/support/triage \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  -d '{"message":"Invoice double-charged last week"}'

Progressive Patterns

From a bare ask to fallback models, tools on ask, and a bounded agent:

const result = await fx.ask(triage, { message: "Cannot reset password" });

Declaration Reference

There is no ai.prompt(...) — mint prompts only via model.prompt.

fx surface

fx.ask options

Undeclared ask → OKE1005 UNDECLARED_ASK. Undeclared embed → OKE1009.

Guardrails

Budgets, version pins, step limits, and PII egress are contracts — not guidelines:

PII egress

Sending a .pii() field to a third-party provider fails the build unless the Flow declares allowPii: true (or pii: "allow"). mock, local, and openai-compatible are not third-party egress.

flow({
  allowPii: true,
  do: async (input, fx) => fx.ask(triage, { email: input.email }),
});

Per-environment drivers

AiDriverId: mock · anthropic · openai-compatible · bedrock · vertex.

Boot implements mock, anthropic, and openai-compatible. bedrock / vertex are reserved and throw until implemented. Dev/test fall back to mock when unset — prod must declare drivers.ai.

import { defineConfig } from "okengine/config";

export default defineConfig({
  drivers: {
    ai: {
      dev: "openai-compatible",
      test: "mock",
      prod: "openai-compatible",
    },
  },
});

Env knobs: OKE_AI_DRIVER, OKE_AI_URL / OPENAI_BASE_URL, provider API keys. Compose does not pin inference — BYO URL + keys, or OpenRouter.

The Capabilities of AI

Troubleshooting

Learn more

• Models — provider registry and baseUrl rules
• Prompts — via, budgets, versions, evals
• Agents — fx.run, tools, maxSteps
• MCP — inbound mcp.tool and outbound ai.mcpServer
• OpenRouter — zero-Docker cloud path
• fx — fx.ask / fx.run / fx.embed
• Errors — OKE1005 · OKE1009

Next