e3:T595,Create `src/evals/suites.ts` in your application: ```ts import { defineSuite } from "kortyx"; export const catalogSmoke = defineSuite({ id: "catalog-smoke", name: "Catalog lookup", cases: [{ id: "blue-backpack-price", name: "Read a product price", // Use the ID of an existing, registered workflow in your application. workflowId: "catalog", steps: [{ message: "What is the price of the blue backpack in my catalog?", expect: { type: "answer", criteria: [ "Looks up the blue backpack using a successful catalog tool call and reports its price and currency faithfully. Fails if the product is missing or no successful lookup evidence is available.", ], }, }], }], }); ``` Choose a product your test account can actually read. Author the scenario from known data; do not discover random products during startup. A suite is JSON data, not authentication code. Add more cases to this array as you learn about failures. For this criterion, enable evidence on the workflow's existing `useReason` call: ```ts const result = await useReason({ model, input, tools, toolExecution: { emit: true }, }); ``` Without emitted tool results the judge cannot establish that the reported price came from the lookup. This flag captures evidence; normal agent telemetry is configured separately if you want workflow costs and workflow inspection links.e4:T7e5,Create `src/evals/index.ts`. Export the eval instance without starting a server: ```ts import { createEvals } from "kortyx"; import { agent } from "../agent"; // Your existing createAgent instance. import { catalogSmoke } from "./suites"; export const evals = createEvals({ agent, suites: [catalogSmoke], }); ``` This minimal instance is sufficient when your workflow needs no caller-specific context. If your tools depend on an authenticated user, add `setup` and `execute` **before running it**: ```ts import { authenticateTestActor, withApplicationRequest } from "../auth"; export const evals = createEvals({ agent, suites: [catalogSmoke], setup: async ({ signal }) => authenticateTestActor({ signal }), execute: async ({ prepared, history, sessionId, command, signal, run }) => withApplicationRequest( { actor: prepared, sessionId, history, command, signal }, () => run({ context: { userId: prepared.userId } }), ), }); ``` `authenticateTestActor` and `withApplicationRequest` above are your application's existing helpers, not Kortyx exports. The first obtains a test identity; the second binds the same permission checks, request-scoped tools and context that ordinary requests use. Adapt their arguments to your app. Reuse that existing logic rather than implement a second permission system for evals. Configure the test account in the **application service**. It may use a username and password, a refreshable token, or another identity mechanism your app already supports. Studio neither obtains that token nor assigns the account's roles. The eval service key authorizes initiation; it does not grant domain data access. Never put user tokens or passwords in suite definitions, progress or judge inputs. Add teardown only if setup acquires resources that need releasing. It is not necessarily a sign-out operation. See [application authentication and execution](../../sdk/v0/03-guides/10-conversation-evals.md) for cancellation, typed callbacks and interrupt responders.e5:T8a4,For **Next.js App Router**, create `src/app/api/evals/route.ts`: ```ts import { createEvalRouteHandler } from "kortyx"; import { evals } from "../../../evals"; const serviceKey = process.env.EVAL_SERVICE_KEY; if (!serviceKey) throw new Error("EVAL_SERVICE_KEY is required"); const handleEvals = createEvalRouteHandler({ evals, serviceKey }); export const runtime = "nodejs"; export const GET = handleEvals; export const POST = handleEvals; ``` Its URL is `https://your-app.example/api/evals`. Keep a single handler instance so its per-process active-run limit is shared across requests. For a **Hono Node server**, mount the same Web handler before starting the server: ```ts import { createEvalRouteHandler } from "kortyx"; import { evals } from "./evals"; const serviceKey = process.env.EVAL_SERVICE_KEY; if (!serviceKey) throw new Error("EVAL_SERVICE_KEY is required"); const handleEvals = createEvalRouteHandler({ evals, serviceKey }); app.on(["GET", "POST"], "/api/evals", (c) => handleEvals(c.req.raw)); ``` For **Express/Fastify or another Node server**, use the framework's Web Request/ Response bridge. It must preserve the request abort signal, stream the returned body, and cancel its reader when the client disconnects. Do not buffer the full POST response or redirect it through the interactive chat route. See the [runnable Node adapter](https://github.com/kortyx-io/kortyx/tree/main/examples/kortyx-eval-endpoint) for a complete application using Hono's Node server bridge. Generate a separate service key, store it privately, and supply it to the app: ```sh node -e 'console.log(require("node:crypto").randomBytes(32).toString("hex"))' ``` The HTTP route explicitly reads `EVAL_SERVICE_KEY`; the local eval module does not need it. **Kortyx does not automatically read application env variables or enable routes.** If your application has its own eval feature flag, enable it in the deployed application. Ensure the server and reverse proxy expose the exact GET/POST path in the target configuration. Restart/deploy the app with its service key, test-account configuration and normal workflow model/tool configuration. A healthy container does not prove that the route was registered.e6:T744,On the **Studio API backend**, mount a private JSON file: ```json [ { "id": "catalog", "name": "Catalog agent", "organizationId": "YOUR-EXISTING-ORGANIZATION-UUID", "projectId": "YOUR-EXISTING-PROJECT-UUID", "environment": "development", "url": "https://your-app.example/api/evals", "serviceKey": "THE-SAME-KEY-AS-THE-CONSUMER" } ] ``` Use the existing Studio organization and project IDs. The environment must be allowed in that project; use its real configured label rather than infer one from the hostname. The application filter gets its ID/name from this file. For Compose, apply this override alongside your installation's normal stack: ```yaml services: api: environment: KORTYX_EVAL_TARGETS_FILE: /run/secrets/eval-targets.json volumes: - ./private/eval-targets.json:/run/secrets/eval-targets.json:ro db-init: environment: KORTYX_STUDIO_ENABLE_EVALS: "1" ``` Keep the target file and env files out of Git and restrict their filesystem permissions. Rerun the existing bootstrap job with the **same stored Studio key** to grant `eval:run`, preserving its key and pepper. Run the release's normal database migrations, then restart the API to load target changes. Hosted systems use their normal secret mounts and bootstrap process; a host `.env` value alone does not create a container mount. For an app running on your host with Studio in Docker Desktop, use `http://host.docker.internal:YOUR-APP-PORT/api/evals` and `"allowInsecureHttp": true` on that target. Remote deployments use HTTPS. `localhost` inside the API container points to that container. Studio fetches the registered suites through authenticated **GET** discovery. It does not receive suites through `kortyx topology push`. Changing code-authored suites requires deploying the application and refreshing discovery.e7:T6f1,| Setting | Owner | Required when | Apply changes | | --- | --- | --- | --- | | `EVAL_SERVICE_KEY` in this example | Application | Exposing the eval handler; explicitly passed to it | Restart/deploy app | | App's own eval enable flag, if present | Application | App gates route registration | Restart/deploy app | | App test-account/token settings | Application | Workflow requires user permissions | Restart app or follow its token refresh mechanism | | Workflow model/tool settings | Application | Existing agent needs them | Follow app configuration | | `KORTYX_EVAL_TARGETS_FILE` and its read-only file mount | Studio API | Discovering/executing consumer suites | Restart API | | Target `serviceKey` | Private target file | Must match the application handler's key | Restart API; coordinate app rotation | | `KORTYX_STUDIO_ENABLE_EVALS=1` | Bootstrap job | Granting `eval:run` to the existing local project key | Rerun bootstrap with stored key | | Existing `KORTYX_STUDIO_API_KEY` | Studio server | Browser proxy needs `studio:read` and `eval:run` | Restart Studio server if its key changes | | `KORTYX_EVAL_JUDGE_MODEL`, `KORTYX_EVAL_JUDGE_API_KEY` | Studio API | Selecting Studio judge | Restart API | | `KORTYX_EVAL_JUDGE_BASE_URL`, `KORTYX_EVAL_JUDGE_API` | Studio API | Using OpenRouter or a compatible endpoint | Restart API | | Variable named by CLI `--api-key-env` | Developer terminal / CI | Connecting the CLI to Studio | Set before invoking CLI | The CLI uses a **Studio project key**, not the application service key or an LLM provider key. Preserve the existing database URL and API-key pepper. The [configuration reference](./08-configuration-reference.md) lists all defaults, optional judge ID/version overrides and existing Studio authentication settings.e8:T813,Use the CLI from the release containing the doctor command. Connect it to the Studio **API URL**, not the browser's URL: ```sh # KORTYX_PROJECT_KEY holds the existing project Studio key in your private environment. pnpm exec kortyx studio evals doctor \ --api-url https://studio-api.example.com \ --api-key-env KORTYX_PROJECT_KEY \ --target catalog --environment development --suite catalog-smoke ``` For a configured connection, use `--connection staging` instead of the direct URL/key flags. The connection's default environment applies unless overridden. Example when the consumer route is missing: ```text Kortyx Evals · Setup check ✓ Authenticated Studio discovery (studio:read). ✓ Studio key has eval:run. ✓ 1 matching application target(s). ✓ catalog (development): target environment allowed. ✗ catalog (development): Application endpoint returned HTTP 404. (HTTP 404) → Ensure the eval route is mounted and enabled in the deployed application; check the target URL and reverse proxy route. – catalog (development): judge compatibility cannot be checked without a manifest. ``` Doctor checks project read/execution access, matching targets, environment access, authenticated manifest validity, registered suites and advertised judge support. It starts **no workflows, judge calls or saved eval runs**. The consumer's GET wrapper may perform its own authentication; the SDK's manifest handler does not call `setup`. Provider credentials, test-user tool permissions and worker health still need a real run. An older Studio API may return only “unavailable”; doctor reports that limitation rather than invent a cause. `--judge app` checks the code judge instead; `--json` returns one report with `schemaVersion`, `status` and `checks`. Each check has `id`, `status`, `message` and an optional `remedy`. Exit `0` means all configuration checks passed; exit `1` means a failure. Failed prerequisites produce skipped downstream checks. Doctor uses discovery GET only; do not use it as a provider-token validation test.e9:T76a,Open **Evals → Suites**, refresh, and choose **Catalog lookup**. Select Studio judge and run the one case once. Or enqueue through the same configured API: ```sh pnpm exec kortyx studio evals runs start catalog-smoke \ --api-url https://studio-api.example.com \ --api-key-env KORTYX_PROJECT_KEY \ --target catalog --environment development --judge studio ``` The command returns a run ID immediately. Inspect it in Studio, or with `kortyx studio evals runs get ` using the same connection flags. An enqueue response confirms a queued record, not a completed eval. Before calling the integration complete, verify: - The real deployed suite is visible, not merely an application connection label. - The test actor reaches the normal tools with its intended roles and data access. - The workflow runs, the selected judge grades it, and the final reasons/evidence are readable. - Reloading the run retains its definition, observations and final result. - Live progress arrives; workflow/judge costs appear when their usage is recorded. - Cancelling a suitable test run reaches a saved terminal state and honors cleanup. A behavioral failure can be a useful successful integration test: inspect the reason rather than weaken criteria to obtain a green result. Authentication, provider or execution errors need resolving before assessing behavior. Use a representative read-only case for onboarding; a passing fixture alone does not prove your real application's permissions or domain logic. Once this works, add [interrupt scenarios and required structured outputs](../../sdk/v0/03-guides/10-conversation-evals.md), [local terminal execution](./04-cli-commands.md#run-locally-without-studio), or [optional post-deployment CI triggering](./04-cli-commands.md#eval-suites-and-post-deployment-ci). Keep CI triggering after application deployment/readiness; it need not block releases.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#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":"$1d"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:31: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:31: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:31: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:31: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":"$1e"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:36:keywords","version":"v0","href":"/docs/sdk/core-concepts/nodes#where-nodes-are-declared","title":"Where nodes are declared","description":"Nodes","section":"Nodes","content":"$1f"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:36: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":"$20"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:36: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":"$21"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:36:keywords","version":"v0","href":"/docs/sdk/core-concepts/nodes#node-return-values","title":"Node return values","description":"Nodes","section":"Nodes","content":"$22"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:36:keywords","version":"v0","href":"/docs/sdk/core-concepts/nodes#routing-from-a-node","title":"Routing from a node","description":"Nodes","section":"Nodes","content":"$23"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:36: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":"$24"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:43: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:43: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:43: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:43: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:43:keywords","version":"v0","href":"/docs/sdk/core-concepts/conditional-routing#studio-topology-visibility","title":"Studio topology visibility","description":"Conditional Routing","section":"Conditional Routing","content":"$25"},{"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":"$26"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:49: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:49: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:49: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":"$27"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:53: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:53: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:53: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":"$28"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:53:keywords","version":"v0","href":"/docs/sdk/core-concepts/stream-chat#buffered-helpers-choose-one","title":"Buffered helpers (choose one)","description":"streamChat","section":"streamChat","content":"$29"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:53: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:53: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:53: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:53: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:53: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:53: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":"$2a"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:64: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:64:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#reporterrorerror-options","title":"reportError(error, options?)","description":"Hooks","section":"Hooks","content":"$2b"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:64:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#usetooltool-input","title":"useTool({tool, input})","description":"Hooks","section":"Hooks","content":"$2c"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:64: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:64: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:64: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:64:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#emission-vs-uimessage","title":"Emission vs ui.message","description":"Hooks","section":"Hooks","content":"$2d"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:64:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#model-selected-output-contracts","title":"Model-selected output contracts","description":"Hooks","section":"Hooks","content":"$2e"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:64: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:64: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":"$2f"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:64:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#what-usereason-returns","title":"What useReason(...) returns","description":"Hooks","section":"Hooks","content":"$30"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:64: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:64:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#mcp-tools","title":"MCP tools","description":"Hooks","section":"Hooks","content":"$31"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:64: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:64:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#current-incremental-streaming-limits","title":"Current incremental streaming limits","description":"Hooks","section":"Hooks","content":"$32"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:64: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:64: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:64: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:64: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:64: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:64: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:64: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":"$33"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:64:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#streamid-and-id","title":"streamId and id","description":"Hooks","section":"Hooks","content":"$34"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:64:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#useabortsignal","title":"useAbortSignal","description":"Hooks","section":"Hooks","content":"$35"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:64:keywords","version":"v0","href":"/docs/sdk/core-concepts/hooks#automatic-model-error-diagnostics","title":"Automatic model error diagnostics","description":"Hooks","section":"Hooks","content":"$36"},{"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":"$37"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:90: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:90: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":"$38"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:90: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:90: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:90: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":"$39"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:96: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:96: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:96: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:96: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:96: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:96: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":"$3a"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:103:keywords","version":"v0","href":"/docs/sdk/guides/interrupts-and-resume#node-side","title":"Node side","description":"Interrupts and Resume","section":"Interrupts and Resume","content":"$3b"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:103: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:103: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:103: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:103: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":"$3c"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:103: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":"$3d"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:103: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:103: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:103: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:103: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":["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":"$3e"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:114: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:114: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:114: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":"$3f"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:114: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:114: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:114: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":"$40"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:121:keywords","version":"v0","href":"/docs/sdk/guides/render-streamed-chat#basic-pattern","title":"Basic Pattern","description":"Rendering Streamed Chat","section":"Rendering Streamed Chat","content":"$41"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:121: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":"$42"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:121:keywords","version":"v0","href":"/docs/sdk/guides/render-streamed-chat#interrupt-controls","title":"Interrupt Controls","description":"Rendering Streamed Chat","section":"Rendering Streamed Chat","content":"$43"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:121: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:121: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:121: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":"$44"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:128: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:128: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":"$45"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:128: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":"$46"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:128: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:128: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:128: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:128: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:128: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:128: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":"$47"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:128: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":"$48"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:139: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":"$49"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:139:keywords","version":"v0","href":"/docs/sdk/guides/child-workflows#type-safety","title":"Type safety","description":"Call Child Workflows","section":"Call Child Workflows","content":"$4a"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:139: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":"$4b"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:139: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":"$4c"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:139: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":"$4d"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:139: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":"$4e"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:139: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":"$4f"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:139: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":"$50"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:148: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":"$51"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:148: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:148: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":"$52"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:148: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":"$53"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:148: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:148: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":"$54"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:148: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":"$55"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:148: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":["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":"$56"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:157: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:157: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":"$57"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:157: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:157: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":"$58"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:157: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":"$59"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:157: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":"$5a"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:157: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":"$5b"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:157: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":"$5c"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:166: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":"$5d"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:166: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":"$5e"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:166: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":"$5f"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:166: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":"$60"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:166: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":"$61"},{"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":"$62"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:172: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":"$63"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:172: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:172: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:172: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":"$64"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:177: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":"$65"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:177:keywords","version":"v0","href":"/docs/sdk/guides/conversation-evals#smallest-configuration","title":"Smallest configuration","description":"Evaluate Agent Conversations","section":"Evaluate Agent Conversations","content":"$66"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:177: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":"$67"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:177: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":"$68"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:177: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":"$69"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:177: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":"$6a"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:177: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":"$6b"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:177: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":"$6c"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:177: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":"$6d"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:177: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":"$6e"},{"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":"$6f"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:188: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":"$70"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:188: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:188: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":"$71"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:188: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:188: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:188:keywords","version":"v0","href":"/docs/sdk/guides/sse#path-behavior","title":"Path behavior","description":"SSE for API Routes","section":"SSE for API Routes","content":"$72"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:188: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":"$73"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:188: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:188: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:188: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","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":"$74"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:199: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":"$75"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:199: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:199: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":"$76"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:199: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":"$77"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:199: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":"$78"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:199: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:199: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":"$79"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:207: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:207: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:207: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:207: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:207: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:207: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:207: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:207: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:207: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:207: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:207: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:207: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:207: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:207: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":"$7a"},{"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":"$7b"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:222: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:222: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:222: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:222: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:222: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:222: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:222: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:222: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:222: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":"$7c"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:222: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":"$7d"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:222: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:222: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:222: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:222: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":"$7e"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:237: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:237: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:237: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:237: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:237: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:237: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:237: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:237: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:237: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":"$7f"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:237: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:237: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:237: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:237: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:237: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":"$80"},{"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":"$81"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:252: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:252: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:252: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:252: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:252: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:252: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:252: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:252: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:252: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:252: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:252: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:252: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:252: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:252: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":"$82"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:267: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:267: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:267: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:267: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:267: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:267: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:267: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:267: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:267: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":"$83"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:267: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:267: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:267: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:267: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:267: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":"$84"},{"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":"$85"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:282: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:282: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:282: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:282: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:282: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:282: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:282: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:282: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:282: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":"$86"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:282: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:282: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:282: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:282: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:282: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":"$87"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:297: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:297: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:297: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:297: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:297: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":"Put OpenRouter-native request fields under `providerOptions.openrouter`:\n\n```ts\nconst model = openrouter(\"anthropic/claude-sonnet-4.6\", {\n providerOptions: {\n openrouter: {\n models: [\"google/gemini-3.1-pro\"],\n provider: {\n zdr: true,\n allowFallbacks: true,\n },\n sessionId: \"support-session-42\",\n },\n },\n});\n```\n\nGeneric Kortyx fields take precedence for normalized concerns such as\n`temperature`, `maxOutputTokens`, `reasoning`, `responseFormat`, and `tools`.\n\nWhen tools or a native JSON schema are present, Kortyx defaults OpenRouter's\n`provider.requireParameters` to `true` unless the caller sets it explicitly.\nThis prevents a route from silently selecting an endpoint that does not accept\nthe required parameters."},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:297: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:297: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:297: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:297: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:297: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":"$88"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:308: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:308: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":"$89"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:308: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:308: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:308: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:308: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:308: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:308: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:308: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:308: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":"$8a"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:319: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:319: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:319: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:319: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:319: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:319: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":"$8b"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:326: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:326: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:326: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":"$8c"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:326: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:326: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:326: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:326: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:326: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:326: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":"$8d"},{"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":"$8e"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:336: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:336:keywords","version":"v0","href":"/docs/sdk/production/observability#configure-opentelemetry-on-the-server","title":"Configure OpenTelemetry on the server","description":"OpenTelemetry","section":"OpenTelemetry","content":"$8f"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:336:keywords","version":"v0","href":"/docs/sdk/production/observability#wire-kortyx-tracing","title":"Wire Kortyx tracing","description":"OpenTelemetry","section":"OpenTelemetry","content":"$90"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:336:keywords","version":"v0","href":"/docs/sdk/production/observability#pass-identity-from-react","title":"Pass identity from React","description":"OpenTelemetry","section":"OpenTelemetry","content":"$91"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:336:keywords","version":"v0","href":"/docs/sdk/production/observability#attach-prompt-metadata","title":"Attach prompt metadata","description":"OpenTelemetry","section":"OpenTelemetry","content":"$92"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:336: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:336: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:336:keywords","version":"v0","href":"/docs/sdk/production/observability#attach-tags-to-traces","title":"Attach tags to traces","description":"OpenTelemetry","section":"OpenTelemetry","content":"$93"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:336: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":"$94"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:336: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":"$95"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:347: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:347: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":"$96"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:347: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":"$97"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:347: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":"$98"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:347: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":"$99"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:347:keywords","version":"v0","href":"/docs/sdk/production/langfuse#map-tags","title":"Map tags","description":"Export To Langfuse","section":"Export To Langfuse","content":"$9a"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:347: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":"$9b"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:347: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":"$9c"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:356: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:356:keywords","version":"v0","href":"/docs/sdk/reference/package-overview#package-map","title":"Package map","description":"Package Overview","section":"Package Overview","content":"$9d"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:356: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":"$9e"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:360: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:360: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:360: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":"$9f"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:360: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:360:keywords","version":"v0","href":"/docs/sdk/reference/api-surface#hooks","title":"Hooks","description":"Main API Surface (kortyx)","section":"Main API Surface (kortyx)","content":"$a0"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:360: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:360: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:360: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:360: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:360: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:360: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":"$a1"},{"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":"$a2"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:372: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:372: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:372: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:372: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:372: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":"$a3"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:372: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:372: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:372: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:372: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:372: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":"$a4"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:372: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":"$a5"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:372: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:372: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:372: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:372:keywords","version":"v0","href":"/docs/sdk/reference/stream-protocol#incremental-mode","title":"Incremental mode","description":"Stream Chunk Protocol","section":"Stream Chunk Protocol","content":"$a6"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:372: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:372: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:372: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":"$a7"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:391: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:391:keywords","version":"v0","href":"/docs/sdk/reference/provider-api#core-types","title":"Core types","description":"Provider API","section":"Provider API","content":"$a8"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:391:keywords","version":"v0","href":"/docs/sdk/reference/provider-api#normalized-call-options","title":"Normalized call options","description":"Provider API","section":"Provider API","content":"$a9"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:391:keywords","version":"v0","href":"/docs/sdk/reference/provider-api#normalized-invoke-results","title":"Normalized invoke results","description":"Provider API","section":"Provider API","content":"$aa"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:391: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":"$ab"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:391: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:391: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":"$ac"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:399: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:399: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:399: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":"$ad"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:403: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:403: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:403: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":"$ae"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:403: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:403: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:403: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:403: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:403: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:403: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:403: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:403:keywords","version":"v0","href":"/docs/sdk/reference/react-client#storage","title":"Storage","description":"React Client (@kortyx/react)","section":"React Client (@kortyx/react)","content":"$af"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:403: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":"$b0"},{"product":"sdk","productLabel":"Kortyx SDK","isLatest":true,"keywords":"$3:props:searchIndex:403: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:417: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:417: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:420: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:420: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:420: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":"$b1"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:424: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:424: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:424: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:424: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:424: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:424:keywords","version":"v0","href":"/docs/studio/overview#child-workflow-visibility","title":"Child workflow visibility","description":"Kortyx Studio Overview","section":"Kortyx Studio Overview","content":"$b2"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:424:keywords","version":"v0","href":"/docs/studio/overview#evaluate-workflow-behavior","title":"Evaluate workflow behavior","description":"Kortyx Studio Overview","section":"Kortyx Studio Overview","content":"$b3"},{"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":"$b4"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:432: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:432: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":"$b5"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:432: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":"$b6"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:432: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:432: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:432: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:432: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":"$b7"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:440: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:440: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:440: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":"$b8"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:440: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":"$b9"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:440: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":"$ba"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:440: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":"$bb"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:440: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:440: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":"$bc"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:449: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:449: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:449: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:449: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:449: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:449: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:449: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":"$bd"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:449: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":"$be"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:449: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:449: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:449: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":"$bf"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:449: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":"$c0"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:449: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":"$c1"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:449: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":"$c2"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:449: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":"$c3"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:465: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":"$c4"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:465: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:465: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:465: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:465: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":"$c5"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:471: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:471: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":"$c6"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:471: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:471: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:471: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:471: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":"$c7"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:471: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:471: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":"$c8"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:480: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:480: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:480: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:480: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:480: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:480: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:480: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:480: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":"$c9"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:480: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:480: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":"$ca"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:491: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:491: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:491: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":"$cb"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:491: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":"$cc"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:491: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":"$cd"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:491: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 read 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 read 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:491: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":"$ce"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:491: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":"$cf"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:491: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:491: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:491: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:491: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:491: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":"$d0"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:505: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:505: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:505: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:505: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:505: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":"$d1"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:505: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:505: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":"$d2"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:505: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:505: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":"$d3"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:505: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:505: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":"$d4"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:505: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":"$d5"},{"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":"$d6"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:518: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":"$d7"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:518: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":"$d8"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:518: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:518: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:518: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:518: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:518: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":"$d9"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:518: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":"$da"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:518: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":"$db"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:528: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":"$dc"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:528: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:528: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:528: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":"$dd"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:528: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":"$de"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:528: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":"$df"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:528: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":"$e0"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:528: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":"$e1"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:528: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":["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":"$e2"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:538: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":"$e3"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:538: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":"$e4"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:538: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":"$e5"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:538: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":"$e6"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:538: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:538: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":"$e7"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:538: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":"$e8"},{"product":"studio","productLabel":"Kortyx Studio","isLatest":true,"keywords":"$3:props:searchIndex:538: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":"$e9"}],"className":""}]