App Schema Writing Guide

1. What is an App Schema?

• An App Schema defines the fields and formats required for Gleo AI to call a specific function within an app.
• An App Schema must follow the JSON Schema following the specification below.

2. App Schema

2.1 Fields

• packageName(string): The package name of an Android application.
• appDescription(string): A concise description that clearly represents the app's main purpose. Refer to Guidelines for Writing App Schema.
• invokeWord(string): A keyword that helps Gleo AI identify which app to run among multiple apps when processing a user’s command. It is recommended to use the language of the service area or country.
• version(string): The version of the application in Pleos App Market.
• actionCalls(array): A list of functions that can be called by a user's voice command (up to maximum of three).
  • type(string, fixed as "function")
  • function(object)
    • component(string, defaults to "activity"): Specifies how the function should be invoked by Gleo AI in Android. You can implement either method depending on your app’s design and use case.
      • "activity": The action will be triggered using Android's context.startActivity() method. Use this when the action requires launching a foreground UI or user interaction.
      • "service": The action will be sent using Android's context.sendBroadcast() method. This is suitable for background processing without UI.
    • name(string): A unique function name used to differentiate calls within an app. It MUST be written in uppercase with words separated by underscores (_).
    • description(string): A clear, concise, and complete explanation of the function’s purpose and role.
    • parameters(object)
      • type(string, fixed as "object")
      • properties(object): An object that specifies properties of parameters. Each property must contain a parameter name as the object name, and an object of type, description, and (optionally) features that follow the JSON Schema as the object value. Refer to Example of an App Schema and Guidelines for Writing App Schema below.
      • required(array<string>): An array of parameter names necessary to execute the function.

3. Example of an App Schema

The following example assumes an app (packageName: ai.dot42.pleos.reminderapp) that supports three functions:

{
  "packageName": "ai.dot42.pleos.reminderapp",
  "appDescription": "A reminder app that lets you schedule tasks and receive notifications at the right time.",
  "invokeWord" : "리마인더",
  "version" : "1.0.0",
  "actionCalls": [
    {
      "type": "function",
      "function": {
        "name": "ADD_REMINDER",
        "description": "Add a reminder that will notify the user at the given date and time.",
        "parameters": {
          "type": "object",
          "properties": {
            "title": {
              "type": "string",
              "description": "Title of the reminder."
            },
            "dateTime": {
              "type": "string",
              "description": "Date and time to trigger the reminder notification, in ISO 8601 date and time format."
            }
          },
          "required": ["title", "dateTime"]
        }, 
        "component": "activity"
      }
    },
    {
      "type": "function",
      "function": {
        "name": "SEARCH_REMINDER",
        "description": "Search for a reminder that matches or contains the search term.",
        "parameters": {
          "type": "object",
          "properties": {
            "searchTerm": {
              "type": "string",
              "description": "The keyword for searching a reminder."
            }
          },
          "required": ["searchTerm"]
        }, 
        "component": "activity"
      }
    },
    {
      "type": "function",
      "function": {
        "name": "DELETE_REMINDER",
        "description": "Delete a reminder from the list of reminders.",
        "parameters": {
          "type": "object",
          "properties": {
            "searchTerm": {
              "type": "string",
              "description": "The title or keyword for deleting a reminder."
            }
          },
          "required": ["searchTerm"]
        }, 
        "component": "activity"
      }
    }
  ]
}

4. Guidelines for Writing App Schema

• actionCalls
  • actionCalls contains functions that can be triggered by a user's voice command. The number of functions is limited to three, but users can still use other features in the app through on-screen (display) interactions.
• Function name
  • Each function name in an App Schema must be unique and must not overlap with others.
  • For optimal performance, try to design each function to perform a full user-level command independently, without requiring orchestration across multiple calls.
  • In addition to just a verb, we recommend to include a specific target using 2~3 words.
• Descriptions for app, function, and parameter
  • All descriptions must be written in English.
  • Do not include any instruction that intentionally manipulates the behavior of Gleo AI, or discourages use of other apps or functions.
  • Avoid writing specific examples in the descriptions, as they may interfere with Gleo AI’s ability to call the appropriate actions based on the context.
  • Ensure the descriptions to be as concise as possible but comprehensive enough to cover the app, function, or parameter. One sentence is recommended, with a maximum of two.
• Parameter properties
  • A parameter’s type must be one of string, number, boolean, or array.
    • The set of supported types is limited for now, but it will be expanded over time, along with a type-checking feature.
  • Parameter names should clearly represent the value so that an LLM can easily understand them.
• required field
  • Include the parameters that are required to call the function, following the parameter order defined in the App Schema. Do not include any optional parameters.
  • Note that Gleo AI does not guarantee all required parameters to be filled in function calling, but specifying them in this field helps improve the success rate.