Quick App Configuration Guide

Introduction

Quick app is one of the application types in DIAL. You can create instances of Quick apps using DIAL API and UI wizards.

Quick app application type is schema-rich - the structure of custom applications of this type is defined by the JSON schema of Quick apps. This document provides a detailed overview of the Quick app JSON schema, explaining the available configuration options primarily useful if you are creating Quick apps using DIAL API.

Quick apps are code-less and conceptually similar to OpenAI's GPTs. They can include tools such as client toolsets, web API toolsets, use apps and models deployed in DIAL as tools and URLs to files for RAG. For example, you can create an app with a toolset allowing it to call an external API to get a real-time weather forecast for a specific location. Another example is a RAG-like application that can generate responses based on predefined sources.

Watch a Demo Video with an introduction to Quick Apps.

Refer to Enable App to learn how to enable Quick apps that you create in DIAL and make them available for other users.

Configuration

The structure of Quick app applications is defined by the schema with ID https://mydial.epam.com/custom_application_schemas/quickapps. This schema, as well as other DIAL application types' schemas, conforms to the meta schema.

Main Parameters

Field	Type	Required	Description	Example
`temperature`	number	Yes	Controls randomness in responses (0.0-1.0). Lower values make responses more deterministic, higher values make them more creative.	`0.8`
`instructions`	string	Yes	System prompt that guides the model's behavior.	`"You are a weather assistant. Help users understand weather conditions and what to wear."`
`model`	string	Yes	The language model ID to use by the application. Refer to Supported Models.	`"gpt-4o-2024-05-13"`

Starter Buttons

You can enhance user interactions in your application by adding buttons, known as starters, at the beginning of the conversation. These buttons allow users to select a predefined message to launch a conversation.

Use starters to enable starter buttons.

Field	Type	Required	Description	Example
`starters`	array of strings	No	Suggested starting prompts shown to users on the UI.	`["What to wear in London", "What is the weather in Paris"]`

Example

  "applicationProperties": {
    "starters": [
      "What to wear in London",
      "What is the weather in Paris"
    ],
  }

Tools

Use tools to extend the functionality of your Quick App. Applications or models deployed in DIAL, external services and web APIs can serve as tools.

Apps & Models as Tools

Your Quick app can be configured to use other applications and models deployed in DIAL as tools to perform specific actions. Set applications_as_tools property in your Quick app to enable this. It can reference specific applications/models by their IDs or use groups of conditions to dynamically match applications/models based on specific properties.

Field	Type	Required	Description	Example
`applications_as_tools`	array of `conditions` or `strings`	No	References to other applications/models that can be used as tools by this application. Can be a direct application/model ID(s) and groups of condition(s) to match applications/models.	`["copilot_deck_app"]` and conditions to match applications/models with specific patterns

Example

  "applicationProperties": {
    "applications_as_tools": [
      "copilot_deck_app"
    ], 
  }

Conditions

applications_as_tools can accept both direct application/model IDs as strings and conditions objects that define matching criteria for applications/models. If provided both, conditions object logically serves as OR in relation to string. The objects within the conditions array are combined using a logical AND operation.

Example in which two tools are enabled RAG and Copilot Deck App

  "applicationProperties": {
    "applications_as_tools": [
      {
        "conditions": [
          {
            "condition_type": "match",
            "property_name": "id",
            "expression": ".*rag.*"
          }
        ]
      },
      "copilot_deck_app"
    ], 
  }

Properties that can be matched

You can match applications/models based on these properties:

id - Application/model identifier
display_name - Display name of the application/model
description - Application/model description
application - whether deployment is an application or a model

Condition types

conditions supports the following condition types:

Condition Type	Description	Required Fields	Example
`eq`	Matches exact values for a property.	`property_name`, `const`	`{"condition_type": "eq", "property_name": "display_name", "const": "RAG Assistant"}`
`match`	Pattern matching using regex.	`property_name`, `expression`	`{"condition_type": "match", "property_name": "id", "expression": ".rag."}`

Here's how to use `conditions`

{
  "applications_as_tools": [
    "direct_application_id",
    {
      "conditions": [
        {
          "condition_type": "match",
          "property_name": "id",
          "expression": ".*rag.*"
        },
        {
          "condition_type": "eq",
          "property_name": "display_name",
          "const": "Specific App Name"
        }
      ]
    }
  ]
}

External Tools

Your application can use external tools that can be invoked outside of the Quick app application. Include the client_toolset property to enable this.

Unlike apps and models as tools, when the LLM decides to call a client_toolset tool, the processing chain is stopped, and Quick app responds with AI message with a tool_call. The response also includes additional metadata (intermediate_steps_to_restore) that needs to be sent back to Quick app along with the tool_call result once the tool execution is completed to ensure proper flow restoration.

Example

{
    "custom_content": {
        "state": {
            "intermediate_steps_to_restore": "[[{\"lc\": 1, \"type\": \"constructor\", \"id\": [\"langchain\", \"schema\", \"agent\", \"ToolAgentAction\"], \"kwargs\": {\"tool\": \"geo_code\", ...}}]]"
        }
    }
}

The client_toolset tools are intended purely for external calls and require aligned handling of communication outside the Quick app environment.

Field	Type	Required	Description	Example
`client_toolset`	array of `ClientToolInfo`	No	A collection of external client tools that can be called outside the Quick app application.	See Structure for details.

Structure

Each tool within the client_toolset is designed to serve a specific functionality, and it is represented by the name, description, and its parameters. These tools can be invoked by providing the required parameters as input. When a tool is invoked, Quick app expects the result to include the metadata for intermediate_steps_to_restore alongside the computed result.

Field	Type	Required	Description
`name`	string	Yes	Name of the tool accessible for LLM.
`description`	string	Yes	Description of the external tool accessible for LLM.
`parameters`	array of ClientToolsetParamInfo	Yes	List of parameters required for the external tool call. Refer to Parameters.

Parameters

The parameters field in the client_toolset defines the input required by the external tool. Each parameter within the tool configuration specifies its name, parameter_type, and a brief description. This ensures that the tool interface is well-documented and easy to utilize.

Field	Type	Required	Description	Example
`name`	string	Yes	Parameter's name used when invoking the tool.	`"param"`
`description`	string	Yes	User-friendly description of the parameter used by the tool.	`"param to multiply"`
`parameter_type`	enum	Yes	Data type of the parameter (string, number, integer, etc.).	`"integer"`

Example

  "applicationProperties": {
    "client_toolset": [
      {
        "name": "multiply_tool",
        "description": "multiply_tool description",
        "parameters": [
          {
            "name": "param",
            "description": "param to multiply",
            "parameter_type": "integer"
          }
        ]
      }
    ],
  }

Web API

Your Quick app can use tools to call different web APIs. Include the web_api_toolset property of the Quick app schema to enable this.

Field	Type	Required	Description	Example
`web_api_toolset`	array of `WebApiToolsetInfo`	No	Collection of API tools that the application can use to fetch external data.	See Structure for details.

Structure

One WebApiToolsetInfo item from the web_api_toolset array corresponds to one specific web API and contains:

allowed endpoints (method + url + parameters) (ToolEndpointInfo)
authorization details (auth_info) for the website

Each WebApiToolsetInfo object has the following structure:

Field	Type	Required	Description
`tool_endpoints`	array of `ToolEndpointInfo`	Yes	Collection of endpoints the tool can call. Refer to Tool Endpoints Definition for details.
`auth_info`	`WebApiToolsetKeyAuthInfo` or null	Yes	Authentication configuration for the endpoints. Refer to API Key Authentication for details.

Tool Endpoints Definition

The tool_endpoints field contains an array of web API endpoints, where each endpoint represents a single web API method (e.g., GET /cart) along with its list of parameters. The primary goal is to convert each method into a tool that the LLM can use.

Each ToolEndpointInfo contains:

Field	Type	Required	Description	Example
`name`	string	Yes	Name of the tool function accessible for LLM.	`"geo_code"`
`method_url`	string	Yes	URL of the API endpoint.	`"https://geocode.maps.co/search"`
`method_type`	string enum	Yes	HTTP method (get, post, put, delete).	`"get"`
`description`	string	Yes	Description of what the tool accessible for LLM does.	`"To get geo information (lat, lon, etc.) for the address, or city, or location"`
`parameters`	array of `ToolEndpointParameterInfo`	Yes	Parameters for the API call.	Refer to Parameters Definition fore details.

