DEV Community

Syeed Talha
Syeed Talha

Posted on

Using Groq API with OpenAI Agents SDK

#ai #agents #python #tutorial

If you have tried using the OpenAI Agents SDK with Groq and ran into confusing import errors or decommissioned model warnings, you are not alone. This guide walks you through the correct setup from scratch, explains why the common mistakes happen, and leaves you with a working example you can build on.

What Is the OpenAI Agents SDK?

The OpenAI Agents SDK is an open-source Python framework for building agentic AI applications. It gives you clean abstractions for agents (an LLM with instructions and tools), handoffs between agents, guardrails, and built-in tracing. Despite the "OpenAI" name, the SDK is designed to work with any OpenAI-compatible API endpoint, which includes Groq.

What Is Groq?

Groq provides cloud-based LLM inference at very high speeds using their custom LPU hardware. Their API is largely compatible with the OpenAI API specification, which means you can point any OpenAI client at Groq's base URL and it will work with minimal changes.

Prerequisites

Before you start, make sure you have the following:

  • Python 3.10 or higher
  • A Groq API key (sign up at console.groq.com)
  • A virtual environment set up for your project

Installation

Install the required packages:

pip install openai-agents python-dotenv
Enter fullscreen mode Exit fullscreen mode

The openai-agents package includes the openai package as a dependency, so you do not need to install it separately.

Project Structure 

your-project/
├── .env
└── main.py
Enter fullscreen mode Exit fullscreen mode

Create a .env file and add your Groq API key:

GROQ_API_KEY=your_groq_api_key_here
OPENAI_AGENTS_DISABLE_TRACING=1
Enter fullscreen mode Exit fullscreen mode

The second line disables trace export to OpenAI's dashboard. Since you are not using an OpenAI API key, the SDK will otherwise print a warning every time you run your script. Setting this variable silences it cleanly.

The Wrong Way (and Why It Fails)

A common pattern beginners try is importing set_default_openai_client from the openai package:

# This will fail
from openai import OpenAI, set_default_openai_client
Enter fullscreen mode Exit fullscreen mode

This throws an ImportError because set_default_openai_client does not exist in the openai package. It is a function from an older or incorrect reference that does not reflect the actual API of either library.

Another mistake is passing the model name as a plain string while using a custom client:

# This does not associate the model with your custom Groq client
agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant",
    model="llama-3.3-70b-versatile",  # SDK will try to use OpenAI, not Groq
)
Enter fullscreen mode Exit fullscreen mode

When you pass a string, the SDK has no way of knowing you want to route requests to Groq. It will attempt to use the default OpenAI endpoint and fail if no OpenAI API key is set.

The Correct Approach

The right way is to use OpenAIChatCompletionsModel from the agents SDK. This class accepts an AsyncOpenAI client, which you configure to point at Groq's base URL. You then pass the model object directly to the Agent.

Here is the complete working example:

import os
from dotenv import load_dotenv
from openai import AsyncOpenAI
from agents import Agent, Runner
from agents.models.openai_chatcompletions import OpenAIChatCompletionsModel

load_dotenv()

# Step 1: Create an async OpenAI client pointed at Groq
groq_client = AsyncOpenAI(
    api_key=os.environ.get("GROQ_API_KEY"),
    base_url="https://api.groq.com/openai/v1"
)

# Step 2: Wrap it in OpenAIChatCompletionsModel
groq_model = OpenAIChatCompletionsModel(
    model="llama-3.3-70b-versatile",
    openai_client=groq_client
)

# Step 3: Pass the model object to the Agent
agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant",
    model=groq_model,
)

# Step 4: Run it
result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
print(result.final_output)
Enter fullscreen mode Exit fullscreen mode

Why AsyncOpenAI and Not OpenAI?

The OpenAI Agents SDK is built on top of Python's asyncio and makes asynchronous HTTP calls internally. The synchronous OpenAI client is not compatible with this. Always use AsyncOpenAI when building the client for the agents SDK, even if you are calling Runner.run_sync(). The sync wrapper handles the event loop externally; the internal model calls are still async.

Choosing the Right Groq Model

Groq periodically deprecates older model IDs. If you see an error like this:

openai.BadRequestError: Error code: 400 - {'error': {'message': 'The model `llama3-70b-8192` 
has been decommissioned...'}}
Enter fullscreen mode Exit fullscreen mode

You are using a model ID that Groq no longer supports. Here are the current recommended replacements as of mid-2025:

Deprecated Model Recommended Replacement
llama3-70b-8192 llama-3.3-70b-versatile
llama3-8b-8192 llama-3.1-8b-instant
mixtral-8x7b-32768 qwen/qwen3-32b

Always check console.groq.com/docs/models for the current list of supported models.

Running the Script 

python main.py
Enter fullscreen mode Exit fullscreen mode

Expected output:

Code within the code,
Functions calling themselves deep,
Infinite loop's dance.
Enter fullscreen mode Exit fullscreen mode

Key Takeaways

  • Do not import set_default_openai_client from openai. It does not exist there.
  • Always use AsyncOpenAI, not OpenAI, when building a client for the agents SDK.
  • Pass a OpenAIChatCompletionsModel object to Agent, not a plain model name string, when using a custom provider like Groq.
  • Set OPENAI_AGENTS_DISABLE_TRACING=1 in your .env to suppress the tracing warning when not using OpenAI.
  • Check Groq's deprecation page if you get a model_decommissioned error and update your model ID accordingly.

What to Build Next

Once you have the basic setup working, you can explore:

  • Adding tools to your agent using the @function_tool decorator
  • Creating multi-agent workflows with handoffs
  • Using Groq's faster, lighter models like llama-3.1-8b-instant for lower-latency tasks

The OpenAI Agents SDK documentation is available at openai.github.io/openai-agents-python and Groq's API reference at console.groq.com/docs.

Top comments (0)