The Developer's Guide to Building Rovo Agents

You build a custom Rovo Agent as an Atlassian Forge app, declaring a rovoAgent module in manifest.yml and implementing each of its actions as a separate Forge function that Rovo invokes based on user prompts. Your manifest must also declare every scope those actions need, because failing to declare required scopes will result in runtime errors.

As AI becomes increasingly central to enterprise operations, the ability to tailor intelligent agents to specific workflows is invaluable. Atlas Bench recently presented a technical deep-dive to our clients on developing custom Rovo Agents using the robust Atlassian Forge platform. This guide distills that expertise, offering developers a comprehensive roadmap for building sophisticated, enterprise-integrated Rovo Agents.

Rovo Agents are more than just AI assistants; they are intelligent teammates capable of executing complex tasks, analyzing vast datasets, and providing contextual insights directly within your Atlassian applications and beyond. While Rovo offers a suite of powerful out-of-the-box agents, the true extensibility of the platform lies in its ability to empower developers to create custom agents precisely tuned to unique organizational needs. Leveraging Atlassian Forge provides the framework for this customization, offering a serverless, secure, and scalable environment for agent development. This deep dive will cover everything from the initial development workflow and manifest configuration to advanced prompt engineering techniques and seamless integration patterns, equipping you to build impactful Rovo Agents.

Understanding the Rovo Agent Development Workflow on Forge

Building a Rovo Agent on Atlassian Forge involves a structured development workflow that leverages Forge's serverless functions and UI Kit or Custom UI capabilities. The process begins with setting up your development environment, defining your agent's core purpose, and then iteratively building and testing its components. Forge simplifies many of the complexities typically associated with cloud development, such as hosting, scaling, and authentication, allowing developers to focus primarily on the agent's logic and behavior. The core idea is to create an Atlassian Forge app that exposes specific "actions" that Rovo can invoke based on user prompts and the agent's defined instructions. This modular approach ensures reusability and maintainability of your agent's functionalities.

The typical development lifecycle for a Rovo Agent involves:

• Initialization: Setting up a new Forge app project using the Forge CLI.
• Manifest Configuration: Defining the Rovo Agent module within the manifest.yml file, including its name, description, and the actions it can perform.
• Action Implementation: Writing the serverless functions (resolvers) that execute the agent's specific tasks, interacting with Atlassian APIs or external systems.
• Prompt Engineering: Crafting precise and effective instructions for the Rovo Agent, guiding its behavior and responses.
• Local Development and Testing: Utilizing the Forge tunnel to debug and test your agent against a live Atlassian instance.
• Deployment: Deploying the Forge app to a development, staging, or production environment.
• Monitoring and Iteration: Observing agent performance, gathering feedback, and continuously refining its logic and prompts.

Manifest Configuration: The Agent's Blueprint

The manifest.yml file serves as the foundational blueprint for your Rovo Agent within the Forge ecosystem. It declares the agent module, defines its capabilities, and specifies how it interacts with the Atlassian platform. Proper configuration of this file is critical for the agent's discovery, functionality, and permissioning.

Here are key aspects and best practices for manifest configuration:

• Declaring the Rovo Agent Module: You'll need to add a rovoAgent module type within your manifest. This module type tells Forge that your app includes a Rovo Agent.

  YAML

  modules:
    rovoAgent:
      - key: my-custom-agent
        name: My Custom Rovo Agent
        description: An agent designed to automate XYZ tasks.
        function: my-agent-function # Refers to a defined Forge function
        actions: # List of actions the agent can perform
          - action-key-1
          - action-key-2
  

• Function Reference: The function property points to a Forge function that acts as the entry point or primary handler for your Rovo Agent's instructions. This function will interpret the user's prompt and decide which actions to invoke.

