Saved versions are read-only. **+ New version** creates a draft from the newest saved version, including messages, configuration, schemas and prompt references. If a draft already exists, **Open draft** resumes it. The **Draft** entry stays at the top of version history until saved or deleted. You can browse saved versions and other tabs, then return to the draft. Valid changes autosave and are flushed when leaving the prompt. Invalid JSON remains in the mounted editor while browsing versions and tabs. **Save version** opens the same diff dialog used by **Compare**: removed content is red, added content is green, and desktop views align both versions. The diff compares the draft against its recorded base version. Change notes are optional by default. Enable **Require a change note when saving a new version** in that prompt’s promotion policy to require them in Studio, the API and CLI. This applies to future saves and does not change existing versions. Accepting creates a new immutable version and removes the draft entry. A changed base or draft revision causes a conflict instead of silently replacing content. Use **Delete draft** in the actions menu to remove the draft after confirmation. Saved versions, live and optional tags stay unchanged. A newer draft saved by another editor cannot be deleted using an outdated revision. Messages, configuration, format, contracts, and exact dependencies contribute to the executable hash. A note-only change cannot create another executable version. Concurrent changes to the head, draft, or assignment are rejected; your local draft remains available for recovery. Retrying an accepted save with the same idempotency key does not create another version.fe:T480,Categories organize the library. On smaller screens, use the categories control on the left to open the category tree. Selecting a category closes the panel. **New category** accepts paths such as `Canvas/Testing`, creating Testing under Canvas. Parents collapse independently. Category actions rename, move, or delete the category. Deleting a category requires choosing Root or a surviving category for every prompt in its subtree. **Test groups** are secondary collections of exact prompt versions. Open Groups, name a group, and add versions from the prompt history or group drawer. A group contains one version per prompt; replacing that selection requires an explicit choice. Removing a prompt from a group and deleting a group require confirmation. Both preserve prompts, versions, and saved eval evidence. A group does not own or save a suite. **Run suite** opens the normal eval drawer, where you choose an application, suite, individual test checkboxes, judge, and attempts. The optional prompt selection chooses live versions, one candidate version, or a test group for this launch. You can test a single candidate without creating a group.ff:Te85,The consumer application's `createPrompts` registration advertises its contracts through `createEvals`. Studio freezes all registered prompt versions, replacing the selected candidates, and validates configuration before starting the run. Companion prompts and exact dependencies remain part of that snapshot. **Evals** on a prompt shows the saved run, selected version, full-suite status, and actual-use verification. A selection alone is not proof: `useReason({ prompt })` records the version and hash actually passed to the model. Unused or mismatched versions cannot satisfy a promotion policy. **Runs** shows executions that reported this version, with model-call provenance linked by key, version, hash, environment, and source. Captured message content follows the application's existing telemetry capture policy; configuration and runtime inputs are not added to identity metadata. Both tabs use the standard Runs and Evals tables, filling the available tab area. Search, status filters, sorting, column controls, and pagination work within the selected version. All tabs share the same version history: a collapsible sidebar on wide surfaces and a dropdown beside the tabs in narrow drawers or mobile layouts. Drawer and expanded views share one compact header. Expand changes to Back in expanded view; secondary actions move into the prompt menu when space is limited. Multiple calls in one execution produce one run row; suites launched together produce one evaluation row, retaining their prompt-usage evidence. **Make this live** is the first action in each version menu. It opens a modal labelled **Promote version** for a newer version or **Roll back version** for an older version, relative to the current live version. Review the exact version, readiness checks, and release impact, then confirm with **Promote** or **Roll back** in that same modal. There is no second confirmation dialog or environment selector: live belongs to this prompt in this project. Saving a candidate never moves live. Rolling back moves live to an older immutable version; **Newest version** still shows the most recently saved version. New executions resolve live by default, while executions holding a snapshot retain it. **Manage tags** adds or removes optional version tags such as `staging` or `development`. Each tag points to one version of a prompt. Moving or removing an existing tag requires confirmation because applications may request it. Tags do not promote a version, and promotion never moves optional tags. The reserved `live` tag can only move through promotion or rollback. Tag names use lowercase letters, numbers, hyphens and underscores, up to 64 characters. Tags are scoped to the project and do not create application environments or copy prompts between projects or deployments. Promotion policies can require a passing full suite, specific application/suite selections, and independent human reviews. Evidence must use the exact version and its companion versions must still match current live versions. Each policy applies to all versions of one prompt; changing it does not affect other prompts. API-key reviews are audited but do not count as independent human reviews. The modal explains unmet requirements before submission. When allowed by policy, an explicit exception requires a non-blank reason and is recorded in Activity. Test a candidate before the first promotion, or use that reviewed exception path to bootstrap live. Open **Promotion policy** from a prompt’s row actions or detail actions. It opens one modal; the table action keeps you on the list. **Save policy** confirms the changes and records them in that prompt’s Activity. Cancel closes the modal without saving.100:T41a,Select up to 100 library rows to move prompts, select their exact latest versions for a test group, export a bundle, or archive unassigned prompts. Category and archive batches are atomic: a stale revision rejects the entire batch. Assigned prompts remain protected from archive. **Import** accepts portable JSON bundles exported by Studio or the CLI. Review conflict handling, destination keys, category paths, and optional test groups, then review the source-to-destination version mapping and hashes. Apply saves candidate versions and reads each hash back. Save the plan to retry through the CLI after a lost response. Import never changes live or optional tags. Bundles support up to 200 immutable versions and a 20 MiB transfer request; individual prompt mutations are limited to 1 MiB. Promotion checks the current application suite revision as well as exact prompt usage, companion versions, required suites, and reviews. A previous pass from an older suite definition is historical evidence and does not satisfy the current promotion gate.101:T146b,# Author and migrate prompts with the CLI Use independently authenticated named connections for the source and destination. Connections store API URLs and environment-variable names, rather than raw keys. `--project-id` on `kortyx connections add` selects a cloud project explicitly. ```sh kortyx connections add staging --api-url https://staging-api.example.com --api-key-env STAGING_STUDIO_KEY kortyx connections add production --api-url https://production-api.example.com --api-key-env PRODUCTION_STUDIO_KEY kortyx studio prompts list --connection staging --json kortyx studio prompts get canvas/classify-intent --connection staging --file prompt.json kortyx studio prompts validate prompt.json --json ``` Modify the executable JSON file, validate it, and review the hash before saving: ```sh kortyx studio prompts update canvas/classify-intent --connection staging \ --file prompt.json --base-version 1 --expected-hash REVIEWED_HASH \ --note "Improve ambiguous intent classification" --idempotency-key SAVE_UUID --json kortyx studio prompts diff canvas/classify-intent 1 2 --connection staging --json kortyx studio prompts test canvas/classify-intent --connection staging \ --version 2 --target support-app --suite regression --case ambiguous-intent --json ``` `edit` is an alias of file-based `update`. `versions` lists identities and notes. `action ` validates and applies category, group, draft, review, policy, or asset mutations using the public action contract. `archive` and `restore` require the reviewed asset revision. Assigned prompts cannot be archived. ## Plan, apply, verify ```sh kortyx studio prompts copy canvas/classify-intent --from staging --to production \ --plan-file transfer-plan.json --json # Review the source-to-destination version/hash mapping, then apply: kortyx studio prompts apply transfer-plan.json --connection production --json ``` The default copy exports the selected head and its exact dependency closure. Use `--version` for one exact version or `--history` for histories, `--groups` for fully covered test groups, and `--rename source/key=destination/key` for intentional key remapping. An unrelated same-key conflict fails by default; `--append` explicitly allows new destination versions. Identical executable content is reused. Category paths are portable; internal category and prompt UUIDs are destination-owned. Dependency keys, versions, and hashes are remapped together, so rewritten parents receive new executable hashes while retaining their source provenance. Plans freeze destination heads and expire after 24 hours. Applying a plan is atomic: concurrent destination edits or group conflicts reject the operation. Save the plan before applying; retrying that plan resumes the accepted operation without duplicating versions. CLI apply reads destination versions back and checks their exact hashes before reporting `verification: "destination-read-back"`. Copying never changes live assignments and never moves source keys, traces, eval results, or review approvals. Source identity and immutable version/hash provenance are retained. Run the imported version against the destination application's suite, then explicitly promote it under project promotion policy: ```sh kortyx studio prompts test canvas/classify-intent --connection production \ --version DESTINATION_VERSION --target support-app --suite regression --json kortyx studio prompts promote canvas/classify-intent --connection production \ --version DESTINATION_VERSION --expected-revision 0 --json ``` For disconnected deployments, use `export --file bundle.json` and `import bundle.json --plan-file transfer-plan.json`. `--apply` combines planning and application when the mapping is already controlled by your automation. CLI failures use nonzero exit codes. `--json` reports versioned errors, including prompt conflict codes, without reflecting arbitrary remote response bodies. ## Editing inclusions with the CLI Studio references appear in executable JSON as `[[prompt:stable/key]]`. Each key needs an exact `{ id, version, hash }` entry in `content.dependencies`; use `prompts get` to read the child version and its hash. Keep inherited input declarations in the parent's `variablesSchema`, review the diff, then update and test the parent. Copy/export includes nested dependencies. Destination rename mappings rewrite both the manifest and inline tokens before recomputing hashes. ## Manage release tags from the CLI Promotion updates only `live`; saving a new version and editing other tags do not: ```bash kortyx studio prompts promote canvas/classify-intent --version 9 --expected-revision 2 kortyx studio prompts tag canvas/classify-intent staging --version 10 --expected-revision 0 kortyx studio prompts untag canvas/classify-intent staging --expected-revision 1 kortyx studio prompts rollback canvas/classify-intent --version 7 --expected-revision 3 ``` Read current tag revisions with `prompts get KEY --json`. Revision 0 creates a new tag; moving or removing one requires its current revision. `live` is reserved for promotion/rollback. Copying between connections imports immutable candidates and never copies or moves release tags automatically. 102:T917,```sh kortyx studio prompts copy canvas/classify-intent --from staging --to production \ --plan-file transfer-plan.json --json # Review the source-to-destination version/hash mapping, then apply: kortyx studio prompts apply transfer-plan.json --connection production --json ``` The default copy exports the selected head and its exact dependency closure. Use `--version` for one exact version or `--history` for histories, `--groups` for fully covered test groups, and `--rename source/key=destination/key` for intentional key remapping. An unrelated same-key conflict fails by default; `--append` explicitly allows new destination versions. Identical executable content is reused. Category paths are portable; internal category and prompt UUIDs are destination-owned. Dependency keys, versions, and hashes are remapped together, so rewritten parents receive new executable hashes while retaining their source provenance. Plans freeze destination heads and expire after 24 hours. Applying a plan is atomic: concurrent destination edits or group conflicts reject the operation. Save the plan before applying; retrying that plan resumes the accepted operation without duplicating versions. CLI apply reads destination versions back and checks their exact hashes before reporting `verification: "destination-read-back"`. Copying never changes live assignments and never moves source keys, traces, eval results, or review approvals. Source identity and immutable version/hash provenance are retained. Run the imported version against the destination application's suite, then explicitly promote it under project promotion policy: ```sh kortyx studio prompts test canvas/classify-intent --connection production \ --version DESTINATION_VERSION --target support-app --suite regression --json kortyx studio prompts promote canvas/classify-intent --connection production \ --version DESTINATION_VERSION --expected-revision 0 --json ``` For disconnected deployments, use `export --file bundle.json` and `import bundle.json --plan-file transfer-plan.json`. `--apply` combines planning and application when the mapping is already controlled by your automation. CLI failures use nonzero exit codes. `--json` reports versioned errors, including prompt conflict codes, without reflecting arbitrary remote response bodies.3:["$","$L10",null,{"searchIndex":[{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","start-here","production","b2b","saas","workflows"],"version":"v0","href":"/docs/sdk/start-here","title":"Start Here","description":"Choose your Kortyx path for building reliable, production-grade AI systems with explicit runtime control.","section":"Start Here","content":"$11"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:0:keywords","version":"v0","href":"/docs/sdk/start-here#choose-your-path","title":"Choose your path","description":"Start Here","section":"Start Here","content":"$12"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:0:keywords","version":"v0","href":"/docs/sdk/start-here#stack-direction","title":"Stack direction","description":"Start Here","section":"Start Here","content":"- Next.js: fastest path for an initial app integration.\n- Express/Fastify: strong fit for server-heavy orchestration and infrastructure-owned deployments.\n - Start with [React Frontend + Node Backend](../03-guides/03-react-node-backend.md)\n - Then read [streamChat](../02-core-concepts/06-stream-chat.md)\n - Then configure [Runtime Persistence Adapters](../04-production/02-framework-adapters.md)\n\n> **Good to know:** The docs are TypeScript-first and prioritize system-builder workflows with production reliability in mind."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:0:keywords","version":"v0","href":"/docs/sdk/start-here#observe-your-kortyx-application","title":"Observe your Kortyx application","description":"Start Here","section":"Start Here","content":"Kortyx Studio turns server-side telemetry into readable sessions, runs, workflow transitions, model calls, interrupts, timing, token usage, and cost.\n\nIf you already have a Kortyx agent running, start the complete local stack with one command:\n\n```bash\nnpx kortyx studio start\n```\n\nThen follow [Run Kortyx Studio Locally](../../../studio/v0/02-run-locally.md) to connect the agent and inspect its first run. Studio is optional observability infrastructure; it does not execute your workflows, and your application continues running if Studio is unavailable."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","installation","nodejs","pnpm","environment"],"version":"v0","href":"/docs/sdk/getting-started/installation","title":"Installation","description":"Install Kortyx, set required environment variables, and configure basic project settings.","section":"Getting Started","content":"# Installation\n\n## Prerequisites\n\n- Node.js 20+\n- pnpm (recommended in this monorepo)\n\n## Install the main package\n\n```bash tabs=\"install-kortyx\" tab=\"pnpm\"\npnpm add kortyx\n```\n\n```bash tabs=\"install-kortyx\" tab=\"npm\"\nnpm install kortyx\n```\n\n```bash tabs=\"install-kortyx\" tab=\"yarn\"\nyarn add kortyx\n```\n\n```bash tabs=\"install-kortyx\" tab=\"bun\"\nbun add kortyx\n```\n\nIf you prefer scoped packages, see [Package Overview](../05-reference/01-package-overview.md).\n\n## Runtime dependency notes\n\n`kortyx` already re-exports agent/runtime/hooks/providers/stream APIs.\n\nYou still need provider credentials at runtime (for example Google):\n\n```bash\nexport GOOGLE_API_KEY=your_key_here\n```\n"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:4:keywords","version":"v0","href":"/docs/sdk/getting-started/installation#prerequisites","title":"Prerequisites","description":"Installation","section":"Installation","content":"- Node.js 20+\n- pnpm (recommended in this monorepo)"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:4:keywords","version":"v0","href":"/docs/sdk/getting-started/installation#install-the-main-package","title":"Install the main package","description":"Installation","section":"Installation","content":"```bash tabs=\"install-kortyx\" tab=\"pnpm\"\npnpm add kortyx\n```\n\n```bash tabs=\"install-kortyx\" tab=\"npm\"\nnpm install kortyx\n```\n\n```bash tabs=\"install-kortyx\" tab=\"yarn\"\nyarn add kortyx\n```\n\n```bash tabs=\"install-kortyx\" tab=\"bun\"\nbun add kortyx\n```\n\nIf you prefer scoped packages, see [Package Overview](../05-reference/01-package-overview.md)."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:4:keywords","version":"v0","href":"/docs/sdk/getting-started/installation#runtime-dependency-notes","title":"Runtime dependency notes","description":"Installation","section":"Installation","content":"`kortyx` already re-exports agent/runtime/hooks/providers/stream APIs.\n\nYou still need provider credentials at runtime (for example Google):\n\n```bash\nexport GOOGLE_API_KEY=your_key_here\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","nextjs","quickstart","api-route","streaming"],"version":"v0","href":"/docs/sdk/getting-started/quickstart-nextjs","title":"Quickstart (Next.js API Route)","description":"Build a working Next.js chat flow using API routes, Kortyx workflows, node-level model wiring, and streaming.","section":"Getting Started","content":"$13"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:8:keywords","version":"v0","href":"/docs/sdk/getting-started/quickstart-nextjs#1-create-a-workflow","title":"1. Create a workflow","description":"Quickstart (Next.js API Route)","section":"Quickstart (Next.js API Route)","content":"$14"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:8:keywords","version":"v0","href":"/docs/sdk/getting-started/quickstart-nextjs#2-add-provider-entrypoint","title":"2. Add provider entrypoint","description":"Quickstart (Next.js API Route)","section":"Quickstart (Next.js API Route)","content":"```ts\n// src/lib/providers.ts\nexport { google } from \"@kortyx/google\";\n```\n\n```js\n// src/lib/providers.js\nexport { google } from \"@kortyx/google\";\n```\n\n> **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(...)`.\n\nThis `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."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:8:keywords","version":"v0","href":"/docs/sdk/getting-started/quickstart-nextjs#3-create-a-node","title":"3. Create a node","description":"Quickstart (Next.js API Route)","section":"Quickstart (Next.js API Route)","content":"$15"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:8:keywords","version":"v0","href":"/docs/sdk/getting-started/quickstart-nextjs#4-wire-an-agent","title":"4. Wire an agent","description":"Quickstart (Next.js API Route)","section":"Quickstart (Next.js API Route)","content":"```ts\n// src/lib/kortyx-client.ts\nimport { createAgent } from \"kortyx\";\nimport { generalChatWorkflow } from \"@/workflows/general-chat.workflow\";\n\nexport const agent = createAgent({\n workflows: [generalChatWorkflow],\n defaultWorkflowId: \"general-chat\",\n});\n```\n\n```js\n// src/lib/kortyx-client.js\nimport { createAgent } from \"kortyx\";\nimport { generalChatWorkflow } from \"@/workflows/general-chat.workflow\";\n\nexport const agent = createAgent({\n workflows: [generalChatWorkflow],\n defaultWorkflowId: \"general-chat\",\n});\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:8:keywords","version":"v0","href":"/docs/sdk/getting-started/quickstart-nextjs#5-add-an-api-route","title":"5. Add an API route","description":"Quickstart (Next.js API Route)","section":"Quickstart (Next.js API Route)","content":"```ts\n// src/app/api/chat/route.ts\nimport { createChatRouteHandler } from \"kortyx\";\nimport { agent } from \"@/lib/kortyx-client\";\n\nexport const runtime = \"nodejs\";\nexport const dynamic = \"force-dynamic\";\n\nconst handleChat = createChatRouteHandler({ agent });\n\nexport async function POST(request: Request): Promise {\n return handleChat(request);\n}\n```\n\n```js\n// src/app/api/chat/route.js\nimport { createChatRouteHandler } from \"kortyx\";\nimport { agent } from \"@/lib/kortyx-client\";\n\nexport const runtime = \"nodejs\";\nexport const dynamic = \"force-dynamic\";\n\nconst handleChat = createChatRouteHandler({ agent });\n\nexport async function POST(request) {\n return handleChat(request);\n}\n```\n\n> **Good to know:** Request body supports optional `stream` (default `true`). Send `{ stream: false }` to receive buffered JSON `{ chunks, text, structured }` instead of SSE. If you only want raw chunks, use `collectStream(...)` in a custom route."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:8:keywords","version":"v0","href":"/docs/sdk/getting-started/quickstart-nextjs#6-call-apichat-from-client-code","title":"6. Call /api/chat from client code","description":"Quickstart (Next.js API Route)","section":"Quickstart (Next.js API Route)","content":"$16"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:8:keywords","version":"v0","href":"/docs/sdk/getting-started/quickstart-nextjs#7-run","title":"7. Run","description":"Quickstart (Next.js API Route)","section":"Quickstart (Next.js API Route)","content":"```bash tabs=\"run-dev\" tab=\"pnpm\"\nGOOGLE_API_KEY=your_key_here pnpm dev\n```\n\n```bash tabs=\"run-dev\" tab=\"npm\"\nGOOGLE_API_KEY=your_key_here npm run dev\n```\n\n```bash tabs=\"run-dev\" tab=\"yarn\"\nGOOGLE_API_KEY=your_key_here yarn dev\n```\n\n```bash tabs=\"run-dev\" tab=\"bun\"\nGOOGLE_API_KEY=your_key_here bun run dev\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:8:keywords","version":"v0","href":"/docs/sdk/getting-started/quickstart-nextjs#what-this-gives-you","title":"What this gives you","description":"Quickstart (Next.js API Route)","section":"Quickstart (Next.js API Route)","content":"- Type-safe workflow definition\n- Explicit provider bootstrap at app level\n- Node-level model control via `useReason(...)`\n- React-first client chat state with `useChat(...)`\n- API-route transport with `createRouteChatTransport(...)`\n- Streaming chunks (`text-start`, `text-delta`, `text-end`, `message`, `done`)\n- Built-in interrupt/resume path when your nodes use `useInterrupt`\n\nNext:\n\n- [Hooks](../02-core-concepts/07-hooks.md)\n- [Interrupts and Resume](../03-guides/02-interrupts-and-resume.md)"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","nextjs","quickstart","server-actions","buffered","chunks"],"version":"v0","href":"/docs/sdk/getting-started/quickstart-nextjs-server-action","title":"Quickstart (Next.js Server Action)","description":"Build a working Next.js chat flow using server actions, Kortyx workflows, and node-level model wiring with buffered chunk handling.","section":"Getting Started","content":"$17"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:17:keywords","version":"v0","href":"/docs/sdk/getting-started/quickstart-nextjs-server-action#1-create-a-workflow","title":"1. Create a workflow","description":"Quickstart (Next.js Server Action)","section":"Quickstart (Next.js Server Action)","content":"$18"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:17:keywords","version":"v0","href":"/docs/sdk/getting-started/quickstart-nextjs-server-action#2-add-provider-entrypoint","title":"2. Add provider entrypoint","description":"Quickstart (Next.js Server Action)","section":"Quickstart (Next.js Server Action)","content":"```ts\n// src/lib/providers.ts\nexport { google } from \"@kortyx/google\";\n```\n\n```js\n// src/lib/providers.js\nexport { google } from \"@kortyx/google\";\n```\n\n> **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(...)`.\n\nThis `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."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:17:keywords","version":"v0","href":"/docs/sdk/getting-started/quickstart-nextjs-server-action#3-create-a-node","title":"3. Create a node","description":"Quickstart (Next.js Server Action)","section":"Quickstart (Next.js Server Action)","content":"$19"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:17:keywords","version":"v0","href":"/docs/sdk/getting-started/quickstart-nextjs-server-action#4-wire-an-agent","title":"4. Wire an agent","description":"Quickstart (Next.js Server Action)","section":"Quickstart (Next.js Server Action)","content":"```ts\n// src/lib/kortyx-client.ts\nimport { createAgent } from \"kortyx\";\nimport { generalChatWorkflow } from \"@/workflows/general-chat.workflow\";\n\nexport const agent = createAgent({\n workflows: [generalChatWorkflow],\n defaultWorkflowId: \"general-chat\",\n});\n```\n\n```js\n// src/lib/kortyx-client.js\nimport { createAgent } from \"kortyx\";\nimport { generalChatWorkflow } from \"@/workflows/general-chat.workflow\";\n\nexport const agent = createAgent({\n workflows: [generalChatWorkflow],\n defaultWorkflowId: \"general-chat\",\n});\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:17:keywords","version":"v0","href":"/docs/sdk/getting-started/quickstart-nextjs-server-action#5-call-streamchat-buffered-in-server-action","title":"5. Call streamChat (buffered in server action)","description":"Quickstart (Next.js Server Action)","section":"Quickstart (Next.js Server Action)","content":"$1a"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:17:keywords","version":"v0","href":"/docs/sdk/getting-started/quickstart-nextjs-server-action#6-run","title":"6. Run","description":"Quickstart (Next.js Server Action)","section":"Quickstart (Next.js Server Action)","content":"```bash tabs=\"run-dev\" tab=\"pnpm\"\nGOOGLE_API_KEY=your_key_here pnpm dev\n```\n\n```bash tabs=\"run-dev\" tab=\"npm\"\nGOOGLE_API_KEY=your_key_here npm run dev\n```\n\n```bash tabs=\"run-dev\" tab=\"yarn\"\nGOOGLE_API_KEY=your_key_here yarn dev\n```\n\n```bash tabs=\"run-dev\" tab=\"bun\"\nGOOGLE_API_KEY=your_key_here bun run dev\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:17:keywords","version":"v0","href":"/docs/sdk/getting-started/quickstart-nextjs-server-action#what-this-gives-you","title":"What this gives you","description":"Quickstart (Next.js Server Action)","section":"Quickstart (Next.js Server Action)","content":"- Type-safe workflow definition\n- Explicit provider bootstrap at app level\n- Node-level model control via `useReason(...)`\n- Buffered chunk collection through a Server Action return value\n- Chunk event types in the buffered result (`text-start`, `text-delta`, `text-end`, `done`)\n- Built-in interrupt/resume path when your nodes use `useInterrupt`\n\nNext:\n\n- [Hooks](../02-core-concepts/07-hooks.md)\n- [Interrupts and Resume](../03-guides/02-interrupts-and-resume.md)"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","defineWorkflow","workflow-schema","node-result"],"version":"v0","href":"/docs/sdk/core-concepts/define-workflows","title":"Define Workflows","description":"Define type-safe workflows and node behavior with Kortyx core contracts.","section":"Core Concepts","content":"$1b"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:25:keywords","version":"v0","href":"/docs/sdk/core-concepts/define-workflows#typescript-workflow-recommended","title":"TypeScript workflow (recommended)","description":"Define Workflows","section":"Define Workflows","content":"$1c"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:25:keywords","version":"v0","href":"/docs/sdk/core-concepts/define-workflows#callable-workflows","title":"Callable workflows","description":"Define Workflows","section":"Define Workflows","content":"A workflow called by `useWorkflow(...)` declares `inputSchema` and `outputSchema`. Its last node returns ordinary `data` and reaches `__end__`; the runtime validates accumulated child data and returns it to the caller. Existing root workflows can omit these schemas.\n\nCalls live in node code or custom hooks. Register both workflows with the agent; no special call edge or return node is required. See [Call Child Workflows](../03-guides/06-child-workflows.md) for typed definitions, string IDs, and interrupts."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:25:keywords","version":"v0","href":"/docs/sdk/core-concepts/define-workflows#opt-in-data-reducers","title":"Opt-in data reducers","description":"Define Workflows","section":"Define Workflows","content":"$1d"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:25:keywords","version":"v0","href":"/docs/sdk/core-concepts/define-workflows#node-return-shape","title":"Node return shape","description":"Define Workflows","section":"Define Workflows","content":"Nodes return a subset of `NodeResult`. See [Nodes](./03-nodes.md#node-return-values) for the full return contract and how returned `data` is passed to the next node.\n\n```ts\nreturn {\n data: { key: \"value\" },\n ui: { message: \"Rendered to user\" },\n condition: \"support.answer\",\n intent: \"optional-routing-token\",\n transitionTo: \"another-workflow-id\",\n};\n```\n\nImportant fields in practice:\n\n- `data`: merged into runtime state and forwarded as future input\n- `ui.message`: emitted as a final message event\n- `ui.structured`: emitted as `structured-data`\n- `condition` / `intent`: used for conditional edge routing\n- `transitionTo`: triggers workflow handoff"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:25:keywords","version":"v0","href":"/docs/sdk/core-concepts/define-workflows#node-behavior-currently-implemented","title":"Node behavior currently implemented","description":"Define Workflows","section":"Define Workflows","content":"From `WorkflowNodeBehavior` and runtime code:\n\n- `behavior.retry.maxAttempts`\n- `behavior.retry.delayMs`\n- `behavior.checkpoint`\n\nNote: `onError.mode` exists in schema types but is not currently applied by the execution graph compiler."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:25:keywords","version":"v0","href":"/docs/sdk/core-concepts/define-workflows#validation","title":"Validation","description":"Define Workflows","section":"Define Workflows","content":"You can validate directly:\n\n```ts\nimport { validateWorkflow } from \"kortyx\";\n\nconst result = validateWorkflow(candidate);\nif (!result.ok) {\n console.error(result.errors);\n}\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","typescript","yaml","json","workflow-loader"],"version":"v0","href":"/docs/sdk/core-concepts/formats-ts-yaml-json","title":"Formats (TS, YAML, JSON)","description":"Author workflows in TypeScript, YAML, or JSON and understand how Kortyx loads each format.","section":"Core Concepts","content":"$1e"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:32:keywords","version":"v0","href":"/docs/sdk/core-concepts/formats-ts-yaml-json#typescript","title":"TypeScript","description":"Formats (TS, YAML, JSON)","section":"Formats (TS, YAML, JSON)","content":"```ts\nimport { defineWorkflow } from \"kortyx\";\nimport { chatNode } from \"@/nodes/chat.node\";\n\nexport const wf = defineWorkflow({\n id: \"general-chat\",\n version: \"1.0.0\",\n nodes: {\n chat: { run: chatNode, params: {} },\n },\n edges: [\n [\"__start__\", \"chat\"],\n [\"chat\", \"__end__\"],\n ],\n});\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:32:keywords","version":"v0","href":"/docs/sdk/core-concepts/formats-ts-yaml-json#yaml","title":"YAML","description":"Formats (TS, YAML, JSON)","section":"Formats (TS, YAML, JSON)","content":"```yaml\nid: general-chat\nversion: 1.0.0\nnodes:\n chat:\n run: ../nodes/chat.node.ts#chatNode\n params: {}\nedges:\n - [\"__start__\", \"chat\"]\n - [\"chat\", \"__end__\"]\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:32:keywords","version":"v0","href":"/docs/sdk/core-concepts/formats-ts-yaml-json#json","title":"JSON","description":"Formats (TS, YAML, JSON)","section":"Formats (TS, YAML, JSON)","content":"```json\n{\n \"id\": \"general-chat\",\n \"version\": \"1.0.0\",\n \"nodes\": {\n \"chat\": {\n \"run\": \"../nodes/chat.node.js#chatNode\",\n \"params\": {}\n }\n },\n \"edges\": [[\"__start__\", \"chat\"], [\"chat\", \"__end__\"]]\n}\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:32:keywords","version":"v0","href":"/docs/sdk/core-concepts/formats-ts-yaml-json#how-loading-works-in-current-packages","title":"How loading works in current packages","description":"Formats (TS, YAML, JSON)","section":"Formats (TS, YAML, JSON)","content":"- `@kortyx/core/loadWorkflow` parses `string | Buffer | object`\n- JSON text starts with `{` / `[` and is parsed as JSON\n- otherwise it is parsed as YAML (`js-yaml`)\n- `@kortyx/runtime/createFileWorkflowRegistry` scans these file extensions:\n - `.workflow.ts`, `.workflow.mts`, `.workflow.js`, `.workflow.mjs`\n - `.workflow.json`, `.workflow.yml`, `.workflow.yaml`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","nodes","node-input","node-params","node-result","workflow-state"],"version":"v0","href":"/docs/sdk/core-concepts/nodes","title":"Nodes","description":"Understand Kortyx nodes, input flow, params, state handoff, and node return values.","section":"Core Concepts","content":"$1f"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:37:keywords","version":"v0","href":"/docs/sdk/core-concepts/nodes#where-nodes-are-declared","title":"Where nodes are declared","description":"Nodes","section":"Nodes","content":"$20"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:37:keywords","version":"v0","href":"/docs/sdk/core-concepts/nodes#how-client-messages-reach-a-node","title":"How client messages reach a node","description":"Nodes","section":"Nodes","content":"$21"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:37:keywords","version":"v0","href":"/docs/sdk/core-concepts/nodes#how-data-reaches-the-next-node","title":"How data reaches the next node","description":"Nodes","section":"Nodes","content":"$22"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:37:keywords","version":"v0","href":"/docs/sdk/core-concepts/nodes#node-return-values","title":"Node return values","description":"Nodes","section":"Nodes","content":"$23"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:37:keywords","version":"v0","href":"/docs/sdk/core-concepts/nodes#routing-from-a-node","title":"Routing from a node","description":"Nodes","section":"Nodes","content":"$24"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:37:keywords","version":"v0","href":"/docs/sdk/core-concepts/nodes#what-to-read-next","title":"What to read next","description":"Nodes","section":"Nodes","content":"- [Define Workflows](./01-define-workflows.md) for the full workflow shape\n- [Conditional Routing](./04-conditional-routing.md) for edge matching\n- [Hooks](./07-hooks.md) for `useReason(...)`, interrupts, and runtime state\n- [Runtime Context](./08-runtime-context.md) for request metadata in nodes\n- [Node Resolution](../05-reference/05-node-resolution.md) for `run` strings, module paths, and registry keys"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","conditional-routing","edges","condition","transition"],"version":"v0","href":"/docs/sdk/core-concepts/conditional-routing","title":"Conditional Routing","description":"Route between workflow nodes with condition tokens, edge matching, loops, and transitions.","section":"Core Concepts","content":"$25"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:44:keywords","version":"v0","href":"/docs/sdk/core-concepts/conditional-routing#edge-syntax","title":"Edge syntax","description":"Conditional Routing","section":"Conditional Routing","content":"```ts\nedges: [\n [\"route\", \"askChoice\", { when: \"choice\" }],\n [\"route\", \"askMulti\", { when: \"multi\" }],\n [\"route\", \"askText\", { when: \"text\" }],\n]\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:44:keywords","version":"v0","href":"/docs/sdk/core-concepts/conditional-routing#node-return","title":"Node return","description":"Conditional Routing","section":"Conditional Routing","content":"```ts\nreturn {\n condition: \"multi\",\n data: { mode: \"multi\" },\n};\n```\n\nExecution routing matches in this order:\n\n1. `state.lastCondition`\n2. `state.lastIntent`\n\nIf no condition matches for that conditional group, runtime falls back to an internal `__end__` mapping for that source node."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:44:keywords","version":"v0","href":"/docs/sdk/core-concepts/conditional-routing#example-loop","title":"Example loop","description":"Conditional Routing","section":"Conditional Routing","content":"Define the condition branches on the workflow edges.\n\n```ts\nedges: [\n [\"todo\", \"todo\", { when: \"more\" }],\n [\"todo\", \"final\", { when: \"done\" }],\n [\"final\", \"__end__\"],\n]\n```\n\nReturn the matching condition from the node.\n\n```ts\nreturn {\n condition: hasMore ? \"more\" : \"done\",\n data: { idx: nextIdx },\n};\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:44:keywords","version":"v0","href":"/docs/sdk/core-concepts/conditional-routing#workflow-transition-different-from-edge-routing","title":"Workflow transition (different from edge routing)","description":"Conditional Routing","section":"Conditional Routing","content":"Use `transitionTo` to jump to another workflow id:\n\n```ts\nreturn {\n transitionTo: \"general-chat\",\n data: { reason: \"fallback\" },\n};\n```\n\nThe orchestrator emits a `transition` chunk and loads the target workflow with `selectWorkflow`."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:44:keywords","version":"v0","href":"/docs/sdk/core-concepts/conditional-routing#studio-topology-visibility","title":"Studio topology visibility","description":"Conditional Routing","section":"Conditional Routing","content":"$26"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","createAgent","workflow-registry","config","runtime","strict"],"version":"v0","href":"/docs/sdk/core-concepts/create-agent","title":"createAgent","description":"Set up createAgent with strict workflow/runtime config and explicit provider wiring in nodes.","section":"Core Concepts","content":"$27"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:50:keywords","version":"v0","href":"/docs/sdk/core-concepts/create-agent#minimal-usage","title":"Minimal usage","description":"createAgent","section":"createAgent","content":"```ts\nimport { createAgent } from \"kortyx\";\nimport { generalChatWorkflow } from \"@/workflows/general-chat.workflow\";\n\nexport const agent = createAgent({\n workflows: [generalChatWorkflow],\n defaultWorkflowId: \"general-chat\",\n});\n```\n\n```js\nimport { createAgent } from \"kortyx\";\nimport { generalChatWorkflow } from \"@/workflows/general-chat.workflow\";\n\nexport const agent = createAgent({\n workflows: [generalChatWorkflow],\n defaultWorkflowId: \"general-chat\",\n});\n```\n\nPass `sessionId` per request when you want analytics/tracing correlation across requests."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:50:keywords","version":"v0","href":"/docs/sdk/core-concepts/create-agent#workflow-source-resolution","title":"Workflow source resolution","description":"createAgent","section":"createAgent","content":"`createAgent` can resolve workflows from:\n\n1. `workflowRegistry`\n2. `workflows`\n3. `workflowsDir`\n4. fallback default: `./src/workflows`\n\nOnly one of `workflowRegistry`, `workflows`, or `workflowsDir` is allowed in the same config."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:50:keywords","version":"v0","href":"/docs/sdk/core-concepts/create-agent#config-knobs","title":"Config knobs","description":"createAgent","section":"createAgent","content":"Useful fields in `CreateAgentArgs`:\n\n- `workflows` / `workflowRegistry` / `workflowsDir`\n- `defaultWorkflowId`\n- `frameworkAdapter`\n- `getProvider` (advanced: custom provider registry lookup)\n\n> **Good to know:** `createAgent(...)` does not manage business/data persistence for your app. Use your own DB or service clients inside node code, and use framework adapters only for runtime persistence such as interrupt/resume.\n\nResult object:\n\n```ts\nconst stream = await agent.streamChat(messages, options);\n```\n\n- `agent.streamChat(...)`: returns `AsyncIterable` (best for custom route handling)"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","streamChat","sse","workflow-selection","resume"],"version":"v0","href":"/docs/sdk/core-concepts/stream-chat","title":"streamChat","description":"Use agent.streamChat for flexible route handling, then return SSE or buffered JSON.","section":"Core Concepts","content":"$28"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:54:keywords","version":"v0","href":"/docs/sdk/core-concepts/stream-chat#recommended-usage","title":"Recommended usage","description":"streamChat","section":"streamChat","content":"```ts\nimport { createAgent } from \"kortyx\";\n\nconst agent = createAgent({\n workflowsDir: \"src/workflows\",\n});\n\nconst stream = await agent.streamChat(messages, {\n // optional\n sessionId,\n workflowId,\n});\n```\n```js\nimport { createAgent } from \"kortyx\";\n\nconst agent = createAgent({\n workflowsDir: \"src/workflows\",\n});\n\nconst stream = await agent.streamChat(messages, {\n // optional\n sessionId,\n workflowId,\n});\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:54:keywords","version":"v0","href":"/docs/sdk/core-concepts/stream-chat#recommended-react-client-path","title":"Recommended React client path","description":"streamChat","section":"streamChat","content":"If your server route returns SSE, the default React client path is now `@kortyx/react`.\n\n```ts\nimport { createRouteChatTransport, useChat } from \"@kortyx/react\";\n\nexport function ChatPage() {\n const chat = useChat({\n transport: createRouteChatTransport({\n endpoint: \"/api/chat\",\n }),\n });\n\n return ;\n}\n```\n```js\nimport { createRouteChatTransport, useChat } from \"@kortyx/react\";\n\nexport function ChatPage() {\n const chat = useChat({\n transport: createRouteChatTransport({\n endpoint: \"/api/chat\",\n }),\n });\n\n return ;\n}\n```\n\nUse `useChat()` when you want:\n\n- finalized `messages`\n- live `streamContentPieces`\n- interrupt resume handling\n- default browser storage\n\n> **Good to know:** `useChat()` is the recommended client abstraction for React apps. Drop down to `useStructuredStreams()` or `applyStructuredChunk(...)` only when you need custom stream wiring."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:54:keywords","version":"v0","href":"/docs/sdk/core-concepts/stream-chat#custom-route-mode-stream-flag","title":"Custom route mode (stream flag)","description":"streamChat","section":"streamChat","content":"$29"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:54:keywords","version":"v0","href":"/docs/sdk/core-concepts/stream-chat#buffered-helpers-choose-one","title":"Buffered helpers (choose one)","description":"streamChat","section":"streamChat","content":"$2a"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:54:keywords","version":"v0","href":"/docs/sdk/core-concepts/stream-chat#parameters","title":"Parameters","description":"streamChat","section":"streamChat","content":"- `messages`: full chat history for the current turn (required).\n- `options.sessionId`: optional conversation id for analytics/tracing correlation.\n- `options.workflowId`: force this request to start in a specific workflow.\n- `options.context`: request metadata available to nodes through `useRuntimeContext(...)`."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:54:keywords","version":"v0","href":"/docs/sdk/core-concepts/stream-chat#returns","title":"Returns","description":"streamChat","section":"streamChat","content":"`agent.streamChat(...)`: `Promise>`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:54:keywords","version":"v0","href":"/docs/sdk/core-concepts/stream-chat#what-happens-under-the-hood","title":"What happens under the hood","description":"streamChat","section":"streamChat","content":"1. resolves runtime config and session context\n2. chooses the workflow (including request-level workflow override)\n3. builds initial state from input + prior messages\n4. resumes interrupted flows when resume metadata is present\n5. runs the workflow graph and streams chunks as SSE\n6. returns an async stream of `StreamChunk` events"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:54:keywords","version":"v0","href":"/docs/sdk/core-concepts/stream-chat#workflow-override-per-request","title":"Workflow override per request","description":"streamChat","section":"streamChat","content":"When not resuming, `options.workflowId` can override entry workflow for this request."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:54:keywords","version":"v0","href":"/docs/sdk/core-concepts/stream-chat#request-context","title":"Request context","description":"streamChat","section":"streamChat","content":"Use `options.context` for request metadata that node code needs, such as selected thread id, locale, or server-approved auth context. See [Runtime Context](./08-runtime-context.md) for the full client-to-node flow and security boundary."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:54:keywords","version":"v0","href":"/docs/sdk/core-concepts/stream-chat#resume-behavior","title":"Resume behavior","description":"streamChat","section":"streamChat","content":"If the last message contains resume metadata, `agent.streamChat(...)` resumes the interrupted flow automatically."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","hooks","useTool","useReason","useInterrupt","useWorkflow","createWorkflowHooks","useWorkflowState","useNodeState","useStructuredData"],"version":"v0","href":"/docs/sdk/core-concepts/hooks","title":"Hooks","description":"Practical guide to when each hook is useful and how structured streaming works in real node logic.","section":"Core Concepts","content":"$2b"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#quick-selection","title":"Quick Selection","description":"Hooks","section":"Hooks","content":"- Need a child workflow result before continuing: `useWorkflow(...)`\n- Need typed workflow names: `createWorkflowHooks(...)`\n- Need direct observable tool execution: `useTool({tool, input})`\n- Need an LLM call in a node: `useReason(...)`\n- Need manual human-in-the-loop input: `useInterrupt(...)`\n- Need state local to one node execution flow: `useNodeState(...)`\n- Need state shared across nodes in the same run: `useWorkflowState(...)`\n- Need request metadata inside a node: `useRuntimeContext(...)`\n- Need structured UI updates in the stream: `useStructuredData(...)`\n- Need to record a handled error without stopping execution: `reportError(...)`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#reporterrorerror-options","title":"reportError(error, options?)","description":"Hooks","section":"Hooks","content":"$2c"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#usetooltool-input","title":"useTool({tool, input})","description":"Hooks","section":"Hooks","content":"$2d"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#useworkflow","title":"useWorkflow(...)","description":"Hooks","section":"Hooks","content":"Await a registered child workflow from a node or custom hook, then use its validated `result.data`. Use a typed workflow definition or bind string IDs with `createWorkflowHooks(...)` for inferred input and output types. Callable workflows declare input/output schemas; calling parents need no extra graph declarations.\n\nThe child uses ordinary nodes and ends at `__end__`. Its human interrupts pause the parent; resume and snapshot-backed forks preserve the nested child state. Calls are sequential and require stable IDs. See [Call Child Workflows](../03-guides/06-child-workflows.md) for the complete implementation and replay contract."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#structured-streaming-mental-model","title":"Structured Streaming Mental Model","description":"Hooks","section":"Hooks","content":"Think about structured streaming as a second channel beside normal assistant text:\n\n- `text-*` chunks are text you render as text\n- `structured-data` chunks are object updates you render as UI state\n- `streamId` identifies one logical structured stream\n- `kind` tells the client how to apply the update\n\nIn practice:\n\n- use `useReason({ outputs })` when the model chooses which contract to emit\n- use `useStructuredData({ contract, ... })` when your node logic owns the updates\n- existing `useReason({ outputSchema, structured })` calls still work, but are deprecated"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#usereason","title":"useReason(...)","description":"Hooks","section":"Hooks","content":"Use this for the main model call in a node.\n\nTypical use:\n\n- schema-constrained outputs\n- optional interrupt flow (`interrupt`)\n- structured stream payloads (`structured`)"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#emission-vs-uimessage","title":"Emission vs ui.message","description":"Hooks","section":"Hooks","content":"$2e"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#model-selected-output-contracts","title":"Model-selected output contracts","description":"Hooks","section":"Hooks","content":"$2f"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#mixed-tool-output-and-interrupt-calls","title":"Mixed tool, output, and interrupt calls","description":"Hooks","section":"Hooks","content":"$30"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#deprecated-single-json-output-schema","title":"Deprecated: single JSON output schema","description":"Hooks","section":"Hooks","content":"`useReason({ outputSchema, structured })` and `result.output` remain supported for existing calls, including incremental field streaming, but are deprecated and scheduled for removal in the next major version. New tool-capable model integrations should use output contracts. TypeSafe Jev is a temporary exception: its native decision API cannot call tools, so keep its current `jevOutputSchema(...)` path until a non-tool replacement is available."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#example-stream-an-email-draft-as-json","title":"Example: stream an email draft as JSON","description":"Hooks","section":"Hooks","content":"$31"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#what-usereason-returns","title":"What useReason(...) returns","description":"Hooks","section":"Hooks","content":"$32"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#common-model-call-options","title":"Common model call options","description":"Hooks","section":"Hooks","content":"These are the main cross-provider options you can pass to `useReason(...)`:\n\n```ts\nconst abortController = new AbortController();\n\nconst result = await useReason({\n model: google(\"gemini-2.5-flash\"),\n input: \"Summarize this changelog.\",\n temperature: 0.2,\n maxOutputTokens: 600,\n stopSequences: [\"\"],\n abortSignal: abortController.signal,\n reasoning: {\n effort: \"medium\",\n maxTokens: 256,\n },\n responseFormat: { type: \"json\" },\n providerOptions: {},\n});\n```\n```js\nconst abortController = new AbortController();\n\nconst result = await useReason({\n model: google(\"gemini-2.5-flash\"),\n input: \"Summarize this changelog.\",\n temperature: 0.2,\n maxOutputTokens: 600,\n stopSequences: [\"\"],\n abortSignal: abortController.signal,\n reasoning: {\n effort: \"medium\",\n maxTokens: 256,\n },\n responseFormat: { type: \"json\" },\n providerOptions: {},\n});\n```\n\nIf a provider cannot fully support one of these generic options yet, it should surface a warning instead of silently ignoring it."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#mcp-tools","title":"MCP tools","description":"Hooks","section":"Hooks","content":"$33"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#default-behavior","title":"Default behavior","description":"Hooks","section":"Hooks","content":"If you provide `structured` but do not provide `fields`, `useReason(...)` emits one final structured object when parsing and validation succeed.\n\nThat is the default and simplest path:\n\n```ts\nconst result = await useReason({\n model: google(\"gemini-2.5-flash\"),\n input: \"Write a short beta launch email for customers.\",\n outputSchema: EmailDraftSchema,\n structured: {\n dataType: \"email.compose\",\n },\n});\n```\n```js\nconst result = await useReason({\n model: google(\"gemini-2.5-flash\"),\n input: \"Write a short beta launch email for customers.\",\n outputSchema: EmailDraftSchema,\n structured: {\n dataType: \"email.compose\",\n },\n});\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#current-incremental-streaming-limits","title":"Current incremental streaming limits","description":"Hooks","section":"Hooks","content":"$34"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#when-to-use-usereason-structured-","title":"When to use useReason({ structured })","description":"Hooks","section":"Hooks","content":"Use it when:\n\n- the model result itself is the UI object you want to render\n- you want the final object validated against `outputSchema`\n- a string field or array field should become visible before the full object is done\n\nUse `useStructuredData(...)` instead when:\n\n- the updates come from app logic rather than the model\n- you need precise control over when fields are emitted\n- you want to emit `set`, `append`, `text-delta`, or `final` directly"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#useinterrupt-request-schemas-","title":"useInterrupt({ request, ...schemas })","description":"Hooks","section":"Hooks","content":"Use this when you want fully manual interrupt payloads without LLM-generated request shaping.\n\n```ts\nimport { useInterrupt } from \"kortyx\";\n\nconst selected = await useInterrupt({\n id: \"pick-one\",\n request: {\n kind: \"choice\",\n question: \"Pick one\",\n options: [\n { id: \"a\", label: \"Alpha\" },\n { id: \"b\", label: \"Beta\" },\n ],\n },\n});\n```\n```js\nimport { useInterrupt } from \"kortyx\";\n\nconst selected = await useInterrupt({\n id: \"pick-one\",\n request: {\n kind: \"choice\",\n question: \"Pick one\",\n options: [\n { id: \"a\", label: \"Alpha\" },\n { id: \"b\", label: \"Beta\" },\n ],\n },\n});\n```\n\nReturn:\n\n- `string` for `text` and `choice`\n- `string[]` for `multi-choice`\n\nUse stable `id` values for interrupts in nodes that can replay or contain multiple interrupt calls."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#usenodestate-and-useworkflowstate","title":"useNodeState and useWorkflowState","description":"Hooks","section":"Hooks","content":"Node-local state:\n\n```ts\nconst [idx, setIdx] = useNodeState(0);\n```\n```js\nconst [idx, setIdx] = useNodeState(0);\n```\n\nWorkflow-shared state:\n\n```ts\nconst [todos, setTodos] = useWorkflowState(\"todos\", []);\n```\n```js\nconst [todos, setTodos] = useWorkflowState(\"todos\", []);\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#state-lifetime-and-limits","title":"State Lifetime and Limits","description":"Hooks","section":"Hooks","content":"`useNodeState`:\n\n- persists for repeated executions of the same node inside one run\n- is node-local only\n\n`useWorkflowState`:\n\n- persists across nodes and workflow transitions within the same run\n- restores on interrupt resume for that run\n- is isolated from state inside child workflows called with `useWorkflow`\n\nAcross messages and sessions:\n\n- hook state is not a long-term session store\n- a new chat request starts a new run with fresh hook state\n- for cross-request persistence, call your own DBs or service clients from node code\n\nDurability and practical limits:\n\n- hook state is tied to runtime checkpoint persistence\n- in-memory framework adapter is process-local and not restart-safe\n- Redis framework adapter can restore across restarts until TTL expiry\n- keep hook state small and JSON-serializable"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#useruntimecontext","title":"useRuntimeContext(...)","description":"Hooks","section":"Hooks","content":"Use this when node code needs request metadata passed from the route, such as selected thread id, locale, or server-approved auth context.\n\n```ts\nimport { useRuntimeContext } from \"kortyx\";\n\ntype AppContext = {\n threadId?: string;\n userId: string;\n};\n\nconst context = useRuntimeContext();\n```\n```js\nimport { useRuntimeContext } from \"kortyx\";\n\nconst context = useRuntimeContext();\n```\n\nSee [Runtime Context](./08-runtime-context.md) for the full client-to-route-to-node flow and security boundary."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#usestructureddata","title":"useStructuredData(...)","description":"Hooks","section":"Hooks","content":"Use this when your node wants to emit UI updates directly.\n\nThe API is intentionally simple:\n\n- `kind: \"set\"` sets one field at a path\n- `kind: \"append\"` appends items to an array field\n- `kind: \"text-delta\"` appends text to a string field\n- `kind: \"final\"` publishes the completed object\n\nIf you omit `kind`, `useStructuredData(...)` defaults to `final`."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#example-drive-an-email-composer-ui-yourself","title":"Example: drive an email composer UI yourself","description":"Hooks","section":"Hooks","content":"$35"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#streamid-and-id","title":"streamId and id","description":"Hooks","section":"Hooks","content":"$36"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#useabortsignal","title":"useAbortSignal","description":"Hooks","section":"Hooks","content":"$37"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:65:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#automatic-model-error-diagnostics","title":"Automatic model error diagnostics","description":"Hooks","section":"Hooks","content":"$38"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","runtime-context","useRuntimeContext","context","request-metadata"],"version":"v0","href":"/docs/sdk/core-concepts/runtime-context","title":"Runtime Context","description":"Pass request metadata from clients and routes into node code without mixing it with user input or node params.","section":"Core Concepts","content":"$39"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:92:keywords","version":"v0","href":"/docs/sdk/core-concepts/runtime-context#the-three-inputs","title":"The Three Inputs","description":"Runtime Context","section":"Runtime Context","content":"Kortyx has three different data lanes:\n\n| Lane | Where it comes from | Where to read it |\n| --- | --- | --- |\n| `input` | latest user message, then merged node `data` | node function argument |\n| `params` | workflow node definition | node function argument |\n| runtime `context` | route/client request metadata | `useRuntimeContext(...)` |"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:92:keywords","version":"v0","href":"/docs/sdk/core-concepts/runtime-context#client-to-node-flow","title":"Client to Node Flow","description":"Runtime Context","section":"Runtime Context","content":"$3a"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:92:keywords","version":"v0","href":"/docs/sdk/core-concepts/runtime-context#read-context-in-a-node","title":"Read Context in a Node","description":"Runtime Context","section":"Runtime Context","content":"Inside node execution, call `useRuntimeContext(...)`.\n\n```ts\nimport { useRuntimeContext } from \"kortyx\";\n\ntype AppContext = {\n threadId?: string;\n locale?: string;\n userId: string;\n tenantId: string;\n};\n\nexport async function supportNode() {\n const context = useRuntimeContext();\n\n return {\n data: {\n threadId: context.threadId,\n userId: context.userId,\n tenantId: context.tenantId,\n },\n };\n}\n```\n```js\nimport { useRuntimeContext } from \"kortyx\";\n\nexport async function supportNode() {\n const context = useRuntimeContext();\n\n return {\n data: {\n threadId: context.threadId,\n userId: context.userId,\n tenantId: context.tenantId,\n },\n };\n}\n```\n\n`useRuntimeContext(...)` returns an object. If no context was passed for the request, it returns an empty object."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:92:keywords","version":"v0","href":"/docs/sdk/core-concepts/runtime-context#what-not-to-put-in-context","title":"What Not to Put in Context","description":"Runtime Context","section":"Runtime Context","content":"- Do not put provider credentials in context.\n- Do not trust client-provided user ids, roles, permissions, or tenant access.\n- Do not put large documents or full chat history in context; use messages, summaries, retrieval, or app services.\n- Do not use context for static node settings; use node `params`."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:92:keywords","version":"v0","href":"/docs/sdk/core-concepts/runtime-context#what-to-read-next","title":"What to Read Next","description":"Runtime Context","section":"Runtime Context","content":"- [Nodes](./03-nodes.md) for `input`, `params`, and `data`\n- [streamChat](./06-stream-chat.md) for request handling\n- [React Client](../05-reference/06-react-client.md) for `useChat({ context })`\n- [SSE for API Routes](../03-guides/11-sse.md) for authenticated streaming routes"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","project-structure","architecture","folders","server-client-boundary"],"version":"v0","href":"/docs/sdk/guides/project-structure","title":"Project Structure","description":"Place Kortyx agent setup, workflows, nodes, providers, persistence, app services, and React UI in clear server/client boundaries.","section":"Guides","content":"$3b"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:98:keywords","version":"v0","href":"/docs/sdk/guides/project-structure#responsibility-boundaries","title":"Responsibility Boundaries","description":"Project Structure","section":"Project Structure","content":"| Area | Owns |\n| --- | --- |\n| Server-only Kortyx modules | `createAgent(...)`, provider setup, workflows, nodes, runtime persistence |\n| Client UI | `@kortyx/react`, chat components, transport setup, stream-piece rendering |\n| App-owned services | auth, rate limits, business database writes, durable conversation history, domain APIs |\n\nDo not import server-only Kortyx runtime modules into client components. Keep provider credentials and runtime persistence adapters on the server."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:98:keywords","version":"v0","href":"/docs/sdk/guides/project-structure#suggested-nextjs-layout","title":"Suggested Next.js Layout","description":"Project Structure","section":"Project Structure","content":"```text\nsrc/\n app/\n api/chat/route.ts\n page.tsx\n components/\n chat/\n chat-window.tsx\n assistant-live-message.tsx\n lib/\n kortyx-client.ts\n providers.ts\n nodes/\n chat.node.ts\n classify.node.ts\n workflows/\n general-chat.workflow.ts\n services/\n auth.ts\n conversations.ts\n schemas/\n chat.ts\n```\n\nUse this as a baseline, not a migration requirement. In existing apps, map each responsibility into the nearest existing folder."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:98:keywords","version":"v0","href":"/docs/sdk/guides/project-structure#suggested-react-plus-node-layout","title":"Suggested React Plus Node Layout","description":"Project Structure","section":"Project Structure","content":"```text\napps/\n web/\n src/\n components/\n chat/\n lib/\n kortyx-transport.ts\n routes/\n api/\n src/\n routes/\n chat.ts\n lib/\n kortyx-client.ts\n providers.ts\n nodes/\n workflows/\n services/\n schemas/\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:98:keywords","version":"v0","href":"/docs/sdk/guides/project-structure#rules","title":"Rules","description":"Project Structure","section":"Project Structure","content":"- Put `createAgent(...)` in a server-only module.\n- Use built-in provider refs such as `google(...)` directly when default environment-variable setup is enough.\n- Put explicit provider factories or custom transport settings in a server-only module.\n- Put workflow topology in workflow files.\n- Put executable node logic in node files.\n- Put database writes, auth, billing checks, and domain APIs in app services.\n- Put durable product records in your app database, not Kortyx runtime state.\n- Put short-lived interrupt/resume execution state in Kortyx runtime persistence."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:98:keywords","version":"v0","href":"/docs/sdk/guides/project-structure#example-server-boundary","title":"Example Server Boundary","description":"Project Structure","section":"Project Structure","content":"```ts\n// src/lib/kortyx-client.ts\nimport { createAgent } from \"kortyx\";\nimport { createFrameworkAdapterFromEnv } from \"kortyx\";\nimport { generalChatWorkflow } from \"@/workflows/general-chat.workflow\";\n\nexport const agent = createAgent({\n workflows: [generalChatWorkflow],\n defaultWorkflowId: \"general-chat\",\n frameworkAdapter: createFrameworkAdapterFromEnv(),\n});\n```\n```js\n// src/lib/kortyx-client.js\nimport { createAgent } from \"kortyx\";\nimport { createFrameworkAdapterFromEnv } from \"kortyx\";\nimport { generalChatWorkflow } from \"@/workflows/general-chat.workflow\";\n\nexport const agent = createAgent({\n workflows: [generalChatWorkflow],\n defaultWorkflowId: \"general-chat\",\n frameworkAdapter: createFrameworkAdapterFromEnv(),\n});\n```\n\n`src/lib/kortyx-client.ts` should be imported by API routes or other server-only modules, not by React client components."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:98:keywords","version":"v0","href":"/docs/sdk/guides/project-structure#what-to-read-next","title":"What to Read Next","description":"Project Structure","section":"Project Structure","content":"- [Quickstart (Next.js API Route)](../01-getting-started/02-quickstart-nextjs.md)\n- [React Frontend + Node Backend](./03-react-node-backend.md)\n- [Runtime Persistence](../04-production/01-persistence.md)\n- [Runtime Persistence Adapters](../04-production/02-framework-adapters.md)"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","interrupt","resume","human-input","pending-requests","checkpoints"],"version":"v0","href":"/docs/sdk/guides/interrupts-and-resume","title":"Interrupts and Resume","description":"Pause node execution for user input and resume deterministically using tokens and request ids.","section":"Guides","content":"$3c"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:105:keywords","version":"v0","href":"/docs/sdk/guides/interrupts-and-resume#node-side","title":"Node side","description":"Interrupts and Resume","section":"Interrupts and Resume","content":"$3d"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:105:keywords","version":"v0","href":"/docs/sdk/guides/interrupts-and-resume#interrupts-inside-child-workflows","title":"Interrupts inside child workflows","description":"Interrupts and Resume","section":"Interrupts and Resume","content":"A child called with `useWorkflow(...)` can use either interrupt hook. Its request is bridged through the parent stream and uses the existing resume token/request ID protocol. The parent continues after the child completes. Do not start the child again as a separate root request to answer its interrupt.\n\nSee [Call Child Workflows](./06-child-workflows.md) for a working typed example, replay rules, and fork behavior."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:105:keywords","version":"v0","href":"/docs/sdk/guides/interrupts-and-resume#stream-side","title":"Stream side","description":"Interrupts and Resume","section":"Interrupts and Resume","content":"During interrupt, runtime/orchestrator emits:\n\n```json\n{\n \"type\": \"interrupt\",\n \"requestId\": \"human-...\",\n \"resumeToken\": \"...\",\n \"workflow\": \"interrupt-demo\",\n \"node\": \"askMulti\",\n \"input\": {\n \"kind\": \"multi-choice\",\n \"multiple\": true,\n \"question\": \"Pick one or more:\",\n \"options\": [\n { \"id\": \"product\", \"label\": \"Product\" },\n { \"id\": \"design\", \"label\": \"Design\" }\n ]\n }\n}\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:105:keywords","version":"v0","href":"/docs/sdk/guides/interrupts-and-resume#resume-payload","title":"Resume payload","description":"Interrupts and Resume","section":"Interrupts and Resume","content":"`@kortyx/agent` resume metadata shape (from `parseResumeMeta`):\n\n```json\n{\n \"role\": \"user\",\n \"content\": \"Product\",\n \"metadata\": {\n \"resume\": {\n \"token\": \"\",\n \"requestId\": \"\",\n \"selected\": [\"product\"]\n }\n }\n}\n```\n\nAccepted `selected` shapes:\n\n- string\n- string[]\n- `{ choice: { id } }`\n- `{ choices: [{ id }, ...] }`\n\nContract interrupts use an opaque structured value instead of `selected`:\n\n```json\n{\n \"resume\": {\n \"token\": \"\",\n \"requestId\": \"\",\n \"value\": { \"type\": \"select\", \"jobId\": \"job-123\" }\n }\n}\n```\n\nIn `@kortyx/react`, custom renderers receive `piece.contract`,\n`piece.request`, `piece.schemaId`, and `piece.schemaVersion`, then call\n`respondToInterrupt(piece, { value })`. The server validates that value against\nthe selected contract's response schema before reasoning continues."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:105:keywords","version":"v0","href":"/docs/sdk/guides/interrupts-and-resume#inspecting-contract-interrupts-in-studio","title":"Inspecting contract interrupts in Studio","description":"Interrupts and Resume","section":"Interrupts and Resume","content":"$3e"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:105:keywords","version":"v0","href":"/docs/sdk/guides/interrupts-and-resume#replay-safe-side-effects","title":"Replay-Safe Side Effects","description":"Interrupts and Resume","section":"Interrupts and Resume","content":"$3f"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:105:keywords","version":"v0","href":"/docs/sdk/guides/interrupts-and-resume#persistence-requirements","title":"Persistence requirements","description":"Interrupts and Resume","section":"Interrupts and Resume","content":"Resume only works if the framework adapter persists pending requests + checkpoints.\n\n- in-memory adapter: good for local dev, not restart-safe\n- redis adapter: recommended for production resume\n- hook state (`useNodeState` / `useWorkflowState`) follows the same checkpoint lifetime and limits"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:105:keywords","version":"v0","href":"/docs/sdk/guides/interrupts-and-resume#expiry-and-late-responses","title":"Expiry and late responses","description":"Interrupts and Resume","section":"Interrupts and Resume","content":"Pending interrupt state expires after 15 minutes by default. Configure the TTL\nfor the application with `KORTYX_FRAMEWORK_TTL_MS`, or pass `ttlMs` to the\nframework adapter:\n\n```ts\nimport { createRedisFrameworkAdapter } from \"kortyx\";\n\nconst frameworkAdapter = createRedisFrameworkAdapter({\n url: process.env.KORTYX_REDIS_URL!,\n ttlMs: 60 * 60 * 1000,\n});\n```\n\nThe runtime includes the resulting `expiresAt` timestamp in\n`interrupt.created`. Clients should stop offering the original resume action\nafter that time.\n\nOnce the checkpoint expires, its resume token cannot continue the original\nrun. If the same message is still sent, Kortyx ignores the expired resume\nmetadata and lets the application handle it as normal input. An application\nfallback may therefore start a new run, but it did not resume the expired run.\nKortyx Studio preserves that distinction."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:105:keywords","version":"v0","href":"/docs/sdk/guides/interrupts-and-resume#static-choices-and-dynamic-pickers","title":"Static choices and dynamic pickers","description":"Interrupts and Resume","section":"Interrupts and Resume","content":"An interrupt can obtain choices in two ways:\n\n- a **static choice** embeds its options in the interrupt request;\n- a **dynamic picker** sends a `schemaId` and lets the client resolve options\n from its own data source.\n\nA dynamic picker can therefore have `optionCount: 0` in telemetry even when the\nclient shows valid choices. The count describes options embedded by the server,\nnot the number rendered by the client.\n\nSee [Runtime Persistence Adapters](../04-production/02-framework-adapters.md)."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:105:keywords","version":"v0","href":"/docs/sdk/guides/interrupts-and-resume#complete-a-response-before-execution-finishes","title":"Complete a response before execution finishes","description":"Interrupts and Resume","section":"Interrupts and Resume","content":"See [Background Continuation](./08-background-continuation.md) for `completeResponse()`, independent execution lifetime, and discovering human requests through `agent.listInterrupts()` without Studio. A `done` chunk ends client delivery; it does not prove successful execution."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:105:keywords","version":"v0","href":"/docs/sdk/guides/interrupts-and-resume#invalid-model-authored-requests","title":"Invalid model-authored requests","description":"Interrupts and Resume","section":"Interrupts and Resume","content":"If a named interrupt tool's request arguments fail its schema, `useReason` returns bounded `isError` feedback to the model. It can correct its arguments within `toolExecution.maxSteps` and the shared model allowance. An invalid attempt does not emit an interrupt or consume `interrupts.maxRequests`. `mode: \"required\"` still requires valid human input before finishing. Invalid human responses remain validation failures; correction feedback never grants approval to execute a tool."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","react","node","backend","sse","separate-apps"],"version":"v0","href":"/docs/sdk/guides/react-node-backend","title":"React Frontend + Node Backend","description":"Run Kortyx on a Node backend while a separate React app consumes streamed chat responses.","section":"Guides","content":"$40"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:117:keywords","version":"v0","href":"/docs/sdk/guides/react-node-backend#backend-responsibilities","title":"Backend Responsibilities","description":"React Frontend + Node Backend","section":"React Frontend + Node Backend","content":"- Own `createAgent(...)`, workflows, nodes, providers, auth, rate limits, and runtime persistence.\n- Expose a chat route that accepts `messages`, `sessionId`, `workflowId`, and approved `context`.\n- Return SSE for live streaming.\n- Return buffered JSON only for non-live clients or tests."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:117:keywords","version":"v0","href":"/docs/sdk/guides/react-node-backend#frontend-responsibilities","title":"Frontend Responsibilities","description":"React Frontend + Node Backend","section":"React Frontend + Node Backend","content":"- Use `@kortyx/react` for chat state and transport.\n- Render finalized `messages` separately from active `streamContentPieces`.\n- Send only request metadata as client context.\n- Never send provider credentials or server-only config to the browser."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:117:keywords","version":"v0","href":"/docs/sdk/guides/react-node-backend#backend-route-shape","title":"Backend Route Shape","description":"React Frontend + Node Backend","section":"React Frontend + Node Backend","content":"$41"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:117:keywords","version":"v0","href":"/docs/sdk/guides/react-node-backend#react-transport","title":"React Transport","description":"React Frontend + Node Backend","section":"React Frontend + Node Backend","content":"On the frontend, point `createRouteChatTransport(...)` at the backend URL.\n\n```tsx\nimport { createRouteChatTransport, useChat } from \"@kortyx/react\";\n\nexport function ChatPage({ apiBaseUrl }: { apiBaseUrl: string }) {\n const chat = useChat({\n transport: createRouteChatTransport({\n endpoint: `${apiBaseUrl}/chat`,\n }),\n context: {\n source: \"web\",\n },\n });\n\n return ;\n}\n```\n```jsx\nimport { createRouteChatTransport, useChat } from \"@kortyx/react\";\n\nexport function ChatPage({ apiBaseUrl }) {\n const chat = useChat({\n transport: createRouteChatTransport({\n endpoint: `${apiBaseUrl}/chat`,\n }),\n context: {\n source: \"web\",\n },\n });\n\n return ;\n}\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:117:keywords","version":"v0","href":"/docs/sdk/guides/react-node-backend#custom-backends","title":"Custom Backends","description":"React Frontend + Node Backend","section":"React Frontend + Node Backend","content":"Use a custom transport only when your backend cannot expose the standard Kortyx stream protocol. A custom transport must:\n\n- preserve `sessionId`, `workflowId`, `messages`, and `context` semantics\n- call `onChunk` for every parsed stream chunk\n- forward `context.signal` to `fetch` or the request layer so `abort()` works\n- surface transport errors instead of swallowing them\n\nSee [React Client](../05-reference/06-react-client.md#custom-transport) for the full transport shape."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:117:keywords","version":"v0","href":"/docs/sdk/guides/react-node-backend#what-to-read-next","title":"What to Read Next","description":"React Frontend + Node Backend","section":"React Frontend + Node Backend","content":"- [Project Structure](./01-project-structure.md)\n- [Rendering Streamed Chat](./04-render-streamed-chat.md)\n- [SSE for API Routes](./11-sse.md)\n- [Runtime Context](../02-core-concepts/08-runtime-context.md)"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","react","rendering","streamContentPieces","useChat","interrupts"],"version":"v0","href":"/docs/sdk/guides/render-streamed-chat","title":"Rendering Streamed Chat","description":"Render finalized chat history, active stream pieces, structured data, interrupts, errors, and abort controls with @kortyx/react.","section":"Guides","content":"$42"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:124:keywords","version":"v0","href":"/docs/sdk/guides/render-streamed-chat#basic-pattern","title":"Basic Pattern","description":"Rendering Streamed Chat","section":"Rendering Streamed Chat","content":"$43"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:124:keywords","version":"v0","href":"/docs/sdk/guides/render-streamed-chat#render-piece-types","title":"Render Piece Types","description":"Rendering Streamed Chat","section":"Rendering Streamed Chat","content":"$44"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:124:keywords","version":"v0","href":"/docs/sdk/guides/render-streamed-chat#interrupt-controls","title":"Interrupt Controls","description":"Rendering Streamed Chat","section":"Rendering Streamed Chat","content":"$45"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:124:keywords","version":"v0","href":"/docs/sdk/guides/render-streamed-chat#abort-and-errors","title":"Abort and Errors","description":"Rendering Streamed Chat","section":"Rendering Streamed Chat","content":"Show an abort control while a stream is active.\n\n```tsx\nimport type { UseChatValue } from \"@kortyx/react\";\n\nexport function ChatControls({ chat }: { chat: UseChatValue }) {\n return (\n

