Fix OpenAI Agent SDK Function Call Error with Ollama: TypeError Union

File "/Users/RandomName/.local/share/uv/python/cpython-3.12.11-macos-aarch64-none/lib/python3.12/typing.py", line 501, in __call__
    raise TypeError(f"Cannot instantiate {self!r}")
TypeError: Cannot instantiate typing.Union

new_tool_call = ChatCompletionMessageToolCallParam(
    id=file_search["id"],
    type="function",
    function={
        "name": "file_search_call",
        "arguments": json.dumps(
            {
                "queries": file_search.get("queries", []),
                "status": file_search.get("status"),
            }
        ),
    },
)

ChatCompletionMessageToolCallParam: TypeAlias = Union[
    ChatCompletionMessageFunctionToolCallParam, ChatCompletionMessageCustomToolCallParam
]

from typing import Union

Foo = Union[int, str]
Foo("hello")

Traceback (most recent call last):
...
raise TypeError(f"Cannot instantiate {self!r}")
TypeError: Cannot instantiate typing.Union

How to Fix It

Solution 1: Downgrade the openai Package (Recommended, Confirmed Fix)

The accepted Stack Overflow answer and the GitHub issue both point to the same fix: downgrade the openai Python package to a version below 1.99.0. The GitHub issue specifically states: "you should downgrade the openai module to <1.99.0".

Step 1: Check your current openai version.

Run this command in your terminal:

pip show openai

Or if you are using uv:

uv pip show openai

Look for the Version field. If it is 1.99.0 or higher, you need to downgrade.

Step 2: Downgrade to a compatible version.

The Stack Overflow user had openai>=1.68.2 in their dependencies. The GitHub issue shows a user with openai==1.75.0 (which is below 1.99.0) and they were not experiencing this specific error. A safe choice is to pin to version 1.75.0 or any version between 1.68.2 and 1.98.x.

Using pip:

pip install "openai<1.99.0"

Or to pin a specific version:

pip install openai==1.75.0

If you are using uv:

uv pip install "openai<1.99.0"

If you are using a pyproject.toml or requirements.txt, update the dependency line:

# pyproject.toml
dependencies = [
    "openai>=1.68.2,<1.99.0",
    "openai-agents>=0.0.15",
]

Or in requirements.txt:

openai>=1.68.2,<1.99.0
openai-agents>=0.0.15

Step 3: Verify the fix.

Run your script again. The error should no longer occur. If it does, double-check that the downgrade took effect:

uv pip show openai | grep Version

What to expect when it works:

The script should run without the TypeError. The agent will call the math_tool function with the arguments a=2, b=2 and return the sum 4. The output will be something like:

Adding 2 and 2
Final output:
4

Or, depending on how you print the output, you might see the full RunResult object.

Solution 2: Upgrade openai-agents to a Newer Version (Theoretical, Not Confirmed)

If you prefer to keep the latest openai package, you could try upgrading openai-agents to a version that has fixed this incompatibility. However, none of the sources confirm that a fix exists in a newer version of openai-agents. The Stack Overflow question uses openai-agents>=0.0.15, and the GitHub issue (which is about a different LangChain error) shows openai-agents installed but does not specify a version.

To try this approach:

pip install --upgrade openai-agents

Or with uv:

uv pip install --upgrade openai-agents

Then test your script. If the error persists, revert to Solution 1.

Why this might not work: The GitHub issue (source 5) is about a different problem (OpenAIEmbeddings not respecting token limits) and does not address the openai-agents compatibility issue. The accepted Stack Overflow answer explicitly recommends downgrading openai, not upgrading openai-agents.

Solution 3: Use the OpenAI API Directly Instead of the Agent SDK

If you cannot downgrade the openai package due to other dependencies, you can bypass the Agent SDK and use the OpenAI Chat Completions API directly with Ollama. This gives you full control over the function calling flow.

Step 1: Install the openai package (keep the latest version).

pip install openai

Step 2: Write a script that manually handles function calls.

Here is an example based on the official OpenAI documentation (source 2) adapted for Ollama:

from openai import OpenAI
import json

# Configure the client to point at Ollama
client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="dummy",  # Ollama doesn't require a real key
)

# Define the tool
math_tool = {
    "type": "function",
    "function": {
        "name": "math_tool",
        "description": "Send two integers and this returns their sum",
        "parameters": {
            "type": "object",
            "properties": {
                "a": {"type": "integer", "description": "First integer"},
                "b": {"type": "integer", "description": "Second integer"},
            },
            "required": ["a", "b"],
            "additionalProperties": False,
        },
        "strict": True,
    },
}

# Implement the function
def math_tool_impl(a: int, b: int) -> int:
    print(f"Adding {a} and {b}")
    return a + b

# Start the conversation
messages = [
    {"role": "user", "content": "What is 2 + 2?"}
]

# First API call
response = client.chat.completions.create(
    model="qwen3:4b",
    messages=messages,
    tools=[math_tool],
)

