ai-agents 0.11.0 → 0.13.0

data/lib/agents/helpers/message_extractor.rb

@@ -76,20 +76,21 @@ module Agents
       end
 
       def extract_user_or_assistant_message(msg, current_agent)
-        content_present = message_content?(msg)
         tool_calls_present = assistant_tool_calls?(msg)
-        return nil unless content_present || tool_calls_present
+        return nil unless extractable_message?(msg, tool_calls_present)
 
-        message = {
-          role: msg.role,
-          content: content_present ? msg.content : ""
-        }
+        message = { role: msg.role, content: persisted_content(msg) }
 
         return message unless msg.role == :assistant
 
         attributed_agent_name = attributed_agent_name_for(msg) || current_agent&.name
         message[:agent_name] = attributed_agent_name if attributed_agent_name
 
+        if msg.respond_to?(:thinking) && msg.thinking&.signature
+          message[:thinking] = msg.thinking.text if msg.thinking.text
+          message[:thinking_signature] = msg.thinking.signature
+        end
+
         if tool_calls_present
           # RubyLLM stores tool_calls as Hash with call_id => ToolCall object
           # Reference: RubyLLM::StreamAccumulator#tool_calls_from_stream
@@ -99,6 +100,21 @@ module Agents
         message
       end
 
+      def persisted_content(msg)
+        content = message_content?(msg) ? msg.content : ""
+        return content if msg.attachments.empty?
+
+        parts = content.to_s.empty? ? [] : [{ type: "text", text: content }]
+        parts + msg.attachments.map do |attachment|
+          { type: "image_url", image_url: { url: attachment.source.to_s } }
+        end
+      end
+
+      def extractable_message?(msg, tool_calls_present)
+        message_content?(msg) || tool_calls_present || msg.attachments.any? ||
+          (msg.role == :assistant && msg.respond_to?(:thinking) && msg.thinking&.signature)
+      end
+
       def message_content?(msg)
         msg.content && !content_empty?(msg.content)
       end
@@ -117,8 +133,8 @@ module Agents
         }
       end
 
-      private_class_method :extract_user_or_assistant_message, :message_content?, :assistant_tool_calls?,
-                           :extract_tool_message
+      private_class_method :extract_user_or_assistant_message, :persisted_content, :extractable_message?,
+                           :message_content?, :assistant_tool_calls?, :extract_tool_message
     end
   end
 end

data/lib/agents/instrumentation/constants.rb

@@ -15,21 +15,27 @@ module Agents
 
       # GenAI semantic conventions (ONLY on generation spans)
       ATTR_GEN_AI_REQUEST_MODEL = "gen_ai.request.model"
+      ATTR_GEN_AI_REQUEST_TEMPERATURE = "gen_ai.request.temperature"
       ATTR_GEN_AI_PROVIDER      = "gen_ai.provider.name"
       ATTR_GEN_AI_USAGE_INPUT   = "gen_ai.usage.input_tokens"
       ATTR_GEN_AI_USAGE_OUTPUT  = "gen_ai.usage.output_tokens"
+      ATTR_GEN_AI_USAGE_REASONING_OUTPUT = "gen_ai.usage.reasoning.output_tokens"
 
       # Langfuse trace-level attributes
       ATTR_LANGFUSE_USER_ID     = "langfuse.user.id"
       ATTR_LANGFUSE_SESSION_ID  = "langfuse.session.id"
+      ATTR_LANGFUSE_PREFIX      = "langfuse."
       ATTR_LANGFUSE_TRACE_TAGS  = "langfuse.trace.tags"
       ATTR_LANGFUSE_TRACE_INPUT = "langfuse.trace.input"
       ATTR_LANGFUSE_TRACE_OUTPUT = "langfuse.trace.output"
+      ATTR_LANGFUSE_TRACE_METADATA_PREFIX = "langfuse.trace.metadata."
 
       # Langfuse observation-level attributes
       ATTR_LANGFUSE_OBS_TYPE   = "langfuse.observation.type"
       ATTR_LANGFUSE_OBS_INPUT  = "langfuse.observation.input"
       ATTR_LANGFUSE_OBS_OUTPUT = "langfuse.observation.output"
