fix(agents): preserve arun and mcp tool output

Author: erichare

src/frontend/src/components/core/chatComponents/ToolOutputDisplay.tsx

@@ -80,6 +80,19 @@ function FormattedOutput({ value }: { value: JSONValue }) {
 
 type Tab = "result" | "metadata";
 
+function isMcpCallToolResultArtifact(
+  value: JSONValue | undefined,
+): value is Record<string, JSONValue> {
+  return (
+    value !== null &&
+    value !== undefined &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Array.isArray(value.content) &&
+    typeof value.isError === "boolean"
+  );
+}
+
 /** Tab control sized for the inside of a tool-call card. Matches the
  * underline-on-active pattern used across assistant-ui / Claude /
  * ChatGPT — quiet by default, the active tab gets a 2px underline in
@@ -118,9 +131,10 @@ function TabButton({
  *   - LangChain ToolMessage envelope with non-standard metadata keys
  *     (additional_kwargs, response_metadata, type, ...) gets a 2-tab UI:
  *     "Result" prefers the structured `.artifact` and falls back to the
- *     model-facing `.content`; "Metadata" shows the rest of the envelope
- *     as pretty JSON. Plumbing keys (name, id, tool_call_id, status) are
- *     suppressed because the accordion trigger already surfaces them.
+ *     model-facing `.content`. MCP `CallToolResult` artifacts are protocol
+ *     envelopes, so their readable content stays in Result and the raw
+ *     artifact stays in Metadata. Plumbing keys (name, id, tool_call_id,
+ *     status) are suppressed because the accordion trigger surfaces them.
  *   - Anything else (simple string, plain dict, unwrappable envelope)
  *     falls through to FormattedOutput directly under the eyebrow —
  *     no tabs, just the body. */
@@ -137,17 +151,20 @@ export function ToolOutputDisplay({ output }: { output: JSONValue }) {
     );
   }
 
-  const result = output.artifact ?? output.content;
+  const artifact = output.artifact;
+  const isMcpArtifact = isMcpCallToolResultArtifact(artifact);
+  const result = artifact != null && !isMcpArtifact ? artifact : output.content;
   // Strip the standard ToolMessage plumbing keys from the metadata view —
   // the accordion trigger already shows tool name and status, and id /
   // tool_call_id aren't useful in the UI. What remains is the actually
   // interesting custom metadata (additional_kwargs, response_metadata,
-  // type, custom fields). Artifact is the primary result, so don't duplicate
-  // it in the Metadata tab.
+  // type, custom fields). Component artifacts are the primary result, while
+  // raw MCP protocol artifacts remain metadata behind readable content.
   const metadata = Object.fromEntries(
-    Object.entries(output).filter(
-      ([k]) => !TOOL_MESSAGE_KEYS_PLUS_CONTENT.has(k),
-    ),
+    Object.entries(output).filter(([key, value]) => {
+      if (key === "artifact") return value != null && isMcpArtifact;
+      return !TOOL_MESSAGE_KEYS_PLUS_CONTENT.has(key);
+    }),
   );
   const hasMetadata = Object.keys(metadata).length > 0;
 
@@ -205,12 +222,12 @@ export function ToolOutputDisplay({ output }: { output: JSONValue }) {
   );
 }
 
