Open Kortyx on GitHub

Runtime Context

Updated 6 hours ago • May 22, 2026

Runtime context is request metadata that server-side node code may need during one chat run.

Use it for values such as selected thread id, locale, UI mode, tenant hints, or server-approved auth context. Do not use it for the user's message. Do not use it as static node configuration.

The Three Inputs

Kortyx has three different data lanes:

LaneWhere it comes fromWhere to read it
inputlatest user message, then merged node datanode function argument
paramsworkflow node definitionnode function argument
runtime contextroute/client request metadatauseRuntimeContext(...)

Client to Node Flow

With @kortyx/react, pass request metadata through useChat({ context }).

import { createRouteChatTransport, useChat } from "@kortyx/react"; export function ChatPage({ threadId }: { threadId: string }) { const chat = useChat({ transport: createRouteChatTransport({ endpoint: "/api/chat", }), context: { threadId, locale: "en-US", }, }); return <ChatWindow chat={chat} />; }

The default route transport sends a body shaped like this:

{ "sessionId": "session-id", "workflowId": "optional-workflow", "messages": [{ "role": "user", "content": "Summarize this thread" }], "context": { "threadId": "thread-123", "locale": "en-US" } }

In your route, parse the request and pass approved context into agent.streamChat(...).

import { parseChatRequestBody, toSSE } from "kortyx"; import { agent } from "@/lib/kortyx-client"; import { requireUser } from "@/services/auth"; export async function POST(request: Request): Promise<Response> { const user = await requireUser(request); const body = parseChatRequestBody(await request.json()); const stream = await agent.streamChat(body.messages, { sessionId: body.sessionId, workflowId: body.workflowId, context: { threadId: body.context?.threadId, locale: body.context?.locale, userId: user.id, tenantId: user.tenantId, }, }); return toSSE(stream); }

Good to know: Client-sent context is request metadata, not trusted authorization state. Authenticate the route and derive sensitive values such as user id, roles, tenant permissions, and billing access on the server.

Read Context in a Node

Inside node execution, call useRuntimeContext(...).

import { useRuntimeContext } from "kortyx"; type AppContext = { threadId?: string; locale?: string; userId: string; tenantId: string; }; export async function supportNode() { const context = useRuntimeContext<AppContext>(); return { data: { threadId: context.threadId, userId: context.userId, tenantId: context.tenantId, }, }; }

useRuntimeContext(...) returns an object. If no context was passed for the request, it returns an empty object.

What Not to Put in Context

  • Do not put provider credentials in context.
  • Do not trust client-provided user ids, roles, permissions, or tenant access.
  • Do not put large documents or full chat history in context; use messages, summaries, retrieval, or app services.
  • Do not use context for static node settings; use node params.

What to Read Next