How to Use Function Calling with OpenAI

Introduction to Function Calling

Function calling is a feature provided by OpenAI that allows developers to describe specific functions to models like gpt-4 and gpt-3.5-turbo. The model can then choose to output a JSON object containing the necessary arguments for those functions. It essentially integrates GPT’s capabilities with external tools and APIs in a seamless manner.

OpenAI’s models have been enhanced to determine when to call a function based on the user’s input. Additionally, they respond with JSON formatted according to the function’s signature. This results in:

• Creating Chatbots: Developers can build chatbots that use external tools, such as ChatGPT Plugins.

• Natural Language Conversion: Convert user queries like “Email Anya about coffee next Friday” into structured function calls. For instance, transforming it to send_email(to: string, body: string). Another example would be converting “What’s the weather in Boston?” to get_current_weather(location: string, unit: 'celsius' | 'fahrenheit').

• API and Database Calls: You can turn user queries into direct API calls or even database requests. For example, “Who are my top customers this month?” could be translated into an API call like get_customers_by_revenue(start_date: string, end_date: string, limit: int).

• Data Extraction: Extracting structured data from texts is also possible. For instance, you could define a function named extract_people_data(people: [{name: string, birthday: string, location: string}]) to fetch details of all individuals mentioned in a Wikipedia article.

Practical Example: Weather Information

Step 1: User’s Initial Request to OpenAI

Using Python’s requests:

import requests
import json

headers = {
    "Authorization": f"Bearer YOUR_OPENAI_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "model": "gpt-3.5-turbo-0613",
    "messages": [{"role": "user", "content": "What is the weather like in Boston?"}],
    "functions": [{
        "name": "get_current_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"]
                }
            },
            "required": ["location"]
        }
    }]
}

response = requests.post("https://api.openai.com/v1/chat/completions", headers=headers, data=json.dumps(data))
print(response.json())

OpenAI’s response:

{
  "id": "chatcmpl-123",
  ...
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "function_call": {
        "name": "get_current_weather",
        "arguments": "{ \"location\": \"Boston, MA\"}"
      }
    },
    "finish_reason": "function_call"
  }]
}

Observe that in the provided response, the “content” key returns a null value. In contrast, the “function_call” key offers structured JSON results. Users can utilize this structured format to make external API calls based on their requirements.

The subsequent steps are independent of OpenAI. We simply harness the structured format provided by OpenAI to proceed further.

Step 2: Use OpenAI’s Response for Your External API Call

An example using the fictional weather API:

weather_response = requests.get("https://weatherapi.com/YOUR_ENDPOINT", params={"location": "Boston, MA"})
print(weather_response.json())

Resulting in:

{ "temperature": 22, "unit": "celsius", "description": "Sunny" }

You can stop here, or use OpenAI again to convert this structured data into natural language.
Following Step 2, we could potentially conclude our workflow and present the response to the users.

Yet, there’s an option to progress further by sending the API response from Step 2 back to OpenAI. This allows OpenAI to transform the structured data into more natural language. However, if our primary intention is merely to have OpenAI shape the initial output into a JSON format for our workflow, there’s no need to advance to Step 3.

Step 3: Convert Structured Data into Natural Language with OpenAI

Making another request to OpenAI:

data["messages"].extend([
    {"role": "assistant", "content": null, "function_call": {"name": "get_current_weather", "arguments": "{ \"location\": \"Boston, MA\"}"}},
    {"role": "function", "name": "get_current_weather", "content": "{\"temperature\": 22, \"unit\": \"celsius\", \"description\": \"Sunny\"}"}
])

final_response = requests.post("https://api.openai.com/v1/chat/completions", headers=headers, data=json.dumps(data))
print(final_response.json())

OpenAI’s final response:

{
  "id": "chatcmpl-123",
  ...
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "The weather in Boston is currently sunny with a temperature of 22 degrees Celsius."
    },
    "finish_reason": "stop"
  }]
}

This example demonstrates the flexibility and power of OpenAI’s function calling feature, allowing for seamless integrations with external tools and services.

Remember to replace placeholders such as YOUR_OPENAI_API_KEY with your actual credentials.