langfuse-haystack 6.0.0__tar.gz → 7.0.0__tar.gz

{langfuse_haystack-6.0.0 → langfuse_haystack-7.0.0}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [integrations/langfuse-v6.0.0] - 2026-09-11
+
+### 🐛 Bug Fixes
+
+- Fix new issues raised by ruff 0.16.0 (#3670)
+- Standardize license files (#3771)
+
+### 🚜 Refactor
+
+- [**breaking**] Langfuse connector - move tracer creation at warm_up (#3949)
+
+### ⚙️ CI
+
+- Improve changelog generation; fix existing changelogs (#3883)
+
+
 ## [integrations/langfuse-v5.2.0] - 2026-07-15
 
 ### 🐛 Bug Fixes

{langfuse_haystack-6.0.0 → langfuse_haystack-7.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: langfuse-haystack
-Version: 6.0.0
+Version: 7.0.0
 Summary: Langfuse integration for Haystack
 Project-URL: Documentation, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/langfuse#readme
 Project-URL: Issues, https://github.com/deepset-ai/haystack-core-integrations/issues

{langfuse_haystack-6.0.0 → langfuse_haystack-7.0.0}/src/haystack_integrations/tracing/langfuse/tracer.py

@@ -6,8 +6,7 @@ import contextlib
 import os
 import sys
 from abc import ABC, abstractmethod
-from collections import Counter
-from collections.abc import Iterator
+from collections.abc import Iterator, Sequence
 from contextlib import AbstractContextManager
 from contextvars import ContextVar
 from dataclasses import dataclass
@@ -15,14 +14,15 @@ from datetime import datetime
 from typing import Any, Literal, cast
 
 from haystack import default_from_dict, default_to_dict, logging
-from haystack.dataclasses import ChatMessage
+from haystack.dataclasses import ChatMessage, FileContent, ImageContent, TextContent
+from haystack.tools import flatten_tools_or_toolsets
 from haystack.tracing import Span, Tracer
 from haystack.tracing import tracer as proxy_tracer
 from haystack.tracing import utils as tracing_utils
 
 import langfuse
+from langfuse import LangfuseAgent, LangfuseGeneration, LangfuseTool, propagate_attributes
 from langfuse import LangfuseSpan as LangfuseClientSpan
-from langfuse import propagate_attributes
 from langfuse.types import TraceContext
 
 logger = logging.getLogger(__name__)
@@ -39,9 +39,16 @@ _COMPONENT_NAME_KEY = "haystack.component.name"
 _COMPONENT_TYPE_KEY = "haystack.component.type"
 _COMPONENT_OUTPUT_KEY = "haystack.component.output"
 _COMPONENT_INPUT_KEY = "haystack.component.input"
+_AGENT_STEP_OPERATION = "haystack.agent.step"
+_AGENT_STEP_LLM_OPERATION = "haystack.agent.step.llm"
+_AGENT_STEP_TOOL_OPERATION = "haystack.agent.step.tool"
+_AGENT_STEP_KEY = "haystack.agent.step"
+_AGENT_STEP_LLM_INPUT_KEY = "haystack.agent.step.llm.input"
+_AGENT_STEP_LLM_OUTPUT_KEY = "haystack.agent.step.llm.output"
+_TOOL_NAME_KEY = "haystack.tool.name"
 
 # Type alias for observation span types
-ObservationSpanType = Literal["tool", "agent", "retriever", "embedding", "generation"]
+ObservationSpanType = Literal["tool", "agent", "chain", "retriever", "embedding", "generation"]
 
 # External session metadata for trace correlation (Haystack system)
 # Stores trace_id, user_id, session_id, tags, version for root trace creation
@@ -88,27 +95,19 @@ class LangfuseSpan(Span):
         """
         if not proxy_tracer.is_content_tracing_enabled:
             return
+        # Only generation and agent observations carry chat messages, other spans like tool calls get a coerced value
+        is_chat = isinstance(self._span, (LangfuseGeneration, LangfuseAgent))
         if key.endswith(".input"):
-            if "messages" in value:
-                messages = [m.to_openai_dict_format(require_tool_call_ids=False) for m in (value.get("messages") or [])]
-                if isinstance(gen_kwargs := value.get("generation_kwargs"), dict):
-                    self._span.update(input={"messages": messages, "generation_kwargs": gen_kwargs})
-                else:
-                    self._span.update(input=messages)
-            else:
-                coerced_value = tracing_utils.coerce_tag_value(value)
-                self._span.update(input=coerced_value)
+            self._span.update(
+                input=_format_chat_input(value=value) if is_chat else tracing_utils.coerce_tag_value(value)
+            )
         elif key.endswith(".output"):
-            if "replies" in value:
-                replies_list = value.get("replies") or []
-                if all(isinstance(r, ChatMessage) for r in replies_list):
-                    replies = [m.to_openai_dict_format(require_tool_call_ids=False) for m in replies_list]
-                else:
-                    replies = replies_list
-                self._span.update(output=replies)
+            if is_chat:
+                self._span.update(output=_format_chat_output(value=value))
+            elif isinstance(self._span, LangfuseTool):
+                self._span.update(output=_format_tool_output(value=value))
             else:
-                coerced_value = tracing_utils.coerce_tag_value(value)
-                self._span.update(output=coerced_value)
+                self._span.update(output=tracing_utils.coerce_tag_value(value))
 
         self._data[key] = value
 
@@ -276,6 +275,150 @@ def _sanitize_usage_data(usage: dict[str, Any]) -> dict[str, Any]:
     return sanitized
 
 
+def _to_openai_content_parts(parts: Sequence[TextContent | ImageContent | FileContent]) -> list[dict[str, Any]]:
+    """
+    Convert content parts to the `text`, `image_url` and `file` parts of OpenAI user messages.
+
+    :param parts: The content parts, e.g. the result of a tool.
+    :returns: The content parts in OpenAI format.
+    """
+    content: list[dict[str, Any]] = []
+    for part in parts:
+        if isinstance(part, TextContent):
+            content.append({"type": "text", "text": part.text})
+        elif isinstance(part, ImageContent):
+            image_url = f"data:{part.mime_type or 'image/jpeg'};base64,{part.base64_image}"
+            content.append({"type": "image_url", "image_url": {"url": image_url}})
+        elif isinstance(part, FileContent):
+            file_data = f"data:{part.mime_type or 'application/pdf'};base64,{part.base64_data}"
+            content.append({"type": "file", "file": {"file_data": file_data, "filename": part.filename}})
+    return content
+
+
+def _to_openai_message(message: ChatMessage) -> dict[str, Any]:
+    """
+    Convert a ChatMessage to OpenAI Chat Completions format for Langfuse.
+
+    Tool results made of content parts get `text`, `image_url` and `file` parts, as used in OpenAI user messages.
+
+    :param message: The ChatMessage to convert.
+    :returns: The message in OpenAI format.
+    :raises ValueError: If the message has no OpenAI format, e.g. because it has no content.
+    """
+    result = message.tool_call_result
+    if result is None or isinstance(result.result, str):
+        return message.to_openai_dict_format(require_tool_call_ids=False)
+
+    openai_message: dict[str, Any] = {"role": "tool", "content": _to_openai_content_parts(parts=result.result)}
+    if result.origin.id is not None:
+        openai_message["tool_call_id"] = result.origin.id
+    return openai_message
+
+
+def _format_tool_output(value: Any) -> Any:
+    """
+    Format the result of a tool call for Langfuse.
+
+    :param value: The tool result.
+    :returns: The content parts in OpenAI format if the result is a list of content parts, e.g. text and images.
+        Any other result is returned as a coerced tag value.
+    """
+    if (
+        isinstance(value, list)
+        and value
+        and all(isinstance(part, (TextContent, ImageContent, FileContent)) for part in value)
+    ):
+        return _to_openai_content_parts(parts=value)
+    return tracing_utils.coerce_tag_value(value)
+
+
+def _format_chat_input(value: Any) -> Any:
+    """
+    Format the input of a generation or agent span for Langfuse.
+
+    :param value: The traced input, e.g. the inputs of a ChatGenerator.
+    :returns: The messages in OpenAI format. If `generation_kwargs` or `tools` are set, a dictionary with the
+        `messages` and the `generation_kwargs` and OpenAI tool definitions is returned instead.
+        Messages that have no OpenAI format are returned as a coerced tag value.
+        Inputs without `messages` are returned as a coerced tag value.
+    """
+    if "messages" not in value:
+        return tracing_utils.coerce_tag_value(value)
+    messages: Any
+    try:
+        messages = [_to_openai_message(message=m) for m in (value.get("messages") or [])]
+    except ValueError:
+        messages = tracing_utils.coerce_tag_value(value.get("messages"))
+
+    formatted: dict[str, Any] = {"messages": messages}
+    if isinstance(gen_kwargs := value.get("generation_kwargs"), dict):
+        formatted["generation_kwargs"] = gen_kwargs
+    # Langfuse shows the tools of `{"messages": ..., "tools": ...}` inputs next to the messages
+    if tools := value.get("tools"):
+        formatted["tools"] = [{"type": "function", "function": t.tool_spec} for t in flatten_tools_or_toolsets(tools)]
+    return formatted if len(formatted) > 1 else messages
+
+
+def _format_chat_output(value: Any) -> Any:
+    """
+    Format the output of a generation or agent span for Langfuse.
+
+    :param value: The traced output, e.g. the outputs of a ChatGenerator.
+    :returns: The replies in OpenAI format. String replies are returned as they are.
+        Replies that have no OpenAI format are returned as a coerced tag value.
+        Outputs without `replies` are returned as a coerced tag value.
+    """
+    if "replies" not in value:
+        return tracing_utils.coerce_tag_value(value)
+    replies = value.get("replies") or []
+    # Generators that aren't ChatGenerators return string replies
+    if not all(isinstance(r, ChatMessage) for r in replies):
+        return replies
+    try:
+        return [_to_openai_message(message=m) for m in replies]
+    except ValueError:
+        return tracing_utils.coerce_tag_value(replies)
+
+
+def _update_generation_details(
+    span: LangfuseSpan, chat_generator_inputs: dict[str, Any], chat_generator_output: dict[str, Any]
+) -> None:
+    """
+    Add the model details of a ChatGenerator call to the span.
+
+    The model, token usage and completion start time come from the first reply, the model parameters from the
+    `generation_kwargs` passed to the ChatGenerator.
+
+    :param span: The generation span.
+    :param chat_generator_inputs: The inputs of the ChatGenerator.
+    :param chat_generator_output: The outputs of the ChatGenerator.
+    """
+    update_kwargs: dict[str, Any] = {}
+    if replies := chat_generator_output.get("replies"):
+        meta = replies[0].meta
+        completion_start_time = meta.get("completion_start_time")
+        if completion_start_time:
+            try:
+                completion_start_time = datetime.fromisoformat(completion_start_time)
+            except ValueError:
+                logger.error(f"Failed to parse completion_start_time: {completion_start_time}")
+                completion_start_time = None
+        usage = meta.get("usage")
+        update_kwargs["usage_details"] = _sanitize_usage_data(usage=usage) if usage else None
+        update_kwargs["model"] = meta.get("model")
+        update_kwargs["completion_start_time"] = completion_start_time
+    if generation_kwargs := chat_generator_inputs.get("generation_kwargs"):
+        # Langfuse model parameters only take primitive values, so nested values like `response_format` are coerced
+        update_kwargs["model_parameters"] = {
+            key: value
+            if value is None or isinstance(value, tracing_utils.PRIMITIVE_TYPES)
+            else tracing_utils.coerce_tag_value(value)
+            for key, value in generation_kwargs.items()
+        }
+    if update_kwargs:
+        span.raw_span().update(**update_kwargs)
+
+
 class DefaultSpanHandler(SpanHandler):
     """DefaultSpanHandler provides the default Langfuse tracing behavior for Haystack."""
 
@@ -313,9 +456,19 @@ class DefaultSpanHandler(SpanHandler):
             return span
 
         span_type = None
+        name = context.name
 
-        if context.component_type == "ToolInvoker":
+        # Agent spans carry no component tags, so they're matched by operation name
+        if context.operation_name == _AGENT_STEP_OPERATION:
+            span_type = "chain"
+            name = f"agent step {context.tags.get(_AGENT_STEP_KEY)}"
+        elif context.operation_name == _AGENT_STEP_LLM_OPERATION:
+            span_type = "generation"
+            name = "llm"
+        elif context.operation_name == _AGENT_STEP_TOOL_OPERATION:
             span_type = "tool"
+            tool_name = context.tags.get(_TOOL_NAME_KEY)
+            name = f"tool - {tool_name}" if tool_name else "tool"
         elif context.operation_name == "haystack.agent.run":
             span_type = "agent"
         elif context.component_type and context.component_type.endswith("Retriever"):
@@ -327,12 +480,10 @@ class DefaultSpanHandler(SpanHandler):
 
         if span_type:
             return LangfuseSpan(
-                self.tracer.start_as_current_observation(
-                    name=context.name, as_type=cast(ObservationSpanType, span_type)
-                )
+                self.tracer.start_as_current_observation(name=name, as_type=cast(ObservationSpanType, span_type))
             )
         else:
-            return LangfuseSpan(self.tracer.start_as_current_observation(name=context.name))
+            return LangfuseSpan(self.tracer.start_as_current_observation(name=name))
 
     def handle(self, span: LangfuseSpan, component_type: str | None) -> None:
         """Process and enrich a span after component execution."""
@@ -342,66 +493,18 @@ class DefaultSpanHandler(SpanHandler):
             coerced_input = tracing_utils.coerce_tag_value(span.get_data().get(_PIPELINE_INPUT_KEY))
             coerced_output = tracing_utils.coerce_tag_value(span.get_data().get(_PIPELINE_OUTPUT_KEY))
             span.raw_span().update(input=coerced_input, output=coerced_output)
-        # special case for ToolInvoker (to update the span name to be: `original_component_name - [tool_names]`)
-        if component_type == "ToolInvoker":
-            tool_names: list[str] = []
-            tool_calls_input: list[dict[str, Any]] = []
-            messages = span.get_data().get(_COMPONENT_INPUT_KEY, {}).get("messages", [])
-            for message in messages:
-                if isinstance(message, ChatMessage) and message.tool_calls:
-                    for call in message.tool_calls:
-                        tool_names.append(call.tool_name)
-                        tool_calls_input.append({"tool_name": call.tool_name, "arguments": call.arguments})
-
-            if tool_names:
-                # Fallback to "ToolInvoker" if we can't retrieve component name
-                tool_invoker_name = span.get_data().get(_COMPONENT_NAME_KEY, "ToolInvoker")
-                tool_counts = Counter(tool_names)  # how many times each tool was called
-                formatted_names = [f"{name} (x{count})" if count > 1 else name for name, count in tool_counts.items()]
-                span.raw_span().update(name=f"{tool_invoker_name} - {sorted(formatted_names)}")
-
-            if tool_calls_input and proxy_tracer.is_content_tracing_enabled:
-                # Replace the noisy full message history with just the tool call arguments
-                span.raw_span().update(input=tool_calls_input)
-
-                output_messages = span.get_data().get(_COMPONENT_OUTPUT_KEY, {}).get("tool_messages", [])
-                tool_results: list[dict[str, Any]] = []
-                for message in output_messages:
-                    if isinstance(message, ChatMessage) and message.tool_call_results:
-                        for tcr in message.tool_call_results:
-                            origin = tcr.origin
-                            # Keys `name`, `arguments` and `id` let Langfuse detect these as tool
-                            # calls at ingestion and populate the Tool Call Name filter in the UI.
-                            tool_results.append(
-                                {
-                                    "id": origin.id if origin else None,
-                                    "name": origin.tool_name if origin else None,
-                                    "arguments": origin.arguments if origin else None,
-                                    "result": tcr.result,
-                                    "error": tcr.error,
-                                }
-                            )
-                if tool_results:
-                    span.raw_span().update(output=tool_results)
-
-        if component_type and component_type.endswith("ChatGenerator"):
-            replies = span.get_data().get(_COMPONENT_OUTPUT_KEY, {}).get("replies")
-            if replies:
-                meta = replies[0].meta
-                completion_start_time = meta.get("completion_start_time")
-                if completion_start_time:
-                    try:
-                        completion_start_time = datetime.fromisoformat(completion_start_time)
-                    except ValueError:
-                        logger.error(f"Failed to parse completion_start_time: {completion_start_time}")
-                        completion_start_time = None
-                usage = meta.get("usage")
-                sanitized_usage = _sanitize_usage_data(usage) if usage else None
-                span.raw_span().update(
-                    usage_details=sanitized_usage,
-                    model=meta.get("model"),
-                    completion_start_time=completion_start_time,
-                )
+        if _AGENT_STEP_LLM_OUTPUT_KEY in span.get_data():
+            _update_generation_details(
+                span=span,
+                chat_generator_inputs=span.get_data().get(_AGENT_STEP_LLM_INPUT_KEY, {}),
+                chat_generator_output=span.get_data()[_AGENT_STEP_LLM_OUTPUT_KEY],
+            )
+        elif component_type and component_type.endswith("ChatGenerator"):
+            _update_generation_details(
+                span=span,
+                chat_generator_inputs=span.get_data().get(_COMPONENT_INPUT_KEY, {}),
+                chat_generator_output=span.get_data().get(_COMPONENT_OUTPUT_KEY, {}),
+            )
         elif component_type and component_type.endswith("Generator"):
             meta = span.get_data().get(_COMPONENT_OUTPUT_KEY, {}).get("meta")
             if meta:

{langfuse_haystack-6.0.0 → langfuse_haystack-7.0.0}/tests/test_tracer.py

@@ -3,13 +3,18 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import asyncio
+import base64
 import datetime
 import logging
 import sys
 from unittest.mock import MagicMock, Mock, patch
 
 import pytest
-from haystack.dataclasses import ChatMessage, ToolCall
+from haystack.dataclasses import ChatMessage, ChatRole, FileContent, ImageContent, TextContent, ToolCall
+from haystack.tools import Tool, Toolset
+from haystack.tracing import utils as tracing_utils
+from langfuse import LangfuseAgent, LangfuseGeneration, LangfuseTool
+from langfuse import LangfuseSpan as LangfuseClientSpan
 
 from haystack_integrations.tracing.langfuse.tracer import (
     _COMPONENT_OUTPUT_KEY,
@@ -32,8 +37,8 @@ def mock_get_client():
 class MockContextManager:
     """Mock context manager that simulates Langfuse v4 context managers"""
 
-    def __init__(self, name="mock_span"):
-        self._span = MockSpan(name)
+    def __init__(self, name="mock_span", span=None):
+        self._span = span or MockSpan(name)
 
     def __enter__(self):
         return self._span
@@ -139,8 +144,9 @@ class TestLangfuseSpan:
             mock_context_manager._span.update.assert_called_with(output="output_value")
 
     # set_content_tag method can update input and output of the span object with messages/replies
-    def test_set_content_tag_updates_input_and_output_with_messages(self):
-        mock_context_manager = MockContextManager()
+    @pytest.mark.parametrize("observation_class", [LangfuseGeneration, LangfuseAgent])
+    def test_set_content_tag_updates_input_and_output_with_messages(self, observation_class):
+        mock_context_manager = MockContextManager(span=Mock(spec=observation_class))
         span = LangfuseSpan(mock_context_manager)
 
         with patch("haystack_integrations.tracing.langfuse.tracer.proxy_tracer.is_content_tracing_enabled", True):
@@ -180,8 +186,40 @@ class TestLangfuseSpan:
             # check we handle properly string list replies
             assert mock_context_manager._span.update.call_args_list[0][1] == {"output": ["reply1", "reply2"]}
 
+    def test_set_content_tag_input_with_tools(self):
+        mock_context_manager = MockContextManager(span=Mock(spec=LangfuseGeneration))
+        span = LangfuseSpan(mock_context_manager)
+        weather = Tool(
+            name="weather",
+            description="Get the weather",
+            parameters={"type": "object", "properties": {"city": {"type": "string"}}},
+            function=lambda city: city,
+        )
+
+        with patch("haystack_integrations.tracing.langfuse.tracer.proxy_tracer.is_content_tracing_enabled", True):
+            span.set_content_tag(
+                "haystack.agent.step.llm.input",
+                {"messages": [ChatMessage.from_user("message")], "tools": Toolset([weather])},
+            )
+
+        mock_context_manager._span.update.assert_called_once_with(
+            input={
+                "messages": [{"role": "user", "content": "message"}],
+                "tools": [
+                    {
+                        "type": "function",
+                        "function": {
+                            "name": "weather",
+                            "description": "Get the weather",
+                            "parameters": {"type": "object", "properties": {"city": {"type": "string"}}},
+                        },
+                    }
+                ],
+            }
+        )
+
     def test_set_content_tag_messages_none_does_not_raise(self):
-        mock_context_manager = MockContextManager()
+        mock_context_manager = MockContextManager(span=Mock(spec=LangfuseGeneration))
         span = LangfuseSpan(mock_context_manager)
 
         with patch("haystack_integrations.tracing.langfuse.tracer.proxy_tracer.is_content_tracing_enabled", True):
@@ -190,7 +228,7 @@ class TestLangfuseSpan:
             assert mock_context_manager._span.update.call_args_list[0][1] == {"input": []}
 
     def test_set_content_tag_replies_none_does_not_raise(self):
-        mock_context_manager = MockContextManager()
+        mock_context_manager = MockContextManager(span=Mock(spec=LangfuseGeneration))
         span = LangfuseSpan(mock_context_manager)
 
         with patch("haystack_integrations.tracing.langfuse.tracer.proxy_tracer.is_content_tracing_enabled", True):
@@ -198,6 +236,91 @@ class TestLangfuseSpan:
             assert mock_context_manager._span.update.call_count == 1
             assert mock_context_manager._span.update.call_args_list[0][1] == {"output": []}
 
+    @pytest.mark.parametrize(
+        "key,value,expected",
+        [
+            ("haystack.agent.step.tool.input", {"messages": ["hi", "there"]}, '{"messages": ["hi", "there"]}'),
+            ("haystack.agent.step.tool.output", None, ""),
+            ("haystack.agent.step.tool.output", 42, 42),
+            ("haystack.agent.step.tool.output", "No replies found", "No replies found"),
+            ("haystack.agent.step.tool.output", {"replies": 5}, '{"replies": 5}'),
+            ("haystack.component.input", {"messages": ["hi", "there"]}, '{"messages": ["hi", "there"]}'),
+        ],
+    )
+    def test_set_content_tag_non_chat_span_coerces_value(self, key, value, expected):
+        span_spec = LangfuseTool if key.startswith("haystack.agent.step.tool") else LangfuseClientSpan
+        mock_context_manager = MockContextManager(span=Mock(spec=span_spec))
+        span = LangfuseSpan(mock_context_manager)
+
+        with patch("haystack_integrations.tracing.langfuse.tracer.proxy_tracer.is_content_tracing_enabled", True):
+            span.set_content_tag(key, value)
+
+        field = "input" if key.endswith(".input") else "output"
+        mock_context_manager._span.update.assert_called_once_with(**{field: expected})
+
+    def test_set_content_tag_tool_result_with_image_and_file(self):
+        mock_context_manager = MockContextManager(span=Mock(spec=LangfuseGeneration))
+        span = LangfuseSpan(mock_context_manager)
+        png = base64.b64encode(b"\x89PNG\r\n\x1a\n").decode()
+        pdf = base64.b64encode(b"%PDF-1.4").decode()
+        tool_message = ChatMessage.from_tool(
+            tool_result=[
+                TextContent("chart"),
+                ImageContent(base64_image=png, mime_type="image/png"),
+                FileContent(base64_data=pdf, mime_type="application/pdf", filename="report.pdf"),
+            ],
+            origin=ToolCall(tool_name="plot", arguments={}, id="call_1"),
+        )
+
+        with patch("haystack_integrations.tracing.langfuse.tracer.proxy_tracer.is_content_tracing_enabled", True):
+            span.set_content_tag("haystack.agent.step.llm.input", {"messages": [tool_message]})
+
+        mock_context_manager._span.update.assert_called_once_with(
+            input=[
+                {
+                    "role": "tool",
+                    "content": [
+                        {"type": "text", "text": "chart"},
+                        {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{png}"}},
+                        {
+                            "type": "file",
+                            "file": {"file_data": f"data:application/pdf;base64,{pdf}", "filename": "report.pdf"},
+                        },
+                    ],
+                    "tool_call_id": "call_1",
+                }
+            ]
+        )
+
+    def test_set_content_tag_tool_output_with_image(self):
+        mock_context_manager = MockContextManager(span=Mock(spec=LangfuseTool))
+        span = LangfuseSpan(mock_context_manager)
+        png = base64.b64encode(b"\x89PNG\r\n\x1a\n").decode()
+
+        with patch("haystack_integrations.tracing.langfuse.tracer.proxy_tracer.is_content_tracing_enabled", True):
+            span.set_content_tag(
+                "haystack.agent.step.tool.output",
+                [TextContent("chart"), ImageContent(base64_image=png, mime_type="image/png")],
+            )
+
+        mock_context_manager._span.update.assert_called_once_with(
+            output=[
+                {"type": "text", "text": "chart"},
+                {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{png}"}},
+            ]
+        )
+
+    def test_set_content_tag_messages_without_openai_format_are_coerced(self):
+        mock_context_manager = MockContextManager(span=Mock(spec=LangfuseGeneration))
+        span = LangfuseSpan(mock_context_manager)
+        # A user message without content has no OpenAI format
+        messages = [ChatMessage.from_user("hi"), ChatMessage(_role=ChatRole.USER, _content=[])]
+
+        with patch("haystack_integrations.tracing.langfuse.tracer.proxy_tracer.is_content_tracing_enabled", True):
+            span.set_content_tag("haystack.agent.step.llm.input", {"messages": messages})
+
+        mock_context_manager._span.update.assert_called_once_with(input=tracing_utils.coerce_tag_value(messages))
+
 
 class TestSpanContext:
     def test_post_init(self):
@@ -344,6 +467,48 @@ class TestDefaultSpanHandler:
             ),
         }
 
+    def test_handle_agent_step_llm(self):
+        mock_span = Mock()
+        mock_span.raw_span.return_value = mock_span
+        mock_span.get_data.return_value = {
+            "haystack.agent.step.llm.output": {
+                "replies": [
+                    ChatMessage.from_assistant(
+                        "This the LLM's response",
+                        meta={"model": "test_model", "usage": {"prompt_tokens": 10, "completion_tokens": 5}},
+                    )
+                ]
+            },
+        }
+
+        handler = DefaultSpanHandler()
+        handler.handle(mock_span, component_type=None)
+
+        mock_span.update.assert_called_once_with(
+            usage_details={"input_tokens": 10, "output_tokens": 5}, model="test_model", completion_start_time=None
+        )
+
+    def test_handle_agent_step_llm_model_parameters(self):
+        mock_span = Mock()
+        mock_span.raw_span.return_value = mock_span
+        mock_span.get_data.return_value = {
+            "haystack.agent.step.llm.input": {
+                "messages": [ChatMessage.from_user("message")],
+                "generation_kwargs": {"temperature": 0.2, "response_format": {"type": "json_object"}},
+            },
+            "haystack.agent.step.llm.output": {"replies": [ChatMessage.from_assistant("reply")]},
+        }
+
+        handler = DefaultSpanHandler()
+        handler.handle(mock_span, component_type=None)
+
+        mock_span.update.assert_called_once_with(
+            usage_details=None,
+            model=None,
+            completion_start_time=None,
+            model_parameters={"temperature": 0.2, "response_format": '{"type": "json_object"}'},
+        )
+
     def test_handle_bad_completion_start_time(self, caplog):
         mock_span = Mock()
         mock_span.raw_span.return_value = mock_span
@@ -463,6 +628,33 @@ class TestDefaultSpanHandler:
             name="SentenceTransformersDocumentEmbedder", as_type="embedding"
         )
 
+    @pytest.mark.parametrize(
+        "operation_name,tags,expected_name,expected_type",
+        [
+            ("haystack.agent.step", {"haystack.agent.step": 1}, "agent step 1", "chain"),
+            ("haystack.agent.step.llm", {}, "llm", "generation"),
+            ("haystack.agent.step.tool", {"haystack.tool.name": "weather_tool"}, "tool - weather_tool", "tool"),
+        ],
+    )
+    def test_create_span_agent_operations(self, operation_name, tags, expected_name, expected_type):
+        mock_client = Mock()
+        mock_client.start_as_current_observation = Mock(return_value=MockContextManager())
+
+        handler = DefaultSpanHandler()
+        handler.init_tracer(mock_client)
+
+        context = SpanContext(
+            name=operation_name,
+            operation_name=operation_name,
+            component_type=None,
+            tags=tags,
+            parent_span=LangfuseSpan(mock_client.start_as_current_observation()),
+        )
+        mock_client.start_as_current_observation.reset_mock()
+
+        handler.create_span(context)
+        mock_client.start_as_current_observation.assert_called_once_with(name=expected_name, as_type=expected_type)
+
     def test_create_span_non_component(self):
         """Test that non-matching components create default span type."""
         mock_client = Mock()
@@ -698,129 +890,6 @@ class TestLangfuseTracer:
             assert span.raw_span()._data["model"] == "test_model"
             assert span.raw_span()._data["completion_start_time"] == datetime.datetime(2021, 7, 27, 16, 2, 8, 12345)  # noqa: DTZ001
 
-    def test_handle_tool_invoker(self):
-        """
-        Test that the ToolInvoker span name is updated correctly with the tool names invoked for better UI/UX
-        """
-        mock_span = Mock()
-        mock_span.raw_span.return_value = mock_span
-
-        # Simulate data for the ToolInvoker component
-        span_data = {
-            "haystack.component.name": "tool_invoker",
-            "haystack.component.type": "ToolInvoker",
-            "haystack.component.input": {
-                "messages": [
-                    # Create a chat message with tool calls
-                    ChatMessage.from_assistant(
-                        text="Calling tools",
-                        tool_calls=[
-                            ToolCall(tool_name="search_tool", arguments={"query": "test"}),
-                            ToolCall(tool_name="search_tool", arguments={"query": "another test"}),
-                            ToolCall(tool_name="weather_tool", arguments={"location": "Berlin"}),
-                        ],
-                    )
-                ]
-            },
-        }
-
-        mock_span.get_data.return_value = span_data
-
-        handler = DefaultSpanHandler()
-        handler.handle(mock_span, component_type="ToolInvoker")
-
-        assert mock_span.update.call_count >= 1
-        name_update_call = None
-        for call in mock_span.update.call_args_list:
-            if "name" in call[1]:
-                name_update_call = call
-                break
-
-        assert name_update_call is not None, "No call to update the span name was made"
-        updated_name = name_update_call[1]["name"]
-
-        # verify the format of the updated span name to be: `original_component_name - [list_of_tool_names]`
-        assert updated_name != "tool_invoker", "Expected 'tool_invoker` to be upddated with tool names"
-        assert " - " in updated_name, f"Expected ' - ' in {updated_name}"
-        assert "[" in updated_name, f"Expected '[' in {updated_name}"
-        assert "]" in updated_name, f"Expected ']' in {updated_name}"
-        assert "tool_invoker" in updated_name, f"Expected 'tool_invoker' in {updated_name}"
-        assert "search_tool (x2)" in updated_name, f"Expected 'search_tool (x2)' in {updated_name}"
-        assert "weather_tool" in updated_name, f"Expected 'weather_tool' in {updated_name}"
-
-    def test_handle_tool_invoker_input_output_with_content_tracing(self):
-        """
-        Test that ToolInvoker spans replace the noisy full-message input with just tool call
-        arguments, and populate output with tool results, when content tracing is enabled.
-        """
-        mock_span = Mock()
-        mock_span.raw_span.return_value = mock_span
-
-        tool_call = ToolCall(id="call_123", tool_name="search_tool", arguments={"query": "RAG pipelines"})
-
-        span_data = {
-            "haystack.component.name": "tool_invoker",
-            "haystack.component.type": "ToolInvoker",
-            "haystack.component.input": {
-                "messages": [
-                    ChatMessage.from_user("what is RAG?"),
-                    ChatMessage.from_assistant(text="Calling search", tool_calls=[tool_call]),
-                ]
-            },
-            "haystack.component.output": {
-                "tool_messages": [ChatMessage.from_tool("RAG stands for Retrieval-Augmented Generation", tool_call)]
-            },
-        }
-        mock_span.get_data.return_value = span_data
-
-        handler = DefaultSpanHandler()
-        with patch("haystack_integrations.tracing.langfuse.tracer.proxy_tracer.is_content_tracing_enabled", True):
-            handler.handle(mock_span, component_type="ToolInvoker")
-
-        update_calls = {k: v for call in mock_span.update.call_args_list for k, v in call[1].items()}
-
-        # input should be just the tool call arguments, not the full message list
-        assert update_calls["input"] == [{"tool_name": "search_tool", "arguments": {"query": "RAG pipelines"}}]
-        # output carries id/name/arguments so Langfuse detects the tool call and populates its filter
-        assert update_calls["output"] == [
-            {
-                "id": "call_123",
-                "name": "search_tool",
-                "arguments": {"query": "RAG pipelines"},
-                "result": "RAG stands for Retrieval-Augmented Generation",
-                "error": False,
-            }
-        ]
-
-    def test_handle_tool_invoker_no_content_tracing(self):
-        """
-        Test that ToolInvoker input/output is NOT updated when content tracing is disabled.
-        The span name update (tool names) should still happen.
-        """
-        mock_span = Mock()
-        mock_span.raw_span.return_value = mock_span
-
-        tool_call = ToolCall(tool_name="weather_tool", arguments={"location": "Tokyo"})
-
-        span_data = {
-            "haystack.component.name": "tool_invoker",
-            "haystack.component.type": "ToolInvoker",
-            "haystack.component.input": {"messages": [ChatMessage.from_assistant(text="", tool_calls=[tool_call])]},
-            "haystack.component.output": {"tool_messages": [ChatMessage.from_tool("Sunny, 28°C", tool_call)]},
-        }
-        mock_span.get_data.return_value = span_data
-
-        handler = DefaultSpanHandler()
-        with patch("haystack_integrations.tracing.langfuse.tracer.proxy_tracer.is_content_tracing_enabled", False):
-            handler.handle(mock_span, component_type="ToolInvoker")
-
-        update_kwargs_keys = {k for call in mock_span.update.call_args_list for k in call[1]}
-        # name should still be updated
-        assert "name" in update_kwargs_keys
-        # input and output must NOT be set when content tracing is off
-        assert "input" not in update_kwargs_keys
-        assert "output" not in update_kwargs_keys
-
     def test_trace_generation_invalid_start_time(self):
         with patch("haystack_integrations.tracing.langfuse.tracer.langfuse.get_client"):
             tracer = LangfuseTracer(tracer=MockLangfuseClient(), name="Haystack", public=False)