Agentic guidance

Static tour libraries replay a fixed cross-route script. Cairn flows can reason: a step can run an async action — fetch state, call an API, or ask an LLM — write the result into context, and branch on it. The output stays what Cairn is good at: in-product UI guidance.

This is the run step. On entering a step with a run, the engine sets state.running = true, awaits your action, merges the returned context patch, then auto-advances via next (resolved against the freshly-patched context). If run rejects it routes to onError, or exposes state.error and stays so you can retry().

{
  id: "decide",
  async run(ctx) {
    const { next, reason } = await agent.decide(ctx);
    return { route: next, reason };
  },
  next: (ctx) => ctx.route, // branch on what the agent decided
}

The "agent" isn't a core concept — it's just userland behind your own interface. The demo below defines a DemoAgent and ships a deterministic SimAgent (no API keys, never flaky); an LLMAgent calling a real model swaps in behind the same interface.

Try it

Toggle Usage 90% and watch the agent reason its way to a different route on the next run — billing when you're near your limit, team when there's headroom.

By default the demo runs the deterministic SimAgent. A real LLMAgent ships behind the same interface, backed by an /api/agent route that asks a model through the Vercel AI Gateway. It's off by default — calling a model on every visit is a cost/abuse hole — and turns on with CAIRN_LLM_ENABLED=1 (server) + NEXT_PUBLIC_CAIRN_LLM=1 (client), with SimAgent as an automatic fallback. Add rate-limiting (e.g. Vercel BotID) before exposing it publicly.