+      ATTR_LANGFUSE_OBS_METADATA_PREFIX = "langfuse.observation.metadata."
+      ATTR_LANGFUSE_REASONING_SUMMARY = "langfuse.observation.metadata.reasoning_summary"
     end
   end
 end

data/lib/agents/instrumentation/tracing_callbacks.rb

@@ -18,6 +18,15 @@ module Agents
     class TracingCallbacks
       include Constants
 
+      CHILD_LANGFUSE_EXCLUDED_ATTRIBUTES = [
+        ATTR_LANGFUSE_TRACE_INPUT,
+        ATTR_LANGFUSE_TRACE_OUTPUT,
+        ATTR_LANGFUSE_OBS_INPUT,
+        ATTR_LANGFUSE_OBS_OUTPUT,
+        ATTR_LANGFUSE_OBS_TYPE
+      ].freeze
+      private_constant :CHILD_LANGFUSE_EXCLUDED_ATTRIBUTES
+
       def initialize(tracer:, trace_name: SPAN_RUN, span_attributes: {}, attribute_provider: nil)
         @tracer = tracer
         @trace_name = trace_name
@@ -31,6 +40,7 @@ module Agents
 
       def on_run_start(agent_name, input, context_wrapper)
         attributes = build_root_attributes(agent_name, input, context_wrapper)
+        child_attributes = build_child_langfuse_attributes(attributes)
 
         root_span = @tracer.start_span(@trace_name, attributes: attributes)
         root_context = OpenTelemetry::Trace.context_with_span(root_span)
@@ -38,6 +48,7 @@ module Agents
         store_tracing_state(context_wrapper,
                             root_span: root_span,
                             root_context: root_context,
+                            child_langfuse_attributes: child_attributes,
                             current_tool_span: nil,
                             current_agent_name: nil,
                             current_agent_span: nil,
@@ -49,6 +60,8 @@ module Agents
         return unless tracing
 
         tracing[:pending_llm_input] = serialize_output(input)
+        # The response hook runs after the provider call; preserve its real start time.
+        tracing[:llm_started_at] = Time.now
 
         return if tracing[:current_agent_name] == agent_name
 
@@ -66,12 +79,18 @@ module Agents
         finish_agent_span(tracing)
       end
 
-      def on_chat_created(chat, agent_name, model, context_wrapper)
+      def on_chat_created(chat, _agent_name, model, context_wrapper, temperature = nil, protocol = nil, thinking = nil)
         tracing = tracing_state(context_wrapper)
         return unless tracing
 
-        chat.on_end_message do |message|
-          handle_end_message(chat, agent_name, model, message, context_wrapper)
+        tracing[:request_attributes] = { model: model, temperature: temperature,
+                                         protocol: protocol, thinking: thinking }
+        return if tracing[:instrumented_chat].equal?(chat)
+
+        tracing[:instrumented_chat] = chat
+
+        chat.after_message do |message|
+          handle_end_message(chat, message, context_wrapper)
         end
       end
 
@@ -84,6 +103,7 @@ module Agents
           ATTR_LANGFUSE_OBS_TYPE => "tool",
           ATTR_LANGFUSE_OBS_INPUT => serialize_output(args)
         }