-// `content` and `artifact` belong in the Result tab; the rest of the
-// canonical plumbing fields aren't worth exposing — keep this set local
-// rather than re-exporting yet another constant.
+// `content` belongs in the Result tab; the canonical plumbing fields aren't
+// worth exposing — keep this set local rather than re-exporting another
+// constant. Artifact routing depends on whether it is component data or an
+// MCP protocol envelope, so it is handled separately above.
 const TOOL_MESSAGE_KEYS_PLUS_CONTENT = new Set([
   "content",
-  "artifact",
   "name",
   "id",
   "tool_call_id",

src/frontend/src/components/core/chatComponents/__tests__/ContentDisplay.test.tsx

@@ -1,4 +1,4 @@
-import { render, screen } from "@testing-library/react";
+import { fireEvent, render, screen } from "@testing-library/react";
 import type {
   CitationContent,
   ContentBlockItem,
@@ -394,6 +394,38 @@ describe("ContentDisplay", () => {
       expect(screen.getAllByRole("tab")).toHaveLength(2);
     });
 
+    it("keeps MCP content as the result and its protocol artifact in metadata", async () => {
+      const tool = {
+        type: "tool_use",
+        name: "mcp_search",
+        tool_input: {},
+        output: {
+          content: "readable MCP output",
+          artifact: {
+            meta: null,
+            content: [{ type: "text", text: "readable MCP output" }],
+            structuredContent: null,
+            isError: false,
+          },
+          additional_kwargs: {},
+          response_metadata: {},
+          type: "tool",
+          name: "mcp_search",
+          tool_call_id: "toolu_mcp",
+          status: "success",
+        },
+      } as unknown as ContentBlockItem;
+
+      render(<ContentDisplay content={tool} chatId="t-t-mcp-artifact" />);
+
+      expect(screen.getByText("readable MCP output")).toBeInTheDocument();
+
+      fireEvent.click(screen.getByRole("tab", { name: "Metadata" }));
+      const metadata = await screen.findByTestId("code-tabs");
+      expect(metadata).toHaveTextContent('"artifact": {');
+      expect(metadata).toHaveTextContent('"isError": false');
+    });
+
     it("renders the error body in a destructive-toned panel", () => {
       // No eyebrow label — the surrounding accordion already says
       // "tool call" and the destructive bg + color carries the meaning.

src/lfx/src/lfx/base/tools/component_tool.py

@@ -63,6 +63,10 @@ async def _arun(
         run_manager: AsyncCallbackManagerForToolRun | None = None,
         **kwargs: Any,
     ) -> tuple[Any, Any | None]:
+        if self.coroutine is None:
+            # StructuredTool falls back to self._run, which already returns the
+            # content-and-artifact tuple. Wrapping it again would nest the tuple.
+            return await super()._arun(*args, config=config, run_manager=run_manager, **kwargs)
         content = await super()._arun(*args, config=config, run_manager=run_manager, **kwargs)
         return self._content_and_artifact(content)
 

src/lfx/tests/unit/custom/component/test_tool_dataframe_return.py

@@ -105,7 +105,6 @@ def test_agent_tool_preserves_dataframe_as_artifact():
     ]
 
 
-@pytest.mark.asyncio
 async def test_sync_agent_tool_preserves_dataframe_as_artifact_when_awaited():
     """Async agent execution of a sync tool must not wrap the response tuple twice."""
     component = DataFrameProducerComponent()
@@ -128,6 +127,17 @@ async def test_sync_agent_tool_preserves_dataframe_as_artifact_when_awaited():
     ]
 
 
+async def test_sync_tool_arun_returns_dataframe_not_wrapped_tuple():
+    """Direct arun calls on sync tools must preserve the legacy raw-result contract."""
+    component = DataFrameProducerComponent()
+    table_tool = next(t for t in ComponentToolkit(component=component).get_tools() if t.name == "get_table")
+
+    result = await table_tool.arun({"query": "test"})
+
+    assert isinstance(result, pd.DataFrame), f"Expected pandas DataFrame, got {type(result).__name__}: {result!r}"
+    assert result["col1"].tolist() == [1, 2, 3]
+
+
 def test_tool_returns_text_for_message():
     """Tool wrapping a Message output must still return text (not change behavior)."""
     component = DataFrameProducerComponent()
@@ -193,7 +203,6 @@ async def test_tool_handles_positional_args_async():
     assert "my_async_query" in result
 
 
-@pytest.mark.asyncio
 async def test_async_agent_tool_preserves_dataframe_as_artifact():
     """Async component tools must preserve structured output under the same Agent contract."""
     component = AsyncTextComponent()