# Check if the model wants to call a tool
if response.choices[0].message.tool_calls:
    # Append the model's response (which includes the tool call)
    messages.append(response.choices[0].message)
    
    for tool_call in response.choices[0].message.tool_calls:
        if tool_call.function.name == "math_tool":
            # Parse arguments
            args = json.loads(tool_call.function.arguments)
            result = math_tool_impl(args["a"], args["b"])
            
            # Append the tool result
            messages.append({
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": json.dumps({"result": result}),
            })
    
    # Second API call to get the final response
    final_response = client.chat.completions.create(
        model="qwen3:4b",
        messages=messages,
        tools=[math_tool],
    )
    print(final_response.choices[0].message.content)
else:
    # The model responded directly
    print(response.choices[0].message.content)

Step 3: Run the script.

python your_script.py

What to expect: The script will make two API calls to Ollama. The first call will return a tool call request. The script executes the function locally and sends the result back. The second call will return the final answer, something like "2 + 2 = 4".

This approach avoids the Agent SDK entirely and works with any version of the openai package.

Solution 4: Use a Different Agent Framework

If you prefer a framework but cannot resolve the version conflict, consider using an alternative agent framework that is compatible with Ollama and the latest openai package. Options include:

• LangChain with its create_openai_tools_agent or create_tool_calling_agent.
• AutoGen from Microsoft.
• CrewAI.

Each of these has its own setup and may or may not have the same compatibility issue. The sources do not provide specific instructions for these alternatives, so you would need to consult their respective documentation.

If Nothing Works

If none of the above solutions resolve the error, consider these escalation paths:

Check the OpenAI Agent SDK GitHub Issues

The openai-agents package is open source. Check its GitHub repository for existing issues or bug reports related to this error. If none exist, open a new issue with:

• Your exact openai and openai-agents versions.
• The full error traceback.
• A minimal reproducible example (like the one in the Stack Overflow question).

Check the OpenAI Python SDK GitHub Issues

Similarly, the openai Python package has a GitHub repository. Search for issues related to ChatCompletionMessageToolCallParam or Cannot instantiate typing.Union. The GitHub issue linked in source 5 is about a different problem (LangChain embeddings), but the openai package maintainers may be aware of the compatibility issue.

Use a Virtual Environment with Pinned Versions

If you have multiple projects with conflicting openai version requirements, use separate virtual environments for each project. This is a standard Python best practice. With uv, you can create a dedicated environment:

uv venv
source .venv/bin/activate
uv pip install "openai<1.99.0" "openai-agents>=0.0.15"

Fallback: Use the Raw HTTP API

As a last resort, you can bypass both the openai package and the Agent SDK and make raw HTTP requests to Ollama's API. This gives you complete control and avoids any library compatibility issues. Ollama's API is compatible with the OpenAI API format. Here is a minimal example using the requests library:

import requests
import json

url = "http://localhost:11434/v1/chat/completions"
headers = {"Content-Type": "application/json"}

payload = {
    "model": "qwen3:4b",
    "messages": [{"role": "user", "content": "What is 2 + 2?"}],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "math_tool",
                "description": "Send two integers and this returns their sum",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "a": {"type": "integer"},
                        "b": {"type": "integer"},
                    },
                    "required": ["a", "b"],
                },
            },
        }
    ],
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

This approach requires you to manually handle the tool calling loop, but it is guaranteed to work with any version of the libraries (or none at all).

How to Prevent It

To avoid this error in the future, follow these practices:

Pin Compatible Versions

When starting a new project that uses openai-agents, explicitly pin the openai package to a version below 1.99.0 in your pyproject.toml or requirements.txt. For example:

# pyproject.toml
[project]
dependencies = [
    "openai>=1.68.2,<1.99.0",
    "openai-agents>=0.0.15",
]

This ensures that pip or uv will not install a breaking version of openai.

Use a Lock File

Use a package manager that generates a lock file, such as uv (which creates uv.lock) or poetry (which creates poetry.lock). A lock file records the exact versions of all dependencies, preventing accidental upgrades. When you need to upgrade, regenerate the lock file and test thoroughly.

Test in a Clean Environment

Before deploying or sharing your code, test it in a fresh virtual environment. This helps catch version conflicts early. For example:

uv venv
uv pip install "openai<1.99.0" "openai-agents>=0.0.15"
uv run your_script.py

Monitor Library Updates

Keep an eye on the release notes for both openai and openai-agents. When a new version of openai-agents is released that explicitly states compatibility with openai>=1.99.0, you can safely upgrade. Until then, stay on the older version.

Use the Responses API (If Using OpenAI Directly)

If you are using OpenAI's API directly (not Ollama), the official documentation (source 2) shows how to use the Responses API with function calling. The Responses API is the newer, recommended way to build agents and may have better compatibility with the latest SDKs. However, this does not apply to Ollama, which only supports the Chat Completions API format.

Consider Using the OpenAI Agents SDK with OpenAI's Models

If you are not tied to Ollama, consider using the OpenAI Agents SDK with OpenAI's own models (like gpt-5.6). The SDK is designed and tested primarily with OpenAI's API, so version compatibility is more likely to be maintained. The official quickstart (source 1) shows how to get started with the OpenAI API and the SDK.