Action Packages and Actions

Action packages are JSON files that define an agent (or group of actions) with the following attributes:

  • versionLabel - The version label for the action package.
  • languageCode - Only en-US is supported for now. Support for more languages is coming later.
  • projectId - The Google developer project ID that is associated with your actions. You use this project to track your actions' approval status.
  • voiceName - The TTS voice type for your actions. There are two male and two female voices to choose from.
  • accountLinking - Defines OAuth 2.0 configuration information if your actions require users to log in. See Account linking for more information.

In addition to these attributes that apply to all actions, action packages contain an actions array that defines the invocation triggers, dialogs, and fulfillment URL for individual actions.

Action package structure

{
  "versionLabel": "action_pkg_version",
  "agentInfo": {
    "languageCode": "en-US",
    "projectId": "google_developer_project_id",
    "voiceName": "male_1|male_2|female_1|female_2"
    "accountLinking": {
      "grantType": ...,
      "clientId": ...,
      "clientSecret": ...,
      "authenticationUrl": ...,
      "accessTokenUrl": ...,
      "scopes": [
        ...
      ]
    }
  },
  "actions": [
    {
      "initialTrigger": {
        "intent": ... ,
        "queryPatterns": [
          {
            "queryPattern": ...
          }
        ]
      },
      "httpExecution": {
        "url": ...
      }
    }
  ]
}

Creating an action package

To create a template action package file that you can modify for your own use:

  1. Create a directory for your actions project. We'll refer to this as <actions-project>.
  2. Run the following command:

    $ gactions init
    

This creates an agent.json file that looks like the following:

{
  "versionLabel": "guess a number V1",
  "agentInfo": {
    "languageCode": "en-US",
    "projectId": "<INSERT YOUR PROJECT ID HERE>",
    "voiceName": "male_1"
  },
  "actions": [
    {
      "description": "Launch intent",
      "initialTrigger": {
        "intent": "assistant.intent.action.MAIN"
      },
      "httpExecution": {
        "url": "<INSERT YOUR EXECUTION URL HERE>"
      }
    },
    {
      "description": "guess a number game",
      "initialTrigger": {
        "intent": "START_GUESS_NUMBER",
        "queryPatterns": [
          {
            "queryPattern": "find a magic number"
          },
          {
            "queryPattern": "guess a number"
          }
        ]
      },
      "httpExecution": {
        "url": "<INSERT YOUR EXECUTION URL HERE>"
      }
    }
  ]
}

Defining actions

An action package can contain one or many actions, which are defined in the actions array. You define the following main components for an individual action within the actions array:

  • Invocation and Discovery - You define this within initialTrigger elements. The Google Assistant invokes your Conversation Action when it detects that it can handle a user's request. Defining these triggers in your action package allows Google to do action ranking so we can deliver the most appropriate actions to users.

    See the Invocation and Discovery guide for information on how to define these elements.

  • Dialogs and Fulfillment - You implement the dialogs that you design in your fulfillment logic. When users say a phrase, it's returned to you as text that you typically process with an NLU (natural language understanding) solution. You define the fulfillment URL with the httpExecution flag.

    See the Dialogs and Fulfillment guide for information on how to define dialogs and fulfillment.

"actions": [
  {
    ...
    "initialTrigger": {
      ...
    },
    "httpExecution": {
      ...
    }
  }
  ...
]

Configuration rules

The following table describes the maximum amount of each property

Actions SDK Maximum #
Actions in Action Package 10
Query patterns per initial trigger 10
UTF characters per query pattern 128
Characters in intent name 255