Groq core workflow a

Groq Core Workflow A: Chat, Tools & Structured Output

Overview

Primary integration patterns for Groq: chat completions, tool/function calling, JSON mode, and structured outputs. Groq's LPU delivers sub-200ms time-to-first-token, making these patterns viable for real-time user-facing features. This skill walks through five workflow steps; the lean skeleton lives here, and the full copy-paste code lives in references/.

Prerequisites

• Install the SDK with npm install groq-sdk.
• Set GROQ_API_KEY in the environment (see Authentication below).
• Familiarity with the Groq model line-up and which model fits each task.

Authentication

Groq authenticates via an API key. Create one at console.groq.com/keys and export it as GROQ_API_KEY; the SDK reads it automatically, so new Groq() needs no explicit argument. Never hardcode the key — read it from the environment (or a secrets manager) so it stays out of source control.

Model Selection for This Workflow

Task	Recommended Model	Why
Chat with tools	llama-3.3-70b-versatile	Best tool-calling accuracy
JSON extraction	llama-3.1-8b-instant	Fast, accurate for structured tasks
Structured outputs	llama-3.3-70b-versatile	Supports strict: true schema compliance
Vision + chat	meta-llama/llama-4-scout-17b-16e-instruct	Multimodal input

Instructions

Work through the five patterns in order. Read the target file, then Write or Edit the integration code into your project.

1. Chat completion — send system + user messages to groq.chat.completions.create and return choices[0].message.content plus usage. Skeleton below; full example in worked examples.
2. Tool use / function calling — a three-phase loop: send the message with tools + tool_choice: "auto", execute any returned tool_calls, then send the results back for the final answer. Full code in implementation.
3. JSON mode — set response_format: { type: "json_object" } and describe the JSON shape in the system prompt. See implementation.
4. Structured outputs — use response_format.json_schema with strict: true for guaranteed schema compliance (no post-validation). See implementation.
5. Multi-turn conversation — accumulate the message history and push each assistant reply back onto the stack. See worked examples.

Minimal chat skeleton:

import Groq from "groq-sdk";
const groq = new Groq();

const completion = await groq.chat.completions.create({
  model: "llama-3.3-70b-versatile",
  messages: [
    { role: "system", content: "You are a concise technical assistant." },
    { role: "user", content: userMessage },
  ],
  temperature: 0.7,
  max_tokens: 1024,
});
// completion.choices[0].message.content, completion.usage

Output

Each pattern returns a predictable shape:

• Chat completion — { reply: string, usage: {...} }; usage carries prompt_tokens / completion_tokens for cost metering.
• Tool use — the final assistant content string, produced after the tool results are fed back; intermediate tool_calls carry function.name and a JSON-string function.arguments.
• JSON mode — a parsed JavaScript object matching the shape described in the system prompt (parse message.content with JSON.parse).
• Structured outputs — a parsed object guaranteed to satisfy the declared JSON schema, so no downstream validation is required.
• Multi-turn — the latest reply string, with conversation state retained in the class instance for the next turn.

Error Handling

Error	Cause	Solution
tool_calls with malformed JSON	Model hallucinated arguments	Wrap JSON.parse in try/catch, retry with lower temperature
json_object returns non-JSON	System prompt missing JSON instruction	Always include "respond with JSON" in system prompt
context_length_exceeded	Conversation too long	Trim older messages, keep system prompt
Tool call loop	Model keeps calling tools	Set tool_choice: "none" on final completion

Examples

The chat skeleton above is the smallest complete call. Two fuller runnable examples live in worked examples:

• Example 1 — Chat completion with system prompt + rolling history, returning reply and token usage.
• Example 2 — Multi-turn conversation class that retains context across turns.

For tool use, JSON mode, and strict structured outputs, see full implementation.

Resources

• Groq Tool Use Docs
• Groq Structured Outputs
• Groq Text Generation
• Full implementation — tool use, JSON mode, structured outputs
• Worked examples — chat completion, multi-turn conversation

Next Steps

For audio, vision, and speech workflows, see the companion groq-core-workflow-b skill, which covers Whisper transcription, vision inputs, and text-to-speech.