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.

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:

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.

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.

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.
3. Find the Hello world Agent and click Enable.
4. Now use the Agent selector to select the Hello world agent.
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.
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:

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:

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:

   

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: