[Good First Issue] Enhance Error Messages in agents-api for Better Readability and Context

[ijindal1]

We're looking to improve the error messages in our agents-api to make them more readable, informative, and context-aware. This is a great opportunity for new contributors to get familiar with our codebase and make a meaningful impact on user experience.

Currently, our error messages are often automated or lack descriptive information, which can make debugging and troubleshooting difficult for users of our API. We want to enhance these messages to provide more context and actionable information.

Objective:

Improve error messages throughout the agents-api, particularly focusing on the error handling in models/utils.py and models/agent/create_agent.py.

Steps to Approach This Issue:

1. Familiarize yourself with the codebase:

• Read through the CONTRIBUTING.md file to understand our contribution process.
• Review the models/utils.py and models/agent/create_agent.py files.
• Pay special attention to the rewrap_exceptions decorator in models/utils.py.

2. Identify error-prone areas:

• Look for try/except blocks and error handling logic.
• Focus on the create_agent function in create_agent.py as a starting point.

3. Analyze current error messages:

• Identify generic or non-descriptive error messages.
• Note any places where context could be added to make the error more informative.

4. Improve error messages:

• For each identified error, consider:
  • What caused the error?
  • What was the system trying to do when the error occurred?
  • What can the user do to resolve the issue?
• Rewrite the error messages to include this information.

5. Implement changes:

• Update the error messages in the code.
• For HTTPExceptions, use the detail parameter to provide more information.
• Consider creating custom exception classes for specific error types if necessary.

6. Test your changes:

• Ensure that the new error messages are triggered correctly.
• Verify that the messages provide useful information for debugging.

7. Document your changes:

• Update any relevant documentation to reflect the new error messages.
• Add comments in the code explaining the context of each error if necessary.

Example Improvement:

Current error in agents_api/models/agents/create_agent.py:

HTTPException(detail="developer not found", status_code=403)

Improved version:

HTTPException(
    detail="Developer not found. Please ensure the provided auth token (which refers to your developer_id) is valid and the developer has the necessary permissions to create an agent.",
    status_code=403
)

Guidelines:

• Keep error messages clear and concise while providing necessary context.
• Use consistent language and formatting across all error messages.
• Avoid exposing sensitive information in error messages.
• Where applicable, provide suggestions for resolving the error.
• Consider different user roles (e.g., developers, end-users) when crafting messages.

Necessary Information:

• Familiarize yourself with the Agent and CreateAgentRequest models.
• Understand the flow of the create_agent function and its interaction with the database.
• Review the rewrap_exceptions decorator to see how exceptions are currently handled.

Additional Notes:

• Feel free to ask questions if you're unsure about any part of the codebase.
• Submit your changes as a pull request, following the guidelines in CONTRIBUTING.md.
• Don't hesitate to suggest improvements beyond just error messages if you notice areas for enhancement.

We're excited to see your contributions to making our error handling more user-friendly and informative!

[HamadaSalhab]

One of the error messages that needs to be improved further is the subworkflow validation while creating/updating tasks. This is an example of what the error message is when the subworkflow isn't a valid workflow:

[AMANCHAUBEY8822]

We have improved the error messages in the agents-api to provide more context and actionable information. Please ensure that any new error messages follow these guidelines:

• Include what caused the error.
• Describe what the system was trying to do.
• Suggest what the user can do to resolve the issue.
• Avoid exposing sensitive information.

Example:

HTTPException(
    detail="Developer not found. Please ensure the provided auth token (which refers to your developer_id) is valid and the developer has the necessary permissions to create an agent.",
    status_code=403


# models/agent/create_agent.py

from fastapi import HTTPException
from .utils import rewrap_exceptions

@rewrap_exceptions
async def create_agent(request: CreateAgentRequest):
    try:
        developer = await get_developer(request.developer_id)
        if not developer:
            raise HTTPException(
                status_code=403,
                detail="Developer not found. Please ensure the provided auth token (which refers to your developer_id) is valid and the developer has the necessary permissions to create an agent."
            )
        # Additional logic for creating an agent
    except DatabaseError as e:
        raise HTTPException(
            status_code=500,
            detail=f"Database error occurred while creating the agent: {str(e)}. Please try again later or contact support."
        )
    except Exception as e:
        raise HTTPException(
            status_code=500,
            detail=f"An unexpected error occurred: {str(e)}. Please contact support if the issue persists."
        )

[RS-labhub]

Hey there, I would like to work on this issue

[ijindal1]

The quickest way is improving the standard pydantic ValidationErrors. Catching them and then pretty formatting before re-raising would be a great place to start @RS-labhub

[RS-labhub]

models/utils.py and models/agent/create_agent.py

There are too many files inside the agents-api > agents-api 🙂 Isn't there's a seperate file/folder for error handling?

[ijindal1]

We use fastapi under the hood so the requests automatically run validations. Otherwise errors are handled in web.py and models/utils.py

[RS-labhub]

We use fastapi under the hood so the requests automatically run validations. Otherwise errors are handled in web.py and models/utils.py

Need some time to understand the code base. Will be back shortly!