Last updated Aug 6, 2024

When you use Rovo APIs, you must comply with the Atlassian Acceptable Use Policy, including the section titled “Artificial intelligence offerings and features.” For the protection of our customers, Atlassian performs safety screening on Agents at our sole discretion. If we identify any issues with your Agent, we may take protective actions, such as preventing the Agent from being deployed or suspending your use of Rovo APIs. Where possible we will notify you of the nature of the issue, and you must use reasonable commercial efforts to correct the issue before deploying your Agent again.

Build a Rovo Agent hello world app

This tutorial walks through creating a Forge app that adds a new Agent to Rovo. You will also create an action, which allows that Agent to invoke custom logic with input from the user's chat.

At the end of this tutorial, you’ll have created a Forge app that creates a Agent that can take a user's prompt and log a simple hello world message inside a Forge function.

Before you begin

Complete Getting started before working through this tutorial.

Install @forge/cli version 10.3.0 or higher.

To install:

1
2
`npm install --g @forge/cli@latest` or

`npm install --g @forge/cli@^10.3.0`

Enable Rovo in your organization

To build an Agent, you need a test site with the Rovo beta enabled.

Go to admin.atlassian.com/rovo to activate your test organisation. It must be the one for which you provided the organizationId during the Forge Rovo Agents EAP sign-up.

Enable orginization on your site

Create your app

  1. Create your app by running:

    1
    2
    forge create
    
  2. Enter a name for your app (up to 50 characters). For example hello-world-rovo-agent.

  3. Select the Rovo agent and action (EAP) category.

  4. Select the rovo-agent template.

  5. Change to the app subdirectory to see the app files.

    1
    2
    cd hello-world-rovo-agent
    

The rovo-agent template uses Node.js and has the following structure:

1
2
├── manifest.yml
├── package.json
└── src
    └── index.js

manifest.yml

Your manifest.yml file should look like the following, with your values for the title and app ID:

For a detailed understanding of the manifest structure, refer to the Agent module.

1
2
modules:
  rovo:agent:
    - key: hello-world-agent
      name: Hello world agent
      description: An Agent for testing Forge agent functionality
      prompt: >
        You are a simple Rovo Agent that helps Forge developers build their first
        Agent.

        You can create Forge logs by using the hello-world-logger action.

        If the user hasn't provided a message when they ask you to create a log ask them to provide one.
      conversationStarters:
        - Log a message to Forge logs
      actions:
        - hello-world-logger
  action:
    - key: hello-world-logger
      function: messageLogger
      actionVerb: TRIGGER
      description: >
        When a user asks to log a message, this action logs the message to the
        Forge logs.
      inputs:
        message:
          title: Message
          type: string
          required: true
          description: |
            "The message that the user has requested be logged to Forge logs"
  function:
    - key: messageLogger
      handler: index.messageLogger
app:
  runtime:
    name: nodejs18.x
  id: <your app id>

index.js

The index.js file exports the messageLogger function, which takes a payload object containing a user-provided message and logs it to the console. This function is invoked by the hello-world-logger action defined in the manifest to log messages as requested by the user.

Install your app

To use your app, it must be installed onto an Atlassian site. The forge deploy command builds, compiles, and deploys your code; it'll also report any compilation errors. The forge install command then installs the deployed app onto an Atlassian site with the required API access.

You must run the forge deploy command before forge install because an installation links your deployed app to an Atlassian site.

  1. Navigate to the app's top-level directory and deploy your app by running:

    1
    2
    forge deploy
    
  2. Install your app by running:

    1
    2
    forge install
    
  3. Select your Atlassian product using the arrow keys and press the enter key.

  4. Enter the URL for your development site. For example, example.atlassian.net. View a list of your active sites at Atlassian administration.

Once the successful installation message appears, your app is installed and ready to use on the specified site. You can always delete your app from the site by running the forge uninstall command.

Running the forge install command only installs your app onto the selected organization. To install onto multiple organizations, repeat these steps again, selecting another organization each time. You must run forge deploy before running forge install in any of the Forge environments.

View your Rovo Agent

With your app installed, it is time to chat with your new Agent.

  1. Access Rovo chat by clicking Chat on the top menu within the product where you have installed the app.
  2. In the Chat side panel, click the Agent selector and go to Browse Agents. example of browsing rovo agent from the list
  3. Find the Hello world Agent and click Enable.
  4. Now use the Agent selector to select the Hello world agent. example of Agent hello world app
  5. Chat with the Agent and invoke your action. Ask the Agent to log a message for you or use the conversation starter, Log a message to Forge logs.
    Agent has now successfully logged a message to Forge logs via your Forge function. example of Rovo agent chat window
  6. Navigate to the app's top-level directory to check the logs by running:
    1
    2
    forge logs
    

You should see a Forge log with your message:

example of Rovo agent creating a log

Change the behaviour of your agent

The main way to change the behaviour of your Agent is by modifying the prompt in the manifest.yml file.

  1. Add an additional instruction to the end of your prompt: After you successfully log a message, respond with a positive affirmation
  2. Deploy your Forge app:
    1
    2
    forge deploy
    
  3. Test your Agent again. Notice the change in tone: example of Agent chat after changing the prompt

Change the behaviour of your action

The behaviour of the action is defined by the Forge function in the index.js file:

1
2
export function messageLogger (payload) {
    console.log(`Message: ${payload.message}`);
    return `Successfully logged payload: ${payload.message}`
}
  1. Add an additional console.log line to inspect the payload object.

    1
    2
        console.log(`Payload: ${JSON.stringify(payload)}`);
    
  2. The payload returns an additional context object, which can contain identifiers relevant to the user’s current context.

    1
    2
    "context":{
    "confluence": {
        "url": "https://mysite.atlassian.com/wiki/spaces/~61df1116125b12007152148f/pages/10092545/Mypage",
        "resourceType": "page",
        "contentId": "10092545",
        "spaceKey": "~61df1116125b12007152148f",
        "spaceId": "33248"
    },
    "cloudId": "13c6457e-69c5-4ad4-880a-dbdd77ef39f2",
    "moduleKey": "hello-world-logger"
    }
    

    These can be useful for checking the identifiers passed in via action inputs which the LLM can sometimes get wrong.

  3. Now we can log an extra message detailing whether the user is a Confluence page, blog post or another resource type.

    Update your messageLogger function as follows:

    1
    2
    export function messageLogger(payload) {
      console.log(`Message: ${payload.message}`);
    
      const message = `The user is on a Confluence ${payload.context?.confluence?.resourceType}`;
      console.log(message);
      return message;
    }
    
  4. Deploy your app:

    1
    2
    forge deploy
    
  5. Test your Agent again:

    example of Agent chat after changing the action

  6. Check the Forge logs to verify that the action was successfully executed:

    1
    2
    forge logs
    

    You should see Forge logs with your messages:

    example of Agent chat after changing the action

Rate this page: