How to beginner · 3 min read

Enum types in function calling

Q: Enum types in function calling

Use enum types in the parameters schema of function calling to restrict argument values to a predefined set of strings. This ensures the AI only selects from allowed options when invoking functions via the tools parameter in client.chat.completions.create.

Quick answer

Use enum types in the parameters schema of function calling to restrict argument values to a predefined set of strings. This ensures the AI only selects from allowed options when invoking functions via the tools parameter in client.chat.completions.create.

PREREQUISITES

Python 3.8+
OpenAI API key (free tier works)
pip install openai>=1.0

Setup

Install the official OpenAI Python SDK and set your API key as an environment variable.

Install SDK: pip install openai
Set API key in your shell: export OPENAI_API_KEY='your_api_key'

bash

pip install openai

output

Collecting openai
  Downloading openai-1.x.x-py3-none-any.whl (xx kB)
Installing collected packages: openai
Successfully installed openai-1.x.x

Step by step

Define a function with an enum type parameter in the tools list to restrict input values. Then call the chat completion with tools= to enable function calling.

python

import os
import json
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# Define a tool with an enum parameter
tools = [{
    "type": "function",
    "function": {
        "name": "set_traffic_light",
        "description": "Set the traffic light color",
        "parameters": {
            "type": "object",
            "properties": {
                "color": {
                    "type": "string",
                    "enum": ["red", "yellow", "green"]
                }
            },
            "required": ["color"]
        }
    }
}]

messages = [{"role": "user", "content": "Set the traffic light to green."}]

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
    tools=tools
)

print("Response:", response.choices[0].message.content)

# Check if the model called the function
if response.choices[0].finish_reason == "tool_calls":
    tool_call = response.choices[0].message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    print(f"Function called: {tool_call.function.name}")
    print(f"Arguments: {args}")

output

Response: Calling function set_traffic_light with color green.
Function called: set_traffic_light
Arguments: {'color': 'green'}

Common variations

You can use enum types with other models like gpt-4o or gpt-4o-mini. Async calls follow the same pattern with async and await. Streaming is not supported with function calling currently.

python

import asyncio
import os
import json
from openai import OpenAI

async def async_function_calling():
    client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

    tools = [{
        "type": "function",
        "function": {
            "name": "set_traffic_light",
            "description": "Set the traffic light color",
            "parameters": {
                "type": "object",
                "properties": {
                    "color": {
                        "type": "string",
                        "enum": ["red", "yellow", "green"]
                    }
                },
                "required": ["color"]
            }
        }
    }]

    messages = [{"role": "user", "content": "Change the light to red."}]

    response = await client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=tools
    )

    print("Async response:", response.choices[0].message.content)

    if response.choices[0].finish_reason == "tool_calls":
        tool_call = response.choices[0].message.tool_calls[0]
        args = json.loads(tool_call.function.arguments)
        print(f"Function called: {tool_call.function.name}")
        print(f"Arguments: {args}")

asyncio.run(async_function_calling())

output

Async response: Calling function set_traffic_light with color red.
Function called: set_traffic_light
Arguments: {'color': 'red'}

Troubleshooting

If the AI returns unexpected values outside the enum, verify your parameters schema is correctly formatted with enum as a list of strings.
If finish_reason is not tool_calls, the model did not invoke the function; try clarifying the user prompt.
Ensure you use the tools= parameter, not deprecated functions=.

✅

Key Takeaways

Use enum in function parameter schemas to restrict argument values to specific strings.
Pass function definitions via the tools parameter in client.chat.completions.create to enable function calling.
Check finish_reason == 'tool_calls' to detect when the model invokes a function.
Async calls support function calling similarly; streaming is not supported with function calls.
Always validate your JSON schema to ensure enums are correctly defined as string arrays.

Verified 2026-04 · gpt-4o-mini, gpt-4o

Verify ↗