• Defining Actions: The actions array lists all the specific capabilities or operations your agent can execute. Each action declared here must correspond to a separate Forge function module. This modularity allows Rovo to understand the precise functions your agent can perform and how to call them.

  YAML

  functions:
    - key: my-agent-function
      handler: index.runAgentHandler
    - key: action-key-1
      handler: actions.performActionOne
    - key: action-key-2
      handler: actions.performActionTwo
  

• Permissions (Scopes): Crucially, your manifest must declare all necessary permissions (scopes) that your Rovo Agent's actions require to access Atlassian APIs or external services. Forge's granular security model means you must explicitly request access to resources like Jira issues, Confluence pages, or even external APIs. Failing to declare required scopes will result in runtime errors.

  YAML

  permissions:
    scopes:
      - read:jira-user
      - read:jira-work
      - write:jira-work
      - read:confluence-content
    external:
      fetch:
        - 'https://api.example.com/*' # If interacting with external APIs
  

• Localization: For agents deployed in multinational enterprises, consider adding internationalization support in your manifest for agent names, descriptions, and potentially action parameters.

Action Creation: Bringing Your Agent to Life with Code

Rovo Agent actions are the executable units of work that your agent performs. Each action is implemented as a separate Forge function (a resolver) that takes specific inputs, performs an operation (e.g., fetching data, creating an issue, sending a notification), and returns a structured output. These functions are typically written in JavaScript or TypeScript.

Consider an example of an action designed to create a Jira issue:

This createJiraIssue action would be referenced in your manifest.yml. When Rovo decides to "create a Jira issue" based on user input, it would invoke this function, passing in the parsed summary, description, projectKey, and issueType. The function then uses Forge's api.asApp().requestJira to securely interact with the Jira API. The return object provides a structured response that Rovo can use to inform the user.

Prompt Engineering Best Practices for Rovo Agents

The effectiveness of your Rovo Agent heavily relies on the quality of its instructions, commonly known as "prompt engineering." This involves crafting clear, concise, and comprehensive directives that guide the AI's understanding and behavior. A well-engineered prompt ensures the agent consistently performs its intended tasks and provides relevant responses.