+        attributes.merge!(tracing[:child_langfuse_attributes])
 
         parent = handoff_tool?(tool_name) ? tracing[:root_context] : parent_context(tracing)
         tool_span = @tracer.start_span(
@@ -95,7 +115,7 @@ module Agents
         tracing[:current_tool_span] = tool_span
       end
 
-      def on_tool_complete(_tool_name, result, context_wrapper)
+      def on_tool_complete(_tool_name, result, context_wrapper, error = nil)
         tracing = tracing_state(context_wrapper)
         return unless tracing
 
@@ -103,6 +123,10 @@ module Agents
         return unless tool_span
 
         tool_span.set_attribute(ATTR_LANGFUSE_OBS_OUTPUT, serialize_output(result))
+        if error
+          tool_span.record_exception(error)
+          tool_span.status = OpenTelemetry::Trace::Status.error(error.message)
+        end
         tool_span.finish
         tracing[:current_tool_span] = nil
       end
@@ -139,26 +163,44 @@ module Agents
 
       private
 
-      def handle_end_message(chat, _agent_name, model, message, context_wrapper)
+      def handle_end_message(chat, message, context_wrapper)
         return unless message.respond_to?(:role) && message.role == :assistant
 
         tracing = tracing_state(context_wrapper)
         return unless tracing
 
-        input = format_chat_messages(chat)
-        attrs = {}
-        attrs[ATTR_LANGFUSE_OBS_INPUT] = input if input
-        llm_span = @tracer.start_span(@llm_span_name, with_parent: parent_context(tracing), attributes: attrs)
+        llm_span = @tracer.start_span(
+          @llm_span_name,
+          with_parent: parent_context(tracing),
+          start_timestamp: tracing.delete(:llm_started_at),
+          attributes: generation_span_attributes(tracing, chat, message, context_wrapper)
+        )
 
-        llm_span.set_attribute(ATTR_GEN_AI_REQUEST_MODEL, model) if model
+        set_llm_request_attributes(llm_span, tracing[:request_attributes])
 
         output = llm_output_text(message)
-        set_llm_response_attributes(llm_span, message, output)
+        set_llm_response_attributes(llm_span, message, output, tracing[:request_attributes])
         tracing[:last_agent_output] = output unless output.empty?
 
         llm_span.finish
       end
 
+      def generation_span_attributes(tracing, chat, message, context_wrapper)
+        attrs = tracing[:child_langfuse_attributes].dup
+        input = format_chat_messages(chat)
+        attrs[ATTR_LANGFUSE_OBS_INPUT] = input if input
+        apply_generation_dynamic_attributes(attrs, context_wrapper, chat, message)
+        attrs
+      end
+
+      def set_llm_request_attributes(span, request_attributes)
+        model = request_attributes[:model]
+        temperature = request_attributes[:temperature]
+
+        span.set_attribute(ATTR_GEN_AI_REQUEST_MODEL, model) if model
+        span.set_attribute(ATTR_GEN_AI_REQUEST_TEMPERATURE, temperature) unless temperature.nil?
+      end
+
       def finish_dangling_spans(tracing)
         if tracing[:current_tool_span]
           tracing[:current_tool_span].finish
@@ -187,16 +229,23 @@ module Agents
         root_span.status = OpenTelemetry::Trace::Status.error(error.message)
       end
 
-      def set_llm_response_attributes(span, response, output)
-        if response.respond_to?(:input_tokens) && response.input_tokens
-          span.set_attribute(ATTR_GEN_AI_USAGE_INPUT, response.input_tokens)
-        end
-        if response.respond_to?(:output_tokens) && response.output_tokens
-          span.set_attribute(ATTR_GEN_AI_USAGE_OUTPUT, response.output_tokens)
-        end
+      def set_llm_response_attributes(span, response, output, request_attributes)
+        tokens = response.tokens if response.respond_to?(:tokens)
+        span.set_attribute(ATTR_GEN_AI_USAGE_INPUT, tokens.input) if tokens&.input
+        span.set_attribute(ATTR_GEN_AI_USAGE_OUTPUT, tokens.output) if tokens&.output
+        span.set_attribute(ATTR_GEN_AI_USAGE_REASONING_OUTPUT, tokens.thinking) if tokens&.thinking
+        set_reasoning_summary(span, response, request_attributes)
         span.set_attribute(ATTR_LANGFUSE_OBS_OUTPUT, output) unless output.empty?
       end
 
+      def set_reasoning_summary(span, response, request_attributes)
+        return unless request_attributes[:protocol] == :responses
+        return unless request_attributes.dig(:thinking, :display).to_s == "summarized"
+        return unless response.respond_to?(:thinking) && response.thinking&.text
+
+        span.set_attribute(ATTR_LANGFUSE_REASONING_SUMMARY, response.thinking.text)
+      end
+
       # Returns serialized text content if present, otherwise falls back to tool call formatting.
       # Uses .to_json for Hash/Array (structured output) to avoid Ruby's .to_s format.
       def llm_output_text(response)
@@ -221,6 +270,7 @@ module Agents
       def format_single_message(msg)
         text = serialize_output(msg.content)
         text = append_tool_calls(msg, text)
+        text = append_attachment_summary(text, msg.attachments) if msg.respond_to?(:attachments)
         { role: msg.role.to_s, content: text }
       end
 
@@ -234,7 +284,16 @@ module Agents
       def serialize_output(value)
         return serialize_multimodal_content(value) if multimodal_content?(value)
 
-        value.is_a?(Hash) || value.is_a?(Array) ? value.to_json : value.to_s
+        return value.map { |part| redact_image_source(part) }.to_json if value.is_a?(Array)
+
+        value.is_a?(Hash) ? redact_image_source(value).to_json : value.to_s
+      end
+
+      def redact_image_source(part)
+        return part unless part.is_a?(Hash) && (part[:type] || part["type"]) == "image_url"
+
+        key = part.key?(:image_url) ? :image_url : "image_url"
+        part.merge(key => "[image]")
       end
 
       def format_tool_calls(response)
@@ -250,13 +309,9 @@ module Agents
         finish_agent_span(tracing) # close previous agent span if missed
 
         span_name = format(@agent_span_name, agent_name)
-        attrs = { "agent.name" => agent_name }
-        input = tracing[:pending_llm_input]
-        attrs[ATTR_LANGFUSE_OBS_INPUT] = input if input && !input.empty?
-
         agent_span = @tracer.start_span(span_name,
                                         with_parent: tracing[:root_context],
-                                        attributes: attrs)
+                                        attributes: agent_span_attributes(tracing, agent_name))
         agent_context = OpenTelemetry::Trace.context_with_span(agent_span)
 
         tracing[:current_agent_name] = agent_name
@@ -265,6 +320,13 @@ module Agents
         tracing[:last_agent_output] = nil
       end
 
+      def agent_span_attributes(tracing, agent_name)
+        attrs = tracing[:child_langfuse_attributes].merge("agent.name" => agent_name)
+        input = tracing[:pending_llm_input]
+        attrs[ATTR_LANGFUSE_OBS_INPUT] = input if input && !input.empty?
+        attrs
+      end
+
       def finish_agent_span(tracing)
         return unless tracing[:current_agent_span]
 
@@ -297,6 +359,57 @@ module Agents
         attributes
       end
 
+      def build_child_langfuse_attributes(root_attributes)
+        root_attributes.each_with_object({}) do |(key, value), attrs|
+          next if value.nil?
+          next unless child_langfuse_attribute?(key)
+
+          attrs[key] = value
+          add_observation_metadata_mirror(attrs, key, value) if mirrored_observation_metadata_attribute?(key)
+        end
+      end
+
+      def child_langfuse_attribute?(key)
+        key.start_with?(ATTR_LANGFUSE_PREFIX) && !child_langfuse_excluded_attribute?(key)
+      end
+
+      def child_langfuse_excluded_attribute?(key)
+        CHILD_LANGFUSE_EXCLUDED_ATTRIBUTES.include?(key)
+      end
+
+      def mirrored_observation_metadata_attribute?(key)
+        key == ATTR_LANGFUSE_USER_ID ||
+          key == ATTR_LANGFUSE_SESSION_ID ||
+          key == ATTR_LANGFUSE_TRACE_TAGS ||
+          key.start_with?(ATTR_LANGFUSE_TRACE_METADATA_PREFIX)
+      end
+
+      def add_observation_metadata_mirror(attrs, key, value)
+        metadata_key = observation_metadata_mirror_key(key)
+        attrs[observation_metadata_key(metadata_key)] = serialize_metadata_value(value)
+      end
+
+      def observation_metadata_mirror_key(key)
+        case key
+        when ATTR_LANGFUSE_USER_ID
+          "user_id"
+        when ATTR_LANGFUSE_SESSION_ID
+          "session_id"
+        when ATTR_LANGFUSE_TRACE_TAGS
+          "trace_tags"
+        else
+          key.delete_prefix(ATTR_LANGFUSE_TRACE_METADATA_PREFIX)
+        end
+      end
+
+      def observation_metadata_key(key)
+        "#{ATTR_LANGFUSE_OBS_METADATA_PREFIX}#{key}"
+      end
+
+      def serialize_metadata_value(value)
+        value.is_a?(Hash) || value.is_a?(Array) ? value.to_json : value.to_s
+      end
+
       def apply_session_id(attributes, context_wrapper)
         session_id = context_wrapper&.context&.dig(:session_id)&.to_s
         attributes[ATTR_LANGFUSE_SESSION_ID] = session_id if session_id && !session_id.empty?
