ai-agents 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '071869beb00d53446a27f489c3817c58b0f8d163f334f0030c95b789a7c4895b'
-  data.tar.gz: 874227bd4dd05dd2947269bec7da2d593777a8600540ef9ec5a8fb50c346a884
+  metadata.gz: 7948199bfccd3d11e42735b9ee9f34a2431d00de5876785fa26e369a128a686c
+  data.tar.gz: 7a5a91260825a6c2fc59192dee83e8e050a1260fef3d6a0589a9d1dbd0fbc0fe
 SHA512:
-  metadata.gz: 7e3814e0e76359be595534eb92ce11d655e19e3997f78aea006be89721aae771c6a1f97ad277ed80581957cdea5a0919506518dfd8e8de1911a03a3641668a8b
-  data.tar.gz: 351b99abda0942df5253e1735faca522b5eee988fc248ec16564dea700b2bcfcf31a8ec4ba8f9db73f3f57103e5f8b37a0997c6e71f4b1a1872ca796046cad2a
+  metadata.gz: d314e6d427f6c9ac5d38ea39b77191c8535e5d0e400690afb15cff48588b7e969b7cb30e88d12e78c027175cdc497e92a74feb899b99f50416af006e3edabe79
+  data.tar.gz: 67b9da18847cddfae2b7866f606d335b51690aeb13c9062b8ae2afa8526ed9ae3343fbf86dd435354ee42b6d3145cefcac3e090ee5ca170895cbfc84f3b510b0

data/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-06-29
+
+### Added
+- Propagate Langfuse trace metadata and filter attributes from root traces to child agent, tool, and generation spans, while keeping span-specific input/output attributes local to each span.
+- Support optional generation-level attributes via `attribute_provider#generation_attributes(context_wrapper, chat, message)`.
+- Add `gen_ai.request.temperature` to generation spans when an agent temperature is configured.
+
 ## [0.11.0] - 2026-05-27
 
 ### Added

data/lib/agents/instrumentation/constants.rb

@@ -15,6 +15,7 @@ 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"
@@ -22,14 +23,17 @@ module Agents
       # 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."
     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,
@@ -66,12 +77,14 @@ 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)
         tracing = tracing_state(context_wrapper)
         return unless tracing
 
+        request_attributes = { model: model, temperature: temperature }
+
         chat.on_end_message do |message|
-          handle_end_message(chat, agent_name, model, message, context_wrapper)
+          handle_end_message(chat, agent_name, request_attributes, message, context_wrapper)
         end
       end
 
@@ -84,6 +97,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(
@@ -139,18 +153,19 @@ module Agents
 
       private
 
-      def handle_end_message(chat, _agent_name, model, message, context_wrapper)
+      def handle_end_message(chat, _agent_name, request_attributes, 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),
+          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, request_attributes)
 
         output = llm_output_text(message)
         set_llm_response_attributes(llm_span, message, output)
@@ -159,6 +174,22 @@ module Agents
         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
@@ -250,13 +281,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 +292,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 +331,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 +402,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

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/runner.rb

@@ -115,7 +115,9 @@ module Agents
       configure_chat_for_agent(chat, current_agent, context_wrapper, replace: false)
       restore_conversation_history(chat, context_wrapper)
       input_already_in_history = last_message_matches?(chat, input)
-      context_wrapper.callback_manager.emit_chat_created(chat, current_agent.name, current_agent.model, context_wrapper)
+      context_wrapper.callback_manager.emit_chat_created(
+        chat, current_agent.name, current_agent.model, context_wrapper, current_agent.temperature
+      )
 
       loop do
         current_turn += 1
@@ -178,7 +180,7 @@ module Agents
           current_params = Helpers::HashNormalizer.merge(agent_params, runtime_params)
           apply_params(chat, current_params)
           context_wrapper.callback_manager.emit_chat_created(
-            chat, current_agent.name, current_agent.model, context_wrapper
+            chat, current_agent.name, current_agent.model, context_wrapper, current_agent.temperature
           )
 
           # Force the new agent to respond to the conversation context

data/lib/agents/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Agents
-  VERSION = "0.11.0"
+  VERSION = "0.12.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ai-agents
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Shivam Mishra