\n {chat.canAbort ? (\n \n ) : null}\n\n {chat.error ? (\n \n ) : null}\n

\n );\n}\n```\n```jsx\nexport function ChatControls({ chat }) {\n return (\n

\n {chat.canAbort ? (\n \n ) : null}\n\n {chat.error ? (\n \n ) : null}\n

\n );\n}\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:124:keywords","version":"v0","href":"/docs/sdk/guides/render-streamed-chat#common-mistakes","title":"Common Mistakes","description":"Rendering Streamed Chat","section":"Rendering Streamed Chat","content":"- Rendering live assistant text from both `streamContentPieces` and the latest `messages` entry.\n- Returning `ui.message` with the same text already streamed by `useReason({ emit: true })`.\n- Treating `messages` as token-by-token state.\n- Ignoring structured pieces and wondering why cards or previews do not update.\n- Rendering interrupt UI without preserving the original piece's `resumeToken` and `requestId`.\n- Building a custom transport but not forwarding `AbortSignal`."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:124:keywords","version":"v0","href":"/docs/sdk/guides/render-streamed-chat#what-to-read-next","title":"What to Read Next","description":"Rendering Streamed Chat","section":"Rendering Streamed Chat","content":"- [React Client](../05-reference/06-react-client.md)\n- [SSE for API Routes](./11-sse.md)\n- [Interrupts and Resume](./02-interrupts-and-resume.md)\n- [Hooks](../02-core-concepts/07-hooks.md)"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","session-checkpoints","rollback","fork","regenerate","usechat"],"version":"v0","href":"/docs/sdk/guides/session-checkpoints","title":"Session Checkpoints, Rollback, and Fork","description":"Let users regenerate, edit-and-retry, undo, or branch a workflow session without losing server-side workflow state.","section":"Guides","content":"$46"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:131:keywords","version":"v0","href":"/docs/sdk/guides/session-checkpoints#prerequisites","title":"Prerequisites","description":"Session Checkpoints, Rollback, and Fork","section":"Session Checkpoints, Rollback, and Fork","content":"- `kortyx` serving chat requests\n- `@kortyx/react` if you use `useChat(...)`\n- a `FrameworkAdapter`\n\nIn-memory persistence works for local development. Use Redis for production rollback/fork, cross-worker resume, or restart-safe sessions.\n\n> **Good to know:** Checkpoints restore Kortyx runtime state. Your product records, documents, users, and long-term conversation history still belong in your app database.\n\n> **Good to know:** In-memory checkpoints are capped by checkpoint count per session, but they stay in the Node process until the process exits. For production traffic, use Redis so checkpoint state has TTLs, survives restarts, and is shared across workers."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:131:keywords","version":"v0","href":"/docs/sdk/guides/session-checkpoints#configure-the-server","title":"Configure the Server","description":"Session Checkpoints, Rollback, and Fork","section":"Session Checkpoints, Rollback, and Fork","content":"$47"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:131:keywords","version":"v0","href":"/docs/sdk/guides/session-checkpoints#configure-the-react-client","title":"Configure the React Client","description":"Session Checkpoints, Rollback, and Fork","section":"Session Checkpoints, Rollback, and Fork","content":"$48"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:131:keywords","version":"v0","href":"/docs/sdk/guides/session-checkpoints#interrupt-responses-are-not-plain-prompts","title":"Interrupt Responses Are Not Plain Prompts","description":"Session Checkpoints, Rollback, and Fork","section":"Session Checkpoints, Rollback, and Fork","content":"This is the main reason checkpoint-aware regenerate exists.\n\nIf the user selects a project or template from an interrupt UI, the visible message may look like a UUID:\n\n```txt\nuser: Help me prepare a report\nassistant: pick-project interrupt\nuser: project-uuid\nassistant: pick-template interrupt\nuser: template-uuid\nassistant: final summary\n```\n\nWhen the final summary is regenerated, Kortyx rolls back to the checkpoint where the workflow was waiting for the template selection. Then `useChat(...)` replays `template-uuid` as an interrupt response, not as a new natural-language prompt.\n\n> **Good to know:** Normal chat messages and interrupt responses use the same visible `messages` list, but `useChat(...)` stores hidden source metadata for interrupt responses so rollback can replay the right protocol."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:131:keywords","version":"v0","href":"/docs/sdk/guides/session-checkpoints#high-level-helpers","title":"High-Level Helpers","description":"Session Checkpoints, Rollback, and Fork","section":"Session Checkpoints, Rollback, and Fork","content":"`useChat(...)` exposes these checkpoint helpers:\n\n```ts\nawait chat.rollbackTo(checkpointId);\nawait chat.fork(checkpointId);\nawait chat.regenerate(assistantMessageId);\nawait chat.retryWithEdit(assistantMessageId, \"Use a shorter format.\");\n```\n```js\nawait chat.rollbackTo(checkpointId);\nawait chat.fork(checkpointId);\nawait chat.regenerate(assistantMessageId);\nawait chat.retryWithEdit(assistantMessageId, \"Use a shorter format.\");\n```\n\n`rollbackTo(...)` requires no active stream. If a stream is running, abort it first."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:131:keywords","version":"v0","href":"/docs/sdk/guides/session-checkpoints#structured-data-invalidation","title":"Structured Data Invalidation","description":"Session Checkpoints, Rollback, and Fork","section":"Session Checkpoints, Rollback, and Fork","content":"Rollback can invalidate structured data that lives outside chat bubbles, such as a report canvas, preview pane, generated table, or extracted fields.\n\nWhen a rollback discards checkpoints that produced structured streams, the server returns those stream ids. The stream protocol also includes:\n\n```json\n{\n \"type\": \"structured-data-invalidated\",\n \"streamId\": \"report-1\",\n \"checkpointId\": \"cp_123\"\n}\n```\n\nFrontend stores can decide how to react:\n\n- chat-only UIs can ignore it\n- artifact canvases can delete the old artifact\n- editors can mark content stale\n- Studio-style timelines can show the invalidated output"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:131:keywords","version":"v0","href":"/docs/sdk/guides/session-checkpoints#agent-api","title":"Agent API","description":"Session Checkpoints, Rollback, and Fork","section":"Session Checkpoints, Rollback, and Fork","content":"The low-level `Agent` methods are available when you need custom transports:\n\n```ts\nconst checkpoints = await agent.listCheckpoints(sessionId);\nconst checkpoint = await agent.getCheckpoint(checkpointId);\nconst rollback = await agent.rollbackTo(checkpointId);\nconst fork = await agent.fork(checkpointId, {\n newSessionId: \"optional-child-session-id\",\n});\n```\n```js\nconst checkpoints = await agent.listCheckpoints(sessionId);\nconst checkpoint = await agent.getCheckpoint(checkpointId);\nconst rollback = await agent.rollbackTo(checkpointId);\nconst fork = await agent.fork(checkpointId, {\n newSessionId: \"optional-child-session-id\",\n});\n```\n\n`fork(...)` creates a new session whose runtime state starts from the checkpoint. Parent and child sessions are isolated after the fork."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:131:keywords","version":"v0","href":"/docs/sdk/guides/session-checkpoints#checkpoints-while-a-child-workflow-is-waiting","title":"Checkpoints while a child workflow is waiting","description":"Session Checkpoints, Rollback, and Fork","section":"Session Checkpoints, Rollback, and Fork","content":"A `useWorkflow(...)` call saves its interrupted child graph inside the parent's checkpoint, including nested children. Forking a snapshot-backed pause creates independent run IDs and resume tokens. Each branch can answer the child differently and continue its own parent. Rollback restores the selected graph and replaces later pending writes.\n\nCompleted children before the selected pause are reused from saved results. External effects after the fork or rollback point still need application idempotency and are not undone by restoring a checkpoint. Legacy records without graph snapshots keep their previous compatibility path.\n\nSee [Call Child Workflows](./06-child-workflows.md) for call identity, version changes, context retention, and restart behavior."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:131:keywords","version":"v0","href":"/docs/sdk/guides/session-checkpoints#storage-behavior","title":"Storage Behavior","description":"Session Checkpoints, Rollback, and Fork","section":"Session Checkpoints, Rollback, and Fork","content":"$49"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:131:keywords","version":"v0","href":"/docs/sdk/guides/session-checkpoints#what-to-read-next","title":"What to Read Next","description":"Session Checkpoints, Rollback, and Fork","section":"Session Checkpoints, Rollback, and Fork","content":"- [Interrupts and Resume](./02-interrupts-and-resume.md)\n- [Rendering Streamed Chat](./04-render-streamed-chat.md)\n- [Runtime Persistence](../04-production/01-persistence.md)\n- [Stream Protocol](../05-reference/03-stream-protocol.md)"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","useWorkflow","createWorkflowHooks","child-workflows","typescript","interrupts","replay","fork"],"version":"v0","href":"/docs/sdk/guides/child-workflows","title":"Call Child Workflows","description":"Await a registered workflow inside a node or custom hook, return typed data, and preserve execution through interrupts, replay, and forks.","section":"Guides","content":"$4a"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:142:keywords","version":"v0","href":"/docs/sdk/guides/child-workflows#define-the-childs-input-and-result","title":"Define the child's input and result","description":"Call Child Workflows","section":"Call Child Workflows","content":"$4b"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:142:keywords","version":"v0","href":"/docs/sdk/guides/child-workflows#type-safety","title":"Type safety","description":"Call Child Workflows","section":"Call Child Workflows","content":"$4c"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:142:keywords","version":"v0","href":"/docs/sdk/guides/child-workflows#human-interrupts-and-resume","title":"Human interrupts and resume","description":"Call Child Workflows","section":"Call Child Workflows","content":"$4d"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:142:keywords","version":"v0","href":"/docs/sdk/guides/child-workflows#run-independent-children-in-parallel","title":"Run independent children in parallel","description":"Call Child Workflows","section":"Call Child Workflows","content":"$4e"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:142:keywords","version":"v0","href":"/docs/sdk/guides/child-workflows#child-calls-in-parallel-graph-branches","title":"Child calls in parallel graph branches","description":"Call Child Workflows","section":"Call Child Workflows","content":"$4f"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:142:keywords","version":"v0","href":"/docs/sdk/guides/child-workflows#fork-rollback-and-persistence","title":"Fork, rollback, and persistence","description":"Call Child Workflows","section":"Call Child Workflows","content":"$50"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:142:keywords","version":"v0","href":"/docs/sdk/guides/child-workflows#limits-and-migration","title":"Limits and migration","description":"Call Child Workflows","section":"Call Child Workflows","content":"$51"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:142:keywords","version":"v0","href":"/docs/sdk/guides/child-workflows#inspect-calls-in-studio","title":"Inspect calls in Studio","description":"Call Child Workflows","section":"Call Child Workflows","content":"See the [Studio overview](../../../studio/v0/01-overview.md#child-workflow-visibility) for the child execution tree, child rows, and observed call links."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","execute","resume","workflows","backend","interrupts"],"version":"v0","href":"/docs/sdk/guides/workflow-execution","title":"Execute and Resume Workflows","description":"Invoke registered workflows with typed input and results, then resolve human interrupts through a separate server entry point.","section":"Guides","content":"$52"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:151:keywords","version":"v0","href":"/docs/sdk/guides/workflow-execution#one-workflow-contract","title":"One workflow contract","description":"Execute and Resume Workflows","section":"Execute and Resume Workflows","content":"$53"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:151:keywords","version":"v0","href":"/docs/sdk/guides/workflow-execution#handle-the-outcome","title":"Handle the outcome","description":"Execute and Resume Workflows","section":"Execute and Resume Workflows","content":"Every result includes `runId` and `sessionId`, plus `checkpointId` and reported `usage` when available.\n\n| Status | Additional fields | Meaning |\n| --- | --- | --- |\n| `completed` | `data` | Validated final workflow output |\n| `suspended` | `interrupt`, `resume` | Waiting for a human response |\n| `cancelled` | `reason` | Active execution or the waiting request was cancelled |\n| `failed` | `error.code`, `error.message` | Execution or output validation failed |\n\nInvalid commands reject with `ExecutionRequestError`: for example invalid input, a mismatched workflow reference, or an invalid/stale resume handle. They do not turn an existing waiting execution into a failed run. A business rejection, such as `{ approved: false }`, can be a successful `completed` result."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:151:keywords","version":"v0","href":"/docs/sdk/guides/workflow-execution#resume-from-another-endpoint","title":"Resume from another endpoint","description":"Execute and Resume Workflows","section":"Execute and Resume Workflows","content":"$54"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:151:keywords","version":"v0","href":"/docs/sdk/guides/workflow-execution#separate-http-routes","title":"Separate HTTP routes","description":"Execute and Resume Workflows","section":"Execute and Resume Workflows","content":"$55"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:151:keywords","version":"v0","href":"/docs/sdk/guides/workflow-execution#tracing-replay-and-limits","title":"Tracing, replay, and limits","description":"Execute and Resume Workflows","section":"Execute and Resume Workflows","content":"Execution continues without a UI stream reader. Model calls may still use provider streaming internally. Reported token usage is cumulative for the logical execution, including child usage available at suspension. Reusing cached work does not charge it again; replayed model calls that actually run again do count. Unknown usage stays absent. Traces remain server-side, with the same run/child identities used by Studio.\n\nA fork inherits completed work and then accumulates its own subsequent usage. Rolling back restores the checkpoint's accounting baseline. Runtime restoration cannot undo committed business side effects; use application idempotency or transactions where needed.\n\nThis API executes in-process until completion, suspension, cancellation, or failure. Whole-tree execution limits are configured in server code (see below)."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:151:keywords","version":"v0","href":"/docs/sdk/guides/workflow-execution#cancel-active-work","title":"Cancel active work","description":"Execute and Resume Workflows","section":"Execute and Resume Workflows","content":"$56"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:151:keywords","version":"v0","href":"/docs/sdk/guides/workflow-execution#bound-an-execution","title":"Bound an execution","description":"Execute and Resume Workflows","section":"Execute and Resume Workflows","content":"$57"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:151:keywords","version":"v0","href":"/docs/sdk/guides/workflow-execution#complete-a-response-before-execution-finishes","title":"Complete a response before execution finishes","description":"Execute and Resume Workflows","section":"Execute and Resume Workflows","content":"See [Background Continuation](./08-background-continuation.md) for `completeResponse()`, independent execution lifetime, and discovering human requests through `agent.listInterrupts()` without Studio. A `done` chunk ends client delivery; it does not prove successful execution."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:151:keywords","version":"v0","href":"/docs/sdk/guides/workflow-execution#continue-and-human-response-delivery","title":"Continue and human response delivery","description":"Execute and Resume Workflows","section":"Execute and Resume Workflows","content":"A submitted response belongs to one interrupt occurrence. If node admission exhausts the allowance before the response is delivered, Continue retains that response for the original question. Once delivered, it remains part of that occurrence's replay history and cannot answer a later review. Completed tool results remain available without another tool execution. This applies to root workflows and nested children; external actions still require application idempotency.\n\nBudget checkpoints carry a versioned Kortyx suspension envelope. Upgrade all workers that can resume the same runs together; older workers do not understand an undelivered answer in that envelope. Ordinary legacy checkpoints and legacy object/array child snapshots and journals remain readable. An old budget checkpoint with ambiguous pending human commands must be restarted safely. Already contaminated snapshots cannot be reliably repaired by removing application-specific fields."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","completeResponse","background","listInterrupts","resume","human approval"],"version":"v0","href":"/docs/sdk/guides/background-continuation","title":"Finish a Response, Continue the Workflow","description":"Close a chat response, continue internal work, and discover human interruptions without requiring Studio.","section":"Guides","content":"$58"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:161:keywords","version":"v0","href":"/docs/sdk/guides/background-continuation#try-it-in-the-example","title":"Try it in the example","description":"Finish a Response, Continue the Workflow","section":"Finish a Response, Continue the Workflow","content":"Start `examples/kortyx-nextjs-chat-api-route` and open `/background`. No model key\nor Studio installation is needed for this example.\n\n1. Click **Start example**. The answer appears and the connection closes.\n2. Internal analysis continues briefly. Click **Refresh pending reviews**.\n3. The application's separate review section shows a pending question.\n4. Click **Save** or **Skip**. The backend resumes the run and the chat stays closed.\n\nThe example uses a server-set, HTTP-only cookie to isolate demo sessions. A real\napplication must derive its scope from authenticated users and authorization rules.\nIf telemetry is configured, inspect the same run and interrupt in Studio. Studio\nshows **Response: Completed** independently of execution status and flags an\ninterrupt requested after response completion. Studio has no approval controls."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:161:keywords","version":"v0","href":"/docs/sdk/guides/background-continuation#put-completion-after-the-last-response-producing-node","title":"Put completion after the last response-producing node","description":"Finish a Response, Continue the Workflow","section":"Finish a Response, Continue the Workflow","content":"$59"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:161:keywords","version":"v0","href":"/docs/sdk/guides/background-continuation#parallel-branches-and-child-workflows","title":"Parallel branches and child workflows","description":"Finish a Response, Continue the Workflow","section":"Finish a Response, Continue the Workflow","content":"Completion applies to the whole response, not just the calling node. It does not\nwait for sibling branches. If both branches contribute to the answer, join them\nfirst and call `completeResponse()` in the following node. A sibling still running\nafter completion can continue internally, but its later output is not delivered.\nThis feature does not add support for parallel child calls.\n\nOnly root-workflow nodes can close the response. A workflow reached through\n`transitionTo` is a root handoff; a workflow invoked with `useWorkflow()` is a child\nand cannot close its caller's response. Await response-producing work before\ncompletion; do not leave a structured response partially emitted."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:161:keywords","version":"v0","href":"/docs/sdk/guides/background-continuation#keep-the-execution-attempt-alive","title":"Keep the execution attempt alive","description":"Finish a Response, Continue the Workflow","section":"Finish a Response, Continue the Workflow","content":"$5a"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:161:keywords","version":"v0","href":"/docs/sdk/guides/background-continuation#save-the-visible-chat-response-on-the-server","title":"Save the visible chat response on the server","description":"Finish a Response, Continue the Workflow","section":"Finish a Response, Continue the Workflow","content":"$5b"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:161:keywords","version":"v0","href":"/docs/sdk/guides/background-continuation#human-input-after-the-response-closes","title":"Human input after the response closes","description":"Finish a Response, Continue the Workflow","section":"Finish a Response, Continue the Workflow","content":"$5c"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:161:keywords","version":"v0","href":"/docs/sdk/guides/background-continuation#checkpoints-and-entry-points","title":"Checkpoints and entry points","description":"Finish a Response, Continue the Workflow","section":"Finish a Response, Continue the Workflow","content":"$5d"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:161:keywords","version":"v0","href":"/docs/sdk/guides/background-continuation#boundaries","title":"Boundaries","description":"Finish a Response, Continue the Workflow","section":"Finish a Response, Continue the Workflow","content":"Kortyx owns execution, suspension, resume, and configurable execution persistence.\nApplications own chat archives, business records, approval interfaces, authorization,\nand background scheduling. Studio observes. This feature introduces no memory\nsystem, message database, PostgreSQL requirement, or Studio dependency."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","errors","retries","validation","recovery","checkpoints"],"version":"v0","href":"/docs/sdk/guides/error-handling","title":"Handle Errors and Recovery","description":"Inspect typed failures, preserve safe domain details across checkpoints, and keep recovery policy separate from control flow.","section":"Guides","content":"$5e"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:170:keywords","version":"v0","href":"/docs/sdk/guides/error-handling#inspect-a-failure","title":"Inspect a failure","description":"Handle Errors and Recovery","section":"Handle Errors and Recovery","content":"$5f"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:170:keywords","version":"v0","href":"/docs/sdk/guides/error-handling#report-a-handled-error","title":"Report a handled error","description":"Handle Errors and Recovery","section":"Handle Errors and Recovery","content":"$60"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:170:keywords","version":"v0","href":"/docs/sdk/guides/error-handling#choose-recovery-deliberately","title":"Choose recovery deliberately","description":"Handle Errors and Recovery","section":"Handle Errors and Recovery","content":"$61"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:170:keywords","version":"v0","href":"/docs/sdk/guides/error-handling#preserve-domain-failures-across-child-calls","title":"Preserve domain failures across child calls","description":"Handle Errors and Recovery","section":"Handle Errors and Recovery","content":"$62"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:170:keywords","version":"v0","href":"/docs/sdk/guides/error-handling#transports-telemetry-and-compatibility","title":"Transports, telemetry and compatibility","description":"Handle Errors and Recovery","section":"Handle Errors and Recovery","content":"$63"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","chat","transcript","persistence","useChat","checkpoints"],"version":"v0","href":"/docs/sdk/guides/server-owned-chat-transcripts","title":"Server-Owned Chat Transcripts","description":"Persist accepted turns and finalized assistant messages from Kortyx route hooks without consuming the SSE response.","section":"Guides","content":"$64"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:176:keywords","version":"v0","href":"/docs/sdk/guides/server-owned-chat-transcripts#chat-route-contract","title":"Chat route contract","description":"Server-Owned Chat Transcripts","section":"Server-Owned Chat Transcripts","content":"$65"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:176:keywords","version":"v0","href":"/docs/sdk/guides/server-owned-chat-transcripts#keep-execution-alive-after-a-disconnect","title":"Keep execution alive after a disconnect","description":"Server-Owned Chat Transcripts","section":"Server-Owned Chat Transcripts","content":"The default route behavior cancels cooperative execution when the client\ndisconnects. For server-owned persistence that must finish after a reader closes,\nset `disconnect: \"continue\"` and supply `onExecution` to retain host lifetime:\n\n```ts\nimport { after } from \"next/server\";\n\ncreateChatRouteHandler({\n agent,\n disconnect: \"continue\",\n onExecution: (completion) => after(() => completion),\n onTurnAccepted,\n onResponseFinalized,\n});\n```\n\nThe completion promise includes the finalization callback. With continuation\nenabled, a browser abort closes delivery but does not cancel server work. If the\nproduct needs a Stop action, implement an authorized server cancellation path\nusing a custom route and `executionSignal`. See the\n[background continuation guide](./08-background-continuation.md#save-the-visible-chat-response-on-the-server)\nfor a complete authenticated route example."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:176:keywords","version":"v0","href":"/docs/sdk/guides/server-owned-chat-transcripts#fork-and-rollback","title":"Fork and rollback","description":"Server-Owned Chat Transcripts","section":"Server-Owned Chat Transcripts","content":"The checkpoint route is separate from the chat route. Configure\n`createCheckpointRouteHandler({ onForked, onRolledBack, onLifecycleError })` to\nupdate app-owned transcript branches after successful runtime mutations.\n`onForked` supplies source/new session and checkpoint IDs. `onRolledBack`\nsupplies the new head checkpoint ID and invalidated structured-stream IDs.\nKortyx cannot identify app turn IDs to invalidate; map checkpoints to turns in\nyour database. Authorize each checkpoint request before passing it to the\ngenerated handler. See [Session Checkpoints](./05-session-checkpoints.md#storage-behavior)."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:176:keywords","version":"v0","href":"/docs/sdk/guides/server-owned-chat-transcripts#delivery-and-access-boundaries","title":"Delivery and access boundaries","description":"Server-Owned Chat Transcripts","section":"Server-Owned Chat Transcripts","content":"Finalization and checkpoint hook failures leave the runtime result intact and\nreach `onLifecycleError` as `ChatLifecycleHookError`. Hooks are attempted once\nper run attempt while the process is alive. They are not a durable outbox or a\ntransaction with the app database. Reconcile stale pending rows, or use an\napp-owned durable outbox when crash recovery is required.\n\nAuthenticate the session before the generated handler; client-supplied IDs and\ncontext are not ownership proof. A finalized interrupt piece includes a resume\ntoken for reload, so protect transcript reads as carefully as checkpoint\nroutes. Use `ChatStorage.load()` to hydrate the server-owned transcript in\n`useChat`; avoid overwriting it with an older browser snapshot. When the server\nsupplies model history, keep `includeHistory: false`."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","evals","evaluation","workflow","interrupts","testing"],"version":"v0","href":"/docs/sdk/guides/conversation-evals","title":"Evaluate Agent Conversations","description":"Test real workflows with scripted conversations, human interrupts, app-owned permissions, and LLM grading.","section":"Guides","content":"$66"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:181:keywords","version":"v0","href":"/docs/sdk/guides/conversation-evals#what-an-eval-tests","title":"What an eval tests","description":"Evaluate Agent Conversations","section":"Evaluate Agent Conversations","content":"$67"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:181:keywords","version":"v0","href":"/docs/sdk/guides/conversation-evals#smallest-configuration","title":"Smallest configuration","description":"Evaluate Agent Conversations","section":"Evaluate Agent Conversations","content":"$68"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:181:keywords","version":"v0","href":"/docs/sdk/guides/conversation-evals#required-structured-outputs","title":"Required structured outputs","description":"Evaluate Agent Conversations","section":"Evaluate Agent Conversations","content":"$69"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:181:keywords","version":"v0","href":"/docs/sdk/guides/conversation-evals#execution-evidence-from-existing-tool-outputs","title":"Execution evidence from existing tool outputs","description":"Evaluate Agent Conversations","section":"Evaluate Agent Conversations","content":"$6a"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:181:keywords","version":"v0","href":"/docs/sdk/guides/conversation-evals#write-criteria-for-the-evidence-your-app-produces","title":"Write criteria for the evidence your app produces","description":"Evaluate Agent Conversations","section":"Evaluate Agent Conversations","content":"$6b"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:181:keywords","version":"v0","href":"/docs/sdk/guides/conversation-evals#compact-judge-evidence","title":"Compact judge evidence","description":"Evaluate Agent Conversations","section":"Evaluate Agent Conversations","content":"$6c"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:181:keywords","version":"v0","href":"/docs/sdk/guides/conversation-evals#choose-the-smallest-evidence-that-supports-the-criterion","title":"Choose the smallest evidence that supports the criterion","description":"Evaluate Agent Conversations","section":"Evaluate Agent Conversations","content":"$6d"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:181:keywords","version":"v0","href":"/docs/sdk/guides/conversation-evals#register-a-custom-selection","title":"Register a custom selection","description":"Evaluate Agent Conversations","section":"Evaluate Agent Conversations","content":"$6e"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:181:keywords","version":"v0","href":"/docs/sdk/guides/conversation-evals#choose-where-judging-runs","title":"Choose where judging runs","description":"Evaluate Agent Conversations","section":"Evaluate Agent Conversations","content":"$6f"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:181:keywords","version":"v0","href":"/docs/sdk/guides/conversation-evals#local-terminal-runner","title":"Local terminal runner","description":"Evaluate Agent Conversations","section":"Evaluate Agent Conversations","content":"$70"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:181:keywords","version":"v0","href":"/docs/sdk/guides/conversation-evals#app-owned-permissions-and-human-responses","title":"App-owned permissions and human responses","description":"Evaluate Agent Conversations","section":"Evaluate Agent Conversations","content":"$71"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:181:keywords","version":"v0","href":"/docs/sdk/guides/conversation-evals#observable-boundary-and-results","title":"Observable boundary and results","description":"Evaluate Agent Conversations","section":"Evaluate Agent Conversations","content":"$72"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:181:keywords","version":"v0","href":"/docs/sdk/guides/conversation-evals#lifecycle-limits-in-this-slice","title":"Lifecycle limits in this slice","description":"Evaluate Agent Conversations","section":"Evaluate Agent Conversations","content":"$73"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:181:keywords","version":"v0","href":"/docs/sdk/guides/conversation-evals#optional-typed-case-parameters","title":"Optional typed case parameters","description":"Evaluate Agent Conversations","section":"Evaluate Agent Conversations","content":"$74"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:181:keywords","version":"v0","href":"/docs/sdk/guides/conversation-evals#concurrent-execution-recovery","title":"Concurrent execution recovery","description":"Evaluate Agent Conversations","section":"Evaluate Agent Conversations","content":"$75"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","sse","api-route","toSSE","createStreamResponse","readStream"],"version":"v0","href":"/docs/sdk/guides/sse","title":"SSE for API Routes","description":"Stream Kortyx chunks over HTTP from your API route and consume them safely in browser clients.","section":"Guides","content":"$76"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:197:keywords","version":"v0","href":"/docs/sdk/guides/sse#recommended-server-pattern-tosse","title":"Recommended server pattern (toSSE)","description":"SSE for API Routes","section":"SSE for API Routes","content":"$77"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:197:keywords","version":"v0","href":"/docs/sdk/guides/sse#recommended-client-pattern-for-react","title":"Recommended client pattern for React","description":"SSE for API Routes","section":"SSE for API Routes","content":"If you are building a React client, start with `@kortyx/react`.\n\n```ts\nimport { createRouteChatTransport, useChat } from \"@kortyx/react\";\n\nexport function ChatPage() {\n const chat = useChat({\n transport: createRouteChatTransport({\n endpoint: \"/api/chat\",\n }),\n });\n\n return ;\n}\n```\n```js\nimport { createRouteChatTransport, useChat } from \"@kortyx/react\";\n\nexport function ChatPage() {\n const chat = useChat({\n transport: createRouteChatTransport({\n endpoint: \"/api/chat\",\n }),\n });\n\n return ;\n}\n```\n\nUse `chat.messages` for finalized history and `chat.streamContentPieces` for the current in-flight assistant response.\n\n> **Good to know:** `useChat(...)` already separates assistant text, structured streams, interrupts, and storage. Most React apps should start here instead of manually reducing raw chunks."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:197:keywords","version":"v0","href":"/docs/sdk/guides/sse#custom-react-ui-with-structured-streams","title":"Custom React UI with structured streams","description":"SSE for API Routes","section":"SSE for API Routes","content":"$78"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:197:keywords","version":"v0","href":"/docs/sdk/guides/sse#example-render-a-streamed-email-draft","title":"Example: render a streamed email draft","description":"SSE for API Routes","section":"SSE for API Routes","content":"If a node uses `useReason({ structured: { fields: { body: \"text-delta\", bullets: \"append\" } } })`, the client can render the draft while the model is still writing:\n\n```ts\nconst email = structured[\"some-stream-id\"];\n\nif (email?.dataType === \"email.compose\") {\n const draft = email.data as {\n subject?: string;\n body?: string;\n bullets?: string[];\n };\n\n renderSubject(draft.subject ?? \"\");\n renderBody(draft.body ?? \"\");\n renderBullets(draft.bullets ?? []);\n setLoading(email.status === \"streaming\");\n}\n```\n```js\nconst email = structured[\"some-stream-id\"];\n\nif (email?.dataType === \"email.compose\") {\n const draft = email.data;\n\n renderSubject(draft.subject ?? \"\");\n renderBody(draft.body ?? \"\");\n renderBullets(draft.bullets ?? []);\n setLoading(email.status === \"streaming\");\n}\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:197:keywords","version":"v0","href":"/docs/sdk/guides/sse#kind-semantics","title":"kind semantics","description":"SSE for API Routes","section":"SSE for API Routes","content":"Structured chunks use one of four kinds:\n\n- `set`: replace a value at a path\n- `append`: append items to an array at a path\n- `text-delta`: append text to a string at a path\n- `final`: replace the whole object and mark the stream complete\n\nYou usually do not need to implement these rules yourself. `useStructuredStreams()` and `useChat()` already apply them for you."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:197:keywords","version":"v0","href":"/docs/sdk/guides/sse#path-behavior","title":"Path behavior","description":"SSE for API Routes","section":"SSE for API Routes","content":"$79"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:197:keywords","version":"v0","href":"/docs/sdk/guides/sse#advanced-manual-reducer-path","title":"Advanced: manual reducer path","description":"SSE for API Routes","section":"SSE for API Routes","content":"$7a"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:197:keywords","version":"v0","href":"/docs/sdk/guides/sse#consumestream","title":"consumeStream(...)","description":"SSE for API Routes","section":"SSE for API Routes","content":"If you prefer the callback helper:\n\n```ts\nimport {\n applyStructuredChunk,\n consumeStream,\n streamChatFromRoute,\n} from \"kortyx/browser\";\n\nconst structured = {};\n\nconst stream = streamChatFromRoute({\n endpoint: \"/api/chat\",\n messages,\n});\n\nawait consumeStream(stream, {\n onChunk: (chunk) => {\n if (chunk.type === \"structured-data\") {\n structured[chunk.streamId] = applyStructuredChunk(\n structured[chunk.streamId],\n chunk,\n );\n }\n },\n});\n```\n```js\nimport {\n applyStructuredChunk,\n consumeStream,\n streamChatFromRoute,\n} from \"kortyx/browser\";\n\nconst structured = {};\n\nconst stream = streamChatFromRoute({\n endpoint: \"/api/chat\",\n messages,\n});\n\nawait consumeStream(stream, {\n onChunk: (chunk) => {\n if (chunk.type === \"structured-data\") {\n structured[chunk.streamId] = applyStructuredChunk(\n structured[chunk.streamId],\n chunk,\n );\n }\n },\n});\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:197:keywords","version":"v0","href":"/docs/sdk/guides/sse#infrastructure-notes","title":"Infrastructure notes","description":"SSE for API Routes","section":"SSE for API Routes","content":"- `toSSE(...)` and `createStreamResponse(...)` set `content-type: text/event-stream`\n- they also set `cache-control: no-cache`, `connection: keep-alive`, and `x-accel-buffering: no`\n- keep this route on a runtime that supports streaming responses\n- if you run behind a proxy or CDN, make sure response buffering is disabled\n\n> **Good to know:** If your client needs a single buffered result instead of live chunks, expose a non-stream mode and return `collectBufferedStream(...)` from your route."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:197:keywords","version":"v0","href":"/docs/sdk/guides/sse#low-level-helper","title":"Low-level helper","description":"SSE for API Routes","section":"SSE for API Routes","content":"Use `createStreamResponse(...)` only when you already have your own `AsyncIterable` and want to convert it to SSE directly.\n\nFor chunk types and protocol details, see [Stream Protocol](../05-reference/03-stream-protocol.md)."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","usePrompt","definePrompt","prompts","studio"],"version":"v0","href":"/docs/sdk/guides/studio-prompts","title":"Use Studio Prompts","description":"Resolve typed prompt versions, preserve chat roles, and attach execution and eval evidence.","section":"Guides","content":"$7b"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:208:keywords","version":"v0","href":"/docs/sdk/guides/studio-prompts#execution-consistency-and-failure-policy","title":"Execution consistency and failure policy","description":"Use Studio Prompts","section":"Use Studio Prompts","content":"$7c"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:208:keywords","version":"v0","href":"/docs/sdk/guides/studio-prompts#runs-and-evals","title":"Runs and evals","description":"Use Studio Prompts","section":"Use Studio Prompts","content":"Pass the same agent to `createEvals`. Its manifest advertises registered prompt\ncontracts, enabling Studio to test candidates or groups with the existing suite\ndrawer. Actual model calls emit prompt identity receipts. Requested-but-unused or\nmismatched candidates cannot satisfy verified promotion evidence. The optional\n`@kortyx/telemetry` adapter attaches the key/version/hash/environment to normal\ngeneration events; message capture follows its existing capture settings.\n\nThe runnable [`examples/kortyx-prompts`](https://github.com/kortyx-io/kortyx/tree/main/examples/kortyx-prompts)\nincludes the complete server, model registry, telemetry, and authenticated eval\nendpoint. See [Version and test prompts](../../../studio/v0/13-prompts.md) and\n[CLI migration](../../../studio/v0/14-prompt-migration.md)."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:208:keywords","version":"v0","href":"/docs/sdk/guides/studio-prompts#included-prompts","title":"Included prompts","description":"Use Studio Prompts","section":"Use Studio Prompts","content":"Studio's `#` picker includes another prompt's matching-role message and pins its\nexact saved version. Latest selects the newest saved version when inserted.\n`usePrompt` expands nested references from the same frozen snapshot before\nfilling template inputs; `useReason` reports both the parent and included versions\nas actual prompt usage. Add inherited inputs to your `definePrompt` schema and\nsupply their values as usual. The parent's configuration controls your application.\nChanging a child does not change a saved parent's executable content. Save and\nevaluate a new parent version to adopt a newer child."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","providers","ai providers","openai","anthropic","google","deepseek","groq","mistral","openrouter"],"version":"v0","href":"/docs/sdk/kortyx-providers/choose-a-provider","title":"Choose a Provider","description":"Pick a Kortyx provider package, configure credentials, and understand the current provider scope.","section":"Kortyx Providers","content":"$7d"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:212:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/choose-a-provider#provider-package-map","title":"Provider package map","description":"Choose a Provider","section":"Choose a Provider","content":"$7e"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:212:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/choose-a-provider#install-the-package-you-need","title":"Install the package you need","description":"Choose a Provider","section":"Choose a Provider","content":"Install only the provider packages your app uses.\n\n```bash tabs=\"install-provider-example\" tab=\"pnpm\"\npnpm add @kortyx/google\n```\n\n```bash tabs=\"install-provider-example\" tab=\"npm\"\nnpm install @kortyx/google\n```\n\n```bash tabs=\"install-provider-example\" tab=\"yarn\"\nyarn add @kortyx/google\n```\n\n```bash tabs=\"install-provider-example\" tab=\"bun\"\nbun add @kortyx/google\n```\n\nUse the provider-specific page if you need package-specific install commands:\n\n- [Google Generative AI](./01-google-generative-ai-provider.md)\n- [OpenAI](./02-openai-provider.md)\n- [Anthropic](./03-anthropic-provider.md)\n- [DeepSeek](./04-deepseek-provider.md)\n- [Groq](./05-groq-provider.md)\n- [Mistral](./06-mistral-provider.md)\n- [OpenRouter](./07-openrouter-provider.md)\n- [TypeSafe Jev through OpenRouter](./08-jev-openrouter.md)"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:212:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/choose-a-provider#centralize-provider-imports","title":"Centralize provider imports","description":"Choose a Provider","section":"Choose a Provider","content":"$7f"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:212:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/choose-a-provider#use-explicit-provider-setup-when-the-app-owns-config","title":"Use explicit provider setup when the app owns config","description":"Choose a Provider","section":"Choose a Provider","content":"$80"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:212:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/choose-a-provider#current-provider-scope","title":"Current provider scope","description":"Choose a Provider","section":"Choose a Provider","content":"$81"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:212:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/choose-a-provider#provider-options","title":"Provider options","description":"Choose a Provider","section":"Choose a Provider","content":"Provider-specific options are usually namespaced under the provider id:\n\n```ts\nconst result = await useReason({\n model: openai(\"gpt-4.1-mini\"),\n input: \"Return a compact JSON summary.\",\n responseFormat: {\n type: \"json\",\n },\n providerOptions: {\n openai: {\n strictJsonSchema: true,\n },\n },\n});\n```\n\n```js\nconst result = await useReason({\n model: openai(\"gpt-4.1-mini\"),\n input: \"Return a compact JSON summary.\",\n responseFormat: {\n type: \"json\",\n },\n providerOptions: {\n openai: {\n strictJsonSchema: true,\n },\n },\n});\n```\n\n```ts\nconst result = await useReason({\n model: deepseek(\"deepseek-reasoner\"),\n input: \"Solve this step by step.\",\n providerOptions: {\n deepseek: {\n thinking: {\n type: \"enabled\",\n },\n },\n },\n});\n```\n\n```js\nconst result = await useReason({\n model: deepseek(\"deepseek-reasoner\"),\n input: \"Solve this step by step.\",\n providerOptions: {\n deepseek: {\n thinking: {\n type: \"enabled\",\n },\n },\n },\n});\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:212:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/choose-a-provider#next-steps","title":"Next steps","description":"Choose a Provider","section":"Choose a Provider","content":"- Pick a provider-specific setup page from the package map above\n- See [Hooks](../02-core-concepts/07-hooks.md) for `useReason(...)` behavior and structured output\n- See [Provider API](../05-reference/04-provider-api.md) for the shared normalized provider contract"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","google","gemini","provider","google-generative-ai"],"version":"v0","href":"/docs/sdk/kortyx-providers/google-generative-ai-provider","title":"Google Generative AI Provider","description":"Use Google's Gemini models in Kortyx with the batteries-included google export or an explicit provider instance.","section":"Kortyx Providers","content":"$82"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:220:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/google-generative-ai-provider#1-install-the-package","title":"1. Install the package","description":"Google Generative AI Provider","section":"Google Generative AI Provider","content":"```bash tabs=\"install-google-provider\" tab=\"pnpm\"\npnpm add @kortyx/google\n```\n\n```bash tabs=\"install-google-provider\" tab=\"npm\"\nnpm install @kortyx/google\n```\n\n```bash tabs=\"install-google-provider\" tab=\"yarn\"\nyarn add @kortyx/google\n```\n\n```bash tabs=\"install-google-provider\" tab=\"bun\"\nbun add @kortyx/google\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:220:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/google-generative-ai-provider#2-what-the-package-exports","title":"2. What the package exports","description":"Google Generative AI Provider","section":"Google Generative AI Provider","content":"```ts\nimport {\n MODELS,\n PROVIDER_ID,\n createGoogleGenerativeAI,\n google,\n} from \"@kortyx/google\";\n```\n\n```js\nimport {\n MODELS,\n PROVIDER_ID,\n createGoogleGenerativeAI,\n google,\n} from \"@kortyx/google\";\n```\n\nWhat each export is for:\n\n- `google`: default provider selector for the fastest start\n- `createGoogleGenerativeAI(...)`: custom provider instance with explicit settings\n- `MODELS`: built-in Google model ids exposed by the package\n- `PROVIDER_ID`: the provider id string, currently `\"google\"`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:220:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/google-generative-ai-provider#3-basic-usage-in-the-same-file","title":"3. Basic usage in the same file","description":"Google Generative AI Provider","section":"Google Generative AI Provider","content":"If you want to use Google directly in the file where you call `useReason(...)`, import `google` and call it there.\n\n```ts\nimport { google } from \"@kortyx/google\";\n\nconst model = google(\"gemini-2.5-flash\");\n```\n\n```js\nimport { google } from \"@kortyx/google\";\n\nconst model = google(\"gemini-2.5-flash\");\n```\n\n`google` is a provider selector, which means:\n\n- it is callable: `google(\"gemini-2.5-flash\")`\n- it also exposes provider metadata: `google.id`, `google.models`\n\n```ts\ngoogle.id; // \"google\"\ngoogle.models; // readonly list of model ids\n```\n\n```js\ngoogle.id; // \"google\"\ngoogle.models; // readonly list of model ids\n```\n\n> **Good to know:** `google(\"gemini-2.5-flash\")` returns a model ref, not a live API client call. The actual provider-native model is resolved later when Kortyx executes `useReason(...)`."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:220:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/google-generative-ai-provider#4-shared-app-bootstrap-usage","title":"4. Shared app bootstrap usage","description":"Google Generative AI Provider","section":"Google Generative AI Provider","content":"If you want one shared import path across your app, re-export `google` from a bootstrap file such as `src/lib/providers.ts`.\n\n```ts\n// src/lib/providers.ts\nexport { google } from \"@kortyx/google\";\n```\n\n```js\n// src/lib/providers.js\nexport { google } from \"@kortyx/google\";\n```\n\nThen import it from that file where you actually use it:\n\n```ts\n// src/nodes/chat.node.ts\nimport { google } from \"@/lib/providers\";\n```\n\n```js\n// src/nodes/chat.node.js\nimport { google } from \"@/lib/providers\";\n```\n\n> **Good to know:** `export { google } from \"@kortyx/google\"` is only a re-export. It does not create a local `google` variable in the same file. If you want to call `google(\"...\")` in that same file, import it normally."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:220:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/google-generative-ai-provider#5-advanced-usage-with-explicit-settings","title":"5. Advanced usage with explicit settings","description":"Google Generative AI Provider","section":"Google Generative AI Provider","content":"Use `createGoogleGenerativeAI(...)` when you want app-owned configuration instead of the default environment-based setup.\n\n```ts\nimport { createGoogleGenerativeAI } from \"@kortyx/google\";\n\nexport const google = createGoogleGenerativeAI({\n apiKey: process.env.GOOGLE_API_KEY,\n});\n```\n\n```js\nimport { createGoogleGenerativeAI } from \"@kortyx/google\";\n\nexport const google = createGoogleGenerativeAI({\n apiKey: process.env.GOOGLE_API_KEY,\n});\n```\n\nUse the factory when you need to:\n\n- pass `apiKey` explicitly\n- use a custom `baseUrl`\n- provide a custom `fetch`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:220:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/google-generative-ai-provider#6-credentials-and-first-use-behavior","title":"6. Credentials and first-use behavior","description":"Google Generative AI Provider","section":"Google Generative AI Provider","content":"The default `google` export resolves credentials on first use, not at import time.\n\nSupported environment variables:\n\n- `GOOGLE_API_KEY`\n- `GEMINI_API_KEY`\n- `GOOGLE_GENERATIVE_AI_API_KEY`\n- `KORTYX_GOOGLE_API_KEY`\n- `KORTYX_GEMINI_API_KEY`\n\nIf none of them are set and you did not pass `apiKey` to `createGoogleGenerativeAI(...)`, the provider throws a configuration error the first time a Google model is actually used."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:220:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/google-generative-ai-provider#7-create-model-refs-for-workflow-and-node-params","title":"7. Create model refs for workflow and node params","description":"Google Generative AI Provider","section":"Google Generative AI Provider","content":"You can pass model refs through workflow or node params just like any other value.\n\n```ts\nparams: {\n model: google(\"gemini-2.5-flash\"),\n temperature: 0.3,\n}\n```\n\n```js\nparams: {\n model: google(\"gemini-2.5-flash\"),\n temperature: 0.3,\n}\n```\n\nYou can also attach default model options to the ref itself:\n\n```ts\nconst model = google(\"gemini-2.5-flash\", {\n temperature: 0.2,\n maxOutputTokens: 800,\n});\n```\n\n```js\nconst model = google(\"gemini-2.5-flash\", {\n temperature: 0.2,\n maxOutputTokens: 800,\n});\n```\n\nThose become default options for later `useReason(...)` calls unless you override them at call time."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:220:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/google-generative-ai-provider#8-use-the-model-with-usereason","title":"8. Use the model with useReason(...)","description":"Google Generative AI Provider","section":"Google Generative AI Provider","content":"```ts\nimport { useReason } from \"kortyx\";\nimport { google } from \"@/lib/providers\";\n\nconst result = await useReason({\n model: google(\"gemini-2.5-flash\"),\n input: \"Write a concise launch update for our beta users.\",\n temperature: 0.3,\n emit: true,\n stream: true,\n});\n\nresult.text;\nresult.usage;\nresult.finishReason;\nresult.providerMetadata;\nresult.warnings;\n```\n\n```js\nimport { useReason } from \"kortyx\";\nimport { google } from \"@/lib/providers\";\n\nconst result = await useReason({\n model: google(\"gemini-2.5-flash\"),\n input: \"Write a concise launch update for our beta users.\",\n temperature: 0.3,\n emit: true,\n stream: true,\n});\n\nresult.text;\nresult.usage;\nresult.finishReason;\nresult.providerMetadata;\nresult.warnings;\n```\n\n> **Good to know:** Provider setup is not done on `createAgent(...)`. Model selection happens where you call `useReason(...)` by passing a model ref."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:220:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/google-generative-ai-provider#9-supported-normalized-call-options","title":"9. Supported normalized call options","description":"Google Generative AI Provider","section":"Google Generative AI Provider","content":"Google currently maps these generic Kortyx options:\n\n- `temperature`\n- `streaming`\n- `maxOutputTokens`\n- `stopSequences`\n- `abortSignal`\n- `reasoning.effort`\n- `reasoning.maxTokens`\n- `reasoning.includeThoughts`\n- `responseFormat.type`\n\nCurrent Google mapping details:\n\n- `responseFormat.type: \"json\"` sets the Google response MIME type to JSON\n- `responseFormat.type: \"text\"` sets the Google response MIME type to plain text\n- `reasoning.*` maps to Google thinking configuration\n\nCurrent warning-backed gaps:\n\n- `responseFormat.schema` maps to native `responseJsonSchema`\n- `providerOptions.google.thinkingConfig` supports native thinking controls; unknown options produce warnings\n- unsupported or rejected `reasoning.effort` values fail explicitly; no request is retried without effort\n\nThat means you should check `result.warnings` if you are relying on advanced generic options and want to confirm how the provider handled them."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:220:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/google-generative-ai-provider#10-normalized-metadata-you-get-back","title":"10. Normalized metadata you get back","description":"Google Generative AI Provider","section":"Google Generative AI Provider","content":"Google returns the normalized Kortyx result fields when the API provides them:\n\n- `usage`\n- `finishReason`\n- `providerMetadata`\n- `warnings`\n- `raw`\n\nGoogle-specific metadata currently includes fields such as:\n\n- `providerId`\n- `modelId`\n- `responseId`\n- `modelVersion`\n- `promptFeedback`\n- `usageMetadata`\n\nUse `providerMetadata` when you need debugging or observability details without coupling your app code to the raw provider payload shape."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:220:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/google-generative-ai-provider#supported-scope","title":"Supported scope","description":"Google Generative AI Provider","section":"Google Generative AI Provider","content":"`@kortyx/google` currently supports text generation through `useReason(...)`, including streaming and non-streaming invocation.\n\nIt does not currently expose provider-native embeddings, image generation, file APIs, Google-hosted tools, or multimodal output APIs. Check `result.warnings` when you rely on advanced generic options and want to verify how Google handled them."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:220:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/google-generative-ai-provider#available-built-in-google-model-ids","title":"Available built-in Google model ids","description":"Google Generative AI Provider","section":"Google Generative AI Provider","content":"- `gemini-2.5-flash`\n- `gemini-2.0-flash`\n- `gemini-1.5-pro`\n- `gemini-1.5-flash`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:220:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/google-generative-ai-provider#next-steps","title":"Next steps","description":"Google Generative AI Provider","section":"Google Generative AI Provider","content":"- See [Hooks](../02-core-concepts/07-hooks.md) for `useReason(...)` behavior and structured output\n- See [Provider API](../05-reference/04-provider-api.md) for the shared normalized provider contract"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:220:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/google-generative-ai-provider#reasoning-tools-and-structured-output","title":"Reasoning, tools, and structured output","description":"Google Generative AI Provider","section":"Google Generative AI Provider","content":"$83"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","openai","provider","gpt","o-series"],"version":"v0","href":"/docs/sdk/kortyx-providers/openai-provider","title":"OpenAI Provider","description":"Use OpenAI models in Kortyx with the batteries-included openai export or an explicit provider instance.","section":"Kortyx Providers","content":"$84"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:235:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openai-provider#1-install-the-package","title":"1. Install the package","description":"OpenAI Provider","section":"OpenAI Provider","content":"```bash tabs=\"install-openai-provider\" tab=\"pnpm\"\npnpm add @kortyx/openai\n```\n\n```bash tabs=\"install-openai-provider\" tab=\"npm\"\nnpm install @kortyx/openai\n```\n\n```bash tabs=\"install-openai-provider\" tab=\"yarn\"\nyarn add @kortyx/openai\n```\n\n```bash tabs=\"install-openai-provider\" tab=\"bun\"\nbun add @kortyx/openai\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:235:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openai-provider#2-what-the-package-exports","title":"2. What the package exports","description":"OpenAI Provider","section":"OpenAI Provider","content":"```ts\nimport { MODELS, PROVIDER_ID, createOpenAI, openai } from \"@kortyx/openai\";\n```\n\n```js\nimport { MODELS, PROVIDER_ID, createOpenAI, openai } from \"@kortyx/openai\";\n```\n\nWhat each export is for:\n\n- `openai`: default provider selector for the fastest start\n- `createOpenAI(...)`: custom provider instance with explicit settings\n- `MODELS`: built-in OpenAI model ids exposed by the package\n- `PROVIDER_ID`: the provider id string, currently `\"openai\"`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:235:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openai-provider#3-basic-usage-in-the-same-file","title":"3. Basic usage in the same file","description":"OpenAI Provider","section":"OpenAI Provider","content":"```ts\nimport { openai } from \"@kortyx/openai\";\n\nconst model = openai(\"gpt-4.1-mini\");\n```\n\n```js\nimport { openai } from \"@kortyx/openai\";\n\nconst model = openai(\"gpt-4.1-mini\");\n```\n\n`openai` is a provider selector, which means:\n\n- it is callable: `openai(\"gpt-4.1-mini\")`\n- it also exposes provider metadata: `openai.id`, `openai.models`\n\n```ts\nopenai.id; // \"openai\"\nopenai.models; // readonly list of built-in model ids\n```\n\n```js\nopenai.id; // \"openai\"\nopenai.models; // readonly list of built-in model ids\n```\n\n> **Good to know:** The built-in model list gives autocomplete, but arbitrary OpenAI model ids are accepted as strings."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:235:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openai-provider#4-shared-app-bootstrap-usage","title":"4. Shared app bootstrap usage","description":"OpenAI Provider","section":"OpenAI Provider","content":"If you want one shared import path across your app, re-export `openai` from a bootstrap file such as `src/lib/providers.ts`.\n\n```ts\n// src/lib/providers.ts\nexport { openai } from \"@kortyx/openai\";\n```\n\n```js\n// src/lib/providers.js\nexport { openai } from \"@kortyx/openai\";\n```\n\nThen import it from that file where you actually use it:\n\n```ts\n// src/nodes/chat.node.ts\nimport { openai } from \"@/lib/providers\";\n```\n\n```js\n// src/nodes/chat.node.js\nimport { openai } from \"@/lib/providers\";\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:235:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openai-provider#5-advanced-usage-with-explicit-settings","title":"5. Advanced usage with explicit settings","description":"OpenAI Provider","section":"OpenAI Provider","content":"Use `createOpenAI(...)` when you want app-owned configuration instead of the default environment-based setup.\n\n```ts\nimport { createOpenAI } from \"@kortyx/openai\";\n\nexport const openai = createOpenAI({\n apiKey: process.env.OPENAI_API_KEY,\n});\n```\n\n```js\nimport { createOpenAI } from \"@kortyx/openai\";\n\nexport const openai = createOpenAI({\n apiKey: process.env.OPENAI_API_KEY,\n});\n```\n\nUse the factory when you need to:\n\n- pass `apiKey` explicitly\n- use a custom `baseUrl`\n- provide a custom `fetch`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:235:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openai-provider#6-credentials-and-first-use-behavior","title":"6. Credentials and first-use behavior","description":"OpenAI Provider","section":"OpenAI Provider","content":"The default `openai` export resolves credentials on first use, not at import time.\n\nSupported environment variables:\n\n- `OPENAI_API_KEY`\n- `KORTYX_OPENAI_API_KEY`\n\nIf neither variable is set and you did not pass `apiKey` to `createOpenAI(...)`, the provider throws a configuration error the first time an OpenAI model is actually used."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:235:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openai-provider#7-create-model-refs-for-workflow-and-node-params","title":"7. Create model refs for workflow and node params","description":"OpenAI Provider","section":"OpenAI Provider","content":"```ts\nparams: {\n model: openai(\"gpt-4.1-mini\"),\n temperature: 0.3,\n}\n```\n\n```js\nparams: {\n model: openai(\"gpt-4.1-mini\"),\n temperature: 0.3,\n}\n```\n\nYou can also attach default model options to the ref itself:\n\n```ts\nconst model = openai(\"gpt-4.1-mini\", {\n temperature: 0.2,\n maxOutputTokens: 800,\n});\n```\n\n```js\nconst model = openai(\"gpt-4.1-mini\", {\n temperature: 0.2,\n maxOutputTokens: 800,\n});\n```\n\nThose become default options for later `useReason(...)` calls unless you override them at call time."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:235:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openai-provider#8-use-the-model-with-usereason","title":"8. Use the model with useReason(...)","description":"OpenAI Provider","section":"OpenAI Provider","content":"```ts\nimport { useReason } from \"kortyx\";\nimport { openai } from \"@/lib/providers\";\n\nconst result = await useReason({\n model: openai(\"gpt-4.1-mini\"),\n input: \"Write a concise launch update for our beta users.\",\n temperature: 0.3,\n emit: true,\n stream: true,\n});\n\nresult.text;\nresult.usage;\nresult.finishReason;\nresult.providerMetadata;\nresult.warnings;\n```\n\n```js\nimport { useReason } from \"kortyx\";\nimport { openai } from \"@/lib/providers\";\n\nconst result = await useReason({\n model: openai(\"gpt-4.1-mini\"),\n input: \"Write a concise launch update for our beta users.\",\n temperature: 0.3,\n emit: true,\n stream: true,\n});\n\nresult.text;\nresult.usage;\nresult.finishReason;\nresult.providerMetadata;\nresult.warnings;\n```\n\n> **Good to know:** Provider setup is not done on `createAgent(...)`. Model selection happens where you call `useReason(...)` by passing a model ref."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:235:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openai-provider#9-supported-normalized-call-options","title":"9. Supported normalized call options","description":"OpenAI Provider","section":"OpenAI Provider","content":"$85"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:235:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openai-provider#10-transport-selection-and-migration","title":"10. Transport selection and migration","description":"OpenAI Provider","section":"OpenAI Provider","content":"$86"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:235:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openai-provider#11-usage-errors-and-studio","title":"11. Usage, errors, and Studio","description":"OpenAI Provider","section":"OpenAI Provider","content":"`providerMetadata.api` identifies the selected transport. Responses also reports response ID, status, reasoning settings and service tier. Studio displays these alongside finish reason and input, output, reasoning and cached-token counts. Older event payloads remain readable.\n\nOpenAI's output-token count already includes reasoning tokens; cached input is a subset of input. Kortyx records these relationships so total tokens and cost do not count them twice. Usage reported by an incomplete/failed response remains charged to the failed execution. Refusals, malformed responses, provider failures, and streams missing a terminal response never become successful results. No usage is invented when the provider supplies none.\n\nThe built-in Luna price card covers standard-tier requests up to 272,000 input tokens. Configure a project rate for other tiers/context sizes; they remain unpriced without one."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:235:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openai-provider#supported-scope","title":"Supported scope","description":"OpenAI Provider","section":"OpenAI Provider","content":"Text generation, executable function tools, structured output, streaming and non-streaming execution are supported through Responses and Chat Completions. OpenAI-hosted tools, embeddings, image generation, audio, transcription and file APIs are not exposed by this transport addition."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:235:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openai-provider#available-built-in-openai-model-ids","title":"Available built-in OpenAI model ids","description":"OpenAI Provider","section":"OpenAI Provider","content":"- `gpt-5.6-luna`\n- `gpt-5.4`\n- `gpt-5.4-mini`\n- `gpt-5.4-nano`\n- `gpt-5.4-pro`\n- `gpt-4.1`\n- `gpt-4.1-mini`\n- `gpt-4o`\n- `gpt-4o-mini`\n- `o4-mini`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:235:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openai-provider#next-steps","title":"Next steps","description":"OpenAI Provider","section":"OpenAI Provider","content":"- See [Hooks](../02-core-concepts/07-hooks.md) for `useReason(...)` behavior and structured output\n- See [Provider API](../05-reference/04-provider-api.md) for the shared normalized provider contract"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","anthropic","claude","provider"],"version":"v0","href":"/docs/sdk/kortyx-providers/anthropic-provider","title":"Anthropic Provider","description":"Use Anthropic Claude models in Kortyx with the batteries-included anthropic export or an explicit provider instance.","section":"Kortyx Providers","content":"$87"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:250:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/anthropic-provider#1-install-the-package","title":"1. Install the package","description":"Anthropic Provider","section":"Anthropic Provider","content":"```bash tabs=\"install-anthropic-provider\" tab=\"pnpm\"\npnpm add @kortyx/anthropic\n```\n\n```bash tabs=\"install-anthropic-provider\" tab=\"npm\"\nnpm install @kortyx/anthropic\n```\n\n```bash tabs=\"install-anthropic-provider\" tab=\"yarn\"\nyarn add @kortyx/anthropic\n```\n\n```bash tabs=\"install-anthropic-provider\" tab=\"bun\"\nbun add @kortyx/anthropic\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:250:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/anthropic-provider#2-what-the-package-exports","title":"2. What the package exports","description":"Anthropic Provider","section":"Anthropic Provider","content":"```ts\nimport {\n MODELS,\n PROVIDER_ID,\n anthropic,\n createAnthropic,\n} from \"@kortyx/anthropic\";\n```\n\n```js\nimport {\n MODELS,\n PROVIDER_ID,\n anthropic,\n createAnthropic,\n} from \"@kortyx/anthropic\";\n```\n\nWhat each export is for:\n\n- `anthropic`: default provider selector for the fastest start\n- `createAnthropic(...)`: custom provider instance with explicit settings\n- `MODELS`: built-in Anthropic model ids exposed by the package\n- `PROVIDER_ID`: the provider id string, currently `\"anthropic\"`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:250:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/anthropic-provider#3-basic-usage-in-the-same-file","title":"3. Basic usage in the same file","description":"Anthropic Provider","section":"Anthropic Provider","content":"```ts\nimport { anthropic } from \"@kortyx/anthropic\";\n\nconst model = anthropic(\"claude-sonnet-4-5\");\n```\n\n```js\nimport { anthropic } from \"@kortyx/anthropic\";\n\nconst model = anthropic(\"claude-sonnet-4-5\");\n```\n\n`anthropic` is a provider selector, which means:\n\n- it is callable: `anthropic(\"claude-sonnet-4-5\")`\n- it also exposes provider metadata: `anthropic.id`, `anthropic.models`\n\n```ts\nanthropic.id; // \"anthropic\"\nanthropic.models; // readonly list of built-in model ids\n```\n\n```js\nanthropic.id; // \"anthropic\"\nanthropic.models; // readonly list of built-in model ids\n```\n\n> **Good to know:** The built-in model list gives autocomplete, but arbitrary Anthropic model ids are accepted as strings."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:250:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/anthropic-provider#4-shared-app-bootstrap-usage","title":"4. Shared app bootstrap usage","description":"Anthropic Provider","section":"Anthropic Provider","content":"If you want one shared import path across your app, re-export `anthropic` from a bootstrap file such as `src/lib/providers.ts`.\n\n```ts\n// src/lib/providers.ts\nexport { anthropic } from \"@kortyx/anthropic\";\n```\n\n```js\n// src/lib/providers.js\nexport { anthropic } from \"@kortyx/anthropic\";\n```\n\nThen import it from that file where you actually use it:\n\n```ts\n// src/nodes/chat.node.ts\nimport { anthropic } from \"@/lib/providers\";\n```\n\n```js\n// src/nodes/chat.node.js\nimport { anthropic } from \"@/lib/providers\";\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:250:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/anthropic-provider#5-advanced-usage-with-explicit-settings","title":"5. Advanced usage with explicit settings","description":"Anthropic Provider","section":"Anthropic Provider","content":"Use `createAnthropic(...)` when you want app-owned configuration instead of the default environment-based setup.\n\n```ts\nimport { createAnthropic } from \"@kortyx/anthropic\";\n\nexport const anthropic = createAnthropic({\n apiKey: process.env.ANTHROPIC_API_KEY,\n});\n```\n\n```js\nimport { createAnthropic } from \"@kortyx/anthropic\";\n\nexport const anthropic = createAnthropic({\n apiKey: process.env.ANTHROPIC_API_KEY,\n});\n```\n\nUse the factory when you need to:\n\n- pass `apiKey` explicitly\n- pass `authToken` explicitly\n- use a custom `baseUrl`\n- provide a custom `fetch`\n\n> **Good to know:** `createAnthropic(...)` accepts either `apiKey` or `authToken`, not both."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:250:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/anthropic-provider#6-credentials-and-first-use-behavior","title":"6. Credentials and first-use behavior","description":"Anthropic Provider","section":"Anthropic Provider","content":"The default `anthropic` export resolves credentials on first use, not at import time.\n\nSupported API key environment variables:\n\n- `ANTHROPIC_API_KEY`\n- `KORTYX_ANTHROPIC_API_KEY`\n\nSupported auth token environment variables:\n\n- `ANTHROPIC_AUTH_TOKEN`\n- `KORTYX_ANTHROPIC_AUTH_TOKEN`\n\nIf no supported credential is set and you did not pass credentials to `createAnthropic(...)`, the provider throws a configuration error the first time an Anthropic model is actually used."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:250:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/anthropic-provider#7-create-model-refs-for-workflow-and-node-params","title":"7. Create model refs for workflow and node params","description":"Anthropic Provider","section":"Anthropic Provider","content":"```ts\nparams: {\n model: anthropic(\"claude-sonnet-4-5\"),\n temperature: 0.3,\n}\n```\n\n```js\nparams: {\n model: anthropic(\"claude-sonnet-4-5\"),\n temperature: 0.3,\n}\n```\n\nYou can also attach default model options to the ref itself:\n\n```ts\nconst model = anthropic(\"claude-sonnet-4-5\", {\n maxOutputTokens: 800,\n providerOptions: {\n anthropic: {\n topP: 0.9,\n },\n },\n});\n```\n\n```js\nconst model = anthropic(\"claude-sonnet-4-5\", {\n maxOutputTokens: 800,\n providerOptions: {\n anthropic: {\n topP: 0.9,\n },\n },\n});\n```\n\nThose become default options for later `useReason(...)` calls unless you override them at call time."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:250:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/anthropic-provider#8-use-the-model-with-usereason","title":"8. Use the model with useReason(...)","description":"Anthropic Provider","section":"Anthropic Provider","content":"```ts\nimport { useReason } from \"kortyx\";\nimport { anthropic } from \"@/lib/providers\";\n\nconst result = await useReason({\n model: anthropic(\"claude-sonnet-4-5\"),\n input: \"Write a concise project update for our beta users.\",\n maxOutputTokens: 800,\n emit: true,\n stream: true,\n});\n\nresult.text;\nresult.usage;\nresult.finishReason;\nresult.providerMetadata;\nresult.warnings;\n```\n\n```js\nimport { useReason } from \"kortyx\";\nimport { anthropic } from \"@/lib/providers\";\n\nconst result = await useReason({\n model: anthropic(\"claude-sonnet-4-5\"),\n input: \"Write a concise project update for our beta users.\",\n maxOutputTokens: 800,\n emit: true,\n stream: true,\n});\n\nresult.text;\nresult.usage;\nresult.finishReason;\nresult.providerMetadata;\nresult.warnings;\n```\n\n> **Good to know:** Provider setup is not done on `createAgent(...)`. Model selection happens where you call `useReason(...)` by passing a model ref."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:250:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/anthropic-provider#9-supported-normalized-call-options","title":"9. Supported normalized call options","description":"Anthropic Provider","section":"Anthropic Provider","content":"$88"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:250:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/anthropic-provider#10-normalized-metadata-you-get-back","title":"10. Normalized metadata you get back","description":"Anthropic Provider","section":"Anthropic Provider","content":"Anthropic returns the normalized Kortyx result fields when the API provides them:\n\n- `usage`\n- `finishReason`\n- `providerMetadata`\n- `warnings`\n- `raw`\n\nAnthropic-specific metadata currently includes fields such as:\n\n- `providerId`\n- `modelId`\n- `responseId`\n- `responseModel`\n- `stopSequence`\n- `usage`\n- `cacheReadTokens`\n- `cacheWriteTokens`\n- `serverToolUse`\n\nUse `providerMetadata` when you need debugging or observability details without coupling your app code to the raw provider payload shape."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:250:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/anthropic-provider#supported-scope","title":"Supported scope","description":"Anthropic Provider","section":"Anthropic Provider","content":"`@kortyx/anthropic` currently supports text generation through the Anthropic Messages API via `useReason(...)`, including streaming and non-streaming invocation.\n\nIt does not currently expose provider-native file APIs, skills, tool execution, or multimodal output APIs. Check `result.warnings` when you rely on advanced generic options and want to verify how Anthropic handled them."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:250:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/anthropic-provider#available-built-in-anthropic-model-ids","title":"Available built-in Anthropic model ids","description":"Anthropic Provider","section":"Anthropic Provider","content":"- `claude-sonnet-4-5`\n- `claude-sonnet-4-5-20250929`\n- `claude-haiku-4-5`\n- `claude-haiku-4-5-20251001`\n- `claude-opus-4-5`\n- `claude-opus-4-5-20251101`\n- `claude-sonnet-4-0`\n- `claude-sonnet-4-20250514`\n- `claude-opus-4-1`\n- `claude-opus-4-1-20250805`\n- `claude-3-haiku-20240307`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:250:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/anthropic-provider#next-steps","title":"Next steps","description":"Anthropic Provider","section":"Anthropic Provider","content":"- See [Hooks](../02-core-concepts/07-hooks.md) for `useReason(...)` behavior and structured output\n- See [Provider API](../05-reference/04-provider-api.md) for the shared normalized provider contract"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:250:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/anthropic-provider#reasoning-tools-and-structured-output","title":"Reasoning, tools, and structured output","description":"Anthropic Provider","section":"Anthropic Provider","content":"$89"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","deepseek","provider","reasoning"],"version":"v0","href":"/docs/sdk/kortyx-providers/deepseek-provider","title":"DeepSeek Provider","description":"Use DeepSeek models in Kortyx with the batteries-included deepseek export or an explicit provider instance.","section":"Kortyx Providers","content":"$8a"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:265:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/deepseek-provider#1-install-the-package","title":"1. Install the package","description":"DeepSeek Provider","section":"DeepSeek Provider","content":"```bash tabs=\"install-deepseek-provider\" tab=\"pnpm\"\npnpm add @kortyx/deepseek\n```\n\n```bash tabs=\"install-deepseek-provider\" tab=\"npm\"\nnpm install @kortyx/deepseek\n```\n\n```bash tabs=\"install-deepseek-provider\" tab=\"yarn\"\nyarn add @kortyx/deepseek\n```\n\n```bash tabs=\"install-deepseek-provider\" tab=\"bun\"\nbun add @kortyx/deepseek\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:265:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/deepseek-provider#2-what-the-package-exports","title":"2. What the package exports","description":"DeepSeek Provider","section":"DeepSeek Provider","content":"```ts\nimport {\n MODELS,\n PROVIDER_ID,\n createDeepSeek,\n deepseek,\n} from \"@kortyx/deepseek\";\n```\n\n```js\nimport {\n MODELS,\n PROVIDER_ID,\n createDeepSeek,\n deepseek,\n} from \"@kortyx/deepseek\";\n```\n\nWhat each export is for:\n\n- `deepseek`: default provider selector for the fastest start\n- `createDeepSeek(...)`: custom provider instance with explicit settings\n- `MODELS`: built-in DeepSeek model ids exposed by the package\n- `PROVIDER_ID`: the provider id string, currently `\"deepseek\"`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:265:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/deepseek-provider#3-basic-usage-in-the-same-file","title":"3. Basic usage in the same file","description":"DeepSeek Provider","section":"DeepSeek Provider","content":"```ts\nimport { deepseek } from \"@kortyx/deepseek\";\n\nconst model = deepseek(\"deepseek-chat\");\n```\n\n```js\nimport { deepseek } from \"@kortyx/deepseek\";\n\nconst model = deepseek(\"deepseek-chat\");\n```\n\n`deepseek` is a provider selector, which means:\n\n- it is callable: `deepseek(\"deepseek-chat\")`\n- it also exposes provider metadata: `deepseek.id`, `deepseek.models`\n\n```ts\ndeepseek.id; // \"deepseek\"\ndeepseek.models; // readonly list of built-in model ids\n```\n\n```js\ndeepseek.id; // \"deepseek\"\ndeepseek.models; // readonly list of built-in model ids\n```\n\n> **Good to know:** The built-in model list gives autocomplete, but arbitrary DeepSeek-compatible model ids are accepted as strings."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:265:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/deepseek-provider#4-shared-app-bootstrap-usage","title":"4. Shared app bootstrap usage","description":"DeepSeek Provider","section":"DeepSeek Provider","content":"If you want one shared import path across your app, re-export `deepseek` from a bootstrap file such as `src/lib/providers.ts`.\n\n```ts\n// src/lib/providers.ts\nexport { deepseek } from \"@kortyx/deepseek\";\n```\n\n```js\n// src/lib/providers.js\nexport { deepseek } from \"@kortyx/deepseek\";\n```\n\nThen import it from that file where you actually use it:\n\n```ts\n// src/nodes/chat.node.ts\nimport { deepseek } from \"@/lib/providers\";\n```\n\n```js\n// src/nodes/chat.node.js\nimport { deepseek } from \"@/lib/providers\";\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:265:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/deepseek-provider#5-advanced-usage-with-explicit-settings","title":"5. Advanced usage with explicit settings","description":"DeepSeek Provider","section":"DeepSeek Provider","content":"Use `createDeepSeek(...)` when you want app-owned configuration instead of the default environment-based setup.\n\n```ts\nimport { createDeepSeek } from \"@kortyx/deepseek\";\n\nexport const deepseek = createDeepSeek({\n apiKey: process.env.DEEPSEEK_API_KEY,\n});\n```\n\n```js\nimport { createDeepSeek } from \"@kortyx/deepseek\";\n\nexport const deepseek = createDeepSeek({\n apiKey: process.env.DEEPSEEK_API_KEY,\n});\n```\n\nUse the factory when you need to:\n\n- pass `apiKey` explicitly\n- use a custom `baseUrl`\n- provide a custom `fetch`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:265:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/deepseek-provider#6-credentials-and-first-use-behavior","title":"6. Credentials and first-use behavior","description":"DeepSeek Provider","section":"DeepSeek Provider","content":"The default `deepseek` export resolves credentials on first use, not at import time.\n\nSupported environment variables:\n\n- `DEEPSEEK_API_KEY`\n- `KORTYX_DEEPSEEK_API_KEY`\n\nIf neither variable is set and you did not pass `apiKey` to `createDeepSeek(...)`, the provider throws a configuration error the first time a DeepSeek model is actually used."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:265:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/deepseek-provider#7-create-model-refs-for-workflow-and-node-params","title":"7. Create model refs for workflow and node params","description":"DeepSeek Provider","section":"DeepSeek Provider","content":"```ts\nparams: {\n model: deepseek(\"deepseek-chat\"),\n temperature: 0.3,\n}\n```\n\n```js\nparams: {\n model: deepseek(\"deepseek-chat\"),\n temperature: 0.3,\n}\n```\n\nYou can also attach default model options to the ref itself:\n\n```ts\nconst model = deepseek(\"deepseek-reasoner\", {\n maxOutputTokens: 800,\n reasoning: {\n effort: \"high\",\n },\n});\n```\n\n```js\nconst model = deepseek(\"deepseek-reasoner\", {\n maxOutputTokens: 800,\n reasoning: {\n effort: \"high\",\n },\n});\n```\n\nThose become default options for later `useReason(...)` calls unless you override them at call time."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:265:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/deepseek-provider#8-use-the-model-with-usereason","title":"8. Use the model with useReason(...)","description":"DeepSeek Provider","section":"DeepSeek Provider","content":"```ts\nimport { useReason } from \"kortyx\";\nimport { deepseek } from \"@/lib/providers\";\n\nconst result = await useReason({\n model: deepseek(\"deepseek-chat\"),\n input: \"Write a concise answer for a support engineer.\",\n temperature: 0.3,\n emit: true,\n stream: true,\n});\n\nresult.text;\nresult.usage;\nresult.finishReason;\nresult.providerMetadata;\nresult.warnings;\n```\n\n```js\nimport { useReason } from \"kortyx\";\nimport { deepseek } from \"@/lib/providers\";\n\nconst result = await useReason({\n model: deepseek(\"deepseek-chat\"),\n input: \"Write a concise answer for a support engineer.\",\n temperature: 0.3,\n emit: true,\n stream: true,\n});\n\nresult.text;\nresult.usage;\nresult.finishReason;\nresult.providerMetadata;\nresult.warnings;\n```\n\n> **Good to know:** Provider setup is not done on `createAgent(...)`. Model selection happens where you call `useReason(...)` by passing a model ref."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:265:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/deepseek-provider#9-supported-normalized-call-options","title":"9. Supported normalized call options","description":"DeepSeek Provider","section":"DeepSeek Provider","content":"DeepSeek currently maps these generic Kortyx options:\n\n- `temperature`\n- `streaming`\n- `maxOutputTokens`\n- `stopSequences`\n- `abortSignal`\n- `reasoning.effort`\n- `reasoning.maxTokens`\n- `responseFormat.type`\n\nCurrent DeepSeek provider options:\n\n- `providerOptions.deepseek.thinking`\n\nCurrent mapping details:\n\n- `responseFormat.type: \"json\"` maps to DeepSeek JSON object mode\n- `reasoning.effort` maps to native effort controls; `none` or a zero budget disables thinking\n- `temperature` defaults to `0.7` when you do not set it\n\nCurrent warning-backed gaps:\n\n- `responseFormat.schema` is not sent as a native provider schema; it is included in instructions\n- DeepSeek does not expose a generic reasoning token budget through this provider\n- unknown `providerOptions` keys are ignored and reported in `result.warnings`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:265:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/deepseek-provider#10-normalized-metadata-you-get-back","title":"10. Normalized metadata you get back","description":"DeepSeek Provider","section":"DeepSeek Provider","content":"DeepSeek returns the normalized Kortyx result fields when the API provides them:\n\n- `usage`\n- `finishReason`\n- `providerMetadata`\n- `warnings`\n- `raw`\n\nDeepSeek-specific metadata currently includes fields such as:\n\n- `providerId`\n- `modelId`\n- `responseId`\n- `responseModel`\n- `created`\n- `usage`\n- `promptCacheHitTokens`\n- `promptCacheMissTokens`\n\nUse `providerMetadata` when you need debugging or observability details without coupling your app code to the raw provider payload shape."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:265:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/deepseek-provider#supported-scope","title":"Supported scope","description":"DeepSeek Provider","section":"DeepSeek Provider","content":"`@kortyx/deepseek` currently supports text generation through DeepSeek chat completions via `useReason(...)`, including streaming and non-streaming invocation.\n\nIt does not currently expose embeddings, image generation, file APIs, or provider-hosted tools. Check `result.warnings` when you rely on advanced generic options and want to verify how DeepSeek handled them."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:265:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/deepseek-provider#available-built-in-deepseek-model-ids","title":"Available built-in DeepSeek model ids","description":"DeepSeek Provider","section":"DeepSeek Provider","content":"- `deepseek-chat`\n- `deepseek-reasoner`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:265:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/deepseek-provider#next-steps","title":"Next steps","description":"DeepSeek Provider","section":"DeepSeek Provider","content":"- See [Hooks](../02-core-concepts/07-hooks.md) for `useReason(...)` behavior and structured output\n- See [Provider API](../05-reference/04-provider-api.md) for the shared normalized provider contract"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:265:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/deepseek-provider#reasoning-and-function-tools","title":"Reasoning and function tools","description":"DeepSeek Provider","section":"DeepSeek Provider","content":"`useReason` preserves `reasoning_content` privately across tool rounds and approval resumes, including earlier assistant turns. Generic `reasoning.effort` is forwarded to the API's `reasoning_effort`; `none` disables thinking. Native controls remain available as `providerOptions.deepseek.thinking` and `providerOptions.deepseek.reasoningEffort`. Unsupported positive token budgets produce a warning.\n\nDeepSeek JSON mode is accompanied by schema instructions and local validation; it is not advertised as native schema enforcement. Streamed function arguments are assembled before execution, and trailing usage does not erase the finish reason.\n\nSee [DeepSeek thinking and tool requirements](https://api-docs.deepseek.com/guides/thinking_mode/)."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","groq","provider","llama","gpt-oss","qwen"],"version":"v0","href":"/docs/sdk/kortyx-providers/groq-provider","title":"Groq Provider","description":"Use Groq-hosted models in Kortyx with the batteries-included groq export or an explicit provider instance.","section":"Kortyx Providers","content":"$8b"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:280:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/groq-provider#1-install-the-package","title":"1. Install the package","description":"Groq Provider","section":"Groq Provider","content":"```bash tabs=\"install-groq-provider\" tab=\"pnpm\"\npnpm add @kortyx/groq\n```\n\n```bash tabs=\"install-groq-provider\" tab=\"npm\"\nnpm install @kortyx/groq\n```\n\n```bash tabs=\"install-groq-provider\" tab=\"yarn\"\nyarn add @kortyx/groq\n```\n\n```bash tabs=\"install-groq-provider\" tab=\"bun\"\nbun add @kortyx/groq\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:280:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/groq-provider#2-what-the-package-exports","title":"2. What the package exports","description":"Groq Provider","section":"Groq Provider","content":"```ts\nimport { MODELS, PROVIDER_ID, createGroq, groq } from \"@kortyx/groq\";\n```\n\n```js\nimport { MODELS, PROVIDER_ID, createGroq, groq } from \"@kortyx/groq\";\n```\n\nWhat each export is for:\n\n- `groq`: default provider selector for the fastest start\n- `createGroq(...)`: custom provider instance with explicit settings\n- `MODELS`: built-in Groq model ids exposed by the package\n- `PROVIDER_ID`: the provider id string, currently `\"groq\"`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:280:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/groq-provider#3-basic-usage-in-the-same-file","title":"3. Basic usage in the same file","description":"Groq Provider","section":"Groq Provider","content":"```ts\nimport { groq } from \"@kortyx/groq\";\n\nconst model = groq(\"llama-3.3-70b-versatile\");\n```\n\n```js\nimport { groq } from \"@kortyx/groq\";\n\nconst model = groq(\"llama-3.3-70b-versatile\");\n```\n\n`groq` is a provider selector, which means:\n\n- it is callable: `groq(\"llama-3.3-70b-versatile\")`\n- it also exposes provider metadata: `groq.id`, `groq.models`\n\n```ts\ngroq.id; // \"groq\"\ngroq.models; // readonly list of built-in model ids\n```\n\n```js\ngroq.id; // \"groq\"\ngroq.models; // readonly list of built-in model ids\n```\n\n> **Good to know:** The built-in model list gives autocomplete, but arbitrary Groq-compatible model ids are accepted as strings."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:280:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/groq-provider#4-shared-app-bootstrap-usage","title":"4. Shared app bootstrap usage","description":"Groq Provider","section":"Groq Provider","content":"If you want one shared import path across your app, re-export `groq` from a bootstrap file such as `src/lib/providers.ts`.\n\n```ts\n// src/lib/providers.ts\nexport { groq } from \"@kortyx/groq\";\n```\n\n```js\n// src/lib/providers.js\nexport { groq } from \"@kortyx/groq\";\n```\n\nThen import it from that file where you actually use it:\n\n```ts\n// src/nodes/chat.node.ts\nimport { groq } from \"@/lib/providers\";\n```\n\n```js\n// src/nodes/chat.node.js\nimport { groq } from \"@/lib/providers\";\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:280:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/groq-provider#5-advanced-usage-with-explicit-settings","title":"5. Advanced usage with explicit settings","description":"Groq Provider","section":"Groq Provider","content":"Use `createGroq(...)` when you want app-owned configuration instead of the default environment-based setup.\n\n```ts\nimport { createGroq } from \"@kortyx/groq\";\n\nexport const groq = createGroq({\n apiKey: process.env.GROQ_API_KEY,\n});\n```\n\n```js\nimport { createGroq } from \"@kortyx/groq\";\n\nexport const groq = createGroq({\n apiKey: process.env.GROQ_API_KEY,\n});\n```\n\nUse the factory when you need to:\n\n- pass `apiKey` explicitly\n- use a custom `baseUrl`\n- provide a custom `fetch`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:280:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/groq-provider#6-credentials-and-first-use-behavior","title":"6. Credentials and first-use behavior","description":"Groq Provider","section":"Groq Provider","content":"The default `groq` export resolves credentials on first use, not at import time.\n\nSupported environment variables:\n\n- `GROQ_API_KEY`\n- `KORTYX_GROQ_API_KEY`\n\nIf neither variable is set and you did not pass `apiKey` to `createGroq(...)`, the provider throws a configuration error the first time a Groq model is actually used."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:280:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/groq-provider#7-create-model-refs-for-workflow-and-node-params","title":"7. Create model refs for workflow and node params","description":"Groq Provider","section":"Groq Provider","content":"```ts\nparams: {\n model: groq(\"llama-3.3-70b-versatile\"),\n temperature: 0.3,\n}\n```\n\n```js\nparams: {\n model: groq(\"llama-3.3-70b-versatile\"),\n temperature: 0.3,\n}\n```\n\nYou can also attach default model options to the ref itself:\n\n```ts\nconst model = groq(\"qwen/qwen3-32b\", {\n providerOptions: {\n groq: {\n reasoningFormat: \"parsed\",\n serviceTier: \"auto\",\n },\n },\n});\n```\n\n```js\nconst model = groq(\"qwen/qwen3-32b\", {\n providerOptions: {\n groq: {\n reasoningFormat: \"parsed\",\n serviceTier: \"auto\",\n },\n },\n});\n```\n\nThose become default options for later `useReason(...)` calls unless you override them at call time."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:280:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/groq-provider#8-use-the-model-with-usereason","title":"8. Use the model with useReason(...)","description":"Groq Provider","section":"Groq Provider","content":"```ts\nimport { useReason } from \"kortyx\";\nimport { groq } from \"@/lib/providers\";\n\nconst result = await useReason({\n model: groq(\"llama-3.3-70b-versatile\"),\n input: \"Write a concise answer for a support engineer.\",\n temperature: 0.3,\n emit: true,\n stream: true,\n});\n\nresult.text;\nresult.usage;\nresult.finishReason;\nresult.providerMetadata;\nresult.warnings;\n```\n\n```js\nimport { useReason } from \"kortyx\";\nimport { groq } from \"@/lib/providers\";\n\nconst result = await useReason({\n model: groq(\"llama-3.3-70b-versatile\"),\n input: \"Write a concise answer for a support engineer.\",\n temperature: 0.3,\n emit: true,\n stream: true,\n});\n\nresult.text;\nresult.usage;\nresult.finishReason;\nresult.providerMetadata;\nresult.warnings;\n```\n\n> **Good to know:** Provider setup is not done on `createAgent(...)`. Model selection happens where you call `useReason(...)` by passing a model ref."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:280:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/groq-provider#9-supported-normalized-call-options","title":"9. Supported normalized call options","description":"Groq Provider","section":"Groq Provider","content":"$8c"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:280:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/groq-provider#10-normalized-metadata-you-get-back","title":"10. Normalized metadata you get back","description":"Groq Provider","section":"Groq Provider","content":"Groq returns the normalized Kortyx result fields when the API provides them:\n\n- `usage`\n- `finishReason`\n- `providerMetadata`\n- `warnings`\n- `raw`\n\nGroq-specific metadata currently includes fields such as:\n\n- `providerId`\n- `modelId`\n- `responseId`\n- `responseModel`\n- `created`\n- `usage`\n- `cachedTokens`\n- `reasoningTokens`\n\nUse `providerMetadata` when you need debugging or observability details without coupling your app code to the raw provider payload shape."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:280:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/groq-provider#supported-scope","title":"Supported scope","description":"Groq Provider","section":"Groq Provider","content":"`@kortyx/groq` currently supports text generation through Groq chat completions via `useReason(...)`, including streaming and non-streaming invocation.\n\nIt does not currently expose Groq transcription, browser search, embeddings, image generation, file APIs, or provider-hosted tools. Check `result.warnings` when you rely on advanced generic options and want to verify how Groq handled them."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:280:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/groq-provider#available-built-in-groq-model-ids","title":"Available built-in Groq model ids","description":"Groq Provider","section":"Groq Provider","content":"- `llama-3.1-8b-instant`\n- `llama-3.3-70b-versatile`\n- `openai/gpt-oss-120b`\n- `openai/gpt-oss-20b`\n- `qwen/qwen3-32b`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:280:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/groq-provider#next-steps","title":"Next steps","description":"Groq Provider","section":"Groq Provider","content":"- See [Hooks](../02-core-concepts/07-hooks.md) for `useReason(...)` behavior and structured output\n- See [Provider API](../05-reference/04-provider-api.md) for the shared normalized provider contract"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:280:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/groq-provider#reasoning-tools-and-structured-output","title":"Reasoning, tools, and structured output","description":"Groq Provider","section":"Groq Provider","content":"$8d"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","mistral","provider","magistral","pixtral"],"version":"v0","href":"/docs/sdk/kortyx-providers/mistral-provider","title":"Mistral Provider","description":"Use Mistral models in Kortyx with the batteries-included mistral export or an explicit provider instance.","section":"Kortyx Providers","content":"$8e"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:295:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/mistral-provider#1-install-the-package","title":"1. Install the package","description":"Mistral Provider","section":"Mistral Provider","content":"```bash tabs=\"install-mistral-provider\" tab=\"pnpm\"\npnpm add @kortyx/mistral\n```\n\n```bash tabs=\"install-mistral-provider\" tab=\"npm\"\nnpm install @kortyx/mistral\n```\n\n```bash tabs=\"install-mistral-provider\" tab=\"yarn\"\nyarn add @kortyx/mistral\n```\n\n```bash tabs=\"install-mistral-provider\" tab=\"bun\"\nbun add @kortyx/mistral\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:295:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/mistral-provider#2-what-the-package-exports","title":"2. What the package exports","description":"Mistral Provider","section":"Mistral Provider","content":"```ts\nimport {\n MODELS,\n PROVIDER_ID,\n createMistral,\n mistral,\n} from \"@kortyx/mistral\";\n```\n\n```js\nimport {\n MODELS,\n PROVIDER_ID,\n createMistral,\n mistral,\n} from \"@kortyx/mistral\";\n```\n\nWhat each export is for:\n\n- `mistral`: default provider selector for the fastest start\n- `createMistral(...)`: custom provider instance with explicit settings\n- `MODELS`: built-in Mistral model ids exposed by the package\n- `PROVIDER_ID`: the provider id string, currently `\"mistral\"`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:295:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/mistral-provider#3-basic-usage-in-the-same-file","title":"3. Basic usage in the same file","description":"Mistral Provider","section":"Mistral Provider","content":"```ts\nimport { mistral } from \"@kortyx/mistral\";\n\nconst model = mistral(\"mistral-large-latest\");\n```\n\n```js\nimport { mistral } from \"@kortyx/mistral\";\n\nconst model = mistral(\"mistral-large-latest\");\n```\n\n`mistral` is a provider selector, which means:\n\n- it is callable: `mistral(\"mistral-large-latest\")`\n- it also exposes provider metadata: `mistral.id`, `mistral.models`\n\n```ts\nmistral.id; // \"mistral\"\nmistral.models; // readonly list of built-in model ids\n```\n\n```js\nmistral.id; // \"mistral\"\nmistral.models; // readonly list of built-in model ids\n```\n\n> **Good to know:** The built-in model list gives autocomplete, but arbitrary Mistral model ids are accepted as strings."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:295:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/mistral-provider#4-shared-app-bootstrap-usage","title":"4. Shared app bootstrap usage","description":"Mistral Provider","section":"Mistral Provider","content":"If you want one shared import path across your app, re-export `mistral` from a bootstrap file such as `src/lib/providers.ts`.\n\n```ts\n// src/lib/providers.ts\nexport { mistral } from \"@kortyx/mistral\";\n```\n\n```js\n// src/lib/providers.js\nexport { mistral } from \"@kortyx/mistral\";\n```\n\nThen import it from that file where you actually use it:\n\n```ts\n// src/nodes/chat.node.ts\nimport { mistral } from \"@/lib/providers\";\n```\n\n```js\n// src/nodes/chat.node.js\nimport { mistral } from \"@/lib/providers\";\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:295:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/mistral-provider#5-advanced-usage-with-explicit-settings","title":"5. Advanced usage with explicit settings","description":"Mistral Provider","section":"Mistral Provider","content":"Use `createMistral(...)` when you want app-owned configuration instead of the default environment-based setup.\n\n```ts\nimport { createMistral } from \"@kortyx/mistral\";\n\nexport const mistral = createMistral({\n apiKey: process.env.MISTRAL_API_KEY,\n});\n```\n\n```js\nimport { createMistral } from \"@kortyx/mistral\";\n\nexport const mistral = createMistral({\n apiKey: process.env.MISTRAL_API_KEY,\n});\n```\n\nUse the factory when you need to:\n\n- pass `apiKey` explicitly\n- use a custom `baseUrl`\n- provide a custom `fetch`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:295:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/mistral-provider#6-credentials-and-first-use-behavior","title":"6. Credentials and first-use behavior","description":"Mistral Provider","section":"Mistral Provider","content":"The default `mistral` export resolves credentials on first use, not at import time.\n\nSupported environment variables:\n\n- `MISTRAL_API_KEY`\n- `KORTYX_MISTRAL_API_KEY`\n\nIf neither variable is set and you did not pass `apiKey` to `createMistral(...)`, the provider throws a configuration error the first time a Mistral model is actually used."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:295:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/mistral-provider#7-create-model-refs-for-workflow-and-node-params","title":"7. Create model refs for workflow and node params","description":"Mistral Provider","section":"Mistral Provider","content":"```ts\nparams: {\n model: mistral(\"mistral-large-latest\"),\n temperature: 0.3,\n}\n```\n\n```js\nparams: {\n model: mistral(\"mistral-large-latest\"),\n temperature: 0.3,\n}\n```\n\nYou can also attach default model options to the ref itself:\n\n```ts\nconst model = mistral(\"mistral-small-latest\", {\n providerOptions: {\n mistral: {\n safePrompt: true,\n reasoningEffort: \"high\",\n },\n },\n});\n```\n\n```js\nconst model = mistral(\"mistral-small-latest\", {\n providerOptions: {\n mistral: {\n safePrompt: true,\n reasoningEffort: \"high\",\n },\n },\n});\n```\n\nThose become default options for later `useReason(...)` calls unless you override them at call time."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:295:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/mistral-provider#8-use-the-model-with-usereason","title":"8. Use the model with useReason(...)","description":"Mistral Provider","section":"Mistral Provider","content":"```ts\nimport { useReason } from \"kortyx\";\nimport { mistral } from \"@/lib/providers\";\n\nconst result = await useReason({\n model: mistral(\"mistral-large-latest\"),\n input: \"Write a concise answer for a support engineer.\",\n temperature: 0.3,\n emit: true,\n stream: true,\n});\n\nresult.text;\nresult.usage;\nresult.finishReason;\nresult.providerMetadata;\nresult.warnings;\n```\n\n```js\nimport { useReason } from \"kortyx\";\nimport { mistral } from \"@/lib/providers\";\n\nconst result = await useReason({\n model: mistral(\"mistral-large-latest\"),\n input: \"Write a concise answer for a support engineer.\",\n temperature: 0.3,\n emit: true,\n stream: true,\n});\n\nresult.text;\nresult.usage;\nresult.finishReason;\nresult.providerMetadata;\nresult.warnings;\n```\n\n> **Good to know:** Provider setup is not done on `createAgent(...)`. Model selection happens where you call `useReason(...)` by passing a model ref."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:295:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/mistral-provider#9-supported-normalized-call-options","title":"9. Supported normalized call options","description":"Mistral Provider","section":"Mistral Provider","content":"$8f"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:295:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/mistral-provider#10-normalized-metadata-you-get-back","title":"10. Normalized metadata you get back","description":"Mistral Provider","section":"Mistral Provider","content":"Mistral returns the normalized Kortyx result fields when the API provides them:\n\n- `usage`\n- `finishReason`\n- `providerMetadata`\n- `warnings`\n- `raw`\n\nMistral-specific metadata currently includes fields such as:\n\n- `providerId`\n- `modelId`\n- `responseId`\n- `responseModel`\n- `created`\n- `usage`\n\nUse `providerMetadata` when you need debugging or observability details without coupling your app code to the raw provider payload shape."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:295:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/mistral-provider#supported-scope","title":"Supported scope","description":"Mistral Provider","section":"Mistral Provider","content":"`@kortyx/mistral` currently supports text generation through Mistral chat completions via `useReason(...)`, including streaming and non-streaming invocation.\n\nIt does not currently expose Mistral embeddings, OCR/document APIs, file APIs, or provider-hosted tools. Check `result.warnings` when you rely on advanced generic options and want to verify how Mistral handled them."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:295:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/mistral-provider#available-built-in-mistral-model-ids","title":"Available built-in Mistral model ids","description":"Mistral Provider","section":"Mistral Provider","content":"- `ministral-3b-latest`\n- `ministral-8b-latest`\n- `ministral-14b-latest`\n- `mistral-large-latest`\n- `mistral-medium-latest`\n- `mistral-large-2512`\n- `mistral-medium-2508`\n- `mistral-medium-2505`\n- `mistral-small-2506`\n- `mistral-small-latest`\n- `mistral-small-2603`\n- `magistral-medium-latest`\n- `magistral-small-latest`\n- `magistral-medium-2509`\n- `magistral-small-2509`\n- `pixtral-large-latest`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:295:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/mistral-provider#next-steps","title":"Next steps","description":"Mistral Provider","section":"Mistral Provider","content":"- See [Hooks](../02-core-concepts/07-hooks.md) for `useReason(...)` behavior and structured output\n- See [Provider API](../05-reference/04-provider-api.md) for the shared normalized provider contract"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:295:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/mistral-provider#reasoning-and-function-tools","title":"Reasoning and function tools","description":"Mistral Provider","section":"Mistral Provider","content":"`useReason` preserves native thinking chunks privately across tool rounds and approval resumes. Configurable reasoning supports current Mistral Small and Medium aliases, including `mistral-medium-3-5`. `effort: \"none\"` disables reasoning; positive generic efforts map to the API's `high` mode, with a warning when the requested level differs. Use `providerOptions.mistral.reasoningEffort` for the native none/high control.\n\nCompatible output schemas continue to use native structured output. Streamed function arguments are assembled before execution, with final usage and finish reason preserved.\n\nSee [Mistral reasoning guidance](https://docs.mistral.ai/studio/conversations/reasoning)."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","openrouter","provider","claude","openai","gemini","routing"],"version":"v0","href":"/docs/sdk/kortyx-providers/openrouter-provider","title":"OpenRouter Provider","description":"Use Claude, OpenAI, Gemini, and other OpenRouter chat models through the standard Kortyx provider shape.","section":"Kortyx Providers","content":"$90"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:310:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openrouter-provider#1-install-the-package","title":"1. Install the package","description":"OpenRouter Provider","section":"OpenRouter Provider","content":"```bash tabs=\"install-openrouter\" tab=\"pnpm\"\npnpm add @kortyx/openrouter\n```\n\n```bash tabs=\"install-openrouter\" tab=\"npm\"\nnpm install @kortyx/openrouter\n```\n\n```bash tabs=\"install-openrouter\" tab=\"yarn\"\nyarn add @kortyx/openrouter\n```\n\n```bash tabs=\"install-openrouter\" tab=\"bun\"\nbun add @kortyx/openrouter\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:310:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openrouter-provider#2-what-the-package-exports","title":"2. What the package exports","description":"OpenRouter Provider","section":"OpenRouter Provider","content":"```ts\nimport {\n MODELS,\n PROVIDER_ID,\n createOpenRouter,\n openrouter,\n} from \"@kortyx/openrouter\";\n```\n\n- `openrouter`: default provider selector\n- `createOpenRouter(...)`: factory for explicit application-owned settings\n- `PROVIDER_ID`: the provider id, currently `\"openrouter\"`\n- `MODELS`: intentionally empty because OpenRouter's catalog changes\n continuously; the selector accepts arbitrary non-empty model ids\n\nThe package also exports `jevOutputSchema(...)`. That helper is specific to\nTypeSafe Jev and is covered in [TypeSafe Jev through OpenRouter](./08-jev-openrouter.md)."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:310:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openrouter-provider#3-same-usage-shape-as-openai","title":"3. Same usage shape as OpenAI","description":"OpenRouter Provider","section":"OpenRouter Provider","content":"Only the provider selector and model id change:\n\n```ts\nimport { openai } from \"@kortyx/openai\";\nimport { openrouter } from \"@kortyx/openrouter\";\n\nconst directOpenAI = openai(\"gpt-5.6-luna\");\nconst routedOpenAI = openrouter(\"openai/gpt-5.6-luna\");\nconst routedClaude = openrouter(\"anthropic/claude-sonnet-4.6\");\nconst routedGemini = openrouter(\"google/gemini-3.1-pro\");\n```\n\nAll are regular Kortyx model refs passed to `useReason(...)`. Normalized call\nfields keep the same shape:\n\n```ts\nconst result = await useReason({\n model: openrouter(\"anthropic/claude-sonnet-4.6\"),\n system: \"Answer concisely.\",\n input: ticket,\n temperature: 0.2,\n maxOutputTokens: 800,\n reasoning: { effort: \"high\" },\n tools,\n outputSchema,\n stream: true,\n emit: true,\n});\n```\n\nThe chosen OpenRouter model and provider route must support the features used\nby the request. OpenRouter broadens model access; it does not make every model\nsupport tools, structured output, reasoning, or media identically."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:310:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openrouter-provider#4-credentials-and-explicit-configuration","title":"4. Credentials and explicit configuration","description":"OpenRouter Provider","section":"OpenRouter Provider","content":"The default `openrouter` export reads credentials on first use from:\n\n- `OPENROUTER_API_KEY`\n- `KORTYX_OPENROUTER_API_KEY`\n\nUse `createOpenRouter(...)` when the application owns configuration:\n\n```ts\nimport { createOpenRouter } from \"@kortyx/openrouter\";\n\nexport const openrouter = createOpenRouter({\n apiKey: process.env.OPENROUTER_API_KEY,\n appTitle: \"Example Chat App\",\n httpReferer: \"https://example.com\",\n});\n```\n\nSupported settings are `apiKey`, `baseUrl`, `appTitle`, `httpReferer`,\n`appCategories`, and a custom `fetch` implementation. Keep all credentials and\nprovider construction on the server."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:310:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openrouter-provider#5-openrouter-routing-controls","title":"5. OpenRouter routing controls","description":"OpenRouter Provider","section":"OpenRouter Provider","content":"$91"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:310:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openrouter-provider#6-structured-output-and-tools","title":"6. Structured output and tools","description":"OpenRouter Provider","section":"OpenRouter Provider","content":"Use the normal Kortyx APIs:\n\n```ts\nimport { z } from \"zod\";\n\nconst Summary = z.object({\n category: z.string(),\n summary: z.string(),\n});\n\nconst result = await useReason({\n model: openrouter(\"openai/gpt-5.6-luna\"),\n input: ticket,\n tools: [lookupCustomer],\n outputSchema: Summary,\n stream: false,\n});\n\nresult.output;\n```\n\nOpenRouter tool calls, streamed arguments, structured output, usage, and finish\nreasons are normalized to the shared Kortyx contracts. Provider-native routing,\ncost, cache, BYOK, and service-tier details remain available in\n`result.providerMetadata` and `result.raw`.\n\nWhen OpenRouter reports cost, Kortyx records that provider-reported USD amount\nas the authoritative generation cost. Kortyx Studio then aggregates it across\nthe run without maintaining a separate rate card for every routed model."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:310:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openrouter-provider#7-reasoning-continuation","title":"7. Reasoning continuation","description":"OpenRouter Provider","section":"OpenRouter Provider","content":"OpenRouter reasoning details are retained as private continuation state for\nlater model passes, including tool rounds. Application code should use the\nnormalized result fields instead of manually replaying provider-native\nreasoning payloads."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:310:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openrouter-provider#8-validation-warnings-and-retries","title":"8. Validation, warnings, and retries","description":"OpenRouter Provider","section":"OpenRouter Provider","content":"- The official OpenRouter SDK validates request and response payloads.\n- Kortyx reports normalized compatibility information through\n `result.warnings`.\n- The SDK's independent retry loop is disabled so Kortyx owns retry policy.\n- OpenRouter routing and fallback behavior remains controlled by the request's\n OpenRouter provider settings.\n\nKortyx intentionally does not publish a static model-capability registry. Use\nOpenRouter's current model metadata and test the exact model and provider route\nused in production."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:310:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openrouter-provider#supported-scope","title":"Supported scope","description":"OpenRouter Provider","section":"OpenRouter Provider","content":"The adapter supports chat-model text generation through `useReason(...)`,\nincluding streaming, function tools, structured output, reasoning controls,\nand normalized usage when supported by the selected route.\n\nEmbeddings, image generation, audio, transcription, file APIs, and arbitrary\nOpenRouter-hosted endpoints are not exposed by this provider adapter.\n\nTypeSafe Jev is the provider-native exception: it uses OpenRouter's System One\nendpoint while preserving the normal `useReason(...)` call shape. Continue with\n[TypeSafe Jev through OpenRouter](./08-jev-openrouter.md) for its different\nschema and compatibility rules."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:310:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/openrouter-provider#next-steps","title":"Next steps","description":"OpenRouter Provider","section":"OpenRouter Provider","content":"- See [TypeSafe Jev through OpenRouter](./08-jev-openrouter.md) for typed\n decisions and probabilities\n- See [Hooks](../02-core-concepts/07-hooks.md) for general `useReason(...)`\n behavior\n- See [Provider API](../05-reference/04-provider-api.md) for the normalized\n provider contract"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","openrouter","typesafe","jev","system one","decisions","classification"],"version":"v0","href":"/docs/sdk/kortyx-providers/jev-openrouter","title":"TypeSafe Jev through OpenRouter","description":"Use TypeSafe Jev as a regular Kortyx model with native System One questions and typed decision output.","section":"Kortyx Providers","content":"$92"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:321:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/jev-openrouter#1-install-and-import","title":"1. Install and import","description":"TypeSafe Jev through OpenRouter","section":"TypeSafe Jev through OpenRouter","content":"Jev support is included in `@kortyx/openrouter`:\n\n```bash tabs=\"jev-install\" tab=\"pnpm\"\npnpm add @kortyx/openrouter\n```\n```bash tabs=\"jev-install\" tab=\"npm\"\nnpm install @kortyx/openrouter\n```\n\n```ts\nimport { jevOutputSchema, openrouter } from \"@kortyx/openrouter\";\nimport { useReason } from \"kortyx\";\n```\n```js\nimport { jevOutputSchema, openrouter } from \"@kortyx/openrouter\";\nimport { useReason } from \"kortyx\";\n```\n\nIt uses the same `OPENROUTER_API_KEY` or `KORTYX_OPENROUTER_API_KEY` credentials\nas other OpenRouter models."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:321:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/jev-openrouter#2-define-native-jev-questions","title":"2. Define native Jev questions","description":"TypeSafe Jev through OpenRouter","section":"TypeSafe Jev through OpenRouter","content":"$93"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:321:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/jev-openrouter#3-call-jev-through-usereason","title":"3. Call Jev through useReason(...)","description":"TypeSafe Jev through OpenRouter","section":"TypeSafe Jev through OpenRouter","content":"```ts\nconst result = await useReason({\n id: \"triage-ticket\",\n model: openrouter(\"typesafe/jev-1.13\"),\n input: ticket,\n outputSchema: TicketDecision,\n});\n\nresult.output?.queue; // \"billing\" | \"technical\"\nresult.output?.urgency; // number from 0 to 2, including fractional values\nresult.output?.needsHuman; // probability from 0 to 1\n```\n```js\nconst result = await useReason({\n id: \"triage-ticket\",\n model: openrouter(\"typesafe/jev-1.13\"),\n input: ticket,\n outputSchema: TicketDecision,\n});\n\nresult.output?.queue;\nresult.output?.urgency;\nresult.output?.needsHuman;\n```\n\nThere is no separate `openrouter.decide(...)` API. Jev is selected through the\nsame `openrouter(modelId)` helper used for chat models, and it participates in\nthe normal Kortyx result, tracing, usage, and telemetry flow."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:321:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/jev-openrouter#4-how-question-types-map-to-output","title":"4. How question types map to output","description":"TypeSafe Jev through OpenRouter","section":"TypeSafe Jev through OpenRouter","content":"| Jev question | Definition | `result.output` |\n| --- | --- | --- |\n| `choice` | named criteria object | selected criterion key, inferred as a string union |\n| `score` | ordered array of 2–10 levels | numeric position from `0` to `criteria.length - 1`; may be fractional |\n| `noul` | yes/no instruction with optional criteria | probability of yes from `0` to `1` |\n\n`noul` is intentionally not converted to a boolean. Choose an application\nthreshold based on the cost of false positives and false negatives:\n\n```ts\nconst HUMAN_THRESHOLD = 0.8;\nconst needsHuman = (result.output?.needsHuman ?? 0) >= HUMAN_THRESHOLD;\n```\n```js\nconst HUMAN_THRESHOLD = 0.8;\nconst needsHuman = (result.output?.needsHuman ?? 0) >= HUMAN_THRESHOLD;\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:321:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/jev-openrouter#5-native-details-and-normalized-result-fields","title":"5. Native details and normalized result fields","description":"TypeSafe Jev through OpenRouter","section":"TypeSafe Jev through OpenRouter","content":"The simplified typed decision lives in `result.output`. Additional native\ndetails remain available for decisions that need uncertainty handling:\n\n```ts\nresult.output;\nresult.usage;\nresult.providerMetadata?.cost;\nresult.providerMetadata?.answers;\nresult.raw;\n```\n```js\nresult.output;\nresult.usage;\nresult.providerMetadata?.cost;\nresult.providerMetadata?.answers;\nresult.raw;\n```\n\n`providerMetadata.answers` retains native choice probabilities, score\nprobabilities and legends, and confidence when returned. `providerMetadata.cost`\nretains OpenRouter's reported cost. `result.usage` contains normalized input,\noutput, and total token counts.\n\nUse `result.output` for ordinary application branching. Read probabilities and\nconfidence when the application has an explicit uncertainty or review policy."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:321:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/jev-openrouter#6-unsupported-fields-fail-or-warn-explicitly","title":"6. Unsupported fields fail or warn explicitly","description":"TypeSafe Jev through OpenRouter","section":"TypeSafe Jev through OpenRouter","content":"Known hard incompatibilities fail before the network request:\n\n- `tools` are not supported by Jev\n- omitting `jevOutputSchema(...)` fails configuration validation\n- supplying an explicit `responseFormat` that replaces the helper metadata\n fails configuration validation\n\nDo not add `responseFormat` manually:\n\n```ts\n// Correct: the helper provides the native wire contract.\nawait useReason({\n model: openrouter(\"typesafe/jev-1.13\"),\n input: ticket,\n outputSchema: TicketDecision,\n});\n```\n```js\n// The helper provides the native wire contract.\nawait useReason({\n model: openrouter(\"typesafe/jev-1.13\"),\n input: ticket,\n outputSchema: TicketDecision,\n});\n```\n\nChat-only controls such as `temperature`, `maxOutputTokens`, `stopSequences`,\nand reasoning settings are not sent to System One. Kortyx reports them through\n`result.warnings` instead of silently pretending they changed the decision."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:321:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/jev-openrouter#7-streaming-behavior","title":"7. Streaming behavior","description":"TypeSafe Jev through OpenRouter","section":"TypeSafe Jev through OpenRouter","content":"OpenRouter System One is non-streaming. If a caller requests a stream, Kortyx\nperforms one decision request and emits the completed serialized output as one\nfinal result. Do not expect token-by-token text from Jev.\n\nFor normal use, omit `stream` and consume the typed `result.output` after the\nhook resolves."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:321:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/jev-openrouter#8-openrouter-options-supported-by-jev","title":"8. OpenRouter options supported by Jev","description":"TypeSafe Jev through OpenRouter","section":"TypeSafe Jev through OpenRouter","content":"These OpenRouter-native controls are forwarded to System One when provided:\n\n- `provider`\n- `sessionId`\n- `trace`\n- `user`\n\n```ts\nconst result = await useReason({\n model: openrouter(\"typesafe/jev-1.13\"),\n input: ticket,\n outputSchema: TicketDecision,\n providerOptions: {\n openrouter: {\n sessionId: ticketId,\n user: accountId,\n provider: { zdr: true },\n },\n },\n});\n```\n```js\nconst result = await useReason({\n model: openrouter(\"typesafe/jev-1.13\"),\n input: ticket,\n outputSchema: TicketDecision,\n providerOptions: {\n openrouter: {\n sessionId: ticketId,\n user: accountId,\n provider: { zdr: true },\n },\n },\n});\n```\n\nOther OpenRouter chat-only provider options produce an unsupported-option\nwarning and are not included in the System One request."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:321:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/jev-openrouter#9-model-ids","title":"9. Model ids","description":"TypeSafe Jev through OpenRouter","section":"TypeSafe Jev through OpenRouter","content":"Use a current OpenRouter Jev model id such as:\n\n- `typesafe/jev-1.13`\n- `~typesafe/jev-latest`\n- `jev-latest`\n\nNamespaced ids make the upstream provider explicit. Alias availability can\nchange, so use the model id chosen by the application rather than hard-coding a\ncatalog in shared framework code."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:321:keywords","version":"v0","href":"/docs/sdk/kortyx-providers/jev-openrouter#next-steps","title":"Next steps","description":"TypeSafe Jev through OpenRouter","section":"TypeSafe Jev through OpenRouter","content":"- Return to the [OpenRouter provider](./07-openrouter-provider.md) for chat\n models, routing, tools, and structured output\n- See [Hooks](../02-core-concepts/07-hooks.md) for the complete `useReason(...)`\n contract\n- See [Provider API](../05-reference/04-provider-api.md) for normalized result\n fields and warnings"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","runtime-persistence","framework-adapter","resume"],"version":"v0","href":"/docs/sdk/production/persistence","title":"Runtime Persistence","description":"Understand when you need Kortyx runtime persistence and when your app should use its own database.","section":"Production","content":"$94"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:332:keywords","version":"v0","href":"/docs/sdk/production/persistence#read-this-page-if","title":"Read this page if","description":"Runtime Persistence","section":"Runtime Persistence","content":"- you use `useInterrupt(...)`\n- you want a paused run to resume later\n- you want resume to survive a server restart or redeploy\n\nIf you are building a simple request -> response flow with no pause/resume, you can usually skip this page for now."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:332:keywords","version":"v0","href":"/docs/sdk/production/persistence#the-simple-rule","title":"The simple rule","description":"Runtime Persistence","section":"Runtime Persistence","content":"| You want to store... | Where it belongs |\n| --- | --- |\n| a paused run waiting for user input | Kortyx runtime persistence |\n| a checkpoint needed to continue after restart | Kortyx runtime persistence |\n| rollback/fork checkpoints for active workflow sessions | Kortyx runtime persistence |\n| conversation history you want to show in your product | your app DB or service layer |\n| users, orgs, tickets, profiles, orders | your app DB or service layer |\n| documents, embeddings, search indexes | your app DB or service layer |"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:332:keywords","version":"v0","href":"/docs/sdk/production/persistence#why-kortyx-needs-its-own-persistence","title":"Why Kortyx needs its own persistence","description":"Runtime Persistence","section":"Runtime Persistence","content":"When a workflow pauses, Kortyx needs to remember enough state to continue safely later.\n\nThat includes:\n\n- the pending interrupt request\n- the checkpoint for the paused run\n- user-facing session checkpoints for rollback, fork, regenerate, and undo\n- short-lived runtime state tied to that run\n\nWithout that stored state, a restart would lose the paused workflow."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:332:keywords","version":"v0","href":"/docs/sdk/production/persistence#what-kortyx-does-not-own","title":"What Kortyx does not own","description":"Runtime Persistence","section":"Runtime Persistence","content":"Kortyx does not manage your product database, schema, or business records.\n\nIf you want to save something because it matters to your product later, save it through your own DB or service layer inside node code.\n\n> **Good to know:** Treat Kortyx runtime persistence as execution state, not as an application data store."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:332:keywords","version":"v0","href":"/docs/sdk/production/persistence#when-the-default-is-enough","title":"When the default is enough","description":"Runtime Persistence","section":"Runtime Persistence","content":"- local dev or demos: in-memory is usually fine\n- production with interrupt/resume across restarts: use Redis\n- production with rollback/fork/regenerate for many users: use Redis\n\nIn-memory runtime persistence is intentionally lightweight. It stores state in the current Node process, so it is not shared across workers and it disappears on restart. Session checkpoints are capped by count per session, but in-memory session checkpoint records do not have a global memory cap or TTL.\n\n> **Good to know:** The config property is still called `frameworkAdapter`, but what it controls is the runtime persistence backend used by Kortyx."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:332:keywords","version":"v0","href":"/docs/sdk/production/persistence#what-to-read-next","title":"What to read next","description":"Runtime Persistence","section":"Runtime Persistence","content":"Read [Runtime Persistence Adapters](./02-framework-adapters.md) when you need to choose or configure the backend used for that runtime state."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","runtime-persistence","framework-adapter","redis","postgresql","retention","ttl"],"version":"v0","href":"/docs/sdk/production/framework-adapters","title":"Runtime Persistence Adapters","description":"Choose and configure the backend Kortyx uses for interrupt/resume checkpoints.","section":"Production","content":"$95"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:339:keywords","version":"v0","href":"/docs/sdk/production/framework-adapters#what-this-adapter-stores","title":"What this adapter stores","description":"Runtime Persistence Adapters","section":"Runtime Persistence Adapters","content":"- pending interrupt requests\n- checkpoints for paused runs\n- user-facing session checkpoints for rollback, fork, regenerate, and undo\n- runtime execution state, with adapter-specific expiry and retention\n\n> **Good to know:** This adapter is only for Kortyx runtime state. Keep your app's business data in your own DB or service layer."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:339:keywords","version":"v0","href":"/docs/sdk/production/framework-adapters#recommended-path","title":"Recommended path","description":"Runtime Persistence Adapters","section":"Runtime Persistence Adapters","content":"For most apps:\n\n1. local dev: pass nothing and use the default\n2. short-lived production resume: set `KORTYX_REDIS_URL`\n3. month-long history: configure PostgreSQL and complete schema setup before traffic\n4. create adapters manually when you want explicit control in code\n\n> **Good to know:** `createFrameworkAdapterFromEnv()` is not a third backend. It is the default helper that chooses between in-memory, Redis, and PostgreSQL."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:339:keywords","version":"v0","href":"/docs/sdk/production/framework-adapters#where-this-is-used","title":"Where this is used","description":"Runtime Persistence Adapters","section":"Runtime Persistence Adapters","content":"$96"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:339:keywords","version":"v0","href":"/docs/sdk/production/framework-adapters#in-memory","title":"In-memory","description":"Runtime Persistence Adapters","section":"Runtime Persistence Adapters","content":"Use this for local development, demos, or quick testing.\n\n```ts\nimport { createInMemoryFrameworkAdapter } from \"kortyx\";\n\nconst frameworkAdapter = createInMemoryFrameworkAdapter({\n ttlMs: 15 * 60 * 1000,\n maxSessionCheckpoints: 50,\n});\n```\n\n```js\nimport { createInMemoryFrameworkAdapter } from \"kortyx\";\n\nconst frameworkAdapter = createInMemoryFrameworkAdapter({\n ttlMs: 15 * 60 * 1000,\n maxSessionCheckpoints: 50,\n});\n```\n\n- stores pending requests in process memory\n- keeps checkpoints only in that running process\n- is not restart-safe\n- is not shared across multiple app instances\n- caps session checkpoints by count per session\n- does not have a global session checkpoint memory cap or session checkpoint TTL"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:339:keywords","version":"v0","href":"/docs/sdk/production/framework-adapters#redis","title":"Redis","description":"Runtime Persistence Adapters","section":"Runtime Persistence Adapters","content":"Use this when paused runs must survive process restarts, deploys, or multiple app instances.\n\n```ts\nimport { createRedisFrameworkAdapter } from \"kortyx\";\n\nconst frameworkAdapter = createRedisFrameworkAdapter({\n url: process.env.KORTYX_REDIS_URL!,\n ttlMs: 15 * 60 * 1000,\n maxSessionCheckpoints: 50,\n});\n```\n\n```js\nimport { createRedisFrameworkAdapter } from \"kortyx\";\n\nconst frameworkAdapter = createRedisFrameworkAdapter({\n url: process.env.KORTYX_REDIS_URL,\n ttlMs: 15 * 60 * 1000,\n maxSessionCheckpoints: 50,\n});\n```\n\n- stores pending requests, internal checkpoints, and session checkpoints in Redis\n- supports resume after restart\n- works better when you have more than one app instance\n- uses the same Redis connection for all Kortyx runtime persistence key spaces\n- applies TTL to Redis-backed runtime state\n\n`maxSessionCheckpoints` controls how many user-facing session checkpoints are retained per session. The default is `50`."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:339:keywords","version":"v0","href":"/docs/sdk/production/framework-adapters#default-env-based-selection","title":"Default env-based selection","description":"Runtime Persistence Adapters","section":"Runtime Persistence Adapters","content":"This is the default behavior used by `createAgent(...)` when you do not pass `frameworkAdapter`.\n\n```ts\nimport { createFrameworkAdapterFromEnv } from \"kortyx\";\n\nconst frameworkAdapter = createFrameworkAdapterFromEnv();\n```\n\n```js\nimport { createFrameworkAdapterFromEnv } from \"kortyx\";\n\nconst frameworkAdapter = createFrameworkAdapterFromEnv();\n```\n\nResolution:\n\n- PostgreSQL if `KORTYX_POSTGRES_URL` exists (explicit schema setup required)\n- otherwise Redis if any of these exist: `KORTYX_REDIS_URL`, `REDIS_URL`, `KORTYX_FRAMEWORK_REDIS_URL`\n- otherwise in-memory\n\nTTL env variables:\n\n- `KORTYX_FRAMEWORK_TTL_MS`\n- `KORTYX_TTL_MS`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:339:keywords","version":"v0","href":"/docs/sdk/production/framework-adapters#practical-recommendation","title":"Practical recommendation","description":"Runtime Persistence Adapters","section":"Runtime Persistence Adapters","content":"- start with the default in local dev\n- use Redis in production if you rely on interrupt/resume, rollback, fork, or regenerate\n- use PostgreSQL for durable runtime history beyond Redis's TTL, with optional Redis caching\n- lower `maxSessionCheckpoints` for high-volume apps when users do not need deep rollback history\n- do not use this adapter as a replacement for your app database"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:339:keywords","version":"v0","href":"/docs/sdk/production/framework-adapters#what-to-read-next","title":"What to read next","description":"Runtime Persistence Adapters","section":"Runtime Persistence Adapters","content":"Go back to [Runtime Persistence](./01-persistence.md) if you want the high-level distinction between Kortyx runtime state and your app's business data."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:339:keywords","version":"v0","href":"/docs/sdk/production/framework-adapters#postgresql-durable-history","title":"PostgreSQL durable history","description":"Runtime Persistence Adapters","section":"Runtime Persistence Adapters","content":"$97"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:339:keywords","version":"v0","href":"/docs/sdk/production/framework-adapters#checkpoint-listing-and-redis-journal-expiry","title":"Checkpoint listing and Redis journal expiry","description":"Runtime Persistence Adapters","section":"Runtime Persistence Adapters","content":"$98"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","opentelemetry","observability","tracing","tokens","gen-ai"],"version":"v0","href":"/docs/sdk/production/observability","title":"OpenTelemetry","description":"Trace Kortyx sessions, workflow nodes, model calls, token usage, and prompt metadata with OpenTelemetry.","section":"Production","content":"$99"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:350:keywords","version":"v0","href":"/docs/sdk/production/observability#maintainer-usage-telemetry","title":"Maintainer usage telemetry","description":"OpenTelemetry","section":"OpenTelemetry","content":"$9a"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:350:keywords","version":"v0","href":"/docs/sdk/production/observability#install","title":"Install","description":"OpenTelemetry","section":"OpenTelemetry","content":"```bash tabs=\"otel-install\" tab=\"pnpm\"\npnpm add @kortyx/otel @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http\n```\n```bash tabs=\"otel-install\" tab=\"npm\"\nnpm install @kortyx/otel @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http\n```\n```bash tabs=\"otel-install\" tab=\"yarn\"\nyarn add @kortyx/otel @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http\n```\n```bash tabs=\"otel-install\" tab=\"bun\"\nbun add @kortyx/otel @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:350:keywords","version":"v0","href":"/docs/sdk/production/observability#configure-opentelemetry-on-the-server","title":"Configure OpenTelemetry on the server","description":"OpenTelemetry","section":"OpenTelemetry","content":"$9b"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:350:keywords","version":"v0","href":"/docs/sdk/production/observability#wire-kortyx-tracing","title":"Wire Kortyx tracing","description":"OpenTelemetry","section":"OpenTelemetry","content":"$9c"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:350:keywords","version":"v0","href":"/docs/sdk/production/observability#pass-identity-from-react","title":"Pass identity from React","description":"OpenTelemetry","section":"OpenTelemetry","content":"$9d"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:350:keywords","version":"v0","href":"/docs/sdk/production/observability#attach-prompt-metadata","title":"Attach prompt metadata","description":"OpenTelemetry","section":"OpenTelemetry","content":"$9e"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:350:keywords","version":"v0","href":"/docs/sdk/production/observability#customize-span-attributes","title":"Customize span attributes","description":"OpenTelemetry","section":"OpenTelemetry","content":"Use mapper hooks when your OpenTelemetry pipeline expects additional attributes.\n\n```ts tabs=\"otel-mapper\" tab=\"TypeScript\"\nconst trace = createOpenTelemetryTraceAdapter({\n mapPromptMetadata: (prompt) => ({\n \"app.prompt.metadata\": prompt.metadata,\n }),\n mapAttributes: ({ attributes }) => ({\n ...(attributes[\"kortyx.trace.metadata.tenantId\"]\n ? { \"app.tenant.id\": attributes[\"kortyx.trace.metadata.tenantId\"] }\n : {}),\n }),\n});\n```\n```js tabs=\"otel-mapper\" tab=\"JavaScript\"\nconst trace = createOpenTelemetryTraceAdapter({\n mapPromptMetadata: (prompt) => ({\n \"app.prompt.metadata\": prompt.metadata,\n }),\n mapAttributes: ({ attributes }) => ({\n ...(attributes[\"kortyx.trace.metadata.tenantId\"]\n ? { \"app.tenant.id\": attributes[\"kortyx.trace.metadata.tenantId\"] }\n : {}),\n }),\n});\n```\n\n> **Good to know:** Prompt text alone is not enough to link a generation to a managed prompt. Pass prompt name, version, type, and any prompt-store metadata in `telemetry.prompt`."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:350:keywords","version":"v0","href":"/docs/sdk/production/observability#capture-inputs-and-outputs","title":"Capture inputs and outputs","description":"OpenTelemetry","section":"OpenTelemetry","content":"Raw prompts and model outputs can contain sensitive data. Kortyx leaves content capture off by default.\n\nEnable it only when your app has an approved retention and redaction policy.\n\n```ts tabs=\"otel-content\" tab=\"TypeScript\"\ncreateOpenTelemetryTraceAdapter({\n captureContent: {\n input: true,\n output: true,\n },\n});\n```\n```js tabs=\"otel-content\" tab=\"JavaScript\"\ncreateOpenTelemetryTraceAdapter({\n captureContent: {\n input: true,\n output: true,\n },\n});\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:350:keywords","version":"v0","href":"/docs/sdk/production/observability#attach-tags-to-traces","title":"Attach tags to traces","description":"OpenTelemetry","section":"OpenTelemetry","content":"$9f"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:350:keywords","version":"v0","href":"/docs/sdk/production/observability#read-trace-ids-from-the-client","title":"Read trace ids from the client","description":"OpenTelemetry","section":"OpenTelemetry","content":"$a0"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:350:keywords","version":"v0","href":"/docs/sdk/production/observability#what-to-read-next","title":"What to read next","description":"OpenTelemetry","section":"OpenTelemetry","content":"- Read [Export To Langfuse](./04-langfuse.md) to use Langfuse as your tracing backend with the right attribute names.\n- Read [Runtime Context](../02-core-concepts/08-runtime-context.md) to pass request metadata into nodes.\n- Read [Runtime Persistence](./01-persistence.md) if your traced flows use interrupts and resume."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","langfuse","observability","tracing","opentelemetry","scores","feedback"],"version":"v0","href":"/docs/sdk/production/langfuse","title":"Export To Langfuse","description":"Export vendor-neutral Kortyx OpenTelemetry traces to Langfuse with the correct attribute names, tags, and trace ids surfaced on the React client.","section":"Production","content":"$a1"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:362:keywords","version":"v0","href":"/docs/sdk/production/langfuse#install","title":"Install","description":"Export To Langfuse","section":"Export To Langfuse","content":"```bash tabs=\"lf-install\" tab=\"pnpm\"\npnpm add @kortyx/otel @langfuse/otel @opentelemetry/api @opentelemetry/sdk-node\n```\n```bash tabs=\"lf-install\" tab=\"npm\"\nnpm install @kortyx/otel @langfuse/otel @opentelemetry/api @opentelemetry/sdk-node\n```\n```bash tabs=\"lf-install\" tab=\"yarn\"\nyarn add @kortyx/otel @langfuse/otel @opentelemetry/api @opentelemetry/sdk-node\n```\n```bash tabs=\"lf-install\" tab=\"bun\"\nbun add @kortyx/otel @langfuse/otel @opentelemetry/api @opentelemetry/sdk-node\n```\n\n`@kortyx/otel` is required regardless of backend because it produces the spans. `@langfuse/otel` provides the `LangfuseSpanProcessor` that exports them to Langfuse.\n\n> **Good to know:** Add `@langfuse/tracing` only when your app also needs Langfuse-specific manual observations or context propagation outside Kortyx. It is not required for the Kortyx adapter path below."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:362:keywords","version":"v0","href":"/docs/sdk/production/langfuse#configure-the-span-processor","title":"Configure the span processor","description":"Export To Langfuse","section":"Export To Langfuse","content":"$a2"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:362:keywords","version":"v0","href":"/docs/sdk/production/langfuse#nextjs-serverless-routes","title":"Next.js serverless routes","description":"Export To Langfuse","section":"Export To Langfuse","content":"$a3"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:362:keywords","version":"v0","href":"/docs/sdk/production/langfuse#translate-kortyx-attributes-to-langfuse-attributes","title":"Translate Kortyx attributes to Langfuse attributes","description":"Export To Langfuse","section":"Export To Langfuse","content":"$a4"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:362:keywords","version":"v0","href":"/docs/sdk/production/langfuse#optional-link-managed-prompts","title":"Optional: link managed prompts","description":"Export To Langfuse","section":"Export To Langfuse","content":"$a5"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:362:keywords","version":"v0","href":"/docs/sdk/production/langfuse#map-tags","title":"Map tags","description":"Export To Langfuse","section":"Export To Langfuse","content":"$a6"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:362:keywords","version":"v0","href":"/docs/sdk/production/langfuse#score-traces-from-the-client","title":"Score traces from the client","description":"Export To Langfuse","section":"Export To Langfuse","content":"$a7"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:362:keywords","version":"v0","href":"/docs/sdk/production/langfuse#what-to-read-next","title":"What to read next","description":"Export To Langfuse","section":"Export To Langfuse","content":"- Read [OpenTelemetry](./03-observability.md) for the base adapter setup, identity propagation, and prompt metadata.\n- Read [`useChat(...)`](../03-guides/04-render-streamed-chat.md) for how `ChatMsg.traceId` flows through the React client."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","package-overview","agent","runtime","core"],"version":"v0","href":"/docs/sdk/reference/package-overview","title":"Package Overview","description":"Map each Kortyx package to its purpose and practical usage in app code.","section":"Reference","content":"$a8"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:371:keywords","version":"v0","href":"/docs/sdk/reference/package-overview#recommended-import-strategy","title":"Recommended import strategy","description":"Package Overview","section":"Package Overview","content":"- Server/runtime app code: import from `kortyx`\n- Browser-safe low-level chunk helpers: import from `kortyx/browser`\n- React client state and chat helpers: import from `@kortyx/react`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:371:keywords","version":"v0","href":"/docs/sdk/reference/package-overview#package-map","title":"Package map","description":"Package Overview","section":"Package Overview","content":"$a9"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:371:keywords","version":"v0","href":"/docs/sdk/reference/package-overview#notes-about-current-implementation","title":"Notes about current implementation","description":"Package Overview","section":"Package Overview","content":"- Providers: install provider packages per need (for example `@kortyx/google`).\n- Business persistence: own it in your app; Kortyx only provides runtime/framework persistence.\n- React apps should start with `@kortyx/react` before reaching for raw browser stream reducers.\n- See [React Client](./06-react-client) for the recommended `useChat(...)` and `useStructuredStreams()` path.\n- Stream structured-data schema currently has a built-in `jobs` discriminated type; apps may still emit custom structured payloads."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","api-surface","exports","facade","typescript"],"version":"v0","href":"/docs/sdk/reference/api-surface","title":"Main API Surface (kortyx)","description":"Reference what the main kortyx package re-exports for application development.","section":"Reference","content":"$aa"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:375:keywords","version":"v0","href":"/docs/sdk/reference/api-surface#re-export-groups","title":"Re-export groups","description":"Main API Surface (kortyx)","section":"Main API Surface (kortyx)","content":""},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:375:keywords","version":"v0","href":"/docs/sdk/reference/api-surface#agent","title":"Agent","description":"Main API Surface (kortyx)","section":"Main API Surface (kortyx)","content":"```ts\nexport { createAgent } from \"@kortyx/agent\";\nexport type { CreateAgentArgs } from \"@kortyx/agent\";\n```\n```js\nexport { createAgent } from \"@kortyx/agent\";\n```\n\nCreated agent methods:\n\n- `agent.streamChat(messages, options?)` → `AsyncIterable`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:375:keywords","version":"v0","href":"/docs/sdk/reference/api-surface#conversation-evals","title":"Conversation evals","description":"Main API Surface (kortyx)","section":"Main API Surface (kortyx)","content":"$ab"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:375:keywords","version":"v0","href":"/docs/sdk/reference/api-surface#core-workflowstate-contracts","title":"Core workflow/state contracts","description":"Main API Surface (kortyx)","section":"Main API Surface (kortyx)","content":"```ts\nexport {\n defineWorkflow,\n loadWorkflow,\n validateWorkflow,\n} from \"@kortyx/core\";\n```\n```js\nexport {\n defineWorkflow,\n loadWorkflow,\n validateWorkflow,\n} from \"@kortyx/core\";\n```\n\nPlus types like `GraphState`, `NodeResult`, `WorkflowDefinition`, `WorkflowId`."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:375:keywords","version":"v0","href":"/docs/sdk/reference/api-surface#hooks","title":"Hooks","description":"Main API Surface (kortyx)","section":"Main API Surface (kortyx)","content":"$ac"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:375:keywords","version":"v0","href":"/docs/sdk/reference/api-surface#providers","title":"Providers","description":"Main API Surface (kortyx)","section":"Main API Surface (kortyx)","content":"```ts\nexport * from \"@kortyx/providers\";\n```\n```js\nexport * from \"@kortyx/providers\";\n```\n\nInstall provider implementation packages separately (for example `@kortyx/google`)."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:375:keywords","version":"v0","href":"/docs/sdk/reference/api-surface#runtime--registries--framework-adapters","title":"Runtime + registries + framework adapters","description":"Main API Surface (kortyx)","section":"Main API Surface (kortyx)","content":"```ts\nexport {\n clearRegisteredNodes,\n createFileWorkflowRegistry,\n createFrameworkAdapterFromEnv,\n createInMemoryFrameworkAdapter,\n createInMemoryWorkflowRegistry,\n createRedisFrameworkAdapter,\n getRegisteredNode,\n listRegisteredNodes,\n registerNode,\n} from \"@kortyx/runtime\";\n```\n```js\nexport {\n clearRegisteredNodes,\n createFileWorkflowRegistry,\n createFrameworkAdapterFromEnv,\n createInMemoryFrameworkAdapter,\n createInMemoryWorkflowRegistry,\n createRedisFrameworkAdapter,\n getRegisteredNode,\n listRegisteredNodes,\n registerNode,\n} from \"@kortyx/runtime\";\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:375:keywords","version":"v0","href":"/docs/sdk/reference/api-surface#stream-helpers","title":"Stream helpers","description":"Main API Surface (kortyx)","section":"Main API Surface (kortyx)","content":"```ts\nexport {\n collectBufferedStream,\n collectStream,\n consumeStream,\n createStreamResponse,\n readStream,\n summarizeStreamChunks,\n toSSE,\n} from \"@kortyx/stream\";\nexport type { BufferedStreamResult, StreamChunk } from \"@kortyx/stream\";\n```\n```js\nexport {\n collectBufferedStream,\n collectStream,\n consumeStream,\n createStreamResponse,\n readStream,\n summarizeStreamChunks,\n toSSE,\n} from \"@kortyx/stream\";\n```\n\n- `collectStream(...)`: raw chunk array\n- `collectBufferedStream(...)`: `{ chunks, text, structured }`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:375:keywords","version":"v0","href":"/docs/sdk/reference/api-surface#browser-entry","title":"Browser entry","description":"Main API Surface (kortyx)","section":"Main API Surface (kortyx)","content":"`packages/kortyx/src/browser.ts` exports browser-safe pieces:\n\n- `readStream`\n- `StreamChunk` type\n\nUse this entry for client-only bundles where you want to avoid Node-only runtime exports."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:375:keywords","version":"v0","href":"/docs/sdk/reference/api-surface#workflow-execution","title":"Workflow execution","description":"Main API Surface (kortyx)","section":"Main API Surface (kortyx)","content":"`agent.execute({ workflow, input, sessionId?, context? })` returns a typed `ExecutionResult` for a registered workflow with input/output schemas. `agent.resume({ workflow, resume, response })` continues a suspended execution, including nested children. Outcomes are `completed`, `suspended`, `cancelled`, or `failed`; invalid commands reject with `ExecutionRequestError`. See [Execute and Resume Workflows](../03-guides/07-workflow-execution.md)."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:375:keywords","version":"v0","href":"/docs/sdk/reference/api-surface#response-completion-and-pending-interrupts","title":"Response completion and pending interrupts","description":"Main API Surface (kortyx)","section":"Main API Surface (kortyx)","content":"$ad"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","streamchunk","sse","interrupt","transition","structured-data"],"version":"v0","href":"/docs/sdk/reference/stream-protocol","title":"Stream Chunk Protocol","description":"Consume typed stream chunks for text deltas, structured data, interrupts, transitions, and completion.","section":"Reference","content":"$ae"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:387:keywords","version":"v0","href":"/docs/sdk/reference/stream-protocol#core-chunk-types","title":"Core chunk types","description":"Stream Chunk Protocol","section":"Stream Chunk Protocol","content":"- `session`\n- `checkpoint`\n- `status`\n- `text-start`\n- `text-delta`\n- `text-end`\n- `tool-call-start`\n- `tool-call-result`\n- `tool-call-error`\n- `tool-result`\n- `message`\n- `structured-data`\n- `structured-data-invalidated`\n- `interrupt`\n- `transition`\n- `done`\n- `error`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:387:keywords","version":"v0","href":"/docs/sdk/reference/stream-protocol#typical-client-loop","title":"Typical client loop","description":"Stream Chunk Protocol","section":"Stream Chunk Protocol","content":"```ts\nimport { readStream, type StreamChunk } from \"kortyx/browser\";\n\nconst chunks: StreamChunk[] = [];\n\nfor await (const chunk of readStream(response.body)) {\n chunks.push(chunk);\n\n if (chunk.type === \"text-delta\") {\n // append to in-flight assistant text\n }\n\n if (chunk.type === \"interrupt\") {\n // render selection UI and resume with token/requestId\n }\n\n if (chunk.type === \"checkpoint\") {\n // map finalized assistant messages to checkpoint ids\n }\n\n if (chunk.type === \"done\") {\n break;\n }\n}\n```\n```js\nimport { readStream } from \"kortyx/browser\";\n\nconst chunks = [];\n\nfor await (const chunk of readStream(response.body)) {\n chunks.push(chunk);\n\n if (chunk.type === \"text-delta\") {\n // append to in-flight assistant text\n }\n\n if (chunk.type === \"interrupt\") {\n // render selection UI and resume with token/requestId\n }\n\n if (chunk.type === \"checkpoint\") {\n // map finalized assistant messages to checkpoint ids\n }\n\n if (chunk.type === \"done\") {\n break;\n }\n}\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:387:keywords","version":"v0","href":"/docs/sdk/reference/stream-protocol#structured-data","title":"Structured Data","description":"Stream Chunk Protocol","section":"Stream Chunk Protocol","content":"Simple mental model:\n\n- `text-*` is for text you show as text\n- `structured-data` is for objects you render as UI state\n- `tool-call-*` is for MCP/tool lifecycle updates when `toolExecution.emit` is enabled\n\nFor current `useReason` MCP tool execution, prefer the `tool-call-*` chunks. `tool-call-result` is the emitted lifecycle event for one concrete model-requested tool call and includes the provider/MCP `toolCallId`. `tool-result` is a legacy generic stream chunk shape retained in the public union for compatibility; it is not emitted by the MCP tool loop.\n\nExamples:\n\n- email drafts\n- project tables\n- growing result lists\n- progress panels\n- validation results\n- MCP search or action progress"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:387:keywords","version":"v0","href":"/docs/sdk/reference/stream-protocol#tool-call-chunks","title":"Tool Call Chunks","description":"Stream Chunk Protocol","section":"Stream Chunk Protocol","content":"When `useReason(...)` runs MCP tools with `toolExecution.emit: true`, Kortyx emits a small lifecycle channel beside assistant text.\n\nExample start chunk:\n\n```json\n{\n \"type\": \"tool-call-start\",\n \"node\": \"support\",\n \"opId\": \"op_123\",\n \"tool\": \"search_issues\",\n \"toolCallId\": \"call_1\",\n \"input\": {\n \"query\": \"open payment bugs\"\n }\n}\n```\n\nExample result chunk:\n\n```json\n{\n \"type\": \"tool-call-result\",\n \"node\": \"support\",\n \"opId\": \"op_123\",\n \"tool\": \"search_issues\",\n \"toolCallId\": \"call_1\",\n \"content\": \"[{\\\"title\\\":\\\"Payment failure\\\"}]\",\n \"structuredContent\": {\n \"results\": [{ \"title\": \"Payment failure\" }]\n }\n}\n```\n\nExample error chunk:\n\n```json\n{\n \"type\": \"tool-call-error\",\n \"node\": \"support\",\n \"opId\": \"op_123\",\n \"tool\": \"search_issues\",\n \"toolCallId\": \"call_1\",\n \"message\": \"MCP request timed out\"\n}\n```\n\nTool chunks are emitted only when the call opts in with `toolExecution.emit`. Tool results are still fed back to the model when emission is disabled."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:387:keywords","version":"v0","href":"/docs/sdk/reference/stream-protocol#structured-chunk-shape","title":"Structured chunk shape","description":"Stream Chunk Protocol","section":"Stream Chunk Protocol","content":"$af"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:387:keywords","version":"v0","href":"/docs/sdk/reference/stream-protocol#kind-values","title":"kind values","description":"Stream Chunk Protocol","section":"Stream Chunk Protocol","content":"- `set`: set one field at `path`\n- `append`: append `items` to an array at `path`\n- `text-delta`: append `delta` to a string at `path`\n- `final`: replace the whole object with `data` and mark the stream done\n\nThat is the full public mental model. Most clients should key by `streamId` and apply chunks in arrival order."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:387:keywords","version":"v0","href":"/docs/sdk/reference/stream-protocol#path-contract","title":"Path contract","description":"Stream Chunk Protocol","section":"Stream Chunk Protocol","content":"- `path` means a dot-separated location inside the object being built, such as `draft.body`\n- dotted paths are valid in raw `structured-data` chunks, manual `useStructuredData(...)` calls, and `useReason({ structured: { fields } })`\n- numeric path segments target array indexes, such as `sections.0.body`\n- `useReason({ structured: { fields } })` also accepts `*` as a single-segment pattern and emits concrete paths, such as `assessment_points.commercial_resilience.criteria_label`\n- one `streamId` represents one logical object; if multiple fields in that object stream incrementally, they all use the same `streamId`\n- use separate `streamId` values only when you are building separate objects"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:387:keywords","version":"v0","href":"/docs/sdk/reference/stream-protocol#reducer-guarantees","title":"Reducer guarantees","description":"Stream Chunk Protocol","section":"Stream Chunk Protocol","content":"`applyStructuredChunk(...)` is the canonical reducer for this protocol.\n\n- `set` writes the value at `path`\n- `append` appends to an existing array at `path`, or creates that array when the path is unset\n- `text-delta` appends to an existing string at `path`, or creates that string when the path is unset\n- `final` replaces any previously accumulated partial object completely and becomes the source of truth\n- no chunk is allowed after `final` for the same `streamId`\n\nRuntime enforcement:\n\n- invalid empty or malformed paths are rejected\n- impossible container-shape conflicts are rejected\n- `append` on a non-array target is rejected\n- `text-delta` on a non-string target is rejected\n- a chunk for a different `streamId` cannot be reduced into existing state for another stream"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:387:keywords","version":"v0","href":"/docs/sdk/reference/stream-protocol#checkpoint-chunks","title":"Checkpoint Chunks","description":"Stream Chunk Protocol","section":"Stream Chunk Protocol","content":"When session checkpoints are enabled through a `FrameworkAdapter`, Kortyx emits a checkpoint boundary before the public `done` chunk:\n\n```json\n{\n \"type\": \"checkpoint\",\n \"id\": \"cp-123\",\n \"sessionId\": \"session-123\",\n \"turnIndex\": 4,\n \"label\": \"before report generation\"\n}\n```\n\nClients should store the checkpoint id on the assistant message finalized by that stream. `@kortyx/react` does this automatically in `useChat(...)`.\n\nField meanings:\n\n- `id`: checkpoint id used by rollback and fork APIs\n- `sessionId`: active session id\n- `turnIndex`: zero-based session checkpoint position\n- `label`: optional app-facing label\n\n> **Good to know:** The checkpoint chunk is emitted before `done` so transports that stop reading on `done` still receive the rollback boundary first."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:387:keywords","version":"v0","href":"/docs/sdk/reference/stream-protocol#structured-data-invalidation","title":"Structured Data Invalidation","description":"Stream Chunk Protocol","section":"Stream Chunk Protocol","content":"$b0"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:387:keywords","version":"v0","href":"/docs/sdk/reference/stream-protocol#recommended-react-helper","title":"Recommended React helper","description":"Stream Chunk Protocol","section":"Stream Chunk Protocol","content":"$b1"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:387:keywords","version":"v0","href":"/docs/sdk/reference/stream-protocol#advanced-low-level-reducer","title":"Advanced: low-level reducer","description":"Stream Chunk Protocol","section":"Stream Chunk Protocol","content":"If you are outside React or want the raw protocol reducer, use `applyStructuredChunk(...)` from `kortyx/browser`.\n\n```ts\nimport {\n applyStructuredChunk,\n type StructuredDataChunk,\n type StructuredStreamState,\n} from \"kortyx/browser\";\n\nconst byStreamId: Record<\n string,\n StructuredStreamState>\n> = {};\n\nfunction onStructuredChunk(chunk: StructuredDataChunk) {\n byStreamId[chunk.streamId] = applyStructuredChunk(\n byStreamId[chunk.streamId],\n chunk,\n );\n}\n```\n```js\nimport { applyStructuredChunk } from \"kortyx/browser\";\n\nconst byStreamId = {};\n\nfunction onStructuredChunk(chunk) {\n byStreamId[chunk.streamId] = applyStructuredChunk(\n byStreamId[chunk.streamId],\n chunk,\n );\n}\n```\n\n`applyStructuredChunk(...)` returns:\n\n- `data`: current accumulated object\n- `status: \"streaming\" | \"done\"`\n- `streamId`\n- `dataType`\n\nIf you already have an array of structured chunks, you can also use `reduceStructuredChunks(...)`."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:387:keywords","version":"v0","href":"/docs/sdk/reference/stream-protocol#how-usereason-structured--uses-this-protocol","title":"How useReason({ structured }) uses this protocol","description":"Stream Chunk Protocol","section":"Stream Chunk Protocol","content":"When you call `useReason(...)` with `structured`, there are two main modes."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:387:keywords","version":"v0","href":"/docs/sdk/reference/stream-protocol#final-only-mode","title":"Final-only mode","description":"Stream Chunk Protocol","section":"Stream Chunk Protocol","content":"If you do not configure `structured.fields`, Kortyx emits one `structured-data` chunk with `kind: \"final\"` after the model output validates."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:387:keywords","version":"v0","href":"/docs/sdk/reference/stream-protocol#incremental-mode","title":"Incremental mode","description":"Stream Chunk Protocol","section":"Stream Chunk Protocol","content":"$b2"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:387:keywords","version":"v0","href":"/docs/sdk/reference/stream-protocol#consuming-text-and-structured-data-together","title":"Consuming text and structured data together","description":"Stream Chunk Protocol","section":"Stream Chunk Protocol","content":"Many clients render both channels at once: text for conversation and structured data for UI state.\n\n```ts\nimport {\n applyStructuredChunk,\n readStream,\n type StructuredStreamState,\n} from \"kortyx/browser\";\n\nlet text = \"\";\nconst structured: Record>> = {};\n\nfor await (const chunk of readStream(response.body)) {\n if (chunk.type === \"text-delta\") {\n text += chunk.delta;\n }\n\n if (chunk.type === \"structured-data\") {\n structured[chunk.streamId] = applyStructuredChunk(\n structured[chunk.streamId],\n chunk,\n );\n }\n}\n```\n```js\nimport { applyStructuredChunk, readStream } from \"kortyx/browser\";\n\nlet text = \"\";\nconst structured = {};\n\nfor await (const chunk of readStream(response.body)) {\n if (chunk.type === \"text-delta\") {\n text += chunk.delta;\n }\n\n if (chunk.type === \"structured-data\") {\n structured[chunk.streamId] = applyStructuredChunk(\n structured[chunk.streamId],\n chunk,\n );\n }\n}\n```"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:387:keywords","version":"v0","href":"/docs/sdk/reference/stream-protocol#notes","title":"Notes","description":"Stream Chunk Protocol","section":"Stream Chunk Protocol","content":"- `done` is terminal for a stream run\n- `error` may be followed by `done`\n- `session` helps clients persist conversation identity"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:387:keywords","version":"v0","href":"/docs/sdk/reference/stream-protocol#complete-a-response-before-execution-finishes","title":"Complete a response before execution finishes","description":"Stream Chunk Protocol","section":"Stream Chunk Protocol","content":"See [Background Continuation](../03-guides/08-background-continuation.md) for `completeResponse()`, independent execution lifetime, and discovering human requests through `agent.listInterrupts()` without Studio. A `done` chunk ends client delivery; it does not prove successful execution."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","provider-api","providers","providerinstance","providermodelref","modeloptions"],"version":"v0","href":"/docs/sdk/reference/provider-api","title":"Provider API","description":"Reference the normalized Kortyx provider contract, provider instances, model refs, call options, and result metadata.","section":"Reference","content":"$b3"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:406:keywords","version":"v0","href":"/docs/sdk/reference/provider-api#mental-model","title":"Mental model","description":"Provider API","section":"Provider API","content":"Kortyx providers are instance-based.\n\n- A provider selector is both a callable function and a provider instance.\n- Calling the selector returns a `ProviderModelRef`.\n- The model ref carries the exact provider instance that should resolve the model.\n- `useReason(...)` uses that instance directly.\n\nThat means Kortyx no longer depends on a global `\"providerId\" + \"modelId\"` lookup as the primary runtime path."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:406:keywords","version":"v0","href":"/docs/sdk/reference/provider-api#core-types","title":"Core types","description":"Provider API","section":"Provider API","content":"$b4"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:406:keywords","version":"v0","href":"/docs/sdk/reference/provider-api#normalized-call-options","title":"Normalized call options","description":"Provider API","section":"Provider API","content":"$b5"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:406:keywords","version":"v0","href":"/docs/sdk/reference/provider-api#normalized-invoke-results","title":"Normalized invoke results","description":"Provider API","section":"Provider API","content":"$b6"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:406:keywords","version":"v0","href":"/docs/sdk/reference/provider-api#normalized-internal-stream-parts","title":"Normalized internal stream parts","description":"Provider API","section":"Provider API","content":"$b7"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:406:keywords","version":"v0","href":"/docs/sdk/reference/provider-api#registry-helpers","title":"Registry helpers","description":"Provider API","section":"Provider API","content":"`@kortyx/providers` still exports registry helpers:\n\n- `createProviderRegistry()`\n- `registerProvider(provider)`\n- `resetProviders()`\n- `getProvider(providerId)`\n- `hasProvider(providerId)`\n- `getInitializedProviders()`\n- `getAvailableModels(providerId)`\n\nUse the registry when you are writing tooling, tests, or low-level runtime code. In normal app code, prefer provider selectors and model refs from provider packages."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:406:keywords","version":"v0","href":"/docs/sdk/reference/provider-api#error-behavior","title":"Error behavior","description":"Provider API","section":"Provider API","content":"Registry helpers fail fast:\n\n- `getProvider(providerId)` throws if the provider is not registered\n- provider packages should throw when the selected model id is unknown\n- provider packages should throw clear configuration errors when required credentials are missing\n\nThat keeps misconfiguration visible early instead of producing vague runtime failures later."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","node-resolution","reference","registerNode","dynamic-import"],"version":"v0","href":"/docs/sdk/reference/node-resolution","title":"Node Resolution","description":"Reference: how Kortyx resolves node run handlers from function refs, module paths, and registry keys.","section":"Reference","content":"$b8"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:414:keywords","version":"v0","href":"/docs/sdk/reference/node-resolution#1-direct-function-typescript-workflows","title":"1. Direct function (TypeScript workflows)","description":"Node Resolution","section":"Node Resolution","content":"```ts\nnodes: {\n chat: { run: chatNode, params: {} }\n}\n```\n\nThis is the cleanest option when your workflows are TypeScript modules."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:414:keywords","version":"v0","href":"/docs/sdk/reference/node-resolution#2-module-path-string-yamljson-or-ts","title":"2. Module path string (YAML/JSON or TS)","description":"Node Resolution","section":"Node Resolution","content":"```yaml\nnodes:\n chat:\n run: ../nodes/chat.node.ts#chatNode\n```\n\nResolution behavior (from `resolveNodeHandler`):\n\n- Path-like strings are dynamically imported\n- If `#exportName` is present, that named export must be a function\n- If absent, runtime tries:\n 1. `default` export as function\n 2. exactly one named function export"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:414:keywords","version":"v0","href":"/docs/sdk/reference/node-resolution#3-registry-key-string","title":"3. Registry key string","description":"Node Resolution","section":"Node Resolution","content":"If the `run` value is not path-like, runtime treats it as a registry id.\n\n```ts\nimport { registerNode } from \"kortyx\";\n\nregisterNode(\"chatNode\", chatNode);\n\n// workflow node:\n// { run: \"chatNode\" }\n```\n\nHelper APIs:\n\n- `registerNode`\n- `getRegisteredNode`\n- `listRegisteredNodes`\n- `clearRegisteredNodes`"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","react","useChat","useStructuredStreams","createRouteChatTransport"],"version":"v0","href":"/docs/sdk/reference/react-client","title":"React Client (@kortyx/react)","description":"Reference the React client helpers for streamed chat, structured streams, transport, and storage.","section":"Reference","content":"$b9"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:418:keywords","version":"v0","href":"/docs/sdk/reference/react-client#recommended-path-usechat","title":"Recommended path: useChat(...)","description":"React Client (@kortyx/react)","section":"React Client (@kortyx/react)","content":"For most React apps, `useChat(...)` should be the first stop.\n\n```ts\nimport { createRouteChatTransport, useChat } from \"@kortyx/react\";\n\nexport function ChatPage() {\n const chat = useChat({\n transport: createRouteChatTransport({\n endpoint: \"/api/chat\",\n }),\n });\n\n return ;\n}\n```\n```js\nimport { createRouteChatTransport, useChat } from \"@kortyx/react\";\n\nexport function ChatPage() {\n const chat = useChat({\n transport: createRouteChatTransport({\n endpoint: \"/api/chat\",\n }),\n });\n\n return ;\n}\n```\n\n`useChat(...)` owns:\n\n- finalized `messages`\n- live `streamContentPieces`\n- `isStreaming`\n- `error` and `clearError()`\n- `abort()` and `canAbort`\n- interrupt resume handling\n- structured stream accumulation\n- default browser storage unless you override it"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:418:keywords","version":"v0","href":"/docs/sdk/reference/react-client#messages-and-active-streams","title":"Messages and active streams","description":"React Client (@kortyx/react)","section":"React Client (@kortyx/react)","content":"`messages` contains finalized chat history only. While the assistant is still streaming, render the active assistant response from `streamContentPieces`.\n\nThis separation is intentional:\n\n- persisted history does not change on every token\n- active text, structured data, interrupts, and errors can render before finalization\n- finalized assistant messages can keep their debug chunks after the stream ends\n\nWhen a stream finishes, `useChat(...)` builds the assistant message and appends it to `messages`."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:418:keywords","version":"v0","href":"/docs/sdk/reference/react-client#request-context-and-message-preparation","title":"Request context and message preparation","description":"React Client (@kortyx/react)","section":"React Client (@kortyx/react)","content":"$ba"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:418:keywords","version":"v0","href":"/docs/sdk/reference/react-client#runtime-controls","title":"Runtime controls","description":"React Client (@kortyx/react)","section":"React Client (@kortyx/react)","content":"`useChat(...)` exposes controls for common chat lifecycle cases:\n\n- `abort()` stops the active stream when the transport supports `AbortSignal`\n- `canAbort` is true while a stream is active\n- `error` stores the latest transport or stream error\n- `clearError()` clears that error state\n- `clearMessages()` clears visible/persisted messages and keeps the current session\n- `resetSession()` clears the current session id\n- `resetChat()` clears messages, active stream state, errors, and session id\n\n`clearChat()` remains available as a compatibility alias for resetting the chat.\n\n> **Good to know:** `clearMessages()` is the right choice for a \"clear visible history\" button. Use `resetChat()` when you want a new local chat session."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:418:keywords","version":"v0","href":"/docs/sdk/reference/react-client#interrupt-responses","title":"Interrupt responses","description":"React Client (@kortyx/react)","section":"React Client (@kortyx/react)","content":"For low-level control, call `respondToHumanInput(...)` with the resume token and request id.\n\nFor UI components rendering a `HumanInputPiece`, use `respondToInterrupt(...)` so the component can pass back the same interrupt piece it received.\n\n`respondToInterrupt(piece, { selected })` handles choice and multi-choice interrupts. `respondToInterrupt(piece, { text })` handles text interrupts.\n\n> **Good to know:** When the live stream or latest assistant message contains a text interrupt, `send(text)` resumes that request automatically. Historical interrupts are not reused after a response or later assistant message.\n\nWhen the server sets interrupt routing metadata, `HumanInputPiece` preserves `schemaId`, `schemaVersion`, `interruptId`, and public `meta`.\nSwitch on `piece.schemaId` for custom controls such as job pickers, file uploaders, or address autocompletes."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:418:keywords","version":"v0","href":"/docs/sdk/reference/react-client#abort-support","title":"Abort support","description":"React Client (@kortyx/react)","section":"React Client (@kortyx/react)","content":"Route transports created with `createRouteChatTransport(...)` receive the `AbortSignal` from `useChat(...)` and pass it to `fetch`.\n\nCustom transports should forward `context.signal` to their own request layer if they want `abort()` to stop the active stream."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:418:keywords","version":"v0","href":"/docs/sdk/reference/react-client#usechat-options","title":"useChat(...) options","description":"React Client (@kortyx/react)","section":"React Client (@kortyx/react)","content":"```ts\nimport type {\n ChatMsg,\n ChatStorage,\n ChatTransport,\n OutgoingChatMessage,\n ToHumanInputPiece,\n} from \"@kortyx/react\";\n\ntype UseChatOptions = {\n transport: ChatTransport>;\n storage?: ChatStorage;\n createId?: () => string;\n context?: Record;\n prepareContextMessages?: (args: {\n messages: ChatMsg[];\n sessionId: string;\n workflowId: string;\n reason: \"send\" | \"resume\";\n context: Record;\n }) => OutgoingChatMessage[] | Promise;\n toHumanInputPiece?: ToHumanInputPiece;\n};\n```\n\nNotes:\n\n- `transport` is required\n- `storage` defaults to browser storage\n- `createId` is optional when you want custom message/piece ids\n- `context` defaults to `{}`\n- `prepareContextMessages` defaults to the finalized message history when `includeHistory` is true\n- `toHumanInputPiece` lets advanced clients customize interrupt projection before pieces enter\n `streamContentPieces` and finalized assistant messages"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:418:keywords","version":"v0","href":"/docs/sdk/reference/react-client#transport-helpers","title":"Transport helpers","description":"React Client (@kortyx/react)","section":"React Client (@kortyx/react)","content":""},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:418:keywords","version":"v0","href":"/docs/sdk/reference/react-client#api-route--sse-transport","title":"API route / SSE transport","description":"React Client (@kortyx/react)","section":"React Client (@kortyx/react)","content":"```ts\nimport { createRouteChatTransport } from \"@kortyx/react\";\n\nconst transport = createRouteChatTransport({\n endpoint: \"/api/chat\",\n createBody: ({ sessionId, workflowId, messages, context }) => ({\n sessionId,\n workflowId,\n messages,\n context,\n }),\n});\n```\n```js\nimport { createRouteChatTransport } from \"@kortyx/react\";\n\nconst transport = createRouteChatTransport({\n endpoint: \"/api/chat\",\n createBody: ({ sessionId, workflowId, messages, context }) => ({\n sessionId,\n workflowId,\n messages,\n context,\n }),\n});\n```\n\nUse this when your backend returns SSE chunks from a route handler. `createBody` is optional; without it the route body is `{ sessionId, workflowId, messages, context }`."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:418:keywords","version":"v0","href":"/docs/sdk/reference/react-client#custom-transport","title":"Custom transport","description":"React Client (@kortyx/react)","section":"React Client (@kortyx/react)","content":"If your app does not use an SSE route, provide your own transport.\n\n```ts\nimport { createChatTransport } from \"@kortyx/react\";\n\nconst transport = createChatTransport({\n stream: ({ sessionId, workflowId, messages }) =>\n runChat({\n sessionId,\n workflowId,\n messages,\n }),\n});\n```\n```js\nimport { createChatTransport } from \"@kortyx/react\";\n\nconst transport = createChatTransport({\n stream: ({ sessionId, workflowId, messages }) =>\n runChat({\n sessionId,\n workflowId,\n messages,\n }),\n});\n```\n\nUse this when you already have an app-specific function that returns chunks."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:418:keywords","version":"v0","href":"/docs/sdk/reference/react-client#storage","title":"Storage","description":"React Client (@kortyx/react)","section":"React Client (@kortyx/react)","content":"$bb"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:418:keywords","version":"v0","href":"/docs/sdk/reference/react-client#custom-react-ui-usestructuredstreams","title":"Custom React UI: useStructuredStreams()","description":"React Client (@kortyx/react)","section":"React Client (@kortyx/react)","content":"$bc"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:418:keywords","version":"v0","href":"/docs/sdk/reference/react-client#when-to-drop-to-kortyxbrowser","title":"When to drop to kortyx/browser","description":"React Client (@kortyx/react)","section":"React Client (@kortyx/react)","content":"Use `kortyx/browser` when:\n\n- you are not using React\n- you want raw `readStream(...)` / `consumeStream(...)`\n- you want the low-level `applyStructuredChunk(...)` reducer directly\n\n```ts\nimport { applyStructuredChunk, readStream } from \"kortyx/browser\";\n```\n\nThat path is lower-level by design. React apps should usually start with `@kortyx/react` and only drop down when they need custom wiring."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","troubleshooting","debugging","errors"],"version":"v0","href":"/docs/sdk/troubleshooting","title":"Troubleshooting","description":"Diagnose common setup and runtime issues quickly with focused checks and linked fixes.","section":"Troubleshooting","content":"# Troubleshooting\n\nUse this section to quickly isolate setup and runtime issues.\n\n## Fast checks\n\n1. Confirm provider credentials are available in runtime env.\n2. Verify package imports match the current API surface.\n3. Ensure your framework adapter configuration matches your deployment model.\n4. Validate stream handling and chunk parsing in your transport layer.\n\n## Related docs\n\n- [Installation](../01-getting-started/01-installation.md)\n- [Google Generative AI Provider](../04-kortyx-providers/01-google-generative-ai-provider.md)\n- [Runtime Persistence Adapters](../04-production/02-framework-adapters.md)\n- [Stream Protocol](../05-reference/03-stream-protocol.md)\n\n> **Good to know:** Prefer reproducing issues with the smallest runnable workflow first, then layer back production integrations one by one.\n"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:432:keywords","version":"v0","href":"/docs/sdk/troubleshooting#fast-checks","title":"Fast checks","description":"Troubleshooting","section":"Troubleshooting","content":"1. Confirm provider credentials are available in runtime env.\n2. Verify package imports match the current API surface.\n3. Ensure your framework adapter configuration matches your deployment model.\n4. Validate stream handling and chunk parsing in your transport layer."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:432:keywords","version":"v0","href":"/docs/sdk/troubleshooting#related-docs","title":"Related docs","description":"Troubleshooting","section":"Troubleshooting","content":"- [Installation](../01-getting-started/01-installation.md)\n- [Google Generative AI Provider](../04-kortyx-providers/01-google-generative-ai-provider.md)\n- [Runtime Persistence Adapters](../04-production/02-framework-adapters.md)\n- [Stream Protocol](../05-reference/03-stream-protocol.md)\n\n> **Good to know:** Prefer reproducing issues with the smallest runnable workflow first, then layer back production integrations one by one."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":["kortyx","migration","versions","upgrade"],"version":"v0","href":"/docs/sdk/migration","title":"Migration & Versions","description":"Versioning and migration guidance for evolving Kortyx apps safely across releases.","section":"Migration & Versions","content":"# Migration & Versions\n\nThis section tracks upgrade guidance and behavior changes across versions.\n\n## Current policy\n\n- Within the same SDK major version, docs are updated in place.\n- The latest SDK docs use `/docs/sdk/...`. Previous majors remain available at `/docs/sdk/vN/...`.\n- Studio has its own documentation and version history at `/docs/studio`.\n- New major versions should include dedicated upgrade notes and breaking-change guidance.\n\n## What to check before upgrading\n\n1. API changes across agent/runtime/hooks/providers packages.\n2. Provider setup and model initialization expectations.\n3. Streaming and interrupt/resume behavior in your app path.\n\n## Related docs\n\n- [API Surface](../05-reference/02-api-surface.md)\n- [Provider API](../05-reference/04-provider-api.md)\n- [Interrupts and Resume](../03-guides/02-interrupts-and-resume.md)\n\n> **Good to know:** When your app is production-critical, validate upgrade changes in a staging workflow before rollout.\n"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:435:keywords","version":"v0","href":"/docs/sdk/migration#current-policy","title":"Current policy","description":"Migration & Versions","section":"Migration & Versions","content":"- Within the same SDK major version, docs are updated in place.\n- The latest SDK docs use `/docs/sdk/...`. Previous majors remain available at `/docs/sdk/vN/...`.\n- Studio has its own documentation and version history at `/docs/studio`.\n- New major versions should include dedicated upgrade notes and breaking-change guidance."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:435:keywords","version":"v0","href":"/docs/sdk/migration#what-to-check-before-upgrading","title":"What to check before upgrading","description":"Migration & Versions","section":"Migration & Versions","content":"1. API changes across agent/runtime/hooks/providers packages.\n2. Provider setup and model initialization expectations.\n3. Streaming and interrupt/resume behavior in your app path."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:435:keywords","version":"v0","href":"/docs/sdk/migration#related-docs","title":"Related docs","description":"Migration & Versions","section":"Migration & Versions","content":"- [API Surface](../05-reference/02-api-surface.md)\n- [Provider API](../05-reference/04-provider-api.md)\n- [Interrupts and Resume](../03-guides/02-interrupts-and-resume.md)\n\n> **Good to know:** When your app is production-critical, validate upgrade changes in a staging workflow before rollout."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":["kortyx","studio","observability","telemetry","self-hosted","runs"],"version":"v0","href":"/docs/studio/overview","title":"Kortyx Studio Overview","description":"Understand what Kortyx Studio observes, how it relates to the SDK runtime, and which setup path to follow.","section":"Getting Started","content":"$bd"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:439:keywords","version":"v0","href":"/docs/studio/overview#what-the-system-contains","title":"What the system contains","description":"Kortyx Studio Overview","section":"Kortyx Studio Overview","content":"| Component | What it does | Where it runs |\n| --- | --- | --- |\n| Kortyx SDK application | Executes your workflows and emits telemetry | Your application server |\n| Telemetry API | Authenticates and stores Studio telemetry | Local Docker or your infrastructure |\n| Kortyx Studio | Reads telemetry and presents the interface | Local Docker or your infrastructure |\n| PostgreSQL | Stores runs, sessions, projections, and key verifiers | Local Docker or managed PostgreSQL |\n\nThe SDK sends telemetry with a Project-scoped write key. Studio reads it with a separate server-side read key. Human access is protected independently."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:439:keywords","version":"v0","href":"/docs/studio/overview#choose-your-path","title":"Choose your path","description":"Kortyx Studio Overview","section":"Kortyx Studio Overview","content":""},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:439:keywords","version":"v0","href":"/docs/studio/overview#develop-on-your-machine","title":"Develop on your machine","description":"Kortyx Studio Overview","section":"Kortyx Studio Overview","content":"Use the CLI-managed stack when you want to inspect an SDK project locally:\n\n1. [Run Studio Locally](./02-run-locally.md)\n2. [Connect Your Project](./03-connect-project.md)\n3. Keep the [CLI Commands](./04-cli-commands.md) nearby\n\nThe CLI starts Studio, the telemetry API, and PostgreSQL with Docker Compose. It also generates the local credentials and waits until the complete stack is healthy."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:439:keywords","version":"v0","href":"/docs/studio/overview#deploy-for-a-team","title":"Deploy for a team","description":"Kortyx Studio Overview","section":"Kortyx Studio Overview","content":"Use an operator-managed deployment when Studio must run beyond one developer's laptop:\n\n1. Read [Credentials and Secrets](./05-credentials-secrets.md)\n2. Follow [Deploy on a Server](./06-deploy-server.md)\n3. Plan backup and upgrades with [Operations and Troubleshooting](./07-operations.md)\n4. Map your platform to the [Configuration Reference](./08-configuration-reference.md)\n\nThe portable deployment uses the same images with externally managed PostgreSQL, secrets, HTTPS, and access control."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:439:keywords","version":"v0","href":"/docs/studio/overview#what-studio-captures","title":"What Studio captures","description":"Kortyx Studio Overview","section":"Kortyx Studio Overview","content":"Structural telemetry can show:\n\n- sessions, runs, status, and duration;\n- workflow and node transitions;\n- model/provider calls and generation timing;\n- token usage and reported cost;\n- interrupt creation, resolution, and expiry; and\n- the trace and raw event story for an execution.\n\nPrompt, input, and output content is excluded by default. The SDK application decides whether that content may be sent. See [Connect Your Project](./03-connect-project.md#choose-what-content-studio-may-store)."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:439:keywords","version":"v0","href":"/docs/studio/overview#child-workflow-visibility","title":"Child workflow visibility","description":"Kortyx Studio Overview","section":"Kortyx Studio Overview","content":"$be"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:439:keywords","version":"v0","href":"/docs/studio/overview#evaluate-workflow-behavior","title":"Evaluate workflow behavior","description":"Kortyx Studio Overview","section":"Kortyx Studio Overview","content":"$bf"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":["kortyx","studio","docker","local","quickstart","telemetry"],"version":"v0","href":"/docs/studio/run-locally","title":"Run Kortyx Studio Locally","description":"Start Kortyx Studio with Docker, connect a Kortyx application, and inspect its first run.","section":"Getting Started","content":"$c0"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:447:keywords","version":"v0","href":"/docs/studio/run-locally#before-you-start","title":"Before you start","description":"Run Kortyx Studio Locally","section":"Run Kortyx Studio Locally","content":"You need:\n\n- Node.js 22 or newer;\n- npm 10 or newer;\n- Docker Engine with Docker Compose v2, or a current Docker Desktop; and\n- free local ports `6300` for Studio and `6400` for the telemetry API.\n\nLinux containers on AMD64 and ARM64 are supported. Docker Desktop on Apple Silicon selects the ARM64 images automatically."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:447:keywords","version":"v0","href":"/docs/studio/run-locally#1-start-studio","title":"1. Start Studio","description":"Run Kortyx Studio Locally","section":"Run Kortyx Studio Locally","content":"$c1"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:447:keywords","version":"v0","href":"/docs/studio/run-locally#2-connect-your-application","title":"2. Connect your application","description":"Run Kortyx Studio Locally","section":"Run Kortyx Studio Locally","content":"$c2"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:447:keywords","version":"v0","href":"/docs/studio/run-locally#3-publish-the-workflow-catalog","title":"3. Publish the workflow catalog","description":"Run Kortyx Studio Locally","section":"Run Kortyx Studio Locally","content":"Publish the workflows declared by your agent before sending traffic:\n\n```bash\nnpx kortyx topology push --entry src/lib/agent.ts\n```\n\nUse the module that exports your configured agent, workflows array, or workflow\ndefinitions. The command reads the `KORTYX_TELEMETRY_*` variables from your\nproject environment and publishes deterministic topology to Studio.\n\nOpen **Workflows** to confirm the catalog. A workflow can appear there before it\nhas run; publishing topology does not create a synthetic run. Runtime topology\nregistration remains a fallback when real traffic executes a workflow, but\n`topology push` is the canonical pre-traffic path."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:447:keywords","version":"v0","href":"/docs/studio/run-locally#4-see-your-first-real-run","title":"4. See your first real run","description":"Run Kortyx Studio Locally","section":"Run Kortyx Studio Locally","content":"1. Restart your application so it reads the new environment values.\n2. Trigger any request that executes the Kortyx agent.\n3. Open [http://localhost:6300](http://localhost:6300).\n4. Sign in with the username and password printed by the CLI.\n5. Open **Runs** and select the new run.\n\nYou are connected when the real run appears. Studio can now explain the\nworkflow path, model calls, timing, token usage, interrupts, and captured\npayloads available for that execution."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:447:keywords","version":"v0","href":"/docs/studio/run-locally#if-the-run-does-not-appear","title":"If the run does not appear","description":"Run Kortyx Studio Locally","section":"Run Kortyx Studio Locally","content":"Check the installation before changing application code:\n\n```bash\nnpx kortyx studio status\nnpx kortyx studio logs --no-follow\n```\n\nThen verify:\n\n- the API URL and key are available to the server process that creates the agent;\n- the workflow catalog was published from the correct agent entry module;\n- the application was restarted after its environment changed;\n- the telemetry API is reachable from that server process; and\n- the Runs time filter includes the current time.\n\nAn `Invalid telemetry API key` error means the application or Studio is presenting a key that does not match the verifier in this installation. Print the current values with `npx kortyx studio credentials`; if you intentionally rotate them, update every affected server process."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:447:keywords","version":"v0","href":"/docs/studio/run-locally#next-steps","title":"Next steps","description":"Run Kortyx Studio Locally","section":"Run Kortyx Studio Locally","content":"- Learn the local lifecycle commands in [CLI Commands](./04-cli-commands.md).\n- Decide whether payload content may be captured in [Connect Your Project](./03-connect-project.md#choose-what-content-studio-may-store).\n- Read [Operations and Troubleshooting](./07-operations.md) before backup, reset, or upgrade.\n- Use [Deploy on a Server](./06-deploy-server.md) when Studio must be reachable beyond your machine."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":["kortyx","studio","telemetry","project","sdk","content-capture"],"version":"v0","href":"/docs/studio/connect-project","title":"Connect Your Kortyx Project","description":"Configure server-side Kortyx telemetry, stable service identity, and deliberate content capture for Studio.","section":"Getting Started","content":"$c3"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:455:keywords","version":"v0","href":"/docs/studio/connect-project#install-the-adapter","title":"Install the adapter","description":"Connect Your Kortyx Project","section":"Connect Your Kortyx Project","content":"```bash tabs=\"connect-studio-install\" tab=\"pnpm\"\npnpm add @kortyx/telemetry\n```\n\n```bash tabs=\"connect-studio-install\" tab=\"npm\"\nnpm install @kortyx/telemetry\n```\n\n```bash tabs=\"connect-studio-install\" tab=\"yarn\"\nyarn add @kortyx/telemetry\n```\n\n```bash tabs=\"connect-studio-install\" tab=\"bun\"\nbun add @kortyx/telemetry\n```"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:455:keywords","version":"v0","href":"/docs/studio/connect-project#configure-the-server-environment","title":"Configure the server environment","description":"Connect Your Kortyx Project","section":"Connect Your Kortyx Project","content":"```bash file=\".env.local\"\nKORTYX_TELEMETRY_API_URL=http://localhost:6400\nKORTYX_TELEMETRY_API_KEY=ktyx_live_...\nKORTYX_TELEMETRY_ENVIRONMENT=development\nKORTYX_TELEMETRY_SERVICE_NAME=my-agent\n```\n\n| Variable | Meaning |\n| --- | --- |\n| `KORTYX_TELEMETRY_API_URL` | Reachable base URL of the telemetry API |\n| `KORTYX_TELEMETRY_API_KEY` | Project-scoped `telemetry:write` key |\n| `KORTYX_TELEMETRY_ENVIRONMENT` | Informational label such as `development` or `production` |\n| `KORTYX_TELEMETRY_SERVICE_NAME` | Stable name for this SDK application or agent service |\n\nDo not prefix these variables with `NEXT_PUBLIC_`, `VITE_`, or another mechanism that exposes them to client code."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:455:keywords","version":"v0","href":"/docs/studio/connect-project#attach-telemetry-to-the-agent","title":"Attach telemetry to the agent","description":"Connect Your Kortyx Project","section":"Connect Your Kortyx Project","content":"$c4"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:455:keywords","version":"v0","href":"/docs/studio/connect-project#collect-response-feedback","title":"Collect response feedback","description":"Connect Your Kortyx Project","section":"Connect Your Kortyx Project","content":"$c5"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:455:keywords","version":"v0","href":"/docs/studio/connect-project#publish-the-declared-workflow-catalog","title":"Publish the declared workflow catalog","description":"Connect Your Kortyx Project","section":"Connect Your Kortyx Project","content":"$c6"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:455:keywords","version":"v0","href":"/docs/studio/connect-project#choose-what-content-studio-may-store","title":"Choose what content Studio may store","description":"Connect Your Kortyx Project","section":"Connect Your Kortyx Project","content":"$c7"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:455:keywords","version":"v0","href":"/docs/studio/connect-project#interrupt-behavior-in-studio","title":"Interrupt behavior in Studio","description":"Connect Your Kortyx Project","section":"Connect Your Kortyx Project","content":"Studio observes interrupt lifecycle events; your application still presents the request and sends the resume response.\n\n- Pending interrupt state expires after 15 minutes by default.\n- Configure the application TTL with `KORTYX_FRAMEWORK_TTL_MS`, or with `frameworkAdapter.ttlMs`.\n- Studio derives **Expired** from the durable `expiresAt` timestamp.\n- A late response cannot resume the expired run, although application fallback may handle it as a new run.\n- A dynamic picker may correctly report zero embedded options because the client resolves choices from its own data source.\n\nFor runtime behavior and replay-safe side effects, read [Interrupts and Resume](../../sdk/v0/03-guides/02-interrupts-and-resume.md)."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:455:keywords","version":"v0","href":"/docs/studio/connect-project#verify-the-connection","title":"Verify the connection","description":"Connect Your Kortyx Project","section":"Connect Your Kortyx Project","content":"Open **Workflows** after the topology push, then trigger one agent request and\nopen **Runs** in Studio. If nothing arrives, use this order:\n\n1. Confirm the application server has all four environment variables.\n2. Confirm it restarted after configuration changed.\n3. Confirm `topology push` used the entry module and service name for this app.\n4. Check the Studio stack with `npx kortyx studio status`.\n5. Inspect recent logs with `npx kortyx studio logs --no-follow`.\n6. Confirm the Studio time filter includes the event.\n\nFor remote deployments, also verify network reachability from the application server to the telemetry API and confirm the supplied key has `telemetry:write` scope."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":["kortyx","studio","cli","commands","docker","credentials"],"version":"v0","href":"/docs/studio/cli-commands","title":"Kortyx Studio CLI Commands","description":"Manage local Studio, inspect workflow runs, and execute conversation eval suites through project connections.","section":"Reference","content":"$c8"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:464:keywords","version":"v0","href":"/docs/studio/cli-commands#everyday-commands","title":"Everyday commands","description":"Kortyx Studio CLI Commands","section":"Kortyx Studio CLI Commands","content":"| Command | Purpose | Preserves data? |\n| --- | --- | --- |\n| `npx kortyx studio start` | Create or update the stack and wait until healthy | Yes |\n| `npx kortyx studio status` | Show container state and local endpoints | Yes |\n| `npx kortyx studio logs` | Follow API, Studio, bootstrap, and database logs | Yes |\n| `npx kortyx studio logs --no-follow` | Print recent logs and return | Yes |\n| `npx kortyx studio credentials` | Print the current local connection details | Yes |\n| `npx kortyx studio credentials --format dotenv --service-name my-agent` | Print copyable server-side SDK variables | Yes |\n| `npx kortyx studio restart` | Recreate the stack and wait until healthy | Yes |\n| `npx kortyx studio stop` | Stop the containers | Yes |\n\n> **Good to know:** Start is idempotent. Running it again is the normal way to bring back a stopped installation or apply a changed image tag or port configuration."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:464:keywords","version":"v0","href":"/docs/studio/cli-commands#start-options","title":"Start options","description":"Kortyx Studio CLI Commands","section":"Kortyx Studio CLI Commands","content":"Choose different host ports:\n\n```bash\nnpx kortyx studio start \\\n --studio-port 7300 \\\n --api-port 7400\n```\n\nPin both Studio images to an immutable published release:\n\n```bash\nnpx kortyx studio start --image-tag vX.Y.Z\n```\n\nStudio image tags use the Studio release version, not the CLI package version.\nCLI and Studio minor versions may differ while remaining compatible through the\nstable Studio API protocol. `studio status` reports the configured image and the\nnegotiated protocol; `studio inspect` rejects only an incompatible protocol major\nor a response that violates the advertised protocol.\n\nUse an alternate state directory or local username:\n\n```bash\nnpx kortyx studio start \\\n --home /path/to/private/studio-state \\\n --username operator\n```\n\nThe same `--home` value must be supplied to later commands. Alternatively, set `KORTYX_STUDIO_HOME` for the shell or automation that manages that installation."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:464:keywords","version":"v0","href":"/docs/studio/cli-commands#print-or-rotate-local-credentials","title":"Print or rotate local credentials","description":"Kortyx Studio CLI Commands","section":"Kortyx Studio CLI Commands","content":"Print the current browser and SDK connection values:\n\n```bash\nnpx kortyx studio credentials\n```\n\nPrint only the server-side SDK variables for an application:\n\n```bash\nnpx kortyx studio credentials --format dotenv --service-name my-agent\n```\n\nThis format intentionally omits the browser password and local state path, but\nit still includes a secret telemetry write key. Keep the output server-side.\n\nReplace the browser password and both application API-key secrets:\n\n```bash\nnpx kortyx studio credentials --rotate\n```\n\nRotation updates the local environment atomically, applies new key verifiers, recreates affected services, and attempts rollback if the application fails. The previous telemetry key becomes invalid, so update and restart every local SDK producer.\n\nThe database password and API-key pepper are deliberately preserved."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:464:keywords","version":"v0","href":"/docs/studio/cli-commands#generate-credentials-for-remote-deployment","title":"Generate credentials for remote deployment","description":"Kortyx Studio CLI Commands","section":"Kortyx Studio CLI Commands","content":"```bash\nnpx kortyx studio credentials --generate\n```\n\nThis produces an unpersisted credential set without creating local Studio state. Store it immediately in the deployment's secret manager. It cannot be printed again later.\n\nSee [Credentials and Secrets](./05-credentials-secrets.md) before using generated values on a server."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:464:keywords","version":"v0","href":"/docs/studio/cli-commands#publish-a-workflow-catalog","title":"Publish a workflow catalog","description":"Kortyx Studio CLI Commands","section":"Kortyx Studio CLI Commands","content":"Catalog publication is a top-level Kortyx command rather than a Studio\nlifecycle command:\n\n```bash\nnpx kortyx topology push --entry src/lib/agent.ts\n```\n\nIt publishes declared workflow topology before traffic arrives without\ncreating runs. Use `--dry-run` to inspect the projection locally. See [Connect\nYour Project](./03-connect-project.md#publish-the-declared-workflow-catalog) for\nthe complete connection flow.\n\n> **Good to know: Publication runs in your application's deployment environment.** The CLI imports the application entry module and calls the telemetry API with its write key. Include it in CI/CD for each application release. For a private API, run from an allowed network, for example in a one-off ECS task using the application's release image; the GitHub runner can launch that task without reaching the private API itself. Deploying Studio does not run this command for your applications."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:464:keywords","version":"v0","href":"/docs/studio/cli-commands#reset-local-data","title":"Reset local data","description":"Kortyx Studio CLI Commands","section":"Kortyx Studio CLI Commands","content":"```bash\nnpx kortyx studio reset --confirm\n```\n\n> **Destructive command:** Reset permanently deletes the local PostgreSQL volume. It preserves generated credentials, so the next `studio start` creates an empty database and bootstraps those keys again.\n\nBack up any telemetry you need before resetting. See [Operations and Troubleshooting](./07-operations.md#back-up-a-local-installation)."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:464:keywords","version":"v0","href":"/docs/studio/cli-commands#read-only-run-and-session-debugging","title":"Read-only run and session debugging","description":"Kortyx Studio CLI Commands","section":"Kortyx Studio CLI Commands","content":"$c9"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:464:keywords","version":"v0","href":"/docs/studio/cli-commands#connect-local-staging-or-another-project","title":"Connect local, staging, or another project","description":"Kortyx Studio CLI Commands","section":"Kortyx Studio CLI Commands","content":"$ca"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:464:keywords","version":"v0","href":"/docs/studio/cli-commands#local-cli-versus-remote-operation","title":"Local CLI versus remote operation","description":"Kortyx Studio CLI Commands","section":"Kortyx Studio CLI Commands","content":"Lifecycle commands manage the local Compose stack; read commands query the\nStudio HTTP API. Read commands cannot execute/resume runs, approve interrupts,\npublish topology, or administer remote projects. The CLI does not SSH into\nservers, edit a remote database, or replace your cloud platform's deployment tools.\n\nFor remote environments, use [Deploy on a Server](./06-deploy-server.md), inject secrets through the platform, and operate the same container contract through your infrastructure tooling."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:464:keywords","version":"v0","href":"/docs/studio/cli-commands#eval-suites-and-post-deployment-ci","title":"Eval suites and post-deployment CI","description":"Kortyx Studio CLI Commands","section":"Kortyx Studio CLI Commands","content":"The CLI uses the same Studio API, project scopes, application targets, worker,\nand PostgreSQL records as the browser. It does not import your agent or obtain\nan end-user token. The application handles its test actor in `createEvals.setup`.\n\nConfigure the [consumer endpoint and Studio targets](./11-evals.md) first.\nYour connection key needs `studio:read` for discovery and result inspection, plus\n`eval:run` for starting and cancelling. The SDK telemetry write key cannot run evals.\nThe application's eval service key stays on the Studio API server."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:464:keywords","version":"v0","href":"/docs/studio/cli-commands#diagnose-deployment-wiring","title":"Diagnose deployment wiring","description":"Kortyx Studio CLI Commands","section":"Kortyx Studio CLI Commands","content":"$cb"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:464:keywords","version":"v0","href":"/docs/studio/cli-commands#run-locally-without-studio","title":"Run locally without Studio","description":"Kortyx Studio CLI Commands","section":"Kortyx Studio CLI Commands","content":"$cc"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:464:keywords","version":"v0","href":"/docs/studio/cli-commands#discover-and-run","title":"Discover and run","description":"Kortyx Studio CLI Commands","section":"Kortyx Studio CLI Commands","content":"$cd"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:464:keywords","version":"v0","href":"/docs/studio/cli-commands#inspect-and-cancel","title":"Inspect and cancel","description":"Kortyx Studio CLI Commands","section":"Kortyx Studio CLI Commands","content":"$ce"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:464:keywords","version":"v0","href":"/docs/studio/cli-commands#optional-post-deployment-github-actions-step","title":"Optional post-deployment GitHub Actions step","description":"Kortyx Studio CLI Commands","section":"Kortyx Studio CLI Commands","content":"Install and pin `kortyx` or `@kortyx/cli` in the application's lockfile. After your\nexisting deployment and readiness check, enqueue a suite:\n\n```yaml\n- name: Start conversation evals\n continue-on-error: true\n env:\n KORTYX_DEPLOY_EVAL_KEY: ${{ secrets.KORTYX_DEPLOY_EVAL_KEY }}\n run: >-\n pnpm exec kortyx studio evals runs start product-ambiguity\n --target catalog --environment staging\n --api-url https://api.example.com\n --api-key-env KORTYX_DEPLOY_EVAL_KEY\n --json\n```\n\nThis step returns after enqueueing and does not wait for grades or gate the\ndeployment. Inspect results in Studio or with `runs get`. Ensure the CI runner can\nreach the Studio API, and the Studio API can reach the deployed consumer endpoint.\nUse a key scoped to the intended project with `studio:read` and `eval:run`.\nEach invocation creates a new run; your deployment workflow owns trigger frequency."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":["kortyx","studio","credentials","secrets","api-key","rotation"],"version":"v0","href":"/docs/studio/credentials-secrets","title":"Kortyx Studio Credentials and Secrets","description":"Understand Studio credential roles, safe storage, local rotation, and remote deployment practices.","section":"Deployment","content":"$cf"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:480:keywords","version":"v0","href":"/docs/studio/credentials-secrets#credential-roles","title":"Credential roles","description":"Kortyx Studio Credentials and Secrets","section":"Kortyx Studio Credentials and Secrets","content":"$d0"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:480:keywords","version":"v0","href":"/docs/studio/credentials-secrets#local-credentials","title":"Local credentials","description":"Kortyx Studio Credentials and Secrets","section":"Kortyx Studio Credentials and Secrets","content":"The CLI creates and stores local values privately under `~/.kortyx/studio`.\n\nPrint the current connection details:\n\n```bash\nnpx kortyx studio credentials\n```\n\nRotate the browser password, telemetry key secret, and Studio key secret:\n\n```bash\nnpx kortyx studio credentials --rotate\n```\n\nThe CLI updates the private environment atomically, applies the new key verifiers, recreates the affected services, and attempts to restore the previous values if the application fails.\n\nRotation invalidates the previous telemetry key immediately. Update and restart every server-side SDK producer using that key. PostgreSQL credentials and the API-key pepper are deliberately preserved."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:480:keywords","version":"v0","href":"/docs/studio/credentials-secrets#generate-credentials-for-a-deployment","title":"Generate credentials for a deployment","description":"Kortyx Studio Credentials and Secrets","section":"Kortyx Studio Credentials and Secrets","content":"```bash\nnpx kortyx studio credentials --generate\n```\n\nThis command prints a fresh deployment credential set without writing local state. Store the output immediately; it cannot be retrieved later.\n\nUse the secret facility appropriate to the target:\n\n| Platform | Recommended destination |\n| --- | --- |\n| AWS | Secrets Manager or an approved equivalent |\n| Google Cloud | Secret Manager |\n| Kubernetes | External secret integration or a tightly controlled Secret |\n| Controlled single server | A root/operator-readable environment file outside the repository |\n\nDo not put secret values in Terraform source, generated manifests, image layers, CI logs, tickets, chat, or screenshots."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:480:keywords","version":"v0","href":"/docs/studio/credentials-secrets#remote-key-rotation","title":"Remote key rotation","description":"Kortyx Studio Credentials and Secrets","section":"Kortyx Studio Credentials and Secrets","content":"The initial deployment contract replaces an API-key secret while retaining its key ID:\n\n1. Preserve the prefix through the final underscore, such as `ktyx_live__`.\n2. Generate a new random secret of at least 32 bytes and append it.\n3. Update the consumer's secret-manager value.\n4. Run `kortyx-studio-db bootstrap` with the new complete key.\n5. Roll or restart the affected consumer.\n6. Verify that the new key works and the previous key receives `401 Unauthorized`.\n\nReusing the key ID replaces its verifier. For the Studio read key, run bootstrap before recreating Studio. For one telemetry write key shared by multiple applications, coordinate a maintenance window; overlapping remote keys are not yet managed through an Admin API.\n\n> **Do not rotate the pepper during routine key rotation.** A new pepper makes every existing API-key verifier unusable."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:480:keywords","version":"v0","href":"/docs/studio/credentials-secrets#backup-and-incident-response","title":"Backup and incident response","description":"Kortyx Studio Credentials and Secrets","section":"Kortyx Studio Credentials and Secrets","content":"Back up PostgreSQL and deployment secret references as one recovery set. A database backup without its matching pepper cannot verify the existing API keys.\n\nIf a raw API key is exposed:\n\n1. replace its secret under the same key ID;\n2. rerun bootstrap;\n3. roll the affected consumer;\n4. verify the new key; and\n5. verify the exposed value now receives `401 Unauthorized`.\n\nTreat captured telemetry backups according to the sensitivity of any input or output content your producers chose to export."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":["kortyx","studio","deploy","docker","postgres","self-hosted"],"version":"v0","href":"/docs/studio/deploy-server","title":"Deploy Kortyx Studio on a Server","description":"Deploy Kortyx Studio with external PostgreSQL, injected secrets, pinned images, HTTPS, and a portable container contract.","section":"Deployment","content":"$d1"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:486:keywords","version":"v0","href":"/docs/studio/deploy-server#prerequisites","title":"Prerequisites","description":"Deploy Kortyx Studio on a Server","section":"Deploy Kortyx Studio on a Server","content":"- Docker Engine with Docker Compose v2, or an equivalent container platform;\n- PostgreSQL reachable from the telemetry API and database job;\n- a pinned Kortyx Studio release tag; and\n- HTTPS plus an access boundary before remote exposure.\n\nRead [Credentials and Secrets](./05-credentials-secrets.md) before provisioning values."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:486:keywords","version":"v0","href":"/docs/studio/deploy-server#1-prepare-the-deployment","title":"1. Prepare the deployment","description":"Deploy Kortyx Studio on a Server","section":"Deploy Kortyx Studio on a Server","content":"$d2"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:486:keywords","version":"v0","href":"/docs/studio/deploy-server#2-start-the-services","title":"2. Start the services","description":"Deploy Kortyx Studio on a Server","section":"Deploy Kortyx Studio on a Server","content":"```bash\ndocker compose \\\n --env-file \"$deployment_dir/deployment.env\" \\\n -f \"$compose_file\" \\\n up -d --wait --wait-timeout 180\n```\n\nCompose runs the retryable migration/bootstrap job before starting the API and Studio.\n\nThe default host bindings are loopback-only:\n\n- Studio: `http://127.0.0.1:6300`\n- Telemetry API: `http://127.0.0.1:6400`\n\nKeep loopback bindings when a reverse proxy runs on the same server. On a container platform, route service traffic directly to container ports `6300` and `6400` rather than assigning both services unrestricted public addresses."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:486:keywords","version":"v0","href":"/docs/studio/deploy-server#3-verify-health","title":"3. Verify health","description":"Deploy Kortyx Studio on a Server","section":"Deploy Kortyx Studio on a Server","content":"```bash\ncurl --fail http://127.0.0.1:6400/ready\n\ndocker compose \\\n --env-file \"$deployment_dir/deployment.env\" \\\n -f \"$compose_file\" \\\n ps\n\ndocker compose \\\n --env-file \"$deployment_dir/deployment.env\" \\\n -f \"$compose_file\" \\\n logs --tail 200\n```\n\nA Studio health response below `500` is healthy; `401` is expected when Basic Auth protects the route."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:486:keywords","version":"v0","href":"/docs/studio/deploy-server#4-put-access-controls-in-front","title":"4. Put access controls in front","description":"Deploy Kortyx Studio on a Server","section":"Deploy Kortyx Studio on a Server","content":"Before users or SDK producers connect:\n\n- terminate HTTPS at a trusted load balancer or reverse proxy;\n- keep PostgreSQL private;\n- restrict the telemetry API to application-server networks when possible;\n- keep Studio and the API on a private service network; and\n- use Basic Auth only over HTTPS, ideally behind a VPN or identity-aware proxy.\n\n> **Basic Auth is not encryption.** It is only acceptable over HTTPS. Never expose a remote Studio instance over plain HTTP."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:486:keywords","version":"v0","href":"/docs/studio/deploy-server#5-connect-sdk-producers","title":"5. Connect SDK producers","description":"Deploy Kortyx Studio on a Server","section":"Deploy Kortyx Studio on a Server","content":"$d3"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:486:keywords","version":"v0","href":"/docs/studio/deploy-server#upgrade","title":"Upgrade","description":"Deploy Kortyx Studio on a Server","section":"Deploy Kortyx Studio on a Server","content":"1. Back up PostgreSQL and deployment secrets.\n2. Change `KORTYX_STUDIO_IMAGE_TAG` to the next supported release.\n3. Pull the images.\n4. Run the database job and wait for success.\n5. Recreate the API and Studio services.\n\n```bash\ndocker compose --env-file \"$deployment_dir/deployment.env\" -f \"$compose_file\" pull\ndocker compose --env-file \"$deployment_dir/deployment.env\" -f \"$compose_file\" run --rm db-init\ndocker compose --env-file \"$deployment_dir/deployment.env\" -f \"$compose_file\" up -d --wait api studio\n```\n\nDatabase downgrade is unsupported. Restore a backup made for the older release if its schema is incompatible."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:486:keywords","version":"v0","href":"/docs/studio/deploy-server#translate-the-contract-to-a-cloud-platform","title":"Translate the contract to a cloud platform","description":"Deploy Kortyx Studio on a Server","section":"Deploy Kortyx Studio on a Server","content":"Infrastructure tooling should represent the same components rather than run Compose verbatim:\n\n1. one retryable job using the API image and `kortyx-studio-db migrate-and-bootstrap`;\n2. one long-running telemetry API service with one or more replicas;\n3. one long-running Studio service with one or more replicas; and\n4. one externally managed PostgreSQL database.\n\nReference secret-manager entries from workload definitions. Do not serialize raw secret values into Terraform state, generated manifests, or CDK source.\n\nUse the [Configuration Reference](./08-configuration-reference.md) to map ports, variables, health checks, startup order, and service responsibilities to your platform.\n\nFor production availability, use at least two replicas and follow the [High Availability contract](./10-high-availability.md).\n\nFor a complete private AWS implementation, continue with [Deploy on AWS with CDK](./09-deploy-aws-cdk.md)."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":["kortyx","studio","operations","backup","restore","upgrade","troubleshooting"],"version":"v0","href":"/docs/studio/operations","title":"Operate and Troubleshoot Kortyx Studio","description":"Back up, restore, upgrade, reset, secure, and troubleshoot a self-hosted Kortyx Studio installation.","section":"Operations","content":"$d4"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:495:keywords","version":"v0","href":"/docs/studio/operations#know-the-durable-state","title":"Know the durable state","description":"Operate and Troubleshoot Kortyx Studio","section":"Operate and Troubleshoot Kortyx Studio","content":"The default local installation lives under `~/.kortyx/studio`:\n\n| Item | Purpose |\n| --- | --- |\n| `.env` | Generated credentials and secrets |\n| `config.json` | Selected image tag, ports, username, and Compose project |\n| `compose.yml` | Generated local stack definition |\n| Docker PostgreSQL volume | Runs, sessions, telemetry, projections, eval suite snapshots/results, and key verifier records |\n\nProtect the directory and database backups as secrets. A useful recovery set contains both the database and the matching credentials, especially the API-key pepper."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:495:keywords","version":"v0","href":"/docs/studio/operations#back-up-a-local-installation","title":"Back up a local installation","description":"Operate and Troubleshoot Kortyx Studio","section":"Operate and Troubleshoot Kortyx Studio","content":"```bash\nstudio_home=\"${KORTYX_STUDIO_HOME:-$HOME/.kortyx/studio}\"\nbackup_dir=\"kortyx-studio-backup-$(date +%Y%m%d-%H%M%S)\"\n\nmkdir -m 700 \"$backup_dir\"\ncp -p \"$studio_home/.env\" \"$studio_home/config.json\" \"$backup_dir/\"\n\ndocker compose \\\n --env-file \"$studio_home/.env\" \\\n -f \"$studio_home/compose.yml\" \\\n exec -T postgres \\\n pg_dump -U kortyx -d kortyx -Fc > \"$backup_dir/database.dump\"\n```\n\nThe backup may contain Studio credentials, telemetry keys, and captured application content. Store and retain it accordingly."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:495:keywords","version":"v0","href":"/docs/studio/operations#restore","title":"Restore","description":"Operate and Troubleshoot Kortyx Studio","section":"Operate and Troubleshoot Kortyx Studio","content":"Restore into the same Studio version first. Stop telemetry producers, or otherwise prevent writes during the restore:\n\n```bash\nstudio_home=\"${KORTYX_STUDIO_HOME:-$HOME/.kortyx/studio}\"\nbackup_dir=/path/to/kortyx-studio-backup\n\nnpx kortyx studio stop\ncp -p \"$backup_dir/.env\" \"$backup_dir/config.json\" \"$studio_home/\"\n\ndocker compose \\\n --env-file \"$studio_home/.env\" \\\n -f \"$studio_home/compose.yml\" \\\n up -d postgres\n\ndocker compose \\\n --env-file \"$studio_home/.env\" \\\n -f \"$studio_home/compose.yml\" \\\n exec -T postgres \\\n pg_restore --clean --if-exists --no-owner -U kortyx -d kortyx \\\n < \"$backup_dir/database.dump\"\n\nnpx kortyx studio start\n```\n\nTest restoration against a non-production copy before relying on the procedure. After verifying the restored installation, upgrade normally."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:495:keywords","version":"v0","href":"/docs/studio/operations#upgrade","title":"Upgrade","description":"Operate and Troubleshoot Kortyx Studio","section":"Operate and Troubleshoot Kortyx Studio","content":"Back up first, then pin the intended published release:\n\n```bash\nnpx kortyx studio start --image-tag vX.Y.Z\n```\n\nStart pulls the selected images and applies forward database migrations before the API starts. Existing data and credentials remain in the Studio home.\n\nDatabase downgrade is unsupported. Do not point an older Studio image at a database migrated by a newer release; restore the matching older backup instead."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:495:keywords","version":"v0","href":"/docs/studio/operations#reset-local-data","title":"Reset local data","description":"Operate and Troubleshoot Kortyx Studio","section":"Operate and Troubleshoot Kortyx Studio","content":"```bash\nnpx kortyx studio reset --confirm\n```\n\n> **Permanent deletion:** Reset removes the local PostgreSQL volume. Generated credentials remain, and the next start creates an empty database using those credentials."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:495:keywords","version":"v0","href":"/docs/studio/operations#security-checklist","title":"Security checklist","description":"Operate and Troubleshoot Kortyx Studio","section":"Operate and Troubleshoot Kortyx Studio","content":"- [ ] Studio and the telemetry API are private or protected by an explicit network boundary.\n- [ ] Remote human access uses HTTPS.\n- [ ] PostgreSQL is not exposed publicly.\n- [ ] SDK write keys exist only in application-server secret storage.\n- [ ] The Studio read key exists only in the Studio server environment.\n- [ ] Input/output content capture matches your data policy.\n- [ ] Backups include the database and corresponding secret references.\n- [ ] Image versions are pinned for managed deployments."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:495:keywords","version":"v0","href":"/docs/studio/operations#troubleshoot-in-order","title":"Troubleshoot in order","description":"Operate and Troubleshoot Kortyx Studio","section":"Operate and Troubleshoot Kortyx Studio","content":"Start with service state and recent logs:\n\n```bash\nnpx kortyx studio status\nnpx kortyx studio logs --no-follow\n```\n\n| Symptom | What to check |\n| --- | --- |\n| Docker cannot be reached | Start Docker, then verify `docker version` and `docker compose version` |\n| A port is occupied | Restart with `--studio-port ` and `--api-port ` |\n| Images cannot be pulled | Verify access to GHCR and retry |\n| Browser sign-in is rejected | Print current values with `npx kortyx studio credentials` |\n| No runs appear | Verify the server environment, API reachability, application restart, and Studio time filter |\n| `Invalid telemetry API key` | Confirm the SDK uses the current Project write key and matching installation |\n| Studio reports an invalid service key | Confirm Studio and bootstrap use the same Studio read key and pepper |\n| Migration fails | Preserve the database, collect logs, and restore the pre-upgrade backup if needed |"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:495:keywords","version":"v0","href":"/docs/studio/operations#eval-discovery-execution-and-judging","title":"Eval discovery, execution and judging","description":"Operate and Troubleshoot Kortyx Studio","section":"Operate and Troubleshoot Kortyx Studio","content":"$d5"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:495:keywords","version":"v0","href":"/docs/studio/operations#after-credential-rotation","title":"After credential rotation","description":"Operate and Troubleshoot Kortyx Studio","section":"Operate and Troubleshoot Kortyx Studio","content":"If the SDK receives `401 Unauthorized`, it is probably still using the previous telemetry key. Print the new credentials, update the server-only application environment, and restart the producer.\n\nIf Studio itself reports an invalid service key, confirm the bootstrap job applied the same `KORTYX_STUDIO_API_KEY` that the Studio server presents. A restored database without its matching pepper cannot verify existing keys."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:495:keywords","version":"v0","href":"/docs/studio/operations#interrupt-looks-pending-after-its-deadline","title":"Interrupt looks pending after its deadline","description":"Operate and Troubleshoot Kortyx Studio","section":"Operate and Troubleshoot Kortyx Studio","content":"Studio derives expiry from `expiresAt`; the SDK does not need an in-process timer to emit an expiry event. Refresh or live updates should project an overdue pending interrupt as **Expired**.\n\nA late user response cannot resume the expired run. Your application's fallback may still process that input as a new run, which is expected and should remain distinct in Studio.\n\nReport security vulnerabilities privately through the repository's [security policy](https://github.com/kortyx-io/kortyx/security/policy), not a public issue."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":["kortyx","studio","configuration","environment","containers","reference"],"version":"v0","href":"/docs/studio/configuration-reference","title":"Kortyx Studio Configuration Reference","description":"Reference the deployment components, environment variables, startup order, health checks, and supported self-hosted boundary.","section":"Reference","content":"$d6"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:506:keywords","version":"v0","href":"/docs/studio/configuration-reference#components","title":"Components","description":"Kortyx Studio Configuration Reference","section":"Kortyx Studio Configuration Reference","content":"| Component | Image or dependency | Responsibility |\n| --- | --- | --- |\n| Studio | `ghcr.io/kortyx-io/kortyx-studio:` | Human observability interface on port `6300` |\n| Telemetry API | `ghcr.io/kortyx-io/kortyx-api:` | Authenticated ingestion and Studio reads on port `6400` |\n| Database job | API image running `kortyx-studio-db` | Idempotent schema migration and single-Project bootstrap |\n| PostgreSQL | PostgreSQL 17 is release-tested | Durable telemetry, projections, Project scope, and key verifiers |\n\nUse the same immutable version tag for both Kortyx images. Published images support Linux AMD64 and ARM64."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:506:keywords","version":"v0","href":"/docs/studio/configuration-reference#startup-and-upgrade-order","title":"Startup and upgrade order","description":"Kortyx Studio Configuration Reference","section":"Kortyx Studio Configuration Reference","content":"Run the database operation as a one-shot job before starting or updating the API:\n\n```bash\nkortyx-studio-db migrate-and-bootstrap\n```\n\nIndividual operations are available when an orchestrator separates them:\n\n```bash\nkortyx-studio-db migrate\nkortyx-studio-db bootstrap\n```\n\nMigration and bootstrap are idempotent, so a failed job can be retried. After it succeeds, start the telemetry API and then Studio.\n\nMigrations hold a PostgreSQL advisory lock across the ordered migration set, so accidentally concurrent jobs serialize. Still schedule one database job per deployment rather than running migrations in every application replica.\n\nDo not start newer application images against an older schema. Database downgrade is unsupported."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:506:keywords","version":"v0","href":"/docs/studio/configuration-reference#telemetry-api-and-database-job-variables","title":"Telemetry API and database job variables","description":"Kortyx Studio Configuration Reference","section":"Kortyx Studio Configuration Reference","content":"$d7"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:506:keywords","version":"v0","href":"/docs/studio/configuration-reference#optional-studio-judge-variables","title":"Optional Studio judge variables","description":"Kortyx Studio Configuration Reference","section":"Kortyx Studio Configuration Reference","content":"$d8"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:506:keywords","version":"v0","href":"/docs/studio/configuration-reference#database-bootstrap-variables","title":"Database bootstrap variables","description":"Kortyx Studio Configuration Reference","section":"Kortyx Studio Configuration Reference","content":"$d9"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:506:keywords","version":"v0","href":"/docs/studio/configuration-reference#studio-variables","title":"Studio variables","description":"Kortyx Studio Configuration Reference","section":"Kortyx Studio Configuration Reference","content":"| Variable | Required | Purpose |\n| --- | --- | --- |\n| `KORTYX_API_URL` | Yes | Internal telemetry API URL, such as `http://api:6400` |\n| `KORTYX_STUDIO_API_KEY` | Yes | Server-only Studio operator credential |\n| `KORTYX_STUDIO_AUTH_MODE` | Yes remotely | Use `basic` for the current self-hosted release |\n| `KORTYX_STUDIO_BASIC_AUTH_USERNAME` | With Basic Auth | Human sign-in username |\n| `KORTYX_STUDIO_BASIC_AUTH_PASSWORD` | With Basic Auth | Human sign-in password |\n| `PORT` | No | Container port; default is `6300` |\n\nThe Studio operator key is consumed by the Next.js server and must never be sent to the browser. The telemetry write key belongs only in server-side SDK producers.\n\nThe same Studio key can execute suites when it also has `eval:run`. This does\nnot require a new user-authentication mechanism. See [Evals](./11-evals.md) for\nconsumer endpoint registration, target-file mounts and execution behavior."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:506:keywords","version":"v0","href":"/docs/studio/configuration-reference#consumer-application-and-cli-configuration","title":"Consumer application and CLI configuration","description":"Kortyx Studio Configuration Reference","section":"Kortyx Studio Configuration Reference","content":""},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:506:keywords","version":"v0","href":"/docs/studio/configuration-reference#maintainer-usage-telemetry","title":"Maintainer usage telemetry","description":"Kortyx Studio Configuration Reference","section":"Kortyx Studio Configuration Reference","content":"$da"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:506:keywords","version":"v0","href":"/docs/studio/configuration-reference#application-eval-settings","title":"Application eval settings","description":"Kortyx Studio Configuration Reference","section":"Kortyx Studio Configuration Reference","content":"$db"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:506:keywords","version":"v0","href":"/docs/studio/configuration-reference#applying-eval-configuration-changes","title":"Applying eval configuration changes","description":"Kortyx Studio Configuration Reference","section":"Kortyx Studio Configuration Reference","content":"$dc"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:506:keywords","version":"v0","href":"/docs/studio/configuration-reference#health-and-shutdown","title":"Health and shutdown","description":"Kortyx Studio Configuration Reference","section":"Kortyx Studio Configuration Reference","content":"| Service | Check |\n| --- | --- |\n| Telemetry API liveness | `GET /live` on port `6400`; `/health` is a compatibility alias |\n| Telemetry API readiness | `GET /ready` on port `6400`; checks traffic acceptance and PostgreSQL |\n| Studio | Any HTTP response below `500` on port `6300`; `401` is healthy with Basic Auth |\n| PostgreSQL | Provider or orchestrator database readiness check |\n\nOn `SIGTERM`, the API stops readiness, drains HTTP for up to 25 seconds, then closes PostgreSQL connections. Set the termination grace period above 25 seconds. PostgreSQL is the durable state boundary; API and Studio containers do not need persistent filesystems."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:506:keywords","version":"v0","href":"/docs/studio/configuration-reference#platform-mapping","title":"Platform mapping","description":"Kortyx Studio Configuration Reference","section":"Kortyx Studio Configuration Reference","content":"| Requirement | AWS | Google Cloud | Kubernetes |\n| --- | --- | --- | --- |\n| Containers | ECS/Fargate or EKS | Cloud Run or GKE | Deployments |\n| PostgreSQL | RDS PostgreSQL | Cloud SQL for PostgreSQL | Managed/external PostgreSQL |\n| Secrets | Secrets Manager | Secret Manager | Secret or ExternalSecret |\n| Database operation | One-off ECS task | Cloud Run Job | Job or Helm hook |\n| HTTPS and human access | ALB plus VPN/OIDC proxy | Load Balancer plus IAP | Ingress plus auth proxy |\n\nCloud-provider SDKs are not required by Studio. The platform injects the documented variables and schedules the documented components.\n\nThe `@kortyx/aws-cdk` package implements a convenient single-task AWS mapping. Use lower-level ECS/EKS resources and the [High Availability contract](./10-high-availability.md) when you need multiple replicas."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:506:keywords","version":"v0","href":"/docs/studio/configuration-reference#supported-boundary","title":"Supported boundary","description":"Kortyx Studio Configuration Reference","section":"Kortyx Studio Configuration Reference","content":""},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:506:keywords","version":"v0","href":"/docs/studio/configuration-reference#supported-now","title":"Supported now","description":"Kortyx Studio Configuration Reference","section":"Kortyx Studio Configuration Reference","content":"- one Project per deployment;\n- one or more API and Studio replicas, with two recommended for production;\n- external PostgreSQL;\n- version-pinned AMD64 or ARM64 images;\n- externally injected secrets;\n- retryable, serialized migration/bootstrap jobs;\n- cross-replica live invalidations through PostgreSQL;\n- rolling deployments for releases explicitly marked `rolling`; and\n- HTTPS and access control supplied at the deployment edge."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:506:keywords","version":"v0","href":"/docs/studio/configuration-reference#not-yet-claimed","title":"Not yet claimed","description":"Kortyx Studio Configuration Reference","section":"Kortyx Studio Configuration Reference","content":"- database high availability or multi-region recovery;\n- unlimited horizontal scaling or published capacity limits;\n- built-in OIDC, users, RBAC, RLS, or audit logs;\n- multiple Project administration;\n- overlapping remote credential rotation through an Admin API; or\n- official Terraform or Helm modules.\n\nContinue with [High Availability](./10-high-availability.md) for the complete multi-replica, migration, health, and release contract."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":["kortyx","studio","aws","cdk","ecs","fargate","rds","self-hosted"],"version":"v0","href":"/docs/studio/deploy-aws-cdk","title":"Deploy Kortyx Studio on AWS with CDK","description":"Deploy Kortyx Studio privately on ECS Fargate with RDS, Secrets Manager, an internal load balancer, and the Kortyx AWS CDK construct.","section":"Deployment","content":"$dd"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:522:keywords","version":"v0","href":"/docs/studio/deploy-aws-cdk#choose-a-deployment-path","title":"Choose a deployment path","description":"Deploy Kortyx Studio on AWS with CDK","section":"Deploy Kortyx Studio on AWS with CDK","content":"This construct is the maintained, batteries-included AWS path, not a requirement for running Kortyx on AWS. Use it when your infrastructure is managed with CDK and its defaults fit your environment.\n\nKortyx also publishes ordinary container images and a stable [deployment contract](./08-configuration-reference.md). You can implement that contract with:\n\n- your own ECS service using Terraform, Pulumi, CloudFormation, or lower-level CDK;\n- EKS or another Kubernetes platform;\n- Docker Compose on EC2; or\n- an existing database, cluster, certificate, and DNS design.\n\nThe CDK package is an infrastructure dependency; the deployed Kortyx workload does not require it at runtime. If your organization already standardizes on another infrastructure tool, keep that tool and use the same containers and environment variables. See [Deploy on a Server](./06-deploy-server.md) for the portable container path."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:522:keywords","version":"v0","href":"/docs/studio/deploy-aws-cdk#architecture","title":"Architecture","description":"Deploy Kortyx Studio on AWS with CDK","section":"Deploy Kortyx Studio on AWS with CDK","content":"```text\nVPC or VPN client\n |\n | HTTPS :443\n v\nstudio.example.com (internal ALB)\n |-- /v1/telemetry/*, /health -> API :6400\n `-- everything else -> Studio :6300\n |\n v\n private RDS PostgreSQL\n```\n\nThe Fargate task starts in this order:\n\n```text\ndatabase migration + bootstrap -> healthy telemetry API -> Studio\n```\n\nA failed migration or bootstrap prevents that task from serving traffic."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:522:keywords","version":"v0","href":"/docs/studio/deploy-aws-cdk#before-you-start","title":"Before you start","description":"Deploy Kortyx Studio on AWS with CDK","section":"Deploy Kortyx Studio on AWS with CDK","content":"You need:\n\n- an AWS account and AWS CLI credentials with permission to deploy CDK stacks;\n- Node.js 22 or newer;\n- an existing VPC with private subnets in at least two Availability Zones;\n- outbound HTTPS from those subnets, through NAT or equivalent egress, so Fargate can pull the public GHCR images; and\n- a public Route 53 hosted zone for the parent domain.\n\nThe minimal example infers `example.com` from `studio.example.com` and creates a DNS-validated ACM certificate. Pass an explicit `hostedZone` or `certificate` when your DNS layout differs.\n\nThis deployment creates billable ECS, RDS, Application Load Balancer, Secrets Manager, CloudWatch Logs, and networking resources. Review `cdk diff` and your expected AWS cost before deployment."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:522:keywords","version":"v0","href":"/docs/studio/deploy-aws-cdk#1-create-a-cdk-application","title":"1. Create a CDK application","description":"Deploy Kortyx Studio on AWS with CDK","section":"Deploy Kortyx Studio on AWS with CDK","content":"```bash\nmkdir kortyx-studio-infra\ncd kortyx-studio-infra\nnpx aws-cdk@latest init app --language typescript\nnpm install @kortyx/aws-cdk aws-cdk-lib constructs\n```\n\nAWS requires each account and Region to be [bootstrapped for CDK](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping-env.html) once."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:522:keywords","version":"v0","href":"/docs/studio/deploy-aws-cdk#2-add-kortyx-studio","title":"2. Add Kortyx Studio","description":"Deploy Kortyx Studio on AWS with CDK","section":"Deploy Kortyx Studio on AWS with CDK","content":"$de"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:522:keywords","version":"v0","href":"/docs/studio/deploy-aws-cdk#3-review-the-defaults","title":"3. Review the defaults","description":"Deploy Kortyx Studio on AWS with CDK","section":"Deploy Kortyx Studio on AWS with CDK","content":"| Resource | Default |\n| --- | --- |\n| ECS | One Fargate task with database-init, API, and Studio containers |\n| RDS | PostgreSQL 17, `db.t4g.micro`, 20 GiB with storage autoscaling |\n| Secrets | Generated database password, key pepper, Project keys, and Basic Auth password |\n| Load balancer | Internal ALB; one hostname with path-based routing |\n| Networking | ALB ingress from the VPC CIDR; no task or database public IP |\n| Recovery | Seven-day database backups, retained secrets and logs, database deletion protection |\n\nCommon overrides remain concise:\n\n```ts\nnew KortyxStudio(this, \"Studio\", {\n vpc,\n domainName: \"studio.example.com\",\n version: \"v0.4.0\",\n allowedCidrs: [vpc.vpcCidrBlock, \"10.50.0.0/16\"],\n databaseMultiAz: true,\n databaseInstanceType: ec2.InstanceType.of(\n ec2.InstanceClass.T4G,\n ec2.InstanceSize.SMALL,\n ),\n});\n```\n\nYou can also supply an existing `cluster`, `hostedZone`, `certificate`, or `database`. The TypeScript API documents the required shape for each value."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:522:keywords","version":"v0","href":"/docs/studio/deploy-aws-cdk#availability-what-one-application-task-means","title":"Availability: what one application task means","description":"Deploy Kortyx Studio on AWS with CDK","section":"Deploy Kortyx Studio on AWS with CDK","content":"$df"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:522:keywords","version":"v0","href":"/docs/studio/deploy-aws-cdk#4-bootstrap-inspect-and-deploy","title":"4. Bootstrap, inspect, and deploy","description":"Deploy Kortyx Studio on AWS with CDK","section":"Deploy Kortyx Studio on AWS with CDK","content":"Confirm the AWS identity and Region:\n\n```bash\naws sts get-caller-identity\naws configure get region\n```\n\nThen bootstrap, compile, inspect, and deploy:\n\n```bash\nnpx cdk bootstrap\nnpm run build\nnpx cdk synth\nnpx cdk diff\nnpx cdk deploy\n```\n\nCommit the CDK source to your infrastructure repository. For shared environments, deploy through your reviewed CI/CD workflow.\n\nThe deployment is ready when the ECS service has one running task and both target groups report it healthy."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:522:keywords","version":"v0","href":"/docs/studio/deploy-aws-cdk#5-retrieve-the-initial-credentials","title":"5. Retrieve the initial credentials","description":"Deploy Kortyx Studio on AWS with CDK","section":"Deploy Kortyx Studio on AWS with CDK","content":"$e0"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:522:keywords","version":"v0","href":"/docs/studio/deploy-aws-cdk#6-connect-and-verify","title":"6. Connect and verify","description":"Deploy Kortyx Studio on AWS with CDK","section":"Deploy Kortyx Studio on AWS with CDK","content":"Give each application's server runtime:\n\n```bash file=\"server environment\"\nKORTYX_TELEMETRY_API_URL=https://studio.example.com\nKORTYX_TELEMETRY_API_KEY=ktyx_live_default-telemetry_...\nKORTYX_TELEMETRY_ENVIRONMENT=production\nKORTYX_TELEMETRY_SERVICE_NAME=my-agent\n```\n\nThe application must have a network route to the internal load balancer. Never put the telemetry key in a browser bundle. Continue with [Connect Your Project](./03-connect-project.md) to publish workflow topology."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:522:keywords","version":"v0","href":"/docs/studio/deploy-aws-cdk#publish-topology-from-the-application-release","title":"Publish topology from the application release","description":"Deploy Kortyx Studio on AWS with CDK","section":"Deploy Kortyx Studio on AWS with CDK","content":"$e1"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:522:keywords","version":"v0","href":"/docs/studio/deploy-aws-cdk#upgrade-with-cdk","title":"Upgrade with CDK","description":"Deploy Kortyx Studio on AWS with CDK","section":"Deploy Kortyx Studio on AWS with CDK","content":"$e2"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":["kortyx","studio","high availability","replicas","rolling deployment","ecs","kubernetes","cloud run"],"version":"v0","href":"/docs/studio/high-availability","title":"Run Kortyx Studio with Multiple Replicas","description":"Deploy highly available Kortyx Studio replicas with serialized migrations, readiness, graceful draining, and safe rolling updates.","section":"Deployment","content":"$e3"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:535:keywords","version":"v0","href":"/docs/studio/high-availability#production-baseline","title":"Production baseline","description":"Run Kortyx Studio with Multiple Replicas","section":"Run Kortyx Studio with Multiple Replicas","content":"$e4"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:535:keywords","version":"v0","href":"/docs/studio/high-availability#health-and-termination-contract","title":"Health and termination contract","description":"Run Kortyx Studio with Multiple Replicas","section":"Run Kortyx Studio with Multiple Replicas","content":"$e5"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:535:keywords","version":"v0","href":"/docs/studio/high-availability#run-database-work-once","title":"Run database work once","description":"Run Kortyx Studio with Multiple Replicas","section":"Run Kortyx Studio with Multiple Replicas","content":"Application replicas must not run migrations in their normal startup command. Schedule the API image as a separate one-shot job before a release:\n\n```bash\nkortyx-studio-db migrate-and-bootstrap\n```\n\nThe job is idempotent and can be retried. Migrations hold a PostgreSQL advisory lock for the complete migration set, so accidentally concurrent jobs serialize instead of racing. The lock is a safety net; keep one job as the normal orchestration model.\n\nDo not start new application images until this job succeeds. Database downgrade is unsupported, so take a provider snapshot or verified backup before changing the schema."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:535:keywords","version":"v0","href":"/docs/studio/high-availability#choose-the-deployment-path-from-the-release","title":"Choose the deployment path from the release","description":"Run Kortyx Studio with Multiple Replicas","section":"Run Kortyx Studio with Multiple Replicas","content":"The stable release manifest is available at `https://updates.kortyx.io/studio/stable.json`. It contains immutable API and Studio image digests and a deployment marker:\n\n```json\n{\n \"format\": 1,\n \"installer\": 1,\n \"version\": \"0.5.0\",\n \"api\": \"ghcr.io/kortyx-io/kortyx-api@sha256:...\",\n \"studio\": \"ghcr.io/kortyx-io/kortyx-studio@sha256:...\",\n \"deployment\": { \"strategy\": \"rolling\" }\n}\n```\n\nTreat a missing or unknown deployment marker as `recreate`."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:535:keywords","version":"v0","href":"/docs/studio/high-availability#rolling","title":"rolling","description":"Run Kortyx Studio with Multiple Replicas","section":"Run Kortyx Studio with Multiple Replicas","content":"The release is explicitly compatible with overlapping old and new application replicas during its migration and rollout. After the database job succeeds:\n\n1. start new replicas without stopping the old replicas;\n2. wait for their readiness checks;\n3. move traffic to healthy new replicas;\n4. terminate old replicas gracefully; and\n5. fail or roll back the application rollout if readiness never succeeds.\n\nUse the rolling path only for the upgrade path reviewed by the release. Treat a skipped, unknown, or locally modified version as `recreate` unless you have independently verified compatibility."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:535:keywords","version":"v0","href":"/docs/studio/high-availability#recreate","title":"recreate","description":"Run Kortyx Studio with Multiple Replicas","section":"Run Kortyx Studio with Multiple Replicas","content":"The release cannot promise safe version overlap. Schedule a maintenance window:\n\n1. stop API ingestion and Studio replicas;\n2. back up PostgreSQL;\n3. run the database job;\n4. start the new API replicas and wait for `/ready`;\n5. start the new Studio replicas; and\n6. verify authenticated reads and a telemetry write before ending maintenance.\n\nThis path can interrupt Studio and telemetry ingestion even when the normal replica count is two. Telemetry producers should retry important writes."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:535:keywords","version":"v0","href":"/docs/studio/high-availability#platform-mapping","title":"Platform mapping","description":"Run Kortyx Studio with Multiple Replicas","section":"Run Kortyx Studio with Multiple Replicas","content":"$e6"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:535:keywords","version":"v0","href":"/docs/studio/high-availability#automate-release-discovery-with-github-actions","title":"Automate release discovery with GitHub Actions","description":"Run Kortyx Studio with Multiple Replicas","section":"Run Kortyx Studio with Multiple Replicas","content":"$e7"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:535:keywords","version":"v0","href":"/docs/studio/high-availability#what-this-does-and-does-not-guarantee","title":"What this does and does not guarantee","description":"Run Kortyx Studio with Multiple Replicas","section":"Run Kortyx Studio with Multiple Replicas","content":"With the baseline above, Kortyx supports continued application service during one replica or task failure and during releases explicitly marked `rolling`. It does not by itself make PostgreSQL highly available. Use your provider's Multi-AZ, regional, backup, restore, and failover features, and test them.\n\nThis contract does not claim multi-region active-active operation, unlimited horizontal scaling, or published capacity limits. Start with two replicas, measure load and database connections, then scale for your workload."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":["kortyx","studio","evals","suites","comparison","cli","ci"],"version":"v0","href":"/docs/studio/evals","title":"Run Eval Suites in Studio","description":"Run workflow conversation suites, inspect grades and compare saved results using existing Studio credentials.","section":"Guides","content":"$e8"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:545:keywords","version":"v0","href":"/docs/studio/evals#register-applications-on-the-studio-api-server","title":"Register applications on the Studio API server","description":"Run Eval Suites in Studio","section":"Run Eval Suites in Studio","content":"$e9"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:545:keywords","version":"v0","href":"/docs/studio/evals#where-application-metadata-comes-from","title":"Where application metadata comes from","description":"Run Eval Suites in Studio","section":"Run Eval Suites in Studio","content":"The target file supplies the application **ID**, display **name**, endpoint and\n**environment**. They are operator-defined labels, not inferred from model calls\nor the agent's telemetry service name. The application's manifest supplies the\nsuite IDs, case definitions, revisions, named handlers and optional code judge.\n\nStudio copies `targetId`, `targetName` and environment into each saved run. The\napplication filter combines currently configured targets with labels from saved\nhistory. Removing a target stops discovery and new execution, but its historical\nruns and application filter entry remain. Suite discovery shows currently\nregistered suites; saved runs retain the definition used when they started.\n\nUse stable target IDs. Renaming a target changes its label for new runs; existing\nrecords keep the saved label. The filter groups by target ID and displays a label\nfrom the current configuration or saved history. Two environments can be\nregistered as separate targets with distinct IDs and clear names."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:545:keywords","version":"v0","href":"/docs/studio/evals#credentials-have-separate-jobs","title":"Credentials have separate jobs","description":"Run Eval Suites in Studio","section":"Run Eval Suites in Studio","content":"| Credential | Where it is configured | What it authorizes |\n| --- | --- | --- |\n| Project Studio key | Studio server or CLI connection | Project discovery/history with `studio:read`; execution/cancellation with `eval:run` |\n| Application eval service key | Consumer route and Studio API target file | Studio API access to that app's eval endpoint |\n| Test actor credentials | Consumer application's server configuration/setup | The app's normal user identity, roles and data access |\n| Judge provider key | Studio API backend for Studio judging; consumer app for App judging | Model requests for semantic grading |\n\nThe service key authorizes starting evals; it does not impersonate an application\nuser. The consumer's setup and execute callbacks bind that user through the same\npermission path used by ordinary application requests."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:545:keywords","version":"v0","href":"/docs/studio/evals#studio-judge-configuration","title":"Studio judge configuration","description":"Run Eval Suites in Studio","section":"Run Eval Suites in Studio","content":"$ea"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:545:keywords","version":"v0","href":"/docs/studio/evals#judge-criteria-and-evidence","title":"Judge criteria and evidence","description":"Run Eval Suites in Studio","section":"Run Eval Suites in Studio","content":"$eb"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:545:keywords","version":"v0","href":"/docs/studio/evals#eval-run-costs","title":"Eval run costs","description":"Run Eval Suites in Studio","section":"Run Eval Suites in Studio","content":"$ec"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:545:keywords","version":"v0","href":"/docs/studio/evals#persistence-and-execution-lifecycle","title":"Persistence and execution lifecycle","description":"Run Eval Suites in Studio","section":"Run Eval Suites in Studio","content":"$ed"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:545:keywords","version":"v0","href":"/docs/studio/evals#use-the-interface","title":"Use the interface","description":"Run Eval Suites in Studio","section":"Run Eval Suites in Studio","content":"$ee"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:545:keywords","version":"v0","href":"/docs/studio/evals#container-configuration","title":"Container configuration","description":"Run Eval Suites in Studio","section":"Run Eval Suites in Studio","content":"$ef"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:545:keywords","version":"v0","href":"/docs/studio/evals#required-structured-responses","title":"Required structured responses","description":"Run Eval Suites in Studio","section":"Run Eval Suites in Studio","content":"Conversation steps can declare `expect.outputs` as an array of required output\ncontracts. Studio displays each ID and either the exact required version or\n“Any version” in the suite definition and case evaluation. The consumer checks\nthat every contract has a completed visible output before either judge runs.\nPartial streams, invalidated outputs and outputs from previous steps do not\nsatisfy the requirement. Missing contracts fail the step with an explicit reason.\nOpen the conversation debugging section to inspect the recorded envelopes.\nUse pass criteria to assess payload meaning; the output requirements check\ncontract presence. See [the conversation guide](../../sdk/v0/03-guides/10-conversation-evals.md#required-structured-outputs)\nfor suite authoring and custom executor support."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:545:keywords","version":"v0","href":"/docs/studio/evals#grouped-evaluation-runs","title":"Grouped evaluation runs","description":"Run Eval Suites in Studio","section":"Run Eval Suites in Studio","content":"$f0"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:545:keywords","version":"v0","href":"/docs/studio/evals#deployment-and-scheduled-ci-examples","title":"Deployment and scheduled CI examples","description":"Run Eval Suites in Studio","section":"Run Eval Suites in Studio","content":"$f1"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:545:keywords","version":"v0","href":"/docs/studio/evals#failure-evidence","title":"Failure evidence","description":"Run Eval Suites in Studio","section":"Run Eval Suites in Studio","content":"In a case attempt, error cards show the phase and safe failure code/message.\nChoose **View diagnostic** to inspect or download its captured private diagnostic.\nThis requires native diagnostic capture and a Studio reader for the same project\nand environment. Credential redaction and explicit capture/delivery limits apply.\nA missing diagnostic reference is identified; old data cannot recover discarded\ncontent. Conversation debugging also retains handled tool-error references.\n\nApplication postcondition verification has its own verdict: unmet behavior is\nFailed; an infrastructure or reset exception is Error. Comparison views preserve\nverification evidence alongside conversation results. Deploy matching API/Studio\nsupport before the SDK/CLI emitting these additive fields. No SQL migration is\nneeded for the existing JSON records."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:545:keywords","version":"v0","href":"/docs/studio/evals#concurrent-execution-recovery","title":"Concurrent execution recovery","description":"Run Eval Suites in Studio","section":"Run Eval Suites in Studio","content":"$f2"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":["kortyx","evals","onboarding","setup","doctor","authentication","deployment"],"version":"v0","href":"/docs/studio/first-eval","title":"Run Your First Workflow Eval","description":"Wire an existing agent to Studio, configure the right services, diagnose setup failures and verify a real suite.","section":"Guides","content":"$f3"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:560:keywords","version":"v0","href":"/docs/studio/first-eval#1-define-one-case","title":"1. Define one case","description":"Run Your First Workflow Eval","section":"Run Your First Workflow Eval","content":"$f4"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:560:keywords","version":"v0","href":"/docs/studio/first-eval#2-create-the-eval-instance-beside-your-agent","title":"2. Create the eval instance beside your agent","description":"Run Your First Workflow Eval","section":"Run Your First Workflow Eval","content":"$f5"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:560:keywords","version":"v0","href":"/docs/studio/first-eval#3-mount-and-deploy-the-application-endpoint","title":"3. Mount and deploy the application endpoint","description":"Run Your First Workflow Eval","section":"Run Your First Workflow Eval","content":"$f6"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:560:keywords","version":"v0","href":"/docs/studio/first-eval#4-register-the-application-on-studio","title":"4. Register the application on Studio","description":"Run Your First Workflow Eval","section":"Run Your First Workflow Eval","content":"$f7"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:560:keywords","version":"v0","href":"/docs/studio/first-eval#5-configure-one-judge","title":"5. Configure one judge","description":"Run Your First Workflow Eval","section":"Run Your First Workflow Eval","content":"This recipe selects **Studio judge**. Configure these on the **Studio API** and\nrestart it:\n\n```dotenv\nKORTYX_EVAL_JUDGE_BASE_URL=https://openrouter.ai/api/v1\nKORTYX_EVAL_JUDGE_API=chat-completions\nKORTYX_EVAL_JUDGE_MODEL=openai/gpt-4o\nKORTYX_EVAL_JUDGE_API_KEY=\n```\n\nChoose a model/provider route supporting structured JSON verdicts. The browser\nand consumer do not receive this key. This model grades execution; it does not\nreplace your workflow model. You can instead configure an App judge with\n`createEvalJudge` and explicitly select it in Studio or with `--judge app`.\nSee [judge selection](./11-evals.md#studio-judge-configuration)."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:560:keywords","version":"v0","href":"/docs/studio/first-eval#configuration-belongs-to-different-services","title":"Configuration belongs to different services","description":"Run Your First Workflow Eval","section":"Run Your First Workflow Eval","content":"$f8"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:560:keywords","version":"v0","href":"/docs/studio/first-eval#6-diagnose-setup-before-executing","title":"6. Diagnose setup before executing","description":"Run Your First Workflow Eval","section":"Run Your First Workflow Eval","content":"$f9"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:560:keywords","version":"v0","href":"/docs/studio/first-eval#7-run-and-verify-the-actual-workflow","title":"7. Run and verify the actual workflow","description":"Run Your First Workflow Eval","section":"Run Your First Workflow Eval","content":"$fa"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":["kortyx","prompts","versioning","configuration","evals","groups"],"version":"v0","href":"/docs/studio/prompts","title":"Version and Test Prompts","description":"Manage prompt versions, test candidates with your application, and promote verified versions.","section":"Guides","content":"$fb"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:569:keywords","version":"v0","href":"/docs/studio/prompts#include-another-prompt","title":"Include another prompt","description":"Version and Test Prompts","section":"Version and Test Prompts","content":"$fc"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:569:keywords","version":"v0","href":"/docs/studio/prompts#review-and-save","title":"Review and save","description":"Version and Test Prompts","section":"Version and Test Prompts","content":"$fd"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:569:keywords","version":"v0","href":"/docs/studio/prompts#version-reviews","title":"Version reviews","description":"Version and Test Prompts","section":"Version and Test Prompts","content":"Open a prompt, select a version, and choose **Reviews** to see its saved notes,\nreviewers, timestamps, and independent-review status. **Review this version**\nopens a modal from the tab or the version menu. After submitting, Studio opens\nthat version’s Reviews tab. Submitting another review as the same reviewer\nupdates the existing note for that version. Reviews of other versions stay separate.\n\nIndependent human reviews can satisfy promotion requirements. Notes from the\nversion’s author or an API key remain visible but do not count as independent."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:569:keywords","version":"v0","href":"/docs/studio/prompts#categories-and-test-groups","title":"Categories and test groups","description":"Version and Test Prompts","section":"Version and Test Prompts","content":"$fe"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:569:keywords","version":"v0","href":"/docs/studio/prompts#evidence-and-promotion","title":"Evidence and promotion","description":"Version and Test Prompts","section":"Version and Test Prompts","content":"$ff"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:569:keywords","version":"v0","href":"/docs/studio/prompts#connect-an-application","title":"Connect an application","description":"Version and Test Prompts","section":"Version and Test Prompts","content":"Follow [Studio prompt SDK integration](../../sdk/v0/03-guides/27-studio-prompts.md).\nThe prompt's **Code helper** includes its real contracts and version pin. Use a\nserver-side key with `prompt:serve`; editing and promotion use separate Studio\npermissions. OSS bootstrap grants prompt management and all other Studio feature\npermissions without feature switches. Existing installations should rerun\nbootstrap with their stored keys and pepper to apply these permissions.\nEval execution still needs a registered consumer target and a configured judge.\n\nSee [Migrate prompts between deployments](./14-prompt-migration.md) for CLI\nauthoring and staging-to-production migration."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:569:keywords","version":"v0","href":"/docs/studio/prompts#bulk-management-and-import","title":"Bulk management and import","description":"Version and Test Prompts","section":"Version and Test Prompts","content":"$100"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":["kortyx","prompts","cli","migration","staging","production"],"version":"v0","href":"/docs/studio/prompt-migration","title":"Author and Migrate Prompts with the CLI","description":"Read, modify, test, and transfer exact prompt versions across projects or independent OSS deployments.","section":"Guides","content":"$101"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:577:keywords","version":"v0","href":"/docs/studio/prompt-migration#plan-apply-verify","title":"Plan, apply, verify","description":"Author and Migrate Prompts with the CLI","section":"Author and Migrate Prompts with the CLI","content":"$102"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:577:keywords","version":"v0","href":"/docs/studio/prompt-migration#editing-inclusions-with-the-cli","title":"Editing inclusions with the CLI","description":"Author and Migrate Prompts with the CLI","section":"Author and Migrate Prompts with the CLI","content":"Studio references appear in executable JSON as `[[prompt:stable/key]]`. Each key\nneeds an exact `{ id, version, hash }` entry in `content.dependencies`; use\n`prompts get` to read the child version and its hash. Keep inherited input\ndeclarations in the parent's `variablesSchema`, review the diff, then update and\ntest the parent. Copy/export includes nested dependencies. Destination rename\nmappings rewrite both the manifest and inline tokens before recomputing hashes."},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:577:keywords","version":"v0","href":"/docs/studio/prompt-migration#manage-release-tags-from-the-cli","title":"Manage release tags from the CLI","description":"Author and Migrate Prompts with the CLI","section":"Author and Migrate Prompts with the CLI","content":"Promotion updates only `live`; saving a new version and editing other tags do not:\n\n```bash\nkortyx studio prompts promote canvas/classify-intent --version 9 --expected-revision 2\nkortyx studio prompts tag canvas/classify-intent staging --version 10 --expected-revision 0\nkortyx studio prompts untag canvas/classify-intent staging --expected-revision 1\nkortyx studio prompts rollback canvas/classify-intent --version 7 --expected-revision 3\n```\n\nRead current tag revisions with `prompts get KEY --json`. Revision 0 creates a new\ntag; moving or removing one requires its current revision. `live` is reserved for\npromotion/rollback. Copying between connections imports immutable candidates and\nnever copies or moves release tags automatically."}]}]