External Services Integration

Custom Functions

This section is a work in progress.

To enable the model to invoke an external HTTP service, you need to: 1. Add the function definition to the configuration file. 2. Enable the function in the conversation template.

Below is an example function definition:

functions:
  - name: getWeather
    description: This function returns weather forecast
    parameters: 
      type: object
      properties: {}
    executor:
      type: http
      http-endpoint-url: https://wttr.in/?A&T&n&Q&F 
      http-method: GET

To enable it, add the default-request message to the conversation template:

- role: default-request
  model: gpt-3.5-turbo
  functions:
    - getWeather
- role: system
  content: You are a helpful assistant. 
- role: user

Notes:

  1. The name, description, and parameters properties are provided to the model as specified in the OpenAI API reference.
  2. The parameters field represents a JSON schema expressed in YAML, and even if the parameter list is empty, it must be defined as shown.
  3. The executor property defines the execution method for the function.
  4. At present, only an HTTP executor is supported.
  5. The http-endpoint-url and http-method parameters are self-descriptive.
  6. The supported HTTP methods are GET, POST, PUT, and PATCH.
  7. For a GET request, function parameters are appended to the query string, whereas for other methods, they are sent as a JSON payload.
  8. HTTP executor supports the following additional properties (for usage, see the example below):
    • http-success-codes - defines which HTTP status codes signify a successful function call (default is 200 OK).
    • http-soft-errors-codes - designates which HTTP status codes indicate soft errors (default is an empty list).
    • http-include-body-in-hard-errors - when true, includes the response body of hard errors in reports to the application, aiding in debugging (default is false).

Hard errors are conveyed to the calling application; for example, in an ai program, they are output to the console. In contrast, soft errors are reported back to the model, indicating that the function call failed.

Below is an example of a sendMessage function that sends a POST request:

functions:
  - name: sendMessage
    description: This function sends an email message.
    parameters: 
      type: object
      properties:
        to:
          description: Recipient's email address
          type: string
        subject:
          description: Subject of the message
          type string
        body:
          description: Body of the message
          type: string
      required:
        - to
        - subject
    executor:
      type: http
      http-endpoint-url: https://example.com/sendEmail 
      http-method: POST
      http-soft-errors-codes:
        - code: 400
          include-status: true

The include-status field indicates if the HTTP status line should be included in the response body returned to the LLM.

Note: Currently, the HTTP function executor does not support any authorization method.