Parameters Definition

The primary purpose of describing parameters is not only to provide type hints and descriptions for the LLM but also to distinguish web API endpoint parameters that should have constant values and must not be exposed to the model.

Each ToolEndpointParameterInfo contains:

Field	Type	Default	Required	Description
`name`	string		Yes	The name of the parameter that the LLM can use to invoke the tool.
`description`	string		Yes	User-friendly explanation of the parameter accessible for the LLM.
`parameter_type`	enum		Yes	Data type (`string`, `number`, `integer`, `boolean`, `object`, `array`) of the parameter.
`url_param`	boolean	`false`		If `true`, the parameter will be sent as query param instead of request body.
`constant_value`	any	`null`		Fixed value that will be used (LLM will not be aware of this parameter at all).
`item_parameter_type`	enum	`null`		Specifies the data type of array items. For arrays only.
`item_descriptor`	string	`null`		Description of individual array items. For arrays only.

Example

  "applicationProperties": {
    "web_api_toolset": [
      {
        "tool_endpoints": [
          {
            "name": "geo_code",
            "method_url": "https://geocode.maps.co/search",
            "method_type": "get",
            "description": "To get geo information (lat, lon, etc.) for the address, or city, or location",
            "parameters": [
              {
                "name": "q",
                "description": "location you want to get geo information about",
                "parameter_type": "string",
                "url_param": true
              }
            ]
          }
        ],
      },
    ]
  }

API Key Authentication

Provide these parameters to configure authentication for the web API endpoints.

Field	Type	Required	Description	Example
`auth_type`	string	Yes	Set to `"apikey"`.	`"apikey"`
`api_key`	string (password)	Yes	API key value.	`"your_api_key"`
`url_param`	boolean	No	Indicates if the key should be sent as a URL parameter. If set to `false`, it will be sent in the request header. Defaults to `false`.	`true`

Example

  "applicationProperties": {
    "web_api_toolset": [
      {
        "tool_endpoints": [
          {
            "name": "geo_code",
            "method_url": "https://geocode.maps.co/search",
            "method_type": "get",
            "description": "To get geo information (lat, lon, etc.) for the address, or city, or location",
            "parameters": [
              {
                "name": "q",
                "description": "location you want to get geo information about",
                "parameter_type": "string",
                "url_param": true
              }
            ]
          }
        ],
        "auth_info": {
          "auth_type": "apikey",
          "api_key": "your_api_key",
          "url_param": true
        }
      },
    ]
  }

RAG Integration

Retrieval Augmented Generation (RAG) is integrated into Quick Apps as a tool named query_document with the description: "Ask RAG a question about the documents assuming it will have access to the conversation history.". When writing instructions for applications using RAG, you should explicitly mention the need to query the document first before answering questions.

For optimal results, the instructions should:

Direct application to use the RAG tool to retrieve relevant information.
Explicitly state to use only the information found in the documents.
Provide a fallback response for questions not covered by the documents.

This approach ensures the AI properly leverages the RAG capabilities and produces responses grounded in the provided documents.

Example

You should help explore the document containing the Copilot Deck. You must query the document first to do that. You should answer using only the information in the document. Answer "I don't know" if there are any other questions.

To provide information sources for RAG, use the document_relative_url field.

Field	Type	Required	Description	Example
`document_relative_url`	string or array of strings	No	Path(s) to document(s) that the application can use for Retrieval Augmented Generation (RAG). Each path must be a valid file reference in DIAL.	`"files/DpZGXdhaFYCWNadE2Ln/GPT Deck text.docx"`

Example

"applicationProperties": {
  "document_relative_url": ["files/DpZGXdFYCWNadE2Ln/GPT%20Deck%20text.docx"]
}

Refer to RAG Example to see an example of a Quick app with RAG integration.

Examples

RAG

