LLM integration.

The integration loop

1. Build a system prompt that matches the live component library with getSystemPrompt().
2. Send the system prompt + the user’s request to your model (through your own server / edge function so the API key stays private).
3. Stream the response tokens into app.appendChunk(token).
4. When the user interacts with something that should talk back to the model, the app fires an assistant-message event — forward it as the next turn.

Choosing the system prompt

getSystemPrompt() emits a prompt that exactly describes the components currently registered (including any you added with registerComponents). Two variants:

The package also ships the prompts as static files (aktion-runtime/system_prompt.txt and system_prompt_chat.txt) for server-side use where you don’t have a live element — but prefer getSystemPrompt() when you register custom components so the prompt stays in sync.

Streaming tokens with appendChunk

appendChunk is incremental: it parses only the new tail and re-renders the affected lines, so it is the cheap path for token-by-token output. Use setResponse only to swap a whole document.

async function generate(app, prompt) {
  app.clear(); // reset any previous program & state
  const res = await fetch("/api/generate", { method: "POST", body: JSON.stringify({ prompt }) });
  const reader = res.body.getReader();
  const decoder = new TextDecoder();
  for (;;) {
    const { value, done } = await reader.read();
    if (done) break;
    app.appendChunk(decoder.decode(value, { stream: true }));
  }
}

A complete end-to-end example

Here are both halves of a minimal integration. The edge function holds the API key, parses the provider’s SSE stream, and re-emits plain Aktion text; the browser feeds that text to appendChunk.

// edge: /api/generate  (Vercel / Cloudflare / Netlify edge function)
import { readFileSync } from "node:fs";

const SYSTEM_PROMPT = readFileSync("system_prompt.txt", "utf8"); // or getSystemPrompt() server-side

export async function POST(req) {
  const { prompt } = await req.json();

  const upstream = await fetch("https://api.openai.com/v1/chat/completions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`, // stays server-side
    },
    body: JSON.stringify({
      model: "gpt-4o",
      stream: true,
      messages: [
        { role: "system", content: SYSTEM_PROMPT },
        { role: "user", content: prompt },
      ],
    }),
  });

  // Transform the provider SSE into a plain text stream of Aktion source.
  const stream = new ReadableStream({
    async start(controller) {
      const reader = upstream.body.getReader();
      const decoder = new TextDecoder();
      let buffer = "";
      for (;;) {
        const { value, done } = await reader.read();
        if (done) break;
        buffer += decoder.decode(value, { stream: true });
        const lines = buffer.split("\n");
        buffer = lines.pop() ?? "";
        for (const line of lines) {
          if (!line.startsWith("data: ")) continue;
          const data = line.slice(6).trim();
          if (data === "[DONE]") continue;
          const delta = JSON.parse(data).choices?.[0]?.delta?.content;
          if (delta) controller.enqueue(new TextEncoder().encode(delta));
        }
      }
      controller.close();
    },
  });
  return new Response(stream, { headers: { "Content-Type": "text/plain; charset=utf-8" } });
}

// browser: stream the edge response into the element
import "aktion-runtime";

const app = document.querySelector("aktion-app");

async function generate(prompt) {
  app.clear();                 // reset previous program + state
  app.setAttribute("streaming", "");
  try {
    const res = await fetch("/api/generate", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ prompt }),
    });
    if (!res.ok) throw new Error(`Generate failed: ${res.status}`);
    const reader = res.body.getReader();
    const decoder = new TextDecoder();
    for (;;) {
      const { value, done } = await reader.read();
      if (done) break;
      app.appendChunk(decoder.decode(value, { stream: true }));
    }
  } catch (err) {
    // Network / provider failure — show your own fallback UI.
    app.setResponse(`$app(Callout("Generation failed — try again.", { tone: "danger" }))`);
    console.error(err);
  } finally {
    app.removeAttribute("streaming"); // tells the parser the document is complete
  }
}

Provider-specific stream parsing

Most providers send Server-Sent Events; extract the text delta from each chunk before passing it on. Do this in your edge function and emit raw Aktion text to the browser, or parse in the browser:

Whatever the provider, the contract with Aktion is the same: concatenate the text deltas and feed them to appendChunk.

The assistant-message round-trip

Generated UI can ask the model a follow-up — e.g. a button wired to send a message. That dispatches an assistant-message event on the host; forward its detail.message as the next user turn:

app.addEventListener("assistant-message", async (e) => {
  const text = e.detail.message;
  history.push({ role: "user", content: text });
  await generate(app, history); // stream the model's reply back in
});

Interceptors

Generated programs make their own network calls via $http. Install host interceptors to add auth, retry, or logging without changing the generated code:

app.registerHttpInterceptors({
  onRequest: (req) => ({ ...req, headers: { ...req.headers, Authorization: token } }),
  onResponse: async (res, retry) => {
    if (res.status === 401) { await refresh(); return retry(); } // one-shot retry
    return res;
  },
  onError: (err) => reportError(err),
});

The delta protocol

For applications that persist or replay a session, Aktion can represent UI changes as deltas rather than whole-document swaps — the same incremental model that powers appendChunk. Persist the program text (and optionally serializeState()) to resume a session; see Production & deployment.

Next