Errors management

Introduction

The agents-server provides a set of error managers mechanisms to ensure that agents can handle errors gracefully and provide meaningful feedback to users. This is essential for maintaining the reliability and usability of the agents.

Error Managers

The agents-server provides a set of error managers that can be used to handle errors in a consistent way. These error managers are designed to be used by agents to handle errors that occur during their execution.

The error managers are:

• AgentErrorManager: This error manager is used to handle errors that occur during the execution of the agent. This results in the corresponding response and error code, depending on the exception thrown at agent level.
• FastApiErrorManager: This error manager is used to handle errors that occur during the execution of the FastAPI application. This results in the corresponding response and error code, depending on the exception thrown at server level.

AgentErrorManager

All these exceptions receive a message and an error code.

This manager controls the following exceptions:

AgentBaseException

This is the base exception for all agent-related exceptions. It is used to catch any other exceptions that are not explicitly handled by the other error managers. It results in a 500 Internal Server Error response. It is formed as follows:

• message: String. Default value: An agent error occurred.
• error_code: String. Default value: AGENT_ERROR.

AgentNotFoundException

This exception is raised when the agent is not found in the system. It results in a 404 Not Found response. It is formed as follows:

• message: String. Default value: Agent not found.
• error_code: String. Default value: AGENT_NOT_FOUND.

AgentConfigException

This exception is raised when there is an error in the agent configuration. It results in a 400 Bad Request response. It is formed as follows:

• message: String. Default value: Agent configuration error.
• error_code: String. Default value: AGENT_CONFIG_ERROR.

AgentValidationException

This exception is raised when there is a validation error in the agent’s input. It results in a 400 Bad Request response. It is formed as follows:

• message: String. Default value: Agent validation failed.
• error_code: String. Default value: AGENT_VALIDATION_ERROR.

AgentExecutionException

This exception is raised when there is an error during the execution of the agent. It results in a 500 Internal Server Error response. It also receives the field detail. It is formed as follows:

• message: String. Default value: Agent execution failed.
• error_code: String. Default value: AGENT_EXECUTION_ERROR.
• detail: String. Used to provide additional information to message. Default value: empty string.

AgentExternalServiceException

This exception is raised when there is an error in the external service that the agent is trying to access. It results in a 502 Bad Gateway response. It also receives the fields service_error_code and service_name. It is formed as follows:

• message: String. Default value: External service error.
• error_code: String. Default value: AGENT_EXTERNAL_SERVICE_ERROR.
• service_error_code: String. Used to provide additional information, adding to the message {service_error_code}`. Default value: empty string.
• service_name: String. Used to provide additional information, adding to the message `Service: {service_name}. Default value: empty string.

AgentModelError

This exception is raised when there is an error in the external service that the agent is trying to access. It results in a 502 Bad Gateway response. It also receives the fields service_error_code and service_name. It is formed as follows:

• message: String. Default value: Model error.
• error_code: String. Default value: AGENT_MODEL_ERROR.
• service_error_code: String. Used to provide additional information, adding to the message {service_error_code}`. Default value: empty string.
• service_name: String. Used to provide additional information, adding to the message `Service: {service_name}. Default value: empty string.

AgentRateLimitError

This exception is raised when the agent exceeds the rate limit for the external service it is trying to access. It results in a 429 Too Many Requests response. It also receives the fields service_error_code and service_name. It is formed as follows:

• message: String. Default value: Rate limit error.
• error_code: String. Default value: AGENT_RATE_LIMIT_ERROR.
• service_error_code: String. Used to provide additional information, adding to the message {service_error_code}`. Default value: empty string.
• service_name: String. Used to provide additional information, adding to the message `Service: {service_name}. Default value: empty string.
• retry_after: String. Mandatory field that adds the value Retry-After in the response header to indicate how long the client should wait before making a new request.

Usage

This manager allows launching these exceptions internally in your new agent.

To launch one of these exceptions, use the following command:

raise AgentExecutionException(message='message error', service_error_code='ERROR CODE', detail='problem with the agent execution')

FastApiErrorManager

This manager controls the following exceptions server:

• ValidationException: This exception is raised when there is a validation error in the request. It results in a 400 Bad Request response.
• RequestValidationError: This exception is raised when there is a validation error in the request body. It results in a 400 Bad Request response.
• ResponseValidationError: This exception is raised when there is a validation error in the response body. It results in a 400 Bad Request response.

Response Error

The error managers return a response with the following structure:

{
    "code": "NOT_FOUND",
    "message": "Agent with identifier XXXX not found.",
    "errors": [
        {
            "type": "AGENT_NOT_FOUND",
            "message": "Agent with identifier XXXX not found."
        }
    ]
}

The response contains the following fields:

• code: The error code that identifies the type of error.
• message: A human-readable message that describes the error.
• errors: A list of errors that occurred during the execution of the agent. Each error contains the following fields:
  • type: The type of error that occurred.
  • message: A human-readable message that describes the error.