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

• Monorepo
• Documentation
• Package overview
• Quickstart: Next.js API Route
• Runtime persistence
• Provider guide

Studio

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

License

Apache-2.0. See LICENSE.