Studio previewSelf-host Studio locally.Run it
Kortyx
Open Kortyx on GitHub
Open navigation
ProductExamplesOpen sourceDocs

Groq Provider

Updated 22 days ago • September 11, 2026

@kortyx/groq is the Groq provider package for Kortyx.

It gives you two entry points:

  • groq: a batteries-included default provider selector
  • createGroq(...): an explicit factory for custom setup

1. Install the package

pnpm add @kortyx/groq

2. What the package exports

import { MODELS, PROVIDER_ID, createGroq, groq } from "@kortyx/groq";

What each export is for:

  • groq: default provider selector for the fastest start
  • createGroq(...): custom provider instance with explicit settings
  • MODELS: built-in Groq model ids exposed by the package
  • PROVIDER_ID: the provider id string, currently "groq"

3. Basic usage in the same file

import { groq } from "@kortyx/groq"; const model = groq("llama-3.3-70b-versatile");

groq is a provider selector, which means:

  • it is callable: groq("llama-3.3-70b-versatile")
  • it also exposes provider metadata: groq.id, groq.models
groq.id; // "groq" groq.models; // readonly list of built-in model ids

Good to know: The built-in model list gives autocomplete, but arbitrary Groq-compatible model ids are accepted as strings.

4. Shared app bootstrap usage

If you want one shared import path across your app, re-export groq from a bootstrap file such as src/lib/providers.ts.

src/lib/providers.ts
export { groq } from "@kortyx/groq";

Then import it from that file where you actually use it:

src/nodes/chat.node.ts
import { groq } from "@/lib/providers";

5. Advanced usage with explicit settings

Use createGroq(...) when you want app-owned configuration instead of the default environment-based setup.

import { createGroq } from "@kortyx/groq"; export const groq = createGroq({ apiKey: process.env.GROQ_API_KEY, });

Use the factory when you need to:

  • pass apiKey explicitly
  • use a custom baseUrl
  • provide a custom fetch

6. Credentials and first-use behavior

The default groq export resolves credentials on first use, not at import time.

Supported environment variables:

  • GROQ_API_KEY
  • KORTYX_GROQ_API_KEY

If 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.

7. Create model refs for workflow and node params

params: { model: groq("llama-3.3-70b-versatile"), temperature: 0.3, }

You can also attach default model options to the ref itself:

const model = groq("qwen/qwen3-32b", { providerOptions: { groq: { reasoningFormat: "parsed", serviceTier: "auto", }, }, });

Those become default options for later useReason(...) calls unless you override them at call time.

8. Use the model with useReason(...)

import { useReason } from "kortyx"; import { groq } from "@/lib/providers"; const result = await useReason({ model: groq("llama-3.3-70b-versatile"), input: "Write a concise answer for a support engineer.", temperature: 0.3, emit: true, stream: true, }); result.text; result.usage; result.finishReason; result.providerMetadata; result.warnings;

Good to know: Provider setup is not done on createAgent(...). Model selection happens where you call useReason(...) by passing a model ref.

9. Supported normalized call options

Groq currently maps these generic Kortyx options:

  • temperature
  • streaming
  • maxOutputTokens
  • stopSequences
  • abortSignal
  • reasoning.effort
  • reasoning.maxTokens
  • responseFormat.type
  • responseFormat.schema

Current Groq provider options:

  • providerOptions.groq.reasoningFormat
  • providerOptions.groq.reasoningEffort
  • providerOptions.groq.serviceTier
  • providerOptions.groq.structuredOutputs
  • providerOptions.groq.strictJsonSchema

Current mapping details:

  • responseFormat.type: "json" maps to Groq JSON mode
  • responseFormat.schema maps to Groq JSON schema output unless structuredOutputs is false
  • generic reasoning effort maps to Groq none, low, medium, or high
  • temperature defaults to 0.7 when you do not set it

Current warning-backed gaps:

  • Groq does not expose a generic reasoning token budget through this provider
  • unsupported generic reasoning effort values are reported in result.warnings
  • unknown providerOptions keys are ignored and reported in result.warnings

10. Normalized metadata you get back

Groq returns the normalized Kortyx result fields when the API provides them:

  • usage
  • finishReason
  • providerMetadata
  • warnings
  • raw

Groq-specific metadata currently includes fields such as:

  • providerId
  • modelId
  • responseId
  • responseModel
  • created
  • usage
  • cachedTokens
  • reasoningTokens

Use providerMetadata when you need debugging or observability details without coupling your app code to the raw provider payload shape.

Supported scope

@kortyx/groq currently supports text generation through Groq chat completions via useReason(...), including streaming and non-streaming invocation.

It 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.

Available built-in Groq model ids

  • llama-3.1-8b-instant
  • llama-3.3-70b-versatile
  • openai/gpt-oss-120b
  • openai/gpt-oss-20b
  • qwen/qwen3-32b

Next steps

  • See Hooks for useReason(...) behavior and structured output
  • See Provider API for the shared normalized provider contract

Reasoning, tools, and structured output

Use a model supporting the requested combination, such as openai/gpt-oss-120b for reasoning and schema output. GPT-OSS cannot disable reasoning. Unsupported settings fail explicitly; no model or reasoning fallback is applied.

Groq does not currently support native schema output together with tools or streaming. When you provide only outputSchema, useReason runs tool rounds and reuses an answer that passes the original local validator, with a compatibility warning. This avoids an extra model call; two tool rounds plus a valid answer fit the default three steps. If validation fails, it makes a separate schema-only final request using the same model and reasoning settings. An explicit responseFormat.schema (including a model default) always requires that native finalization, even when the draft is valid. The extra request counts toward toolExecution.maxSteps, execution model-pass limits, usage and Studio telemetry; allow four steps for two tool rounds when finalization is needed. Approval/resume and cancellation cover finalization too. Schema-only responses are buffered even when stream: true.

Direct provider requests combining native schemas and tools fail with guidance. An explicit providerOptions.groq.structuredOutputs: false retains JSON mode plus local validation; Kortyx does not silently choose that weaker mode. reasoningFormat: "raw" cannot be combined with tools or JSON output.

See Groq structured-output restrictions.