API Function Calling

Runbear supports API function calling using OpenAI Assistants Function Calling. You can define custom actions by making one or more APIs available to Runbear. This feature is similar to Actions in OpenAI GPTs.

Common Use Cases

API function calls enable utilizing external services. For example, you can:

• Create assistants that answer questions by calling external APIs, e.g., GET https://weatherapi.com/new-york
• Convert natural language into API calls, e.g., convert "Who are my top customers?" to GET https://internal.service.com/customers/leaderboard and call your internal API

⋯ And much more!

Defining API Functions

Runbear API function is identical to OpenAI Function Calling except for the __api__ field under properties. You define API specification in the field.

__api__ Schema

The __api__ object is described as a JSON Schema object. See JSON Schema reference for documentation about the format.

field	type	description
type	string	It should be "object"
value	object	A definition of the API
value.url	string	URL of the API endpoint
value.method	string (optional)	HTTP method to use (GET, POST, PUT, DELETE, etc.)
value.headers	object (optional)	A JSON object of HTTP headers

Passing GET Parameters

Parameters defined in function.parameters.properties of the OpenAI Function Calling JSON Schema will be passed to the GET API request using query parameters.

You can also utilize the dynamic URL path by leveraging the function.parameters.properties. To use a parameter in the URL, assign a key and enclose it with curly braces ({}).

Example Function Calling JSON

{
  "name": "sample_function",
  "parameters": {
    "type": "object",
    "properties": {
      "example_path_parameter": {
        "type": "string",
        "description": "Describe the parameter here."
      },
      "example_query_parameter": {
        "type": "string",
        "description": "Describe the parameter here."
      },
      "__api__": {
        "type": "object",
        "value": {
          "url": "https://your.domain/path/{example_path_parameter}/",
        }
      }
    },
    "required": ["example_path_parameter", "example_query_parameter"]
  },
}

The example function will send a GET request to the URL below.

https://your.domain/path/generated_path_parameter/?example_query_parameter=Some%20Generated%20Query%20Parameter%20String

Passing POST Parameters

Parameters defined in function.parameters.properties of the OpenAI Function Calling JSON Schema will be passed to the POST API request using body parameters.

Example POST method Function Calling JSON

{
  "name": "sample_post_function",
  "parameters": {
    "type": "object",
    "properties": {
      "example_body_parameter": {
        "type": "string",
        "description": "Describe the parameter here."
      },
      "__api__": {
        "type": "object",
        "value": {
          "url": "https://your.domain/path/",
          "method": "POST",
        }
      }
    },
    "required": ["example_body_parameter"]
  },
}

The example function will send a POST request to https://your.domain.path with a JSON body:

{ "example_body_parameter": "String generated by LLM" }

API Function Example

The provided JSON example outlines an API function designed for sending requests to swapi.dev. It extracts resource and search value from user queries, injects the resource to the URL path, and adds search as the URL query parameter.

{
  "name": "search_starwars",
  "parameters": {
    "type": "object",
    "properties": {
      "search": {
        "type": "string",
        "description": "Search keyword"
      },
      "resource": {
        "type": "string",
        "description": "Type of searching resource. The value should be one of 'people', 'planets' or 'starships'."
      },
      "__api__": {
        "type": "object",
        "value": {
          "url": "https://swapi.dev/api/{resource}/",
          "method": "GET",
          "headers": {
            "Content-Type": "application/json"
          }
        }
      }
    },
    "required": ["search", "resource"]
  },
  "description": "Search about the keyword from Starwars"
}