Quickstart (Next.js Server Action)

Updated 6 hours ago • May 22, 2026

This quickstart matches the current OSS implementation and mirrors examples/kortyx-nextjs-chat-server-action.

Good to know: As of Next.js 16.1.6 (March 8, 2026), Server Actions return after completion and do not stream chunk updates to client UI in real time. For live token/chunk rendering, use Quickstart (Next.js API Route).

1. Create a workflow

src/workflows/general-chat.workflow.ts

2. Add provider entrypoint

src/lib/providers.ts

Good to know: The default google export reads GOOGLE_API_KEY, GEMINI_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, KORTYX_GOOGLE_API_KEY, or KORTYX_GEMINI_API_KEY on first use. If you want explicit provider setup or custom transport settings, replace this with createGoogleGenerativeAI(...).

This src/lib/providers.ts file is a re-export only. In files where you call google("...") directly, import google from @/lib/providers or from @kortyx/google; do not expect export { google } from "@kortyx/google" to create a local variable in the same file.

3. Create a node

src/nodes/chat.node.ts

import type { ProviderModelRef } from "kortyx";
import { useReason } from "kortyx";
import { google } from "@/lib/providers";

export type ChatNodeParams = {
  model?: ProviderModelRef;
  temperature?: number;
  system?: string;
};

export const chatNode = async ({
  input,
  params,
}: {
  input: unknown;
  params: ChatNodeParams;
}) => {
  const {
    model = google("gemini-2.5-flash"),
    temperature = 0.3,
    system = "",
  } = params;

  const res = await useReason({
    id: "chat",
    model,
    system: system || "You are a concise assistant.",
    input: String(input ?? ""),
    temperature,
    emit: true, // publish text events
    stream: true, // token-by-token output
  });

  return {
    data: { text: res.text },
  };
};

4. Wire an agent

src/lib/kortyx-client.ts

5. Call `streamChat` (buffered in server action)

src/app/actions/chat.ts

src/app/actions/chat.js

Good to know: Use collectStream(...) when you want to process raw chunk events yourself. Use collectBufferedStream(...) when you want merged text + structured summaries.

6. Run

What this gives you

Type-safe workflow definition
Explicit provider bootstrap at app level
Node-level model control via useReason(...)
Buffered chunk collection through a Server Action return value
Chunk event types in the buffered result (text-start, text-delta, text-end, done)
Built-in interrupt/resume path when your nodes use useInterrupt