solace-agent-mesh 1.6.1__py3-none-any.whl → 1.13.2__py3-none-any.whl

solace_agent_mesh/agent/protocol/event_handlers.py

@@ -2,52 +2,113 @@
 Contains event handling logic for the A2A_ADK_HostComponent.
 """
 
-import logging
-import json
 import asyncio
-from typing import TYPE_CHECKING, Dict, Any
 import fnmatch
-from solace_ai_connector.common.message import Message as SolaceMessage
-from ...agent.adk.callbacks import _publish_data_part_status_update
-from ...common.data_parts import ToolResultData
-from ...common.a2a.types import ToolsExtensionParams
-from solace_ai_connector.common.event import Event, EventType
+import json
+import logging
+from typing import TYPE_CHECKING, Any, Dict
+
+from litellm.exceptions import BadRequestError
+
 from a2a.types import (
     A2ARequest,
-    AgentCard,
     AgentCapabilities,
+    AgentCard,
     AgentExtension,
     DataPart,
     JSONRPCResponse,
     Task,
     TaskArtifactUpdateEvent,
+    TaskState,
     TaskStatusUpdateEvent,
     TextPart,
 )
+from google.adk.agents import RunConfig
+from google.adk.agents.run_config import StreamingMode
+from solace_ai_connector.common.event import Event, EventType
+from solace_ai_connector.common.message import Message as SolaceMessage
+from sqlalchemy.exc import OperationalError
+
+from ...agent.adk.callbacks import _publish_data_part_status_update
+from ...agent.adk.runner import TaskCancelledError, run_adk_async_task_thread_wrapper
+from ...agent.utils.artifact_helpers import generate_artifact_metadata_summary
 from ...common import a2a
+from ...common.error_handlers import get_error_message
+from ...common.utils.embeds.constants import (
+    EMBED_DELIMITER_OPEN,
+    EMBED_DELIMITER_CLOSE,
+)
 from ...common.a2a import (
     get_agent_request_topic,
-    get_discovery_topic,
-    translate_a2a_to_adk_content,
-    get_client_response_topic,
     get_agent_response_subscription_topic,
     get_agent_status_subscription_topic,
+    get_client_response_topic,
+    get_discovery_topic,
     get_sam_events_subscription_topic,
     get_text_from_message,
     topic_matches_subscription,
+    translate_a2a_to_adk_content,
 )
-from ...agent.utils.artifact_helpers import (
-    generate_artifact_metadata_summary,
-)
-from ...agent.adk.runner import run_adk_async_task_thread_wrapper
+from ...common.a2a.types import ToolsExtensionParams
+from ...common.data_parts import ToolResultData
 from ..sac.task_execution_context import TaskExecutionContext
-from google.adk.agents import RunConfig
 
 if TYPE_CHECKING:
     from ..sac.component import SamAgentComponent
-from google.adk.agents.run_config import StreamingMode
 
 log = logging.getLogger(__name__)
+trace_logger = logging.getLogger("sam_trace")
+
+
+def _forward_jsonrpc_response(
+    component: "SamAgentComponent",
+    original_jsonrpc_request_id: str,
+    result_data: Any,
+    target_topic: str,
+    main_logical_task_id: str,
+    peer_agent_name: str,
+    message: SolaceMessage,
+) -> None:
+    """
+    Utility method to forward a JSONRPCResponse with the given result data.
+
+    Args:
+        component: The SamAgentComponent instance
+        original_jsonrpc_request_id: The original JSONRPC request ID
+        result_data: The data to include in the response result
+        target_topic: The topic to publish to
+        main_logical_task_id: The main logical task ID for logging
+        peer_agent_name: The peer agent name for logging
+        message: The original message to acknowledge
+    """
+    forwarded_rpc_response = JSONRPCResponse(
+        id=original_jsonrpc_request_id,
+        result=result_data,
+    )
+    payload_to_publish = forwarded_rpc_response.model_dump(
+        by_alias=True, exclude_none=True
+    )
+
+    try:
+        component.publish_a2a_message(
+            payload_to_publish,
+            target_topic,
+        )
+        log.debug(
+            "%s Forwarded DataPart signal for main task %s (from peer %s) to %s.",
+            component.log_identifier,
+            main_logical_task_id,
+            peer_agent_name,
+            target_topic,
+        )
+    except Exception as pub_err:
+        log.exception(
+            "%s Failed to publish forwarded status signal for main task %s: %s",
+            component.log_identifier,
+            main_logical_task_id,
+            pub_err,
+        )
+    message.call_acknowledgements()
 
 
 def _register_peer_artifacts_in_parent_context(
@@ -196,7 +257,7 @@ async def process_event(component, event: Event):
 
 async def _publish_peer_tool_result_notification(
     component: "SamAgentComponent",
-    correlation_data: Dict[str, Any],
+    correlation_data: dict[str, Any],
     payload_to_queue: Any,
     log_identifier: str,
 ):
@@ -436,6 +497,34 @@ async def handle_a2a_request(component, message: SolaceMessage):
                                 logical_task_id,
                                 sub_task_info,
                             )
+                else:
+                    # No peer sub-tasks - check if task is paused and needs immediate finalization
+                    if task_context.get_is_paused():
+                        log.info(
+                            "%s Task %s is paused with no peer sub-tasks. Scheduling immediate finalization.",
+                            component.log_identifier,
+                            logical_task_id,
+                        )
+                        loop = component.get_async_loop()
+                        if loop and loop.is_running():
+                            task_context.set_paused(False)
+
+                            asyncio.run_coroutine_threadsafe(
+                                component.finalize_task_with_cleanup(
+                                    task_context.a2a_context,
+                                    is_paused=False,
+                                    exception=TaskCancelledError(
+                                        f"Task {logical_task_id} cancelled while paused."
+                                    )
+                                ),
+                                loop,
+                            )
+                        else:
+                            log.error(
+                                "%s Cannot finalize cancelled paused task %s - event loop not available.",
+                                component.log_identifier,
+                                logical_task_id,
+                            )
             else:
                 log.info(
                     "%s No active task found for cancellation (ID: %s) or task already completed. Ignoring signal.",
@@ -465,6 +554,35 @@ async def handle_a2a_request(component, message: SolaceMessage):
             # The gateway/client is the source of truth for the task ID.
             # The agent adopts the ID from the JSON-RPC request envelope.
             logical_task_id = str(a2a.get_request_id(a2a_request))
+
+            try:
+                from solace_agent_mesh_enterprise.auth.input_required import (
+                    a2a_auth_message_handler,
+                )
+
+                try:
+                    message_handled = await a2a_auth_message_handler(
+                        component, a2a_message, logical_task_id
+                    )
+                    if message_handled:
+                        message.call_acknowledgements()
+                        log.debug(
+                            "%s ACKed message handled by input-required auth handler.",
+                            component.log_identifier,
+                        )
+                        return None
+                except Exception as auth_import_err:
+                    log.error(
+                        "%s Error in input-required auth handler: %s",
+                        component.log_identifier,
+                        auth_import_err,
+                    )
+                    message.call_acknowledgements()
+                    return None
+
+            except ImportError:
+                pass
+
             # The session id is now contextId on the message
             original_session_id = a2a_message.context_id
             message_id = a2a_message.message_id
@@ -490,7 +608,7 @@ async def handle_a2a_request(component, message: SolaceMessage):
                     )
             else:
                 session_behavior = component.default_session_behavior
-                log.info(
+                log.debug(
                     "%s No 'sessionBehavior' in task metadata. Using component default: '%s'.",
                     component.log_identifier,
                     session_behavior,
@@ -632,7 +750,6 @@ async def handle_a2a_request(component, message: SolaceMessage):
                 "is_streaming": is_streaming_request,
                 "statusTopic": status_topic_from_peer,
                 "replyToTopic": reply_topic_from_peer,
-                "original_solace_message": message,
                 "a2a_user_config": a2a_user_config,
                 "effective_session_id": effective_session_id,
                 "is_run_based_session": is_run_based_session,
@@ -644,6 +761,7 @@ async def handle_a2a_request(component, message: SolaceMessage):
                 "system_purpose": system_purpose,
                 "response_format": response_format,
                 "host_agent_name": agent_name,
+                "original_message_metadata": task_metadata,  # Store original message metadata for tools
             }
 
             # Store verified user identity claims in a2a_context (not the raw token)
@@ -654,17 +772,28 @@ async def handle_a2a_request(component, message: SolaceMessage):
                     component.log_identifier,
                     logical_task_id,
                 )
-            log.debug(
-                "%s A2A Context (shared service model): %s",
-                component.log_identifier,
-                a2a_context,
-            )
+            if trace_logger.isEnabledFor(logging.DEBUG):
+                trace_logger.debug(
+                    "%s A2A Context (shared service model): %s",
+                    component.log_identifier,
+                    a2a_context,
+                )
+            else:
+                log.debug(
+                    "%s A2A Context prepared for task %s",
+                    component.log_identifier,
+                    a2a_context.get("logical_task_id", "unknown"),
+                )
 
             # Create and store the execution context for this task
             task_context = TaskExecutionContext(
                 task_id=logical_task_id, a2a_context=a2a_context
             )
 
+            # Store the original Solace message in TaskExecutionContext instead of a2a_context
+            # This avoids serialization issues when a2a_context is stored in ADK session state
+            task_context.set_original_solace_message(message)
+
             # Store auth token for peer delegation using generic security storage
             if hasattr(component, "trust_manager") and component.trust_manager:
                 auth_token = message.get_user_properties().get("authToken")
@@ -760,7 +889,7 @@ async def handle_a2a_request(component, message: SolaceMessage):
             streaming_mode = StreamingMode.SSE
 
             max_llm_calls_per_task = component.get_config("max_llm_calls_per_task", 20)
-            log.info(
+            log.debug(
                 "%s Using max_llm_calls_per_task: %s",
                 component.log_identifier,
                 max_llm_calls_per_task,
@@ -850,6 +979,101 @@ async def handle_a2a_request(component, message: SolaceMessage):
         component.handle_error(e, Event(EventType.MESSAGE, message))
         return None
 
+    except BadRequestError as e:
+        log.error(
+            "%s Bad Request error handling A2A request: %s", component.log_identifier, e
+        )
+        
+        # Use centralized error handler
+        error_message, is_context_limit = get_error_message(e)
+        
+        if is_context_limit:
+            log.error(
+                "%s Context limit exceeded for task %s",
+                component.log_identifier,
+                logical_task_id,
+            )
+        
+        error_response = a2a.create_invalid_request_error_response(
+            message=error_message,
+            request_id=jsonrpc_request_id,
+            data={"taskId": logical_task_id},
+        )
+        target_topic = reply_topic_from_peer or (
+            get_client_response_topic(namespace, client_id) if client_id else None
+        )
+        if target_topic:
+            component.publish_a2a_message(
+                error_response.model_dump(exclude_none=True),
+                target_topic,
+            )
+
+        try:
+            message.call_negative_acknowledgements()
+            log.warning(
+                "%s NACKed original A2A request due to bad request error.",
+                component.log_identifier,
+            )
+        except Exception as nack_e:
+            log.error(
+                "%s Failed to NACK message after bad request error: %s",
+                component.log_identifier,
+                nack_e,
+            )
+
+        component.handle_error(e, Event(EventType.MESSAGE, message))
+        return None
+
+    except OperationalError as e:
+        log.error(
+            "%s Database error while processing A2A request: %s",
+            component.log_identifier,
+            e,
+        )
+
+        # Check if it's a schema error
+        error_msg = str(e).lower()
+        if "no such column" in error_msg or "no such table" in error_msg:
+            user_message = (
+                "Database schema update required. "
+                "Please contact your administrator to run database migrations."
+            )
+        else:
+            user_message = (
+                "Database error occurred. Please try again or contact support."
+            )
+
+        error_response = a2a.create_internal_error_response(
+            message=user_message,
+            request_id=jsonrpc_request_id,
+            data={"taskId": logical_task_id} if logical_task_id else None,
+        )
+
+        target_topic = reply_topic_from_peer or (
+            get_client_response_topic(namespace, client_id) if client_id else None
+        )
+        if target_topic:
+            component.publish_a2a_message(
+                error_response.model_dump(exclude_none=True),
+                target_topic,
+            )
+
+        try:
+            message.call_negative_acknowledgements()
+            log.warning(
+                "%s NACKed A2A request due to database error.",
+                component.log_identifier,
+            )
+        except Exception as nack_e:
+            log.error(
+                "%s Failed to NACK message after database error: %s",
+                component.log_identifier,
+                nack_e,
+            )
+
+        component.handle_error(e, Event(EventType.MESSAGE, message))
+        return None
+
     except Exception as e:
         log.exception(
             "%s Unexpected error handling A2A request: %s", component.log_identifier, e
@@ -926,13 +1150,13 @@ def handle_agent_card_message(component, message: SolaceMessage):
                     break
 
         if is_allowed:
-            
+
             # Also store in peer_agents for backward compatibility
             component.peer_agents[agent_name] = agent_card
 
             # Store the agent card in the registry for health tracking
             is_new = component.agent_registry.add_or_update_agent(agent_card)
-            
+
             if is_new:
                 log.info(
                     "%s Registered new agent '%s' in registry.",
@@ -1053,137 +1277,219 @@ async def handle_a2a_response(component, message: SolaceMessage):
                     if isinstance(payload_data, TaskStatusUpdateEvent):
                         try:
                             status_event = payload_data
+
                             data_parts = a2a.get_data_parts_from_status_update(
                                 status_event
                             )
                             if data_parts:
-                                for data_part in data_parts:
-                                    log.info(
-                                        "%s Received DataPart signal from peer for sub-task %s. Forwarding...",
-                                        component.log_identifier,
-                                        sub_task_id,
-                                    )
-                                    correlation_data = await component._get_correlation_data_for_sub_task(
-                                        sub_task_id
-                                    )
-                                    if not correlation_data:
-                                        log.warning(
-                                            "%s Correlation data not found for sub-task %s. Cannot forward status signal.",
-                                            component.log_identifier,
-                                            sub_task_id,
-                                        )
-                                        message.call_acknowledgements()
-                                        return
 
-                                    original_task_context = correlation_data.get(
-                                        "original_task_context"
+                                peer_agent_name = (
+                                    status_event.metadata.get(
+                                        "agent_name", "UnknownPeer"
                                     )
-                                    if not original_task_context:
-                                        log.warning(
-                                            "%s original_task_context not found in correlation data for sub-task %s. Cannot forward status signal.",
-                                            component.log_identifier,
-                                            sub_task_id,
-                                        )
-                                        message.call_acknowledgements()
-                                        return
+                                    if status_event.metadata
+                                    else "UnknownPeer"
+                                )
 
-                                    main_logical_task_id = original_task_context.get(
-                                        "logical_task_id"
-                                    )
-                                    original_jsonrpc_request_id = (
-                                        original_task_context.get("jsonrpc_request_id")
+                                correlation_data = (
+                                    await component._get_correlation_data_for_sub_task(
+                                        sub_task_id
                                     )
-                                    main_context_id = original_task_context.get(
-                                        "contextId"
+                                )
+                                if not correlation_data:
+                                    log.warning(
+                                        "%s Correlation data not found for sub-task %s. Cannot forward status signal.",
+                                        component.log_identifier,
+                                        sub_task_id,
                                     )
+                                    message.call_acknowledgements()
+                                    return
 
-                                    target_topic_for_forward = (
-                                        original_task_context.get("statusTopic")
+                                original_task_context = correlation_data.get(
+                                    "original_task_context"
+                                )
+                                if not original_task_context:
+                                    log.warning(
+                                        "%s original_task_context not found in correlation data for sub-task %s. Cannot forward status signal.",
+                                        component.log_identifier,
+                                        sub_task_id,
                                     )
+                                    message.call_acknowledgements()
+                                    return
 
-                                    if (
-                                        not main_logical_task_id
-                                        or not original_jsonrpc_request_id
-                                        or not target_topic_for_forward
-                                    ):
-                                        log.error(
-                                            "%s Missing critical info (main_task_id, original_rpc_id, or target_status_topic) in context for sub-task %s. Cannot forward. Context: %s",
-                                            component.log_identifier,
-                                            sub_task_id,
-                                            original_task_context,
-                                        )
-                                        message.call_acknowledgements()
-                                        return
+                                main_logical_task_id = original_task_context.get(
+                                    "logical_task_id"
+                                )
+                                original_jsonrpc_request_id = original_task_context.get(
+                                    "jsonrpc_request_id"
+                                )
+                                main_context_id = original_task_context.get("contextId")
 
-                                    peer_agent_name = (
-                                        status_event.metadata.get(
-                                            "agent_name", "UnknownPeer"
-                                        )
-                                        if status_event.metadata
-                                        else "UnknownPeer"
-                                    )
+                                target_topic_for_forward = original_task_context.get(
+                                    "statusTopic"
+                                )
 
-                                    forwarded_message = a2a.create_agent_parts_message(
-                                        parts=[data_part],
-                                        metadata={
-                                            "agent_name": component.agent_name,
-                                            "forwarded_from_peer": peer_agent_name,
-                                            "original_peer_event_taskId": status_event.task_id,
-                                            "original_peer_event_timestamp": (
-                                                status_event.status.timestamp
-                                                if status_event.status
-                                                and status_event.status.timestamp
-                                                else None
-                                            ),
-                                            "function_call_id": correlation_data.get(
-                                                "adk_function_call_id", None
-                                            ),
-                                        },
+                                if (
+                                    not main_logical_task_id
+                                    or not original_jsonrpc_request_id
+                                    or not target_topic_for_forward
+                                ):
+                                    log.error(
+                                        "%s Missing critical info (main_task_id, original_rpc_id, or target_status_topic) in context for sub-task %s. Cannot forward. Context: %s",
+                                        component.log_identifier,
+                                        sub_task_id,
+                                        original_task_context,
                                     )
-                                    forwarded_event = a2a.create_status_update(
-                                        task_id=main_logical_task_id,
-                                        context_id=main_context_id,
-                                        message=forwarded_message,
-                                        is_final=False,
+                                    message.call_acknowledgements()
+                                    return
+
+                                event_metadata = {
+                                    "agent_name": component.agent_name,
+                                    "forwarded_from_peer": peer_agent_name,
+                                    "original_peer_event_taskId": status_event.task_id,
+                                    "original_peer_event_timestamp": (
+                                        status_event.status.timestamp
+                                        if status_event.status
+                                        and status_event.status.timestamp
+                                        else None
+                                    ),
+                                    "function_call_id": correlation_data.get(
+                                        "adk_function_call_id", None
+                                    ),
+                                }
+
+                                if (
+                                    status_event.status.state
+                                    == TaskState.input_required
+                                ):
+                                    log.debug(
+                                        "%s Received input-required status for sub-task %s. Requesting user input. Forwarding to target.",
+                                        component.log_identifier,
+                                        sub_task_id,
                                     )
+
                                     if (
-                                        status_event.status
-                                        and status_event.status.timestamp
-                                    ):
-                                        forwarded_event.status.timestamp = (
-                                            status_event.status.timestamp
+                                        status_event.metadata
+                                        and "task_call_stack" in status_event.metadata
+                                        and isinstance(
+                                            status_event.metadata["task_call_stack"],
+                                            list,
                                         )
-                                    forwarded_rpc_response = JSONRPCResponse(
-                                        id=original_jsonrpc_request_id,
-                                        result=forwarded_event,
-                                    )
-                                    payload_to_publish = (
-                                        forwarded_rpc_response.model_dump(
-                                            by_alias=True, exclude_none=True
+                                    ):
+                                        task_call_stack = status_event.metadata[
+                                            "task_call_stack"
+                                        ].copy()
+                                        task_call_stack.insert(0, sub_task_id)
+                                        event_metadata["task_call_stack"] = (
+                                            task_call_stack
                                         )
+                                    else:
+                                        event_metadata["task_call_stack"] = [
+                                            sub_task_id
+                                        ]
+
+                                    status_event.metadata = event_metadata
+                                    status_event.task_id = main_logical_task_id
+
+                                    _forward_jsonrpc_response(
+                                        component=component,
+                                        original_jsonrpc_request_id=original_jsonrpc_request_id,
+                                        result_data=status_event,
+                                        target_topic=target_topic_for_forward,
+                                        main_logical_task_id=main_logical_task_id,
+                                        peer_agent_name=peer_agent_name,
+                                        message=message,
                                     )
+                                    # Reset the timeout since we received a status update
+                                    await component.reset_peer_timeout(sub_task_id)
+                                    return
 
-                                    try:
-                                        component.publish_a2a_message(
-                                            payload_to_publish,
-                                            target_topic_for_forward,
-                                        )
+                                # Filter out artifact creation progress from peer agents.
+                                # These are implementation details that should not leak across
+                                # agent boundaries. Artifacts are properly bubbled up in the
+                                # final Task response metadata.
+                                filtered_data_parts = []
+                                has_deep_research_report = False
+                                for data_part in data_parts:
+                                    if isinstance(data_part.data, dict):
+                                        data_type = data_part.data.get("type")
+                                        if data_type == "artifact_creation_progress":
+                                            log.debug(
+                                                "%s Filtered out artifact_creation_progress DataPart from peer sub-task %s. Not forwarding to user.",
+                                                component.log_identifier,
+                                                sub_task_id,
+                                            )
+                                            continue
+                                        if data_type == "deep_research_report":
+                                            # Track that we've seen a deep research report
+                                            # This will be used to suppress text content in the final response
+                                            has_deep_research_report = True
+                                            log.info(
+                                                "%s Detected deep_research_report DataPart from peer sub-task %s. Will suppress text in final response.",
+                                                component.log_identifier,
+                                                sub_task_id,
+                                            )
+                                    filtered_data_parts.append(data_part)
+                                
+                                # Store the deep research report flag in correlation data for later use
+                                if has_deep_research_report:
+                                    main_logical_task_id_for_flag = original_task_context.get("logical_task_id")
+                                    with component.active_tasks_lock:
+                                        task_context_for_flag = component.active_tasks.get(main_logical_task_id_for_flag)
+                                        if task_context_for_flag:
+                                            # Store flag in task context to suppress text in final response
+                                            task_context_for_flag.set_flag("peer_sent_deep_research_report", True)
+                                            log.info(
+                                                "%s Set peer_sent_deep_research_report flag for task %s",
+                                                component.log_identifier,
+                                                main_logical_task_id_for_flag,
+                                            )
+
+                                # Only forward if there are non-filtered data parts
+                                if filtered_data_parts:
+                                    for data_part in filtered_data_parts:
                                         log.info(
-                                            "%s Forwarded DataPart signal for main task %s (from peer %s) to %s.",
+                                            "%s Received DataPart signal from peer for sub-task %s. Forwarding...",
                                             component.log_identifier,
-                                            main_logical_task_id,
-                                            peer_agent_name,
-                                            target_topic_for_forward,
+                                            sub_task_id,
                                         )
-                                    except Exception as pub_err:
-                                        log.exception(
-                                            "%s Failed to publish forwarded status signal for main task %s: %s",
-                                            component.log_identifier,
-                                            main_logical_task_id,
-                                            pub_err,
+
+                                        forwarded_message = a2a.create_agent_parts_message(
+                                            parts=[data_part],
+                                            metadata=event_metadata,
                                         )
-                                    message.call_acknowledgements()
+
+                                        forwarded_event = a2a.create_status_update(
+                                            task_id=main_logical_task_id,
+                                            context_id=main_context_id,
+                                            message=forwarded_message,
+                                            is_final=False,
+                                        )
+                                        if (
+                                            status_event.status
+                                            and status_event.status.timestamp
+                                        ):
+                                            forwarded_event.status.timestamp = (
+                                                status_event.status.timestamp
+                                            )
+                                        _forward_jsonrpc_response(
+                                            component=component,
+                                            original_jsonrpc_request_id=original_jsonrpc_request_id,
+                                            result_data=forwarded_event,
+                                            target_topic=target_topic_for_forward,
+                                            main_logical_task_id=main_logical_task_id,
+                                            peer_agent_name=peer_agent_name,
+                                            message=message,
+                                        )
+                                    # Reset the timeout since we received a status update
+                                    await component.reset_peer_timeout(sub_task_id)
                                     return
+                                else:
+                                    log.debug(
+                                        "%s All DataParts from peer sub-task %s were filtered. Not forwarding.",
+                                        component.log_identifier,
+                                        sub_task_id,
+                                    )
 
                             payload_to_queue = status_event.model_dump(
                                 by_alias=True, exclude_none=True
@@ -1464,6 +1770,16 @@ async def handle_a2a_response(component, message: SolaceMessage):
                                             header_text=header_text,
                                         )
                                     )
+
+                                    # Add guidance about artifact_return responsibility
+                                    artifact_return_guidance = (
+                                        f"\n\n**Note:** If any of these artifacts fulfill the user's request, "
+                                        f"you should return them directly to the user using the "
+                                        f"{EMBED_DELIMITER_OPEN}artifact_return:filename:version{EMBED_DELIMITER_CLOSE} embed. "
+                                        f"This is more convenient for the user than just describing the artifacts. "
+                                        f"Replace 'filename' and 'version' with the actual values from the artifact metadata above."
+                                    )
+                                    artifact_summary += artifact_return_guidance
                                 else:
                                     log.warning(
                                         "%s Could not generate artifact summary: missing user_id or session_id in correlation data.",
@@ -1484,9 +1800,28 @@ async def handle_a2a_response(component, message: SolaceMessage):
             else:
                 final_text = str(payload_to_queue)
 
-            full_response_text = final_text
-            if artifact_summary:
-                full_response_text = f"{artifact_summary}\n\n{full_response_text}"
+            # Check if a deep research report was sent by the peer agent
+            # If so, suppress the verbose text but keep artifact info to use
+            peer_sent_deep_research = task_context.get_flag("peer_sent_deep_research_report", False)
+            if peer_sent_deep_research:
+                # Clear the flag after using it
+                task_context.set_flag("peer_sent_deep_research_report", False)
+                if artifact_summary:
+                    full_response_text = (
+                        f"{artifact_summary}\n---\n\n"
+                        "SUCCESS: Deep research task completed. The report has been delivered to the user "
+                        "and is being displayed. Use artifact_return to include the artifact reference "
+                        "in your response so users can click on it."
+                    )
+                else:
+                    full_response_text = (
+                        "SUCCESS: Deep research task completed successfully. "
+                        "The research report has been delivered to the user."
+                    )
+            else:
+                full_response_text = final_text
+                if artifact_summary:
+                    full_response_text = f"{artifact_summary}\n---\n\nPeer Agent Response:\n\n{full_response_text}"
 
             await _publish_peer_tool_result_notification(
                 component=component,