solace-agent-mesh 1.11.2__py3-none-any.whl → 1.12.0__py3-none-any.whl

solace_agent_mesh/agent/adk/callbacks.py

@@ -33,6 +33,7 @@ from ...agent.utils.context_helpers import (
     get_session_from_callback_context,
 )
 from ..tools.tool_definition import BuiltinTool
+from ..tools.peer_agent_tool import PEER_TOOL_PREFIX
 
 from ...common.utils.embeds import (
     EMBED_DELIMITER_OPEN,
@@ -47,6 +48,7 @@ from ...common.utils.embeds.types import ResolutionMode
 from ...common.utils.embeds.modifiers import MODIFIER_IMPLEMENTATIONS
 
 from ...common import a2a
+from ...common.a2a.types import ArtifactInfo
 from ...common.data_parts import (
     AgentProgressUpdateData,
     ArtifactCreationProgressData,
@@ -141,12 +143,17 @@ async def _resolve_early_embeds_in_chunk(
         # Build resolution context from callback_context (pattern from EmbedResolvingMCPToolset)
         invocation_context = callback_context._invocation_context
         if not invocation_context:
-            log.warning("%s No invocation context available for embed resolution", log_identifier)
+            log.warning(
+                "%s No invocation context available for embed resolution",
+                log_identifier,
+            )
             return chunk
 
         session_context = invocation_context.session
         if not session_context:
-            log.warning("%s No session context available for embed resolution", log_identifier)
+            log.warning(
+                "%s No session context available for embed resolution", log_identifier
+            )
             return chunk
 
         resolution_context = {
@@ -183,7 +190,9 @@ async def _resolve_early_embeds_in_chunk(
         return resolved_text
 
     except Exception as e:
-        log.error("%s Error resolving embeds in chunk: %s", log_identifier, e, exc_info=True)
+        log.error(
+            "%s Error resolving embeds in chunk: %s", log_identifier, e, exc_info=True
+        )
         return chunk  # Return original chunk on error
 
 
@@ -208,7 +217,9 @@ async def process_artifact_blocks_callback(
         session.state[parser_state_key] = parser
         session.state["completed_artifact_blocks_list"] = []
         session.state["completed_template_blocks_list"] = []
-        session.state["artifact_chars_sent"] = 0  # Reset character tracking for new turn
+        session.state["artifact_chars_sent"] = (
+            0  # Reset character tracking for new turn
+        )
 
     stream_chunks_were_processed = callback_context.state.get(
         A2A_LLM_STREAM_CHUNKS_PROCESSED_KEY, False
@@ -317,7 +328,9 @@ async def process_artifact_blocks_callback(
 
                             # Track the cumulative character count of what we've sent
                             # We need character count (not bytes) to slice correctly later
-                            previous_char_count = session.state.get("artifact_chars_sent", 0)
+                            previous_char_count = session.state.get(
+                                "artifact_chars_sent", 0
+                            )
                             new_char_count = previous_char_count + len(event.chunk)
                             session.state["artifact_chars_sent"] = new_char_count
 
@@ -439,7 +452,9 @@ async def process_artifact_blocks_callback(
                             if a2a_context:
                                 # Check if there's unsent content (content after last progress event)
                                 total_bytes = len(event.content.encode("utf-8"))
-                                chars_already_sent = session.state.get("artifact_chars_sent", 0)
+                                chars_already_sent = session.state.get(
+                                    "artifact_chars_sent", 0
+                                )
 
                                 if chars_already_sent < len(event.content):
                                     # There's unsent content - send it as a final progress update
@@ -475,7 +490,6 @@ async def process_artifact_blocks_callback(
                                     mime_type=params.get("mime_type"),
                                     version=version_for_tool,
                                 )
-
                                 await _publish_data_part_status_update(
                                     host_component, a2a_context, progress_data
                                 )
@@ -499,6 +513,9 @@ async def process_artifact_blocks_callback(
                                 "filename": filename,
                                 "version": version_for_tool,
                                 "status": status_for_tool,
+                                "description": params.get("description"),
+                                "mime_type": params.get("mime_type"),
+                                "bytes_transferred": len(event.content),
                                 "original_text": original_text,
                             }
                         )
@@ -651,8 +668,12 @@ async def process_artifact_blocks_callback(
                 len(completed_blocks_list),
             )
 
+            # Get a2a_context for sending signals
+            a2a_context = callback_context.state.get("a2a_context")
+
             tool_call_parts = []
             for block_info in completed_blocks_list:
+                function_call_id = f"host-notify-{uuid.uuid4()}"
                 notify_tool_call = adk_types.FunctionCall(
                     name="_notify_artifact_save",
                     args={
@@ -660,10 +681,40 @@ async def process_artifact_blocks_callback(
                         "version": block_info["version"],
                         "status": block_info["status"],
                     },
-                    id=f"host-notify-{uuid.uuid4()}",
+                    id=function_call_id,
                 )
                 tool_call_parts.append(adk_types.Part(function_call=notify_tool_call))
 
+                # Send artifact saved notification now that we have the function_call_id
+                # This ensures the signal and tool call arrive together
+                if block_info["status"] == "success" and a2a_context:
+                    try:
+                        artifact_info = ArtifactInfo(
+                            filename=block_info["filename"],
+                            version=block_info["version"],
+                            mime_type=block_info.get("mime_type") or "application/octet-stream",
+                            size=block_info.get("bytes_transferred", 0),
+                            description=block_info.get("description"),
+                            version_count=None,  # Count not available in save context
+                        )
+                        await host_component.notify_artifact_saved(
+                            artifact_info=artifact_info,
+                            a2a_context=a2a_context,
+                            function_call_id=function_call_id,
+                        )
+                        log.debug(
+                            "%s Published artifact saved notification for fenced block: %s (function_call_id=%s)",
+                            log_identifier,
+                            block_info["filename"],
+                            function_call_id,
+                        )
+                    except Exception as signal_err:
+                        log.warning(
+                            "%s Failed to publish artifact saved notification: %s",
+                            log_identifier,
+                            signal_err,
+                        )
+
             existing_parts = llm_response.content.parts if llm_response.content else []
             final_existing_parts = existing_parts
 
@@ -1124,6 +1175,11 @@ Example - CSV Table:
 {{% for row in data_rows %}}| {{% for cell in row %}}{{{{ cell }}}} | {{% endfor %}}{{% endfor %}}
 {close_delim}
 
+**IMPORTANT - Pipe Characters in Markdown Tables:**
+Text data may contain "|" characters which will break markdown table rendering by pushing data into wrong columns. For text fields that might contain pipes, use the `replace` filter to escape them:
+`{{{{ item.summary | replace: "|", "&#124;" }}}}`
+Only apply this to text fields that might contain pipes - numerical columns don't need it.
+
 Negative Examples
 Use {{ issues.size }} instead of {{ issues|length }}
 Use {{ forloop.index }} instead of {{ loop.index }} (Liquid uses forloop not loop)
@@ -1209,6 +1265,21 @@ def _generate_examples_instruction() -> str:
         + f"""{close_delim}
 
     Example 4:
+    - User: "Show me the Jira issues as a table"
+    <note>There is a JSON artifact jira_issues.json with items containing key, summary, status, type, assignee, updated fields</note>
+    - OrchestratorAgent:
+    {embed_open_delim}status_update:Rendering Jira issues table...{embed_close_delim}
+    {open_delim}template_liquid: data="jira_issues.json" limit="10"
+    """
+        + """| Key | Summary | Status | Type | Assignee | Updated |
+    |-----|---------|--------|------|----------|---------|
+    {% for item in items %}| [{{ item.key }}](https://jira.example.com/browse/{{ item.key }}) | {{ item.summary | replace: "|", "&#124;" }} | {{ item.status }} | {{ item.type }} | {{ item.assignee }} | {{ item.updated }} |
+    {% endfor %}"""
+        + f"""
+    {close_delim}
+    <note>The replace filter on item.summary escapes any pipe characters that would break the markdown table. Only apply to text fields that might contain pipes.</note>
+
+    Example 5:
     - User: "Search the database for all orders from last month"
     - OrchestratorAgent:
     {embed_open_delim}status_update:Querying order database...{embed_close_delim}
@@ -1216,7 +1287,7 @@ def _generate_examples_instruction() -> str:
     [After getting results:]
     Found 247 orders from last month totaling $45,231.
 
-    Example 5:
+    Example 6:
     - User: "Create an HTML with the chart image you just generated with the customer data."
     - OrchestratorAgent:
     {embed_open_delim}status_update:Generating HTML report with chart...{embed_close_delim}
@@ -1284,7 +1355,30 @@ Examples:
 - `The result of 23.5 * 4.2 is {open_delim}math:23.5 * 4.2 | .2f{close_delim}` (Embeds calculated result with 2 decimal places)
 
 The following embeds are resolved *late* (by the gateway before final display):
-- `{open_delim}artifact_return:filename[:version]{close_delim}`: This is the primary way to return an artifact to the user. It attaches the specified artifact to the message. The embed itself is removed from the text. Use this instead of describing a file and expecting the user to download it. Note: artifact_return is not necessary if the artifact was just created by you in this same response, since newly created artifacts are automatically attached to your message.
+- `{open_delim}artifact_return:filename[:version]{close_delim}`: Attaches an artifact to your message so the user receives the file. The embed itself is removed from the text.
+
+  **CRITICAL - Returning Artifacts to Users:**
+  Only artifacts created with the `{open_delim}save_artifact:...{close_delim}` fenced block syntax are automatically sent to the user.
+
+  **You MUST use artifact_return for:**
+  - Artifacts created by tools (e.g., image generation, chart creation, file conversion)
+  - Artifacts created by other agents you called
+  - Artifacts from MCP servers
+
+  **When deciding whether to return an artifact:**
+  - Return artifacts the user explicitly requested or that answer their question
+  - Return final outputs (charts, reports, images, documents)
+  - Do NOT return intermediate/temporary artifacts (e.g., temp files, internal data)
+
+  **Example - Tool creates an image:**
+  User: "Create a chart of sales data"
+  [You call a charting tool that creates sales_chart.png]
+  Your response: "Here's the sales chart. {open_delim}artifact_return:sales_chart.png{close_delim}"
+
+  **Example - Agent creates a report:**
+  User: "Generate a quarterly report"
+  [You call ReportAgent which creates quarterly_report.pdf]
+  Your response: "The quarterly report is ready. {open_delim}artifact_return:quarterly_report.pdf{close_delim}"
 """
 
     artifact_content_instruction = f"""
@@ -2316,3 +2410,76 @@ def auto_continue_on_max_tokens_callback(
     )
 
     return hijacked_response
+
+
+def preregister_long_running_tools_callback(
+    callback_context: CallbackContext,
+    llm_response: LlmResponse,
+    host_component: "SamAgentComponent",
+) -> Optional[LlmResponse]:
+    """
+    ADK after_model_callback to pre-register all long-running tool calls
+    before any tool execution begins. This prevents race conditions where
+    one tool completes before another has registered.
+
+    The race condition occurs because tools are executed via asyncio.gather
+    (non-deterministic order) and each tool calls register_parallel_call_sent()
+    inside its run_async(). If Tool A completes before Tool B even registers,
+    the system thinks all calls are done (completed=1, total=1).
+
+    By pre-registering all long-running tools in this callback (which runs
+    BEFORE tool execution), we ensure the total count is set correctly upfront.
+    """
+    log_identifier = "[Callback:PreregisterLongRunning]"
+
+    # Only process non-partial responses with function calls
+    if llm_response.partial:
+        return None
+
+    if not llm_response.content or not llm_response.content.parts:
+        return None
+
+    # Find all long-running tool calls (identified by peer_ prefix)
+    long_running_calls = []
+    for part in llm_response.content.parts:
+        if part.function_call:
+            tool_name = part.function_call.name
+            if tool_name.startswith(PEER_TOOL_PREFIX):
+                long_running_calls.append(part.function_call)
+
+    if not long_running_calls:
+        return None
+
+    # Get task context
+    a2a_context = callback_context.state.get("a2a_context")
+    if not a2a_context:
+        log.warning("%s No a2a_context, cannot pre-register tools", log_identifier)
+        return None
+
+    logical_task_id = a2a_context.get("logical_task_id")
+    invocation_id = callback_context._invocation_context.invocation_id
+
+    with host_component.active_tasks_lock:
+        task_context = host_component.active_tasks.get(logical_task_id)
+
+    if not task_context:
+        log.warning(
+            "%s TaskContext not found for %s, cannot pre-register",
+            log_identifier,
+            logical_task_id,
+        )
+        return None
+
+    # Pre-register ALL long-running calls atomically
+    for fc in long_running_calls:
+        task_context.register_parallel_call_sent(invocation_id)
+
+    log.info(
+        "%s Pre-registered %d long-running tool call(s) for invocation %s (task %s)",
+        log_identifier,
+        len(long_running_calls),
+        invocation_id,
+        logical_task_id,
+    )
+
+    return None  # Don't alter the response

solace_agent_mesh/agent/adk/embed_resolving_mcp_toolset.py

@@ -343,6 +343,7 @@ class EmbedResolvingMCPToolset(_BaseMcpToolsetClass):
         self,
         connection_params,
         tool_filter=None,
+        tool_name_prefix=None,
         auth_scheme=None,
         auth_credential=None,
         auth_discovery=None,
@@ -357,6 +358,7 @@ class EmbedResolvingMCPToolset(_BaseMcpToolsetClass):
             super().__init__(
                 connection_params=connection_params,
                 tool_filter=tool_filter,
+                tool_name_prefix=tool_name_prefix,
                 auth_scheme=auth_scheme,
                 auth_credential=auth_credential,
                 auth_discovery=auth_discovery,
@@ -367,6 +369,7 @@ class EmbedResolvingMCPToolset(_BaseMcpToolsetClass):
             super().__init__(
                 connection_params=connection_params,
                 tool_filter=tool_filter,
+                tool_name_prefix=tool_name_prefix,
                 auth_scheme=auth_scheme,
                 auth_credential=auth_credential,
             )

solace_agent_mesh/agent/adk/models/lite_llm.py

@@ -328,26 +328,41 @@ def _schema_to_dict(schema: types.Schema) -> dict:
     """
 
     schema_dict = schema.model_dump(exclude_none=True)
+
+    # Convert top-level type from enum to lowercase string
     if "type" in schema_dict:
-        schema_dict["type"] = schema_dict["type"].lower()
+        if isinstance(schema_dict["type"], types.Type):
+            schema_dict["type"] = schema_dict["type"].value.lower()
+        else:
+            schema_dict["type"] = str(schema_dict["type"]).lower()
+
+    # Recursively handle items (for array types)
     if "items" in schema_dict:
-        if isinstance(schema_dict["items"], dict):
+        # Check if we have the original Schema object for items
+        if isinstance(schema.items, types.Schema):
+            # Recursively convert the Schema object - this ensures nested Type enums are converted
+            schema_dict["items"] = _schema_to_dict(schema.items)
+        elif isinstance(schema_dict["items"], dict):
+            # If items is already a dict, validate and recurse
             schema_dict["items"] = _schema_to_dict(
                 types.Schema.model_validate(schema_dict["items"])
             )
-        elif isinstance(schema_dict["items"]["type"], types.Type):
-            schema_dict["items"]["type"] = TYPE_LABELS[
-                schema_dict["items"]["type"].value
-            ]
+
+    # Recursively handle properties (for object types)
     if "properties" in schema_dict:
         properties = {}
         for key, value in schema_dict["properties"].items():
             if isinstance(value, types.Schema):
+                # If it's a Schema object, recursively convert it
                 properties[key] = _schema_to_dict(value)
+            elif isinstance(value, dict):
+                # If it's already a dict, validate and recurse to handle nested Type enums
+                properties[key] = _schema_to_dict(
+                    types.Schema.model_validate(value)
+                )
             else:
+                # For other types, just copy as-is
                 properties[key] = value
-                if "type" in properties[key]:
-                    properties[key]["type"] = properties[key]["type"].lower()
         schema_dict["properties"] = properties
     return schema_dict
 
@@ -366,20 +381,23 @@ def _function_declaration_to_tool_param(
 
     assert function_declaration.name
 
-    properties = {}
-    if function_declaration.parameters and function_declaration.parameters.properties:
-        for key, value in function_declaration.parameters.properties.items():
-            properties[key] = _schema_to_dict(value)
+    # Convert the entire parameters schema to ensure all fields (type, properties, required, etc.)
+    # are properly converted, including nested Type enums
+    # If no parameters provided, default to empty object schema (required by OpenAI)
+    if function_declaration.parameters:
+        parameters = _schema_to_dict(function_declaration.parameters)
+    else:
+        parameters = {
+            "type": "object",
+            "properties": {},
+        }
 
     return {
         "type": "function",
         "function": {
             "name": function_declaration.name,
             "description": function_declaration.description or "",
-            "parameters": {
-                "type": "object",
-                "properties": properties,
-            },
+            "parameters": parameters,
         },
     }
 

solace_agent_mesh/agent/adk/runner.py

@@ -201,13 +201,13 @@ async def run_adk_async_task_thread_wrapper(
             llm_limit_e,
         )
     except BadRequestError as e:
+        exception_to_finalize_with = e
         log.error(
-            "%s Bad Request for task %s: %s.",
+            "%s Bad Request for task %s: %s. Scheduling finalization.",
             component.log_identifier,
             logical_task_id,
             e.message,
         )
-        raise
     except Exception as e:
         exception_to_finalize_with = e
         log.exception(
@@ -261,7 +261,11 @@ async def run_adk_async_task(
     logical_task_id = a2a_context.get("logical_task_id", "unknown_task")
     event_loop_stored = False
     current_loop = asyncio.get_running_loop()
-    is_paused = False
+    # Track pending long-running tools by their function_call IDs
+    # This replaces the simple boolean is_paused to properly handle sync returns
+    pending_long_running_tools: set[str] = set()
+    # Collect synchronous responses from long-running tools for potential re-run
+    sync_tool_responses: list[adk_types.Part] = []
 
     adk_event_generator = component.runner.run_async(
         user_id=adk_session.user_id,
@@ -316,7 +320,10 @@ async def run_adk_async_task(
                 break
 
             if event.long_running_tool_ids:
-                is_paused = True
+                # Track which long-running tool calls are pending (waiting for async response)
+                pending_long_running_tools = pending_long_running_tools.union(
+                    event.long_running_tool_ids
+                )
 
             if not event_loop_stored and event.invocation_id:
                 task_context.set_event_loop(current_loop)
@@ -342,8 +349,18 @@ async def run_adk_async_task(
             if event.content and event.content.parts:
                 for part in event.content.parts:
                     if part.function_response:
-                        if part.function_response.name.startswith("peer_"):
-                            pass
+                        # Check if this is a sync response from a long-running tool
+                        # (i.e., the tool returned immediately instead of async)
+                        response_id = part.function_response.id
+                        if response_id and response_id in pending_long_running_tools:
+                            pending_long_running_tools.discard(response_id)
+                            sync_tool_responses.append(part)
+                            log.info(
+                                "%s Long-running tool %s (id=%s) returned synchronously.",
+                                component.log_identifier,
+                                part.function_response.name,
+                                response_id,
+                            )
 
     except TaskCancelledError:
         raise
@@ -374,14 +391,55 @@ async def run_adk_async_task(
             f"Task {logical_task_id} was cancelled before finalization."
         )
 
-    if is_paused:
+    invocation_id = a2a_context.get("invocation_id")
+
+    # Check if we still have pending long-running tools (waiting for async responses)
+    if pending_long_running_tools:
+        # Store any sync responses using the SAME format as event_handlers.py
+        # This ensures they're combined with async responses when _retrigger is called
+        if sync_tool_responses:
+            for part in sync_tool_responses:
+                result = {
+                    "adk_function_call_id": part.function_response.id,
+                    "peer_tool_name": part.function_response.name,
+                    "payload": part.function_response.response,  # Already a dict from ADK
+                }
+                task_context.record_parallel_result(result, invocation_id)
+            log.info(
+                "%s Stored %d sync tool response(s) for later combination. Waiting for: %s",
+                component.log_identifier,
+                len(sync_tool_responses),
+                pending_long_running_tools,
+            )
+
         log.info(
-            "%s ADK run completed by invoking a long-running tool. Task %s will remain open, awaiting peer response.",
+            "%s Task %s paused, waiting for %d async tool response(s).",
             component.log_identifier,
             logical_task_id,
+            len(pending_long_running_tools),
         )
         return True
 
+    # All tools returned synchronously - re-run ADK with their responses
+    # The ADK already created the Part objects, so we use them directly (no duplication)
+    if sync_tool_responses:
+        log.info(
+            "%s All %d long-running tool(s) returned synchronously for task %s. Re-running ADK.",
+            component.log_identifier,
+            len(sync_tool_responses),
+            logical_task_id,
+        )
+        # Use the Part objects directly from the ADK (already properly formatted)
+        tool_response_content = adk_types.Content(role="tool", parts=sync_tool_responses)
+        return await run_adk_async_task(
+            component=component,
+            task_context=task_context,
+            adk_session=adk_session,
+            adk_content=tool_response_content,
+            run_config=run_config,
+            a2a_context=a2a_context,
+        )
+
     log.debug(
         "%s ADK run_async completed for task %s. Returning to wrapper for finalization.",
         component.log_identifier,