kortyx

Kortyx is a TypeScript framework for building production AI agents with explicit workflows, provider-agnostic models, typed hooks, streaming, interrupts, and runtime persistence.

Use kortyx as the main package. It re-exports the public server/runtime APIs from the supporting @kortyx/* packages so application code can stay focused on workflows, nodes, providers, and UI transport.

Install

pnpm add kortyx @kortyx/google @kortyx/react

npm install kortyx @kortyx/google @kortyx/react

Quickstart

Create a workflow:

// src/workflows/general-chat.workflow.ts
import { defineWorkflow } from "kortyx";
import { chatNode } from "@/nodes/chat.node";

export const generalChatWorkflow = defineWorkflow({
  id: "general-chat",
  version: "1.0.0",
  description: "Single-node chat workflow.",
  nodes: {
    chat: {
      run: chatNode,
      params: {
        temperature: 0.3,
      },
    },
  },
  edges: [
    ["__start__", "chat"],
    ["chat", "__end__"],
  ],
});

Add a server-side node:

// src/nodes/chat.node.ts
import { google } from "@kortyx/google";
import { useReason } from "kortyx";

type ChatParams = {
  temperature?: number;
};

export const chatNode = async ({
  input,
  params,
}: {
  input: unknown;
  params: ChatParams;
}) => {
  const result = await useReason({
    id: "chat",
    model: google("gemini-2.5-flash"),
    system: "You are a concise assistant.",
    input: String(input ?? ""),
    temperature: params.temperature ?? 0.3,
    stream: true,
    emit: true,
  });

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

Wire the agent:

// src/lib/agent.ts
import { createAgent } from "kortyx";
import { generalChatWorkflow } from "@/workflows/general-chat.workflow";

export const agent = createAgent({
  workflows: [generalChatWorkflow],
  defaultWorkflowId: "general-chat",
});

Expose it through a Next.js API route:

import { createChatRouteHandler } from "kortyx";
import { agent } from "@/lib/agent";

export const runtime = "nodejs";
export const dynamic = "force-dynamic";

const handleChat = createChatRouteHandler({ agent });

export async function POST(request: Request): Promise<Response> {
  return handleChat(request);
}

Consume the stream from React:

"use client";

import { createRouteChatTransport, useChat } from "@kortyx/react";

export function Chat() {
  const chat = useChat({
    transport: createRouteChatTransport({ endpoint: "/api/chat" }),
  });

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const form = new FormData(event.currentTarget);
        chat.send(String(form.get("message") ?? ""));
        event.currentTarget.reset();
      }}
    >
      {chat.messages.map((message) => (
        <p key={message.id}>{message.content}</p>
      ))}
      {chat.streamContentPieces.map((piece) =>
        piece.type === "text" ? (
          <span key={piece.id}>{piece.content}</span>
        ) : null,
      )}
      <input name="message" />
      <button type="submit" disabled={chat.isStreaming}>
        Send
      </button>
    </form>
  );
}

Set a provider key and run your app:

GOOGLE_API_KEY=your_key_here pnpm dev

API Groups

Area	Exports
Agent	`createAgent`, `createChatRouteHandler`, `streamChatFromRoute`
Workflows	`defineWorkflow`, `loadWorkflow`, `validateWorkflow`
Hooks	`useReason`, `useInterrupt`, `useStructuredData`, `useNodeState`, `useWorkflowState`, `useRuntimeContext`
Runtime	workflow registries, node registry, in-memory/Redis framework adapters
Providers	provider contracts and registry helpers from `@kortyx/providers`
Streams	SSE helpers, stream readers, collectors, structured reducers

Provider Packages

Install only the provider integrations your app needs.

Provider	Package	Factory	Default environment variable
Google Gemini	`@kortyx/google`	`google(...)`	`GOOGLE_API_KEY` or `GEMINI_API_KEY`
OpenAI	`@kortyx/openai`	`openai(...)`	`OPENAI_API_KEY`
Anthropic	`@kortyx/anthropic`	`anthropic(...)`	`ANTHROPIC_API_KEY`
DeepSeek	`@kortyx/deepseek`	`deepseek(...)`	`DEEPSEEK_API_KEY`
Groq	`@kortyx/groq`	`groq(...)`	`GROQ_API_KEY`
Mistral	`@kortyx/mistral`	`mistral(...)`	`MISTRAL_API_KEY`

Documentation

Studio

Kortyx Studio is on the way for cost tracking, logs, observability, prompt tracking, and operational review.

License

Apache-2.0. See LICENSE.