Bixby Developer Center

A behavioral mode that modifies how the planner will attempt to instantiate the input.

Always

In this behavioral mode, the planner requires that this input be instantiated (either directly by a value signal or indirectly by property projection). If the input cannot be instantiated silently and instead has to be obtained by more involved methods requiring user input, such as elicitation, the resulting plan is avoided in favor of plans that do not go through this input.

Example

Here is a lazy-source action to get the distance between a business and the user's current location. This should run in the background without user involvement, so mark the GeoPoint input as plan-behavior (Always) so that the action is only called when the GeoPoint can be instantiated from the business (by doing a property projection of its coordinates). If a business is missing coordinates, then instead of prompting the user to provide a GeoPoint, the action is simply ignored.

action (GetCurrentDistance) {
  type (Fetch)
  collect {
    input (point) {
      type (GeoPoint)
      min (Required)
      plan-behavior (Always)
    }
  }
  output (Distance)
}

Direct

In this behavioral mode, the planner only instantiates this input with the direct usage of a value signal. In other words, the input is used to collect an explicit value from an intent, but is not instantiated otherwise.

Example

In this example, you allow users to refine their search for a contact by phone type (home, mobile), so add the input (type) to the find phone number action. This effectively captures that input when present. When absent, the planner's default plan behavior leads it to instantiate the phone type from the contact input, pulling in contact.phoneInfo.type. To avoid this extraneous planning, annotate the phone type input as plan-behavior (Direct)

action (FindPhoneNumber) {
  type (Search)
  description (Find a phone number for a contact.)

  collect {
    input (contact) {
      type (Contact)
      min (Required) max (One)
    }
    input (type) {
      type (PhoneType)
      min (Optional) max (One)
      plan-behavior (Direct)
    }
  }

  output (PhoneNumber)
}

Never

In this behavioral mode, the planner only instantiates this input with the direct usage of a value signal. Indirect instantiation (such as with property projections) is not allowed. Note that these inputs can still be instantiated by execution through validation effects, on-empty effects, instantiation strategies, and context (historical) values.

Example

This examples adds a property upcomingEvents to the Performer structure and registers a lazy-source action to fetch all upcoming events for the given performer. The only input to this action is a Performer and the output is Events. This is problematic because there is already a base FindEvents action with multiple input requirements (such as search region and date time interval) and this new FetchPerformerUpcomingEvents creates a path of least resistance that allows the planner to bypass the base FindEvents action for use cases where the only input is a Performer (such as "Find events by Stromae"). To prevent this, declare plan-behavior(Never) on the input such that it can only be used when instantiated directly.

action (FetchPerformerUpcomingEvents) {
  output (Event)
  type (Fetch)
  collect {
    input (performer) {
      min (Required)
      max (One)
      type (Performer)
      plan-behavior (Never) // Only use this to fetch lazy-source properties
    }
  }
}

Role

In this behavioral mode, the planner attempts to instantiate this input using role assignment. Unless you specify plan-behavior (Role), Bixby does not do a role assignment.

Example

The only time-related input in finding recipes is to allow searching by preparation time. You can train these use cases using time patterns like this:

[g:viv.recipe.Recipe] find me a recipe I can make in (30
minutes)[v:viv.time.DurationPeriod].

However, the planner does not know to assign this time.DurationPeriod into the maxPreparationPeriod input, and the plan will appear disconnected. You can manipulate this behavior by marking the input as plan-behavior (Role):

action (FindRecipes) {
  type (Search)
  input (maxPreparationPeriod) {
    description (Be able to prepare a recipe in under this time period, such as 1 hour or 30 minutes.)
    type (MaxPreparationPeriod)
    plan-behavior (Role)
  }
  ...
}