Coverage for src / agent / utils / responses.py: 100%

1# Copyright 2025-2026 Microsoft Corporation 

2# 

3# Licensed under the Apache License, Version 2.0 (the "License"); 

4# you may not use this file except in compliance with the License. 

5# You may obtain a copy of the License at 

6# 

7# http://www.apache.org/licenses/LICENSE-2.0 

8# 

9# Unless required by applicable law or agreed to in writing, software 

10# distributed under the License is distributed on an "AS IS" BASIS, 

11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 

12# See the License for the specific language governing permissions and 

13# limitations under the License. 

14 

15"""Shared response helper functions for tools and managers. 

16 

17This module provides standardized response formatting used across toolsets 

18and memory managers. All tools and managers should use these helpers to 

19ensure consistent response formats for the agent to consume. 

20""" 

21 

22from typing import Any 

23 

24 

25def create_success_response(result: Any, message: str = "") -> dict: 

26 """Create standardized success response. 

27 

28 All tools and managers should return responses in this format for consistency. 

29 This makes it easy for the agent to handle results uniformly. 

30 

31 Args: 

32 result: Operation result (can be any type) 

33 message: Optional success message for logging/display 

34 

35 Returns: 

36 Structured response dict with success=True 

37 

38 Example: 

39 >>> response = create_success_response( 

40 ... result="Hello, World!", 

41 ... message="Greeting generated" 

42 ... ) 

43 >>> response 

44 {'success': True, 'result': 'Hello, World!', 'message': 'Greeting generated'} 

45 """ 

46 return { 

47 "success": True, 

48 "result": result, 

49 "message": message, 

50 } 

51 

52 

53def create_error_response(error: str, message: str) -> dict: 

54 """Create standardized error response. 

55 

56 Tools and managers should use this when they encounter errors rather than 

57 raising exceptions. This allows the agent to handle errors gracefully and 

58 provide better feedback. 

59 

60 Args: 

61 error: Machine-readable error code (e.g., "resource_not_found") 

62 message: Human-friendly error message 

63 

64 Returns: 

65 Structured response dict with success=False 

66 

67 Example: 

68 >>> response = create_error_response( 

69 ... error="file_not_found", 

70 ... message="The file 'data.txt' does not exist" 

71 ... ) 

72 >>> response 

73 {'success': False, 'error': 'file_not_found', 'message': '...'} 

74 """ 

75 return { 

76 "success": False, 

77 "error": error, 

78 "message": message, 

79 }