Repository: VoltAgent/voltagent
Pull request #40: feat(groq-ai): initial implementation using groq-sdk
Author: login: TheEmi
Created: 2025-04-24T22:16:39Z | Merged: 2025-04-26T01:12:18Z

Initial implementation of GroqProvider class

This includes:

`GroqProvider` class implementing `LLMProvider`.
Integration with the `groq-sdk`.
Implementation of `generateText`, `streamText`, `generateObject`.
Stub for `streamObject`.
Basic build (tsup.config.ts, tsconfig.json) and package (package.json) setup copied from `VercelAIProvider`.


Diff:
diff --git a/.changeset/gold-jokes-design.md b/.changeset/gold-jokes-design.md
new file mode 100644
index 000000000..b9f152b8a
--- /dev/null
+++ b/.changeset/gold-jokes-design.md
@@ -0,0 +1,13 @@
+---
+"@voltagent/groq-ai": major
+---
+
+feat(groq-ai): initial implementation using groq-sdk
+
+GroqProvider class implementing LLMProvider.
+Integration with the groq-sdk.
+Implementation of generateText, streamText, generateObject.
+Stub for streamObject.
+Basic build (tsup.config.ts, tsconfig.json) and package (package.json) setup copied from VercelAIProvider.
+
+Feature #13
diff --git a/examples/with-groq-ai/.gitignore b/examples/with-groq-ai/.gitignore
new file mode 100644
index 000000000..0ca39c007
--- /dev/null
+++ b/examples/with-groq-ai/.gitignore
@@ -0,0 +1,3 @@
+node_modules
+dist
+.DS_Store
diff --git a/examples/with-groq-ai/README.md b/examples/with-groq-ai/README.md
new file mode 100644
index 000000000..b37cf9e02
--- /dev/null
+++ b/examples/with-groq-ai/README.md
@@ -0,0 +1,53 @@
+<div align="center">
+<a href="https://voltagent.dev/">
+<img width="1800" alt="435380213-b6253409-8741-462b-a346-834cd18565a9" src="https://github.com/user-attachments/assets/452a03e7-eeda-4394-9ee7-0ffbcf37245c" />
+</a>
+
+<br/>
+<br/>
+
+<div align="center">
+    <a href="https://voltagent.dev">Home Page</a> |
+    <a href="https://voltagent.dev/docs/">Documentation</a> |
+    <a href="https://github.com/voltagent/voltagent/tree/main/examples">Examples</a> |
+    <a href="https://s.voltagent.dev/discord">Discord</a> |
+    <a href="https://voltagent.dev/blog/">Blog</a>
+</div>
+</div>
+
+<br/>
+
+<div align="center">
+    <strong>VoltAgent is an open source TypeScript framework for building and orchestrating AI agents.</strong><br>
+Escape the limitations of no-code builders and the complexity of starting from scratch.
+    <br />
+    <br />
+</div>
+
+<div align="center">
+    
+[![npm version](https://img.shields.io/npm/v/@voltagent/core.svg)](https://www.npmjs.com/package/@voltagent/core)
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](CODE_OF_CONDUCT.md)
+[![Discord](https://img.shields.io/discord/1361559153780195478.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://s.voltagent.dev/discord)
+[![Twitter Follow](https://img.shields.io/twitter/follow/voltagent_dev?style=social)](https://twitter.com/voltagent_dev)
+    
+</div>
+
+<br/>
+
+<div align="center">
+<a href="https://voltagent.dev/">
+<img width="896" alt="Screenshot 2025-04-20 at 22 44 38" src="https://github.com/user-attachments/assets/f0627868-6153-4f63-ba7f-bdfcc5dd603d" />
+</a>
+
+</div>
+
+## VoltAgent: Build AI Agents Fast and Flexibly
+
+VoltAgent is an open-source TypeScript framework for creating and managing AI agents. It provides modular components to build, customize, and scale agents with ease. From connecting to APIs and memory management to supporting multiple LLMs, VoltAgent simplifies the process of creating sophisticated AI systems. It enables fast development, maintains clean code, and offers flexibility to switch between models and tools without vendor lock-in.
+
+## Try Example
+
+```bash
+npm create voltagent-app@latest -- --example with-groq-ai
+```
diff --git a/examples/with-groq-ai/package.json b/examples/with-groq-ai/package.json
new file mode 100644
index 000000000..9655ad9e8
--- /dev/null
+++ b/examples/with-groq-ai/package.json
@@ -0,0 +1,29 @@
+{
+  "name": "voltagent-example-groq-ai",
+  "private": true,
+  "keywords": [
+    "voltagent",
+    "ai",
+    "agent"
+  ],
+  "license": "MIT",
+  "author": "",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch --env-file=.env ./src ",
+    "start": "node dist/index.js",
+    "volt": "volt"
+  },
+  "dependencies": {
+    "@voltagent/cli": "^0.1.2",
+    "@voltagent/core": "^0.1.3",
+    "@voltagent/groq-ai": "^0.1.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.5",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  }
+}
diff --git a/examples/with-groq-ai/src/index.ts b/examples/with-groq-ai/src/index.ts
new file mode 100644
index 000000000..fbb375741
--- /dev/null
+++ b/examples/with-groq-ai/src/index.ts
@@ -0,0 +1,15 @@
+import { VoltAgent, Agent } from "@voltagent/core";
+import { GroqProvider } from "@voltagent/groq-ai";
+
+const agent = new Agent({
+  name: "finance",
+  description: "A helpful assistant that answers questions without using tools",
+  llm: new GroqProvider(),
+  model: "meta-llama/llama-4-scout-17b-16e-instruct",
+});
+
+new VoltAgent({
+  agents: {
+    agent,
+  },
+});
diff --git a/examples/with-groq-ai/tsconfig.json b/examples/with-groq-ai/tsconfig.json
new file mode 100644
index 000000000..cee90c6f3
--- /dev/null
+++ b/examples/with-groq-ai/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "outDir": "dist",
+    "skipLibCheck": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/packages/groq-ai/CHANGELOG.md b/packages/groq-ai/CHANGELOG.md
new file mode 100644
index 000000000..e69de29bb
diff --git a/packages/groq-ai/README.md b/packages/groq-ai/README.md
new file mode 100644
index 000000000..6ec47dc00
--- /dev/null
+++ b/packages/groq-ai/README.md
@@ -0,0 +1,41 @@
+# @voltagent/groq-ai
+
+VoltAgent Groq AI provider integration using the Groq SDK (`@groq-sdk`).
+
+This package allows you to use Gorq's fast inferencing models within your VoltAgent agents.
+
+## Installation
+
+```bash
+npm install @voltagent/groq-ai
+# or
+yarn add @voltagent/groq-ai
+# or
+pnpm add @voltagent/groq-ai
+```
+
+## Usage
+
+You need to provide your Groq API key. You can get one from [Groq](https://groq.com/) after signing up.
+
+```typescript
+import { VoltAgent, Agent } from "@voltagent/core";
+import { GroqProvider } from "@voltagent/groq-ai";
+
+const agent = new Agent({
+  name: "finance",
+  description: "A helpful assistant that answers questions without using tools",
+  llm: new GroqProvider(),
+  model: "meta-llama/llama-4-scout-17b-16e-instruct",
+});
+
+new VoltAgent({
+  agents: {
+    agent,
+  },
+});
+```
+
+## License
+
+Licensed under the MIT License, Copyright © 2025-present VoltAgent.
diff --git a/packages/groq-ai/jest.config.js b/packages/groq-ai/jest.config.js
new file mode 100644
index 000000000..51110a4ca
--- /dev/null
+++ b/packages/groq-ai/jest.config.js
@@ -0,0 +1,11 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  testMatch: ["**/__tests__/**/*.test.ts", "**/*.spec.ts"],
+  transform: {
+    "^.+\\.ts$": "ts-jest",
+  },
+  coverageDirectory: "coverage",
+  collectCoverageFrom: ["src/**/*.ts", "!src/**/*.d.ts", "!src/**/index.ts"],
+};
diff --git a/packages/groq-ai/package.json b/packages/groq-ai/package.json
new file mode 100644
index 000000000..c81164cbd
--- /dev/null
+++ b/packages/groq-ai/package.json
@@ -0,0 +1,34 @@
+{
+  "name": "@voltagent/groq-ai",
+  "version": "0.1.0",
+  "description": "VoltAgent Groq AI - Groq provider integration for VoltAgent",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "dist/*.map"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src --ext .ts,.tsx",
+    "test": "jest --passWithNoTests"
+  },
+  "dependencies": {
+    "@voltagent/core": "^0.1.3",
+    "groq-sdk": "^0.20.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^18.15.11",
+    "eslint": "^8.0.0",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "tsup": "^6.7.0",
+    "typescript": "^5.0.4"
+  }
+}
diff --git a/packages/groq-ai/src/index.ts b/packages/groq-ai/src/index.ts
new file mode 100644
index 000000000..5fe39dc21
--- /dev/null
+++ b/packages/groq-ai/src/index.ts
@@ -0,0 +1,330 @@
+import type {
+  BaseMessage,
+  GenerateObjectOptions,
+  GenerateTextOptions,
+  LLMProvider,
+  MessageRole,
+  ProviderObjectResponse,
+  ProviderObjectStreamResponse,
+  ProviderTextResponse,
+  ProviderTextStreamResponse,
+  StepWithContent,
+  StreamObjectOptions,
+  StreamTextOptions,
+} from "@voltagent/core";
+import type { z } from "zod";
+import { GroqProviderOptions, GroqMessage } from "./types";
+import { Groq } from "groq-sdk";
+
+export class GroqProvider implements LLMProvider<string> {
+  // @ts-ignore
+  private groq: Groq;
+  constructor(private options?: GroqProviderOptions) {
+    // Bind methods to preserve 'this' context
+    this.groq = new Groq({
+      apiKey: this.options?.apiKey || process.env.GROQ_API_KEY,
+    });
+    this.generateText = this.generateText.bind(this);
+    this.streamText = this.streamText.bind(this);
+    this.generateObject = this.generateObject.bind(this);
+    this.streamObject = this.streamObject.bind(this);
+    this.toMessage = this.toMessage.bind(this);
+    this.createStepFromChunk = this.createStepFromChunk.bind(this);
+    this.getModelIdentifier = this.getModelIdentifier.bind(this);
+  }
+
+  getModelIdentifier = (model: Groq.Model): string => {
+    return model.id;
+  };
+
+  toMessage = (message: BaseMessage): Groq.Chat.ChatCompletionMessageParam => {
+    const groqMessage: GroqMessage = {
+      role: message.role,
+      content:
+        typeof message.content === "string" ? message.content : JSON.stringify(message.content),
+    };
+    return groqMessage;
+  };
+
+  createStepFromChunk = (chunk: {
+    type: string;
+    [key: string]: any;
+  }): StepWithContent | null => {
+    if (chunk.type === "text" && chunk.text) {
+      return {
+        id: "",
+        type: "text",
+        content: chunk.text,
+        role: "assistant" as MessageRole,
+        usage: chunk.usage || undefined,
+      };
+    }
+    return null;
+  };
+
+  generateText = async (
+    options: GenerateTextOptions<string>,
+  ): Promise<ProviderTextResponse<any>> => {
+    try {
+      const groqMessages = options.messages.map(this.toMessage);
+
+      // Extract common parameters
+      const {
+        temperature = 0.7,
+        maxTokens,
+        topP,
+        frequencyPenalty,
+        presencePenalty,
+        stopSequences,
+      } = options.provider || {};
+
+      // Call Groq API
+      const response = await this.groq.chat.completions.create({
+        model: options.model,
+        messages: groqMessages,
+        temperature,
+        max_tokens: maxTokens,
+        top_p: topP,
+        frequency_penalty: frequencyPenalty,
+        presence_penalty: presencePenalty,
+        stop: stopSequences,
+      });
+
+      // Extract usage information
+      const usage = response.usage
+        ? {
+            promptTokens: response.usage.prompt_tokens,
+            completionTokens: response.usage.completion_tokens,
+            totalTokens: response.usage.total_tokens,
+          }
+        : undefined;
+
+      // Handle step finish callback
+      if (options.onStepFinish) {
+        // If there's text content, create a text step
+        if (response.choices[0].message.content) {
+          const textStep = this.createStepFromChunk({
+            type: "text",
+            text: response.choices[0].message.content,
+            usage,
+          });
+          if (textStep) await options.onStepFinish(textStep);
+        }
+      }
+
+      // Return standardized response
+      return {
+        provider: response,
+        text: response.choices[0].message.content || "",
+        usage,
+        finishReason: response.choices[0].finish_reason,
+      };
+    } catch (error) {
+      // Handle API errors
+      console.error("Groq API error:", error);
+      throw error;
+    }
+  };
+
+  async streamText(options: StreamTextOptions<string>): Promise<ProviderTextStreamResponse<any>> {
+    try {
+      const groqMessages = options.messages.map(this.toMessage);
+      // Extract common parameters
+      const {
+        temperature = 0.7,
+        maxTokens,
+        topP,
+        frequencyPenalty,
+        presencePenalty,
+        stopSequences,
+      } = options.provider || {};
+
+      // Create stream from Groq API
+      const stream = await this.groq.chat.completions.create({
+        model: options.model,
+        messages: groqMessages,
+        temperature,
+        max_tokens: maxTokens,
+        top_p: topP,
+        frequency_penalty: frequencyPenalty,
+        presence_penalty: presencePenalty,
+        stop: stopSequences,
+        // Enable streaming
+        stream: true,
+      });
+
+      let accumulatedText = "";
+      let usage: any;
+      let finishReason: string | undefined;
+
+      // Create a readable stream to return to the caller
+      const textStream = new ReadableStream({
+        async start(controller) {
+          try {
+            // Process each chunk from the Groq stream
+            for await (const chunk of stream) {
+              // Extract content from the chunk
+              const content = chunk.choices[0]?.delta?.content || "";
+
+              // If we have content, add it to accumulated text and emit it
+              if (content) {
+                accumulatedText += content;
+                controller.enqueue(content);
+
+                // Call onChunk with text chunk
+                if (options.onChunk) {
+                  const step = {
+                    id: "",
+                    type: "text" as const,
+                    content,
+                    role: "assistant" as MessageRole,
+                  };
+                  await options.onChunk(step);
+                }
+              }
+
+              // Extract finish reason and usage when available
+              if (chunk.choices[0]?.finish_reason) {
+                finishReason = chunk.choices[0].finish_reason;
+              }
+
+              if (chunk.x_groq?.usage) {
+                usage = {
+                  promptTokens: chunk.x_groq?.usage.prompt_tokens,
+                  completionTokens: chunk.x_groq?.usage.completion_tokens,
+                  totalTokens: chunk.x_groq?.usage.total_tokens,
+                };
+              }
+            }
+
+            // When stream completes, close the controller
+            controller.close();
+
+            // Call onFinish with complete result
+            if (options.onFinish) {
+              await options.onFinish({
+                text: accumulatedText,
+                usage,
+                finishReason,
+              });
+            }
+
+            // Call onStepFinish with complete result if provided
+            if (options.onStepFinish) {
+              if (accumulatedText) {
+                const textStep = {
+                  id: "",
+                  type: "text" as const,
+                  content: accumulatedText,
+                  role: "assistant" as MessageRole,
+                  usage,
+                };
+                await options.onStepFinish(textStep);
+              }
+            }
+          } catch (error) {
+            // Handle errors during streaming
+            console.error("Error during Groq stream processing:", error);
+            controller.error(error);
+            if (options.onError) options.onError(error);
+          }
+        },
+      });
+
+      // Return provider and text stream
+      return {
+        provider: stream,
+        textStream,
+      };
+    } catch (error) {
+      // Handle API errors
+      console.error("Groq streaming API error:", error);
+      if (options.onError) options.onError(error);
+      throw error;
+    }
+  }
+
+  // Generate object with Groq API (if supported)
+  async generateObject<TSchema extends z.ZodType>(
+    options: GenerateObjectOptions<string, TSchema>,
+  ): Promise<ProviderObjectResponse<any, z.infer<TSchema>>> {
+    try {
+      const groqMessages = options.messages.map(this.toMessage);
+
+      // Add system message instructing to generate JSON following the schema
+      const schemaDescription =
+        options.schema.description ||
+        "Respond with a JSON object according to the specified schema.";
+      const systemMessage = {
+        role: "system",
+        content: `${schemaDescription}\nRespond with ONLY a valid JSON object, nothing else.`,
+      };
+
+      // Extract common parameters
+      const {
+        temperature = 0.2, // Lower temperature for more deterministic JSON generation
+        maxTokens,
+        topP,
+      } = options.provider || {};
+
+      // Call Groq API with JSON mode
+      const response = await this.groq.chat.completions.create({
+        model: options.model,
+        messages: [systemMessage, ...groqMessages],
+        temperature,
+        max_tokens: maxTokens,
+        top_p: topP,
+        response_format: { type: "json_object" },
+      });
+
+      // Parse JSON response
+      let parsedObject: z.infer<TSchema>;
+      try {
+        const content = response.choices[0].message.content || "{}";
+        const rawObject = JSON.parse(content);
+        parsedObject = options.schema.parse(rawObject);
+      } catch (parseError: any) {
+        console.error("Error parsing JSON from Groq response:", parseError);
+        throw new Error(`Failed to parse JSON response: ${parseError.message}`);
+      }
+
+      // Extract usage information
+      const usage = response.usage
+        ? {
+            promptTokens: response.usage.prompt_tokens,
+            completionTokens: response.usage.completion_tokens,
+            totalTokens: response.usage.total_tokens,
+          }
+        : undefined;
+
+      // Call onStepFinish if provided
+      if (options.onStepFinish) {
+        const step = {
+          id: "",
+          type: "text" as const,
+          content: JSON.stringify(parsedObject, null, 2),
+          role: "assistant" as MessageRole,
+          usage,
+        };
+        await options.onStepFinish(step);
+      }
+
+      // Return standardized response
+      return {
+        provider: response,
+        object: parsedObject,
+        usage,
+        finishReason: response.choices[0].finish_reason,
+      };
+    } catch (error) {
+      console.error("Groq generateObject API error:", error);
+      throw error;
+    }
+  }
+
+  async streamObject<TSchema extends z.ZodType>(
+    options: StreamObjectOptions<string, TSchema>,
+  ): Promise<ProviderObjectStreamResponse<any, z.infer<TSchema>>> {
+    throw new Error("streamObject is not implemented for GoogleGenAIProvider yet.");
+  }
+}
diff --git a/packages/groq-ai/src/types.ts b/packages/groq-ai/src/types.ts
new file mode 100644
index 000000000..404f0daef
--- /dev/null
+++ b/packages/groq-ai/src/types.ts
@@ -0,0 +1,9 @@
+export interface GroqProviderOptions {
+  apiKey?: string;
+}
+
+// Define Groq message format
+export interface GroqMessage {
+  role: string;
+  content: string;
+}
diff --git a/packages/groq-ai/tsconfig.json b/packages/groq-ai/tsconfig.json
new file mode 100644
index 000000000..f956d4bf3
--- /dev/null
+++ b/packages/groq-ai/tsconfig.json
@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "es2015",
+    "module": "esnext",
+    "lib": ["dom", "esnext"],
+    "declaration": true,
+    "sourceMap": true,
+    "moduleResolution": "node",
+    "skipLibCheck": true,
+    "strict": true,
+    "isolatedModules": true,
+    "noFallthroughCasesInSwitch": true,
+    "esModuleInterop": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "resolveJsonModule": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "test"]
+}
diff --git a/packages/groq-ai/tsup.config.ts b/packages/groq-ai/tsup.config.ts
new file mode 100644
index 000000000..f39017936
--- /dev/null
+++ b/packages/groq-ai/tsup.config.ts
@@ -0,0 +1,17 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["cjs", "esm"],
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  target: "es2015",
+  outDir: "dist",
+  minify: false,
+  dts: true,
+  esbuildOptions(options) {
+    options.keepNames = true;
+    return options;
+  },
+});
diff --git a/website/docs/agents/providers.md b/website/docs/agents/providers.md
index aad687e51..92955a4f6 100644
--- a/website/docs/agents/providers.md
+++ b/website/docs/agents/providers.md
@@ -140,6 +140,31 @@ const agentVertex = new Agent({
 
 **Choose `@voltagent/google-ai` when:** You specifically want to use Google's Gemini models via their dedicated SDK. It also supports Vertex AI configurations but only for server-side usage.
 
+### `@voltagent/groq-ai` (Groq Provider)
+
+Implements the [groq-sdk](https://github.com/groq/groq-typescript) as a provider to allow inferencing [supported models](https://console.groq.com/docs/models).
+
+```ts
+import { Agent } from "@voltagent/core";
+import { GroqProvider } from "@voltagent/groq-ai";
+
+// Instantiate the provider, optionally passing the API key to overwrite the default GROQ_API_KEY
+const groqProvider = new GroqProvider({
+  //apiKey: process.env.GROQ_API_KEY,
+});
+
+const agent = new Agent({
+  name: "Groq Assistant",
+  description: "A helpful assistant using the groq-ai provider",
+  llm: groqProvider,
+  // Pass the model name as a string recognized by the target API
+  model: "meta-llama/llama-4-scout-17b-16e-instruct", //Example for Ollama
+  //See groq documentation for others
+});
+```
+
+**Choose `@voltagent/groq-ai` when:** You need to connect specifically to Groq API used for fast inferencing of supported models.
+
 ## The `model` Parameter
 
 When creating an `Agent`, the `model` parameter's value is interpreted _by the selected `llm` provider_. Each provider uses its `getModelIdentifier` method to process this value.


Reviews:
user: login: omeraplak
state: APPROVED
author_association: MEMBER
submitted_at: 2025-04-26T00:51:12Z

Review comments:
diff_hunk: @@ -0,0 +1,53 @@
+<div align="center">
+<a href="https://voltagent.dev/">
+<img width="1800" alt="435380213-b6253409-8741-462b-a346-834cd18565a9" src="https://github.com/user-attachments/assets/452a03e7-eeda-4394-9ee7-0ffbcf37245c" />
+</a>
+
+<br/>
+<br/>
+
+<div align="center">
+    <a href="https://voltagent.dev">Home Page</a> |
+    <a href="https://voltagent.dev/docs/">Documentation</a> |
+    <a href="https://github.com/voltagent/voltagent/tree/main/examples">Examples</a> |
+    <a href="https://s.voltagent.dev/discord">Discord</a> |
+    <a href="https://voltagent.dev/blog/">Blog</a>
+</div>
+</div>
+
+<br/>
+
+<div align="center">
+    <strong>VoltAgent is an open source TypeScript framework for building and orchestrating AI agents.</strong><br>
+Escape the limitations of no-code builders and the complexity of starting from scratch.
+    <br />
+    <br />
+</div>
+
+<div align="center">
+    
+[![npm version](https://img.shields.io/npm/v/@voltagent/core.svg)](https://www.npmjs.com/package/@voltagent/core)
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](CODE_OF_CONDUCT.md)
+[![Discord](https://img.shields.io/discord/1361559153780195478.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://s.voltagent.dev/discord)
+[![Twitter Follow](https://img.shields.io/twitter/follow/voltagent_dev?style=social)](https://twitter.com/voltagent_dev)
+    
+</div>
+
+<br/>
+
+<div align="center">
+<a href="https://voltagent.dev/">
+<img width="896" alt="Screenshot 2025-04-20 at 22 44 38" src="https://github.com/user-attachments/assets/f0627868-6153-4f63-ba7f-bdfcc5dd603d" />
+</a>
+
+</div>
+
+## VoltAgent: Build AI Agents Fast and Flexibly
+
+VoltAgent is an open-source TypeScript framework for creating and managing AI agents. It provides modular components to build, customize, and scale agents with ease. From connecting to APIs and memory management to supporting multiple LLMs, VoltAgent simplifies the process of creating sophisticated AI systems. It enables fast development, maintains clean code, and offers flexibility to switch between models and tools without vendor lock-in.
+
+## Try Example
+
+```bash
+npm create voltagent-app@latest -- --example with-vercel-ai
path: examples/with-groq-ai/README.md
user: login: omeraplak
body: ```suggestion
npm create voltagent-app@latest -- --example with-groq-ai
```
created_at: 2025-04-26T00:46:00Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,20 @@
+# @voltagent/vercel-ai
+
+## 0.1.1
+
+- 🚀 **Introducing VoltAgent: TypeScript AI Agent Framework!**
+
+  This initial release marks the beginning of VoltAgent, a powerful toolkit crafted for the JavaScript developer community. We saw the challenges: the complexity of building AI from scratch, the limitations of No-Code tools, and the lack of first-class AI tooling specifically for JS.
+
+  ![VoltAgent Demo](https://cdn.voltagent.dev/readme/demo.gif)
+  VoltAgent aims to fix that by providing the building blocks you need:
+
+  - **`@voltagent/core`**: The foundational engine for agent capabilities.
+  - **`@voltagent/voice`**: Easily add voice interaction.
+  - **`@voltagent/vercel-ai`**: Seamless integration with [Vercel AI SDK](https://sdk.vercel.ai/docs/introduction).
+  - **`@voltagent/xsai`**: A Seamless integration with [xsAI](https://xsai.js.org/).
+  - **`@voltagent/cli` & `create-voltagent-app`**: Quick start tools to get you building _fast_.
+
+  We're combining the flexibility of code with the clarity of visual tools (like our **currently live [VoltAgent Console](https://console.voltagent.dev/)**) to make AI development easier, clearer, and more powerful. Join us as we build the future of AI in JavaScript!
+
+  Explore the [Docs](https://voltagent.dev/docs/) and join our [Discord community](https://s.voltagent.dev/discord)!
path: packages/groq-ai/CHANGELOG.md
user: login: omeraplak
body: ```suggestion
```
created_at: 2025-04-26T00:47:03Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,41 @@
+# @voltagent/groq-ai
+
+VoltAgent Groq AI provider integration using the Groq SDK (`@groq-sdk`).
+
+This package allows you to use Gorq's fast inferencing models within your VoltAgent agents.
+
+## Installation
+
+```bash
+npm install @voltagent/groq-ai
+# or
+yarn add @voltagent/groq-ai
+# or
+pnpm add @voltagent/groq-ai
+```
+
+## Usage
+
+You need to provide your Groq API key. You can get one from [Groq](https://groq.com/) after signing up.
+
+```typescript
+import { VoltAgent, Agent } from "@voltagent/core";
+import { GroqProvider } from "@voltagent/groq-ai";
+
+const agent = new Agent({
+  name: "finance",
+  description: "A helpful assistant that answers questions without using tools",
+  llm: new GroqProvider(),
path: packages/groq-ai/README.md
user: login: omeraplak
body: ```suggestion
  llm: new GroqProvider({
     apiKey: process.env.GROQ_API_KEY,
  }),
```
Would this be clearer this way?


created_at: 2025-04-26T00:50:04Z
author_association: MEMBER
diff_hunk: @@ -140,6 +140,31 @@ const agentVertex = new Agent({
 
 **Choose `@voltagent/google-ai` when:** You specifically want to use Google's Gemini models via their dedicated SDK. It also supports Vertex AI configurations but only for server-side usage.
 
+### `@voltagent/groq-ai` (Groq Provider)
+
+Implements the [groq-sdk](https://github.com/groq/groq-typescript) as a provider to allow inferencing [supported models](https://console.groq.com/docs/models).
+
+```ts
+import { Agent } from "@voltagent/core";
+import { GroqProvider } from "@voltagent/groq-ai";
+
+// Instantiate the provider, optionally passing the API key to overwrite the default GROQ_API_KEY
path: website/docs/agents/providers.md
user: login: omeraplak
body: ```suggestion
// Instantiate the provider, optionally passing the API key to overwrite the default process.env.GROQ_API_KEY
```
created_at: 2025-04-26T00:50:38Z
author_association: MEMBER
diff_hunk: @@ -140,6 +140,31 @@ const agentVertex = new Agent({
 
 **Choose `@voltagent/google-ai` when:** You specifically want to use Google's Gemini models via their dedicated SDK. It also supports Vertex AI configurations but only for server-side usage.
 
+### `@voltagent/groq-ai` (Groq Provider)
+
+Implements the [groq-sdk](https://github.com/groq/groq-typescript) as a provider to allow inferencing [supported models](https://console.groq.com/docs/models).
+
+```ts
+import { Agent } from "@voltagent/core";
+import { GroqProvider } from "@voltagent/groq-ai";
+
+// Instantiate the provider, optionally passing the API key to overwrite the default GROQ_API_KEY
+const groqProvider = new GroqProvider({
+  //apiKey: process.env.GROQ_API_KEY,
path: website/docs/agents/providers.md
user: login: omeraplak
body: ```suggestion
  apiKey: process.env.GROQ_API_KEY,
```
created_at: 2025-04-26T00:51:04Z
author_association: MEMBER

PR comments:
user: login: TheEmi
created_at: 2025-04-24T22:23:43Z
body: Hey @omeraplak can you please check out the initial implementation and tell me if you see anything out of place?
author_association: CONTRIBUTOR
user: login: omeraplak
created_at: 2025-04-24T23:04:18Z
body: Hey @TheEmi ,
Thanks so much for the PR! 🙌 I’ll review it shortly and get back to you soon. ⚡
author_association: MEMBER
user: login: omeraplak
created_at: 2025-04-25T04:16:09Z
body: Hey! If you’d like to add a changeset, that would be awesome but no pressure at all.
I can also add it for you if you prefer, just let me know!

Here’s a quick guide on how to create one:
https://voltagent.dev/docs/community/contributing/#creating-a-changeset

Thanks again for the contribution ⚡
author_association: MEMBER
user: login: omeraplak
created_at: 2025-04-25T15:20:59Z
body: Hey @TheEmi ,
Thank you for your contribution ⚡

Would be awesome if you could also:
    •    Add it to the Providers Docs here:
https://github.com/VoltAgent/voltagent/blob/main/website/docs/agents/providers.md
(live version: https://voltagent.dev/docs/agents/providers/)
    •    And include a minimal example app like these:
https://github.com/VoltAgent/voltagent/tree/main/examples/with-vercel-ai
https://github.com/VoltAgent/voltagent/tree/main/examples/with-xsai
author_association: MEMBER
user: login: TheEmi
created_at: 2025-04-25T19:24:17Z
body: Sounds good! I'll add the changeset and update the docs and examples! Thx
author_association: CONTRIBUTOR
user: login: TheEmi
created_at: 2025-04-25T20:30:51Z
body: Please take a look at the changes again @omeraplak 
author_association: CONTRIBUTOR
user: login: omeraplak
created_at: 2025-04-25T20:34:53Z
body: Thank you @TheEmi . I’ll review it shortly and get back to you soon. ⚡
author_association: MEMBER
user: login: omeraplak
created_at: 2025-04-26T01:15:31Z
body: Thank you again @TheEmi for your contribution! 🙌
By the way, what’s your Discord username? We’d love to give you the Contributor badge on our server! ⚡
author_association: MEMBER