Developer Documentation

This developer guide will help you get setup with ROSA and start developing your own ROSA agents or contributing to the ROSA project.

Contents

• Installing ROSA
• Creating @tool Functions
• System Prompts

Installing ROSA

There are two methods to install ROSA, either by cloning the git repository and installing as a user package, or by installing directly with pip.

Tip

Use the pip install method if you do not need to modify the core ROSA class.

From PyPI (for use in other projects)

pip install jpl-rosa

From Source (for Development)

git clone https://github.com/nasa-jpl/rosa.git
cd rosa
pip install --user -e .

Creating @tool Functions

LangChain provides a decorator called @tool that can be used to define the actions that the ROSA agent can take in the ROS environment. These functions should take in the necessary parameters and return a string that describes the action taken.

Elements of a good @tool function

• Descriptive Name: The name of the function should describe the action taken as clearly as possible.
• Type Annotations: Use type annotations to specify the types of the parameters and return value.
• Docstring: Include a docstring that describes what the function does and the purpose of each parameter. These docstrings will be consumed by the LLM to determine if the tool is relevant to the user query.
• Parameter Validation: Validate the parameters to ensure that they are of the correct type and within the expected range.
• Safety Checks: Include safety checks in the tool to ensure that the agent does not perform unsafe actions.
• Error Handling: Include error handling to gracefully handle any exceptions that may occur during the execution of the tool.
• Return Value: The function should return a string that describes either (1) the action taken by the tool and its results, or (2) an error message if the tool fails to execute. You may also choose to return a dict, list, or other object that properly resolves as a string.

Example

@tool
def descriptive_tool_name(param1: type1, param2: type2) -> str:
    """
    Description of the tool.
    
    :param param1: Description of param1 and how it is used.
    :param param2: Description of param2 and how it is used.
    """
    # Your code here ...
    return f"Action taken: {ACTION}, retrieved data: {DATA}."

Adding System Prompts

System prompts are used to guide ROSA's behavior and provide context for its actions. The RobotSystemPrompts class contains attributes that describe the robot's identity, environment, and objectives. These prompts are used by the LLM to generate responses that are consistent with the robot's persona and capabilities.

Attributes of the RobotSystemPrompts class

The RobotSystemPrompts class contains the following attributes, each of which provides context for the ROSA agent:

• embodiment_and_persona: Gives the agent a sense of identity and helps it understand its role.
• about_your_operators: Provides information about the operators who interact with the robot, which can help the agent understand the context of the interaction.
• critical_instructions: Provides critical instructions that the agent should follow to ensure the safety and well-being of the robot and its operators.
• constraints_and_guardrails: Gives the robot a sense of its limitations and informs its decision-making process.
• about_your_environment: Provides information about the physical and digital environment in which the robot operates.
• about_your_capabilities: Describes what the robot can and cannot do, which can help the agent understand its limitations.
• nuance_and_assumptions: Provides information about the nuances and assumptions that the agent should consider when interacting with the robot.
• mission_and_objectives: Describes the mission and objectives of the robot, which can help the agent understand its purpose and goals.
• environment_variables: Provides information about the environment variables that the agent should consider when interacting with the robot. e.g. $ROS_MASTER_URI, or $ROS_IP.

Elements of good system prompts

• Use a consistent tone: Use a consistent tone and style across all prompts to maintain the robot's persona.
• Be clear and concise: Keep the prompts clear and concise to ensure that the agent can understand and act on them.
• Avoid jargon: Avoid technical jargon and use plain language to describe the robot's capabilities and limitations.
• Provide contextual information: Include contextual information that helps the agent understand its role and objectives.
• Do not contradict yourself: Ensure that the prompts are consistent with each other and do not contradict the robot's identity or capabilities.
• Update prompts as needed: Update the prompts as needed to reflect changes in the robot's capabilities or environment.

Example

prompts = RobotSystemPrompts(
    embodiment_and_persona="You are a cool robot that does cool stuff.",
    critical_instructions="You must confirm all actions with the operator before proceeding. Failure to do so might result in damage to the robot or its environment.",
)