Am example of a configuration in DIAL Core for the Copilot Deck application:

 "applications":
    "copilot_deck_app": {
      "displayName": "Copilot Deck Explorer",
      "description": "You can ask about the copilot deck there",
      "applicationTypeSchemaId": "https://mydial.epam.com/custom_application_schemas/quickapps",
      "applicationProperties": {
        "temperature": 0.8,
        "instructions": "Answer using only the information in the document.",
        "model": "gpt-4o-2024-05-13",
        "web_api_toolset": [],
        "document_relative_url": ["files/DpZGXdFYCWNadE2Ln/GPT%20Deck%20text.docx"]
      }
    }

Complete Example

{
  "displayName": "Weather Quick App Demo",
  "description": "You can ask about the weather or clothes to wear",
  "applicationTypeSchemaId": "https://mydial.epam.com/custom_application_schemas/quickapps",
  "applicationProperties": {
    "temperature": 0.8,
    "instructions": "You are a weather assistant. Help users understand weather conditions and what to wear.",
    "model": "gpt-4o-2024-05-13",
    "document_relative_url": ["files/DpZGXdFYCWNadE2Ln/GPT%20Deck%20text.docx"],
    "starters": [
      "What to wear in London",
      "What is the weather in Paris"
    ],
    "applications_as_tools": [
      {
        "conditions": [
          {
            "condition_type": "match",
            "property_name": "id",
            "expression": ".*rag.*"
          }
        ]
      },
      "copilot_deck_app"
    ], 
    "client_toolset": [
      {
        "name": "multiply_tool",
        "description": "multiply_tool description",
        "parameters": [
          {
            "name": "param",
            "description": "param to multiply",
            "parameter_type": "integer"
          }
        ]
      }
    ],
    "web_api_toolset": [
      {
        "tool_endpoints": [
          {
            "name": "geo_code",
            "method_url": "https://geocode.maps.co/search",
            "method_type": "get",
            "description": "To get geo information (lat, lon, etc.) for the address, or city, or location",
            "parameters": [
              {
                "name": "q",
                "description": "location you want to get geo information about",
                "parameter_type": "string",
                "url_param": true
              }
            ]
          }
        ],
        "auth_info": {
          "auth_type": "apikey",
          "api_key": "your_api_key",
          "url_param": true
        }
      },
      {
        "tool_endpoints": [
          {
            "name": "weather",
            "method_url": "https://api.open-meteo.com/v1/forecast",
            "method_type": "get",
            "description": "To get current weather for geo coordinates (lat, lon)",
            "parameters": [
              {
                "name": "latitude",
                "description": "latitude of location you want to get current weather",
                "parameter_type": "number",
                "url_param": true
              },
              {
                "name": "longitude",
                "description": "longitude of location you want to get current weather",
                "parameter_type": "number",
                "url_param": true
              },
              {
                "name": "current",
                "description": "values you want to get info about in terms of current weather",
                "parameter_type": "string",
                "url_param": true,
                "constant_value": "temperature_2m"
              },
              {
                "name": "format",
                "description": "format of output data",
                "parameter_type": "string",
                "url_param": true,
                "constant_value": "csv"
              }
            ]
          }
        ],
        "auth_info": null
      }
    ]
  }
}

Quick App Configuration Guide

Introduction​

Configuration​

Main Parameters​

Starter Buttons​

Example​

Tools​

Apps & Models as Tools​

Example​

Conditions​

Example in which two tools are enabled RAG and Copilot Deck App​

Properties that can be matched​

Condition types​

Here's how to use conditions​

External Tools​

Example​

Structure​

Parameters​

Example​

Web API​

Structure​

Tool Endpoints Definition​

Parameters Definition​

Example​

API Key Authentication​

Example​

RAG Integration​

Example​

Example​

Examples​

RAG​

Complete Example​

Introduction

Configuration

Main Parameters

Starter Buttons

Example

Tools

Apps & Models as Tools

Example

Conditions

Example in which two tools are enabled RAG and Copilot Deck App

Properties that can be matched

Condition types

Here's how to use `conditions`

External Tools

Example

Structure

Parameters

Example

Web API

Structure

Tool Endpoints Definition

Parameters Definition

Example

API Key Authentication

Example

RAG Integration

Example

Example

Examples

RAG

Complete Example