An assistant and modules are created and modified via API call. This guide leads you through the calls you have to do and the settings and configurations that can be set.

...

• Token of a user / service-user which has an admin role assigned → <yourToken>

• The base URL of your application → <baseUrl>!

Assistant

Create a new assistant

...

• <baseUrl> / <yourToken>

• <assistantId>

• <updateAssistant> "param1": "<paramValue>" → contains variables that should be updated. Variables that are not contained in <updateAssistant> input remain unchanged

curl --location --globoff 'https://gateway.<baseUrl>/chat/graphql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <yourToken>' \
--data '{"query":"mutation UpdateAssistant($updateAssistantId: String!, $input: AssistantUpdateInput!) {\n  updateAssistant(id: $updateAssistantId, input: $input) {\n    name\n    id\n    languageModel\n    settings\n    chatUpload\n    modules {\n      id\n      name\n      configuration\n    }\n  }\n}","variables":{"updateAssistantId":"<assistantId>","input":{<updateAssistant>"param1": "<paramValue>"}}}'

Delete an assistant

To delete an assistant, use the following cURL. Update these placeholders:

...

<baseUrl> / <yourToken>

...

An example command to update the languageModelused to perform function calling and module selection can be updated with the following curl command:

curl --location --globoff 'https://gateway.<baseUrl>/chat/graphql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YourToken><yourToken>' \
--data '{"query":"mutation CreateAssistantUpdateAssistant($deleteAssistantId$updateAssistantId: String!, $input: AssistantUpdateInput!) {\n     deleteAssistant updateAssistant(id: $updateAssistantId, input: $deleteAssistantId$input) {\n            name\n  }\n}","variables":{"deleteAssistantId":"<assistantId>"}}'

Assistant variables and settings

The list contains various parameters that need to be set when an assistant is created/updated.

...

Variable

...

Description

...

Options

...

optional / required

...

name

...

Name of assistant

...

required

...

fallbackModule

...

fallbackModule if module selection could not find a suitable module

...

required

...

languageModel

...

Language module used for module selection

...

see below section with GPT-models

default: AZURE_GPT_35_TURBO

...

optional

...

chatUpload

...

Enable/disable upload of documents into chat

...

DISABLED (default)

ENABLED

...

optional

...

settings

...

Collection of settings:

• showPdfHighlighting: Open references in same chat window on the right side. Referenced section is highlighted in the PDF

• modelChoosing: type of module selection

...

showPdfHighlighting

• false (default)

• true

modelChoosing

• BY_FUNCTION_CALL

• BY_PROMPT (default)

...

optional

...

modules

...

List of modules to create. See Module section for details about configuration of a module

...

required

Example input for an Internal Knowledge assistant containing two modules (SearchInVectorDB, Translate).

{
  "input":           id    \n            languageModel    \n            settings    \n            chatUpload    \n            modules {\n                id\n                name\n                configuration   \n            }\n       }\n}","variables":{"updateAssistantId":"<assistantID>","input":{"languageModel":"AZURE_GPT_4_0613"}}}'

Delete an assistant

To delete an assistant, use the following cURL. Update these placeholders:

• <baseUrl> / <yourToken>

• <assistantId>

curl --location --globoff 'https://gateway.<baseUrl>/chat/graphql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YourToken>' \
--data '{"query":"mutation CreateAssistant($deleteAssistantId: String!) {\n  deleteAssistant(id: $deleteAssistantId) {\n    name\n  }\n}","variables":{"deleteAssistantId":"<assistantId>"}}'

Assistant variables and settings

The list contains various parameters that need to be set when an assistant is created/updated.

Example input for an Internal Knowledge assistant containing two modules (SearchInVectorDB, Translate).

{
  "input": {
    "name": "Internal Knowledge",
    "fallbackModule": "SearchInVectorDB",
    "languageModel": "AZURE_GPT_35_TURBO_0613",
    "chatUpload": "Disabled",
    "settings": {
        "showPdfHighlighting": true,
        "modelChoosing": "BY_FUNCTION_CALL",
        "isPinned": true        
    },
    "modules": {
      "create": [
        {
            "name": "SearchInVectorDB",
            "configuration": {
            },
            "description": null,
            "isExternal": false,
            "weight": 10000
        },
        {
            "name": "Translate",
            "configuration": {
            },
            "description": null,
            "isExternal": false,
            "weight": 6000
        }
      ]
    }
  }
}

Module

Create a module

This can be done with this cURL. Just replace the following placeholders:

• <baseUrl> / <yourToken>

• <assistantId> → ID of the assistant where the module should be created

• <moduleDefinition> → Definition of the new module (see example below)