@@ -317,6 +430,13 @@ module Agents
         attributes.merge!(dynamic_attrs) if dynamic_attrs.is_a?(Hash)
       end
 
+      def apply_generation_dynamic_attributes(attributes, context_wrapper, chat, message)
+        return unless @attribute_provider.respond_to?(:generation_attributes)
+
+        dynamic_attrs = @attribute_provider.generation_attributes(context_wrapper, chat, message)
+        attributes.merge!(dynamic_attrs) if dynamic_attrs.is_a?(Hash)
+      end
+
       def store_tracing_state(context_wrapper, **state)
         context_wrapper.context[:__otel_tracing] = state
       end
@@ -334,16 +454,17 @@ module Agents
       end
 
       def serialize_multimodal_content(content)
-        parts = []
-        text = content.text
-        parts << text if text && !text.empty?
+        append_attachment_summary(content.text.to_s, content.attachments)
+      end
 
-        if content.attachments&.any?
-          urls = content.attachments.map { |a| a.respond_to?(:source) ? a.source.to_s : a.to_s }
-          parts << "Attachments: #{urls.join(", ")}"
-        end
+      def append_attachment_summary(text, attachments)
+        return text unless attachments&.any?
 
-        parts.join("\n")
+        types = attachments.map do |attachment|
+          type = attachment.mime_type if attachment.respond_to?(:mime_type)
+          type.to_s.empty? ? "file" : type
+        end
+        [text, "Attachments: #{types.join(", ")}"].reject(&:empty?).join("\n")
       end
     end
   end

data/lib/agents/instrumentation.rb

@@ -34,6 +34,22 @@ module Agents
   #       { 'langfuse.user.id' => ctx.context[:account_id].to_s }
   #     }
   #   )
+  #
+  # @example With custom generation attributes
+  #   class MyAttributeProvider
+  #     def call(ctx)
+  #       { 'langfuse.user.id' => ctx.context[:account_id].to_s }
+  #     end
+  #
+  #     def generation_attributes(_ctx, _chat, message)
+  #       { 'app.generation.has_tool_calls' => message.tool_calls&.any? }
+  #     end
+  #   end
+  #
+  #   Agents::Instrumentation.install(runner,
+  #     tracer: tracer,
+  #     attribute_provider: MyAttributeProvider.new
+  #   )
   module Instrumentation
     INSTALL_MUTEX = Mutex.new
     private_constant :INSTALL_MUTEX
@@ -52,7 +68,9 @@ module Agents
     # @param tracer [OpenTelemetry::Trace::Tracer] OTel tracer instance
     # @param trace_name [String] Name for the root span (default: "agents.run")
     # @param span_attributes [Hash] Static attributes applied to the root span
-    # @param attribute_provider [Proc, nil] Lambda receiving context_wrapper, returning dynamic attributes
+    # @param attribute_provider [#call, nil] Object receiving context_wrapper and returning dynamic root attributes.
+    #   If it also responds to #generation_attributes, that method receives context_wrapper, chat, and message,
+    #   and can return dynamic attributes for generation spans.
     # @return [Agents::AgentRunner, nil] The runner (for chaining), or nil if OTel is unavailable
     def self.install(runner, tracer:, trace_name: Constants::SPAN_RUN, span_attributes: {},
                      attribute_provider: nil)

data/lib/agents/run_context.rb

@@ -95,16 +95,17 @@ module Agents
 
       # Add usage metrics from an LLM response to the running totals.
       # Only tracks usage for responses that have token data (e.g., RubyLLM::Message).
-      # Safely skips responses without token methods (e.g., RubyLLM::Tool::Halt).
+      # Safely skips values without token usage.
       #
       # @param response [RubyLLM::Message] A RubyLLM::Message object with token usage data
       # @example Adding usage from an LLM response
       #   usage.add(llm_response)
       def add(response)
-        return unless response.respond_to?(:input_tokens)
+        tokens = response.tokens if response.respond_to?(:tokens)
+        return unless tokens
 
-        input = response.input_tokens || 0
-        output = response.output_tokens || 0
+        input = tokens.input || 0
+        output = tokens.output || 0
 
         @input_tokens += input
         @output_tokens += output