Action (Preview)

An action module lets a Rovo Agent perform a specific task, like calling an API or running predefined code. Actions are implemented as a Forge function and have a plain text name and description, so Rovo Agent can understand what it does and decide when to invoke it.

Manifest structure

1
2
modules {}
└─ action []
   ├─ key (string) [Mandatory]
   ├─ name (string) [Mandatory]
   ├─ function (string) [Mandatory]
   ├─ actionVerb (string) [Mandatory]
   ├─ description (string) [Mandatory]
   ├─ inputs {} [Mandatory]
   │  └─ inputName {}
   │     ├─ title (string) [Mandatory]
   │     ├─ type (string) [Mandatory]
   │     ├─ required (boolean) [Mandatory]
   │     └─ description (string) [Optional]
function []
└─ key (string) [Mandatory]
└─ handler (string) [Mandatory]

In this structure:

• The action array includes generic properties such as key, name, function, actionVerb, description, and inputs.
• The inputs object contains input fields, represented generically as inputName, with properties title, type, required, and description.
• The function array includes properties key and handler.

Properties

Inputs

Each input must have a unique user-defined name, referred to as inputName, which acts as a parent container for the properties listed below.

Example using a hosted Forge function:

1
2
modules:
  action:
    - key: fetch-timesheet-by-date
      name: Fetch timesheet by date
      function: getTimesheetByDate
      actionVerb: GET
      description: |
        Retrieve a user's timesheet based on a date
      inputs:
        timesheetDate:
          title: Timesheet Date
          type: string
          required: true
          description: "The date that the user wants a timesheet for"
  function:
    - key: getTimesheetByDate
      handler: index.getTimesheetByDate

Example using a Forge remote endpoint

1
2
modules:
  action:
    - key: log-time
      endpoint: logTime
      name: Log time
      actionVerb: CREATE
      description: |
        Log some time for the user against a Jira issue
      inputs:
        issueKey:
          title: Jira Issue Key
          type: string
          required: true
          description: "The jira issue to log time against"
        time:
          title: Time to log in minutes
          type: integer
          required: true
          description: "The number of minutes to log"
  endpoint:
  - key: logTime
    remote: timesheetapp
      route:
        path: log-time
      auth:
        appUserToken:
          enabled: true
        appSystemToken:
          enabled: false
remote: 
  - key: timesheetapp
    baseUrl: "https://backend.timesheetapp.com"

Writing your action

The business logic for your action is in the referenced Forge function (or remote endpoint if you are using Forge remote).

The payload and requestContext are passed into the function as arguments.

The payload will include the inputs defined for the action. In certain contexts (e.g. viewing a Jira issue, Confluence page) the payload will also include a context object with relevant product identifiers (e.g. issueKey, contentId).

The requestContext contains the user's accountId.

Jira issue example

1
2
"payload": {
    "input1ToYourAction": 1241,
    "input2ToYourAction": 12412,
    "context": {
        "cloudId":"7607d59e-650b-4c16-adcf-c19d17c915ac",
        "moduleKey":"sum-2-numbers-new-action",
        "jira": {
          "url": "https://mysite.atlassian.com/browse/FAA-1",
          "resourceType": "issue",
          "issueKey": 1,
          "issueId": 123,
          "issueType": "story",
          "issueTypeId": 1234,
          "projectKey": "FAA",
          "projectId": 5678
      }
    }
}

Confluence page example

1
2
"payload": {
    "input1ToYourAction": 1241,
    "input2ToYourAction": 12412,
    "context": {
        "cloudId":"7607d59e-650b-4c16-adcf-c19d17c915ac",
        "moduleKey":"sum-2-numbers-new-acion",
        "confluence" : {
            "url": "https://mysite.atlassian.com/wiki/spaces/~65536301eb7512314748ebb489aba9d526b0f8/blog/2024/06/27/44662787/Holiday+in+Japan",
            "resourceType": "blog",
            "contentId": "44662787",
            "spaceKey": "~65536301eb7512314748ebb489aba9d526b0f8",
            "spaceId": "2064386"
        }
    }
}

Understanding input and context

• Input: The LMM extracts inputs from the product context and user interactions (e.g., chat prompts). This makes it more flexible but also leaves it subject to hallucination.

  Your app should never rely on values passed as inputs to perform critical checks like authorization. If you need a user’s accountId read it from the requestContext.

• Context: For certain contexts (e.g., issue view, page view), the product context will be included as part of the payload. This is done deterministically in the same way the product context is passed to other Forge modules.

Providing both for the early access program is somewhat of an experiment to see what is most useful, or how they might be used in combination. For example, you might run a basic regex on an issueKey passed through the inputs, and if it isn’t valid, then fall back to the value in the context if present. We’re keen to get your feedback on how this works in practice. Please provide your input on the CDAC or Slack channels.

Returning data

Your function can return any string or JSON object, which the Agent will interpret and transform into a natural-language response to the customer.

Example function

The logTime function from the previous example might look like this:

1
2
export function logTime (payload, requestContext) {
    console.log(`payload: ${JSON.stringify(payload)}`);
    console.log(`payload: ${JSON.stringify(requestContext)}`);
    
    // Extract necessary information
    const { issueKey, minutes } = payload;
    
    // Code to actually log time to the timesheet
    
    // Construct the success message
    const result = `${minutes} minutes added to issue ${issueKey}`;
    return result;
}