• Define a Clear Role and Persona: Assign a specific role to your agent (e.g., "You are an expert Jira Project Manager," "You are a Confluence documentation assistant"). This sets the context for its responses.
• Specify Tasks and Objectives: Clearly list the main tasks the agent is expected to perform. Be explicit about what it should do and, equally important, what it should not do.
• Provide Context and Constraints: Include any necessary background information or constraints. For example, "Always prioritize security considerations," or "Only use information from the provided Confluence spaces."
• Define Input and Output Formats: Specify the expected format of user inputs and the desired format of the agent's outputs (e.g., "Respond in a concise bulleted list," "If an error occurs, provide a detailed but user-friendly explanation.").
• Handle Edge Cases and Ambiguity: Anticipate situations where user input might be ambiguous or incomplete and instruct the agent on how to handle them (e.g., "If information is missing for an action, ask clarifying questions.").
• Iterate and Refine: Prompt engineering is an iterative process. Start with a simple prompt and progressively add detail and nuance as you test and observe the agent's behavior. Small changes in wording can lead to significant differences in performance.
• Leverage Action Descriptions: Ensure that the descriptions for your actions in the Rovo Agent configuration (often defined in Rovo Studio or within the agent's schema if building purely via Forge) are clear and inform the AI about what each action does. This helps Rovo correctly determine which action to call.

Deployment Processes and Environments

Deploying your Rovo Agent built on Forge involves moving your app from your local development environment to an Atlassian Cloud instance, accessible to your users. Forge provides dedicated environments for development, staging, and production, facilitating a structured deployment pipeline.

• Local Development (Forge Tunnel):

  • Use forge deploy to deploy your app to your development environment.
  • Use forge tunnel to create a secure tunnel from your local machine to your deployed Forge app. This allows you to test changes locally and get real-time logs and debug information as Rovo interacts with your agent.

• Staging/Test Deployment:

  • Once satisfied with local testing, deploy your app to a staging environment using forge deploy -e staging.
  • Install the app on a designated staging Atlassian Cloud site. This environment should mimic your production setup as closely as possible for comprehensive testing by a wider internal audience.

• Production Deployment:

  • After successful staging tests, deploy to production using forge deploy -e production.
  • Install the app on your production Atlassian Cloud site. This is the version that end-users will interact with.

Crucially, Forge handles the underlying infrastructure, scaling, and security of your deployed functions. You don't need to manage servers or worry about capacity planning; Forge automatically scales your agents to meet demand.

Common Pitfalls to Avoid

Building sophisticated Rovo Agents with Forge can be powerful, but developers should be aware of common pitfalls:

• Insufficient Permissions (Scopes): This is a frequent issue. Always double-check that your manifest.yml explicitly lists all necessary API scopes and external fetch permissions for every action and function your agent performs.
• Overly Broad or Ambiguous Prompts: A poorly defined prompt will lead to inconsistent or irrelevant agent responses. Be specific, provide context, and iterate on your prompts.
• Ignoring Error Handling: Robust error handling within your Forge functions is crucial. Ensure your actions gracefully handle API failures, invalid inputs, and unexpected scenarios, returning informative messages to Rovo.
• Complex Actions: While Forge functions can be complex, try to keep individual actions focused on a single, well-defined task. For multi-step workflows, consider orchestrating multiple actions or guiding the user through a series of interactions.
• Lack of Testing: Thoroughly test your agent with various inputs, including edge cases and erroneous queries, to ensure predictable behavior. Leverage Forge's logging and debugging tools.
• Data Size Limitations: Be mindful of payload size limits for inputs and outputs in Forge functions. For very large data sets, consider alternative patterns like streaming or fetching data in chunks.
• Rate Limiting: Be aware of API rate limits when your agent frequently interacts with Atlassian or external APIs. Implement retry mechanisms with exponential backoff if necessary.

Advanced Techniques for Sophisticated Agents

To truly unlock the potential of Rovo Agents, consider these advanced techniques:

• Integration with Enterprise Systems (Beyond Atlassian):

  • External APIs: Use the Forge fetch API to securely integrate with your organization's custom APIs or third-party business applications (e.g., CRM, ERP, HR systems). Ensure proper authentication (e.g., OAuth 2.0, API keys) is handled.
  • Webhooks: Configure webhooks from external systems to trigger Rovo Agent actions or update agent knowledge in real-time, enabling proactive behaviors.
  • Message Queues: For asynchronous or long-running tasks, integrate with message queues (e.g., AWS SQS, Azure Service Bus) to decouple the Rovo Agent's response from the execution of the backend task.

• Dynamic Knowledge Sources: While Rovo can natively connect to Jira and Confluence, consider fetching knowledge dynamically from other sources (e.g., a SharePoint library, a proprietary knowledge base, or a database) via your Forge actions. This allows your agent to leverage a broader, real-time context.

• Stateful Agents (with Storage API): For agents that need to remember context across multiple user interactions within a session, leverage Forge's Storage API. This allows you to store and retrieve small amounts of structured data associated with a user or a conversation.

• Custom UI for Complex Interactions: For scenarios requiring more elaborate user interaction than simple text prompts, you can embed a Custom UI Forge module within your agent's responses. This allows you to render interactive forms, dashboards, or data visualizations directly within the Atlassian interface, guided by the agent.

• Observability and Monitoring: Implement robust logging and monitoring within your Forge functions. Integrate with external logging services (e.g., AWS CloudWatch, Splunk) for deeper insights into agent performance, errors, and usage patterns.

By mastering these techniques, developers can move beyond basic automation to build Rovo Agents that truly act as intelligent, integrated components of their enterprise workflows, streamlining operations, enhancing decision-making, and fostering a more productive work environment.