curl --location --globoff 'https://gateway.<baseUrl>/chat/graphql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <yourToken>' \
--data '{"query":"mutation CreateModule($assistantId: String!, $input: ModuleCreateInput!) {\n  createModule(assistantId: $assistantId, input: $input) {\n    id\n    name\n    assistantId\n  }\n}","variables":{"assistantId":"<assistantId>","input":<moduleDefinition>}'

Update a module

This can be done with this cURL. Just replace the following placeholders:

• <baseUrl> / <yourToken>

• <moduleId>

• <updatesModule> → New set of module parameters

curl --location --globoff 'https://gateway.<baseUrl>/chat/graphql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <yourToken>' \
--data '{"query":"mutation UpdateModule($input: ModuleUpdateInput!, $moduleId: String!) {\n  updateModule(input: $input, moduleId: $moduleId) {\n    id\n    name\n    configuration\n    weight\n  }\n}","variables":{"input":{<updatesModule>},"moduleId":"<moduleId>"}}'

Delete a module

This can be done with this cURL. Just replace the following placeholders:

• <baseUrl> / <yourToken>

• <moduleId>

curl --location --globoff 'https://gateway.<baseUrl>/chat/graphql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <yourToken>' \
--data '{"query":"mutation DeleteModule($moduleId: String!) {\n  deleteModule(moduleId: $moduleId)\n}","variables":{"moduleId":"<moduleId>"}}'

Module variables and configuration

Below is an example of parameters for a module:

• configuration → depends on module. See section Module dependent configurations for more details

• isExternal → flag if module is external (= developed with SDK)

• weight → defines the order of modules in module selection prompt

• toolDefinition → Description of module used for function calling. Here, the same structure as openAI is used (therefore, this parameter is called toolDefinition and not moduleDefinition)

{
    "name": "Internal Knowledge",
    "fallbackModule": "SearchInVectorDB",
    "languageModelconfiguration": null,
    "chatUpload": "Disabled",{
     "settings": {<collectionOfParameters>
    },
    "showPdfHighlightingisExternal": truefalse,
    }"weight": 10000,
    "modulestoolDefinition": {
        "createtype": "function",
[        "function": {
            "name": "SearchInVectorDB",
            "configurationdescription": {
            },
            "description": null,
            "isExternal": false,
            "weight": 10000"Search information in the employee knowledge base for a specific question or assignment, e.g. explain, elaborate or describe. If the employee mentions a specific document and you do not know it, ALWAYS use this function. The employee can ask specific formats. Some examples: 'summarise directive 76 in bullet points', 'how to export data to third-parties', 'what are employee benefits'.",
         },   "parameters":  {
   {             "nametype": "Translateobject",
                "configurationproperties": {
            },
            "descriptioninstruction": null,{
            "isExternal": false,            "type": "weightstring":,
  6000          }       ]     }
  }
}

Module

Create a module

This can be done with this cURL. Just replace the following placeholders:

• <baseUrl> / <yourToken>

• <assistantId> → ID of the assistant where the module should be created

• <moduleDefinition> → Definition of the new module (see example below)

curl --location --globoff 'https://gateway.<baseUrl>/chat/graphql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <yourToken>' \
--data '{"query":"mutation CreateModule($assistantId: String!, $input: ModuleCreateInput!) {\n  createModule(assistantId: $assistantId, input: $input) {\n    id\n    name\n    assistantId\n  }\n}","variables":{"assistantId":"<assistantId>","input":<moduleDefinition>}'

Update a module

This can be done with this cURL. Just replace the following placeholders:

• <baseUrl> / <yourToken>

• <moduleId>

• <updatesModule> → New set of module parameters

curl --location --globoff 'https://gateway.<baseUrl>/chat/graphql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <yourToken>' \
--data '{"query":"mutation UpdateModule($input: ModuleUpdateInput!, $moduleId: String!) {\n  updateModule(input: $input, moduleId: $moduleId) {\n    id\n    name\n    configuration\n    weight\n  }\n}","variables":{"input":{<updatesModule>},"moduleId":"<moduleId>"}}'

Delete a module

This can be done with this cURL. Just replace the following placeholders:

• <baseUrl> / <yourToken>

• <moduleId>

curl --location --globoff 'https://gateway.<baseUrl>/chat/graphql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <yourToken>' \
--data '{"query":"mutation DeleteModule($moduleId: String!) {\n  deleteModule(moduleId: $moduleId)\n}","variables":{"moduleId":"<moduleId>"}}'

Module variables and configuration

Below is an example of parameters for a module:

• configuration → depends on module. See section Module dependent configurations for more details

• description → description of module. Required only for external modules

• isExternal → flag if module is external (= developed with SDK)

• weight → defines the order of modules in module selection prompt

{
    "name": "SearchInVectorDB",
    "configuration": {
      <collectionOfParameters>
    },
    "description": null,
    "isExternal": false,
    "weight": 10000
}

Module dependent configurations

...

Module

...

Example

...

Description

...

Parameter

...

Options

...

SearchInVectorDB

...

"configuration": {
        "languageModel": "AZURE_GPT_4_TURBO_1106",
        "scopeIds": ["scope_1", "scope_2"],
        "searchType": "COMBINED",
        "chunkedSources": true, 
        "scopeToChatOnUpload": true,
        "includeHistory": false,
        "maxTokens": 7000
}

...

GPT model to be used

...

languageModel: string

...

see below section with GPT-models

default: AZURE_GPT_35_TURBO: GPT-35-turbo (0301)

...

Scopes that the module can access

...

scopeIds: object

...

RAG approach to search for chunks

...

searchType: string

...

VECTOR: semantic search (similarity of input and chunk embeddings)

COMBINED: hybrid search combining vector and fulltext search

...

Describing if chunks of same document are appended as individual sources to GPT content or merged to one source

...

chunkedSources: boolean

...

true: each chunk is a separate source

false: chunks from the same document are merged to one source

...

Scope restriction to documents that are uploaded. If no documents are uploaded, then scopes in scopeIds are relevant.

...

scopeToChatUpload: boolean

...

true: Scope restriction on (if document uploaded)

false: Scope restriction off

...

Flag that allows to include previous chat conversation in GPT-calls only if the new user input is a follow-up question

...

historyIncluded: boolean

...

true: History always included

false: History only included for follow-up questions

...

Max tokens used by sources and previous conversation

...

maxTokens: integer

...

Default value depends on the used languageModel

AZURE_GPT_35_TURBO: 3000

AZURE_GPT_35_TURBO_0613: 3000

AZURE_GPT_35_TURBO_16K: 14000

AZURE_GPT_4_0613: 7000

AZURE_GPT_4_32K_0613: 30000

AZURE_GPT_4_VISION_PREVIEW: 7000

AZURE_GPT_4_TURBO_1106: 7000

...

"description": "The question to search in the knowledge base, e.g. Was gibt es zu essen?"
                    }
                }
            }
        }
    }
}

Module dependent configurations

"configuration": {
        "languageModel": "AZURE_GPT_4_TURBO_1106",
        "scopeIds": ["scope_1", "scope_2"],
        "searchType": "COMBINED",
        "chunkedSources": true, 
        "scopeToChatOnUpload": true,
        "historyIncluded": false,
        "maxTokens": 7000,
        "ftsSearchLanguage": "english"
}

"configuration": {
        "languageModel": "AZURE_GPT_4_TURBO_1106",
        "chunkedSources": true
}

"configuration": {
        "languageModel": "AZURE_GPT_4_TURBO_1106"
}

"configuration": {
        "languageModel": "AZURE_GPT_4_TURBO_1106"

}

"configuration": {
        "languageModel": "AZURE_GPT_4_TURBO_1106",
        "temperature": 0.5,
        "systemPromptExternalKnowledge": "Example system prompt",
        "

maxHistoryInteraction": 

2
}

"configuration": {
        "languageModel": "AZURE_GPT_4_TURBO_1106"
}

You are ChatGPT, a large language model trained by OpenAI, based on the GPT-4 architecture.\nKnowledge cutoff: 2023-04.\nCurrent date: DAYDATE.

"configuration": {
        "languageModel": "AZURE_GPT_4_TURBO_1106

"

}

"configuration": {
        "languageModel": "AZURE_GPT_4_TURBO

_1106",
        "tableConfig": TableConfig[],
        "searchExamples": ChatCompletionRequestMessage[],
        "showTableReference": boolean
        
}

"configuration": {
        "languageModel": "AZURE_GPT_4_TURBO_1106",
        "

scopeId": 

"scope_1",
        "

maxTokens": 

7000,
        "

templateName": 

"template.xlsx"
        
}

"configuration": {
        "languageModel": "AZURE_GPT_4_TURBO_1106"

}

"configuration": {
        "

languageModel": "

AZURE_GPT_4_TURBO_1106"
}

"configuration": {
        "languageModel": "AZURE_GPT_4_TURBO_1106"
}

"configuration": {
        "languageModel": "AZURE_GPT_4_TURBO_1106"
}

Available GPT models

The list below contains available GPT-models with the corresponding name that has to be used in the configurations for the assistants and modules:

...

GPT-35-turbo (0301): AZURE_GPT_35_TURBO

...

GPT-35-turbo (0613): AZURE_GPT_35_TURBO_0613

...

GPT-35-turbo-16K (0613): AZURE_GPT_35_TURBO_16K

...

GPT-4 (0613): AZURE_GPT_4_0613

...

Available GPT models

The list below contains available GPT-models with the corresponding name that has to be used in the configurations for the assistants and modules:

GPT versions available in Preview mode (not recommended to be used in productive applications):

...

...