ai-agents 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df386be7e27f87111901954d72e4caa3e26a1d789ec113fbf9e2da9d2f87587e
-  data.tar.gz: f05b6827852966d0514abae61c7732a34ea92aeebe30855132ec8bee39c1e4c2
+  metadata.gz: 6d4dc10b4aceae77705002488794ecdd15531f604641adaa03445d72374220f0
+  data.tar.gz: b056fcf690121a790808e6aa1229dc1a16b6e19b609fbaa09a5e32613f5bc58f
 SHA512:
-  metadata.gz: 2180b6b495519d34ff4762cd027d6079fb39ad91117242f6f366779fd7360c7bbb55521761e151ad246eee3004363de9bf768ca953a8e69a1e39e2f2dfeb5345
-  data.tar.gz: 41dadb09fd62a2ce47b063c6b85685f1efa8be73dbee467e83ad69cdb32793926aaadacbce7bfa820960c0d5f35e57325a7078733c19bef0e1121076bc6a9002
+  metadata.gz: b80b45ccaa92140f6155dceeb2227235150f913c90385197878074af9df0c22b913e611c46424f9efa9b3f8f128b8921795c3136685a889a758c4b8dd81f4dbd
+  data.tar.gz: 63662db9f1dcbed10439dfa64746a868a0ee2cc64266c48e55f613296e90dca0d1661466af01825bbec3015c928209f20f000bc9aeb882f5ff510be7ad7110f7

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+
+## [0.10.0] - 2026-04-20
+
+### Added
+- Support for provider-specific params via `with_params` (#44)
+
+### Changed
+- **Bump `ruby_llm` dependency**: now `~> 1.14` (was `~> 1.9.1`). Trusts upstream semantic versioning by dropping the PATCH-level pin so minor-version fixes are picked up automatically (#61)
+- Various internal refactors to `TracingCallbacks`, `Runner`, and helper modules
+
+
+## [0.9.1] - 2026-02-24
+
+### Fixed
+- **Multimodal Conversation History**: Restored multimodal image content from conversation history, ensuring image URLs and base64 data are preserved across agent turns (#46)
+- **Tracing Instrumentation**: Improved serialization of multimodal content in tracing callbacks, returning JSON for non-text content types
+
+### Changed
+- **Test Infrastructure**: OpenTelemetry stubs in tests are now conditionally applied only when the `opentelemetry-api` gem is not installed (#45)
+
 ## [0.9.0] - 2026-02-09
 
 ### Added

data/docs/guides/provider-params.md

@@ -0,0 +1,90 @@
+---
+layout: default
+title: Provider-Specific Parameters
+parent: Guides
+nav_order: 7
+---
+
+# Provider-Specific Parameters
+
+Provider-specific parameters let you pass additional options directly into the LLM request payload via RubyLLM's `with_params` method. This is useful for features like OpenAI's `service_tier`, Anthropic's `reasoning_effort`, or any other provider-specific option that isn't exposed as a first-class SDK attribute.
+
+## Basic Usage
+
+### Agent-Level Params
+
+Set default parameters when creating an agent that will be applied to all requests:
+
+```ruby
+agent = Agents::Agent.new(
+  name: "Assistant",
+  instructions: "You are a helpful assistant",
+  params: {
+    service_tier: "flex",
+    max_completion_tokens: 2048
+  }
+)
+
+runner = Agents::Runner.with_agents(agent)
+result = runner.run("Hello!")
+# All requests will include the provider-specific params
+```
+
+### Runtime Params
+
+Override or add parameters for specific requests:
+
+```ruby
+agent = Agents::Agent.new(
+  name: "Assistant",
+  instructions: "You are a helpful assistant"
+)
+
+runner = Agents::Runner.with_agents(agent)
+
+# Pass params at runtime
+result = runner.run(
+  "Explain quantum computing",
+  params: {
+    service_tier: "default",
+    max_completion_tokens: 4096
+  }
+)
+```
+
+### Parameter Precedence
+
+When both agent-level and runtime params are provided, **runtime params take precedence**:
+
+```ruby
+agent = Agents::Agent.new(
+  name: "Assistant",
+  instructions: "You are a helpful assistant",
+  params: {
+    service_tier: "flex",
+    top_p: 0.9
+  }
+)
+
+runner = Agents::Runner.with_agents(agent)
+
+result = runner.run(
+  "Hello!",
+  params: {
+    service_tier: "default",       # Overrides agent's flex value
+    max_completion_tokens: 1000    # Additional param
+  }
+)
+
+# Final params sent to LLM API:
+# {
+#   service_tier: "default",          # Runtime value wins
+#   top_p: 0.9,                       # From agent
+#   max_completion_tokens: 1000       # From runtime
+# }
+```
+
+## See Also
+
+- [Custom Request Headers](request-headers.html) - Adding custom HTTP headers using the same two-level precedence pattern
+- [Multi-Agent Systems](multi-agent-systems.html) - Using params across agent handoffs

data/docs/guides.md

@@ -18,4 +18,5 @@ Practical guides for building real-world applications with the AI Agents library
 - **[State Persistence](guides/state-persistence.html)** - Managing conversation state and context across sessions and processes
 - **[Structured Output](guides/structured-output.html)** - Enforcing JSON schema validation for reliable agent responses
 - **[Custom Request Headers](guides/request-headers.html)** - Adding custom HTTP headers for authentication, tracking, and provider-specific features
+- **[Provider-Specific Parameters](guides/provider-params.html)** - Passing provider-specific parameters like service_tier to the underlying LLM request
 - **[OpenTelemetry Instrumentation](guides/instrumentation.html)** - Trace agent execution with Langfuse and other OTel backends

data/lib/agents/agent.rb

@@ -4,7 +4,7 @@
 # Agents are immutable, thread-safe objects that can be cloned with modifications.
 # They encapsulate the configuration needed to interact with an LLM including
 # instructions, tools, and potential handoff targets.
-require_relative "helpers/headers"
+require_relative "helpers/hash_normalizer"
 # @example Creating a basic agent
 #   agent = Agents::Agent.new(
 #     name: "Assistant",
@@ -50,7 +50,7 @@ require_relative "helpers/headers"
 #   )
 module Agents
   class Agent
-    attr_reader :name, :instructions, :model, :tools, :handoff_agents, :temperature, :response_schema, :headers
+    attr_reader :name, :instructions, :model, :tools, :handoff_agents, :temperature, :response_schema, :headers, :params
 
     # Initialize a new Agent instance
     #
@@ -62,8 +62,9 @@ module Agents
     # @param temperature [Float] Controls randomness in responses (0.0 = deterministic, 1.0 = very random, default: 0.7)
     # @param response_schema [Hash, nil] JSON schema for structured output responses
     # @param headers [Hash, nil] Default HTTP headers applied to LLM requests
+    # @param params [Hash, nil] Default provider-specific parameters applied to LLM requests (e.g., service_tier)
     def initialize(name:, instructions: nil, model: "gpt-4.1-mini", tools: [], handoff_agents: [], temperature: 0.7,
-                   response_schema: nil, headers: nil)
+                   response_schema: nil, headers: nil, params: nil)
       @name = name
       @instructions = instructions
       @model = model
@@ -71,7 +72,8 @@ module Agents
       @handoff_agents = []
       @temperature = temperature
       @response_schema = response_schema
-      @headers = Helpers::Headers.normalize(headers, freeze_result: true)
+      @headers = Helpers::HashNormalizer.normalize(headers, label: "headers", freeze_result: true)
+      @params = Helpers::HashNormalizer.normalize(params, label: "params", freeze_result: true)
 
       # Mutex for thread-safe handoff registration
       # While agents are typically configured at startup, we want to ensure
@@ -167,7 +169,8 @@ module Agents
         handoff_agents: changes.fetch(:handoff_agents, @handoff_agents),
         temperature: changes.fetch(:temperature, @temperature),
         response_schema: changes.fetch(:response_schema, @response_schema),
-        headers: changes.fetch(:headers, @headers)
+        headers: changes.fetch(:headers, @headers),
+        params: changes.fetch(:params, @params)
       )
     end
 

data/lib/agents/agent_runner.rb

@@ -29,6 +29,8 @@ module Agents
   # can safely register callbacks concurrently without data races.
   #
   class AgentRunner
+    attr_reader :agents
+
     # Initialize with a list of agents. The first agent becomes the default entry point.
     #
     # @param agents [Array<Agents::Agent>] List of agents, first one is the default entry point
@@ -64,8 +66,9 @@ module Agents
     # @param context [Hash] Conversation context (will be restored if continuing conversation)
     # @param max_turns [Integer] Maximum turns before stopping (default: 10)
     # @param headers [Hash, nil] Custom HTTP headers to pass through to the underlying LLM provider
+    # @param params [Hash, nil] Provider-specific parameters to pass through to the underlying LLM (e.g., service_tier)
     # @return [RunResult] Execution result with output, messages, and updated context
-    def run(input, context: {}, max_turns: Runner::DEFAULT_MAX_TURNS, headers: nil)
+    def run(input, context: {}, max_turns: Runner::DEFAULT_MAX_TURNS, headers: nil, params: nil)
       # Determine which agent should handle this conversation
       # Uses conversation history to maintain continuity across handoffs
       current_agent = determine_conversation_agent(context)
@@ -78,6 +81,7 @@ module Agents
         registry: @registry,
         max_turns: max_turns,
         headers: headers,
+        params: params,
         callbacks: @callbacks
       )
     end

data/lib/agents/agent_tool.rb

@@ -97,7 +97,7 @@ module Agents
     private
 
     def transform_agent_name(name)
-      name.downcase.gsub(/\s+/, "_").gsub(/[^a-z0-9_]/, "")
+      Helpers::NameNormalizer.to_tool_name(name)
     end
 
     # Create isolated context that only shares state, not conversation artifacts

data/lib/agents/handoff.rb

@@ -53,7 +53,7 @@ module Agents
       @target_agent = target_agent
 
       # Set up the tool with a standardized name and description
-      @tool_name = "handoff_to_#{target_agent.name.downcase.gsub(/\s+/, "_")}"
+      @tool_name = "handoff_to_#{Helpers::NameNormalizer.to_tool_name(target_agent.name)}"
       @tool_description = "Transfer conversation to #{target_agent.name}"
 
       super()

data/lib/agents/helpers/hash_normalizer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Agents
+  module Helpers
+    module HashNormalizer
+      module_function
+
+      # NOTE: freeze_result performs a shallow freeze on the top-level hash only.
+      # Nested values remain mutable — e.g. hash[:nested][:key] = "x" would succeed.
+      def normalize(input, label:, freeze_result: false)
+        return freeze_result ? {}.freeze : {} if input.nil? || (input.respond_to?(:empty?) && input.empty?)
+
+        hash = input.respond_to?(:to_h) ? input.to_h : input
+        raise ArgumentError, "#{label} must be a Hash or respond to #to_h" unless hash.is_a?(Hash)
+
+        result = hash.transform_keys { |key| key.is_a?(Symbol) ? key : key.to_sym }
+        freeze_result ? result.freeze : result
+      end
+
+      def merge(base, override)
+        return override if base.empty?
+        return base if override.empty?
+
+        base.merge(override)
+      end
+    end
+  end
+end

data/lib/agents/helpers/name_normalizer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Agents
+  module Helpers
+    module NameNormalizer
+      module_function
+
+      def to_tool_name(name)
+        name.downcase.gsub(/\s+/, "_").gsub(/[^a-z0-9_]/, "")
+      end
+    end
+  end
+end

data/lib/agents/helpers.rb

@@ -5,5 +5,6 @@ module Agents
   end
 end
 
-require_relative "helpers/headers"
+require_relative "helpers/hash_normalizer"
+require_relative "helpers/name_normalizer"
 require_relative "helpers/message_extractor"

data/lib/agents/instrumentation/tracing_callbacks.rb

@@ -48,7 +48,7 @@ module Agents
         tracing = tracing_state(context_wrapper)
         return unless tracing
 
-        tracing[:pending_llm_input] = input.to_s
+        tracing[:pending_llm_input] = serialize_output(input)
 
         return if tracing[:current_agent_name] == agent_name
 
@@ -151,9 +151,9 @@ module Agents
         llm_span = @tracer.start_span(@llm_span_name, with_parent: parent_context(tracing), attributes: attrs)
 
         llm_span.set_attribute(ATTR_GEN_AI_REQUEST_MODEL, model) if model
-        set_llm_response_attributes(llm_span, message)
 
         output = llm_output_text(message)
+        set_llm_response_attributes(llm_span, message, output)
         tracing[:last_agent_output] = output unless output.empty?
 
         llm_span.finish
@@ -187,29 +187,25 @@ module Agents
         root_span.status = OpenTelemetry::Trace::Status.error(error.message)
       end
 
-      def set_llm_response_attributes(span, response)
+      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
-        output = llm_output_text(response)
         span.set_attribute(ATTR_LANGFUSE_OBS_OUTPUT, output) unless output.empty?
       end
 
-      # Falls back to formatting tool calls when response has no text content,
-      # and uses .to_json for Hash/Array (structured output) to avoid Ruby's .to_s format.
+      # 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)
-        return format_tool_calls(response) unless response.respond_to?(:content)
-
-        content = response.content
-        return format_tool_calls(response) if content.nil?
-
-        text = content.is_a?(Hash) || content.is_a?(Array) ? content.to_json : content.to_s
-        return format_tool_calls(response) if text.empty?
+        if response.respond_to?(:content) && response.content
+          text = serialize_output(response.content)
+          return text unless text.empty?
+        end
 
-        text
+        format_tool_calls(response)
       end
 
       # Excludes the last message (current response) — returns what was sent to the LLM.
@@ -223,23 +219,21 @@ module Agents
       end
 
       def format_single_message(msg)
-        text = serialize_content(msg.content)
+        text = serialize_output(msg.content)
         text = append_tool_calls(msg, text)
         { role: msg.role.to_s, content: text }
       end
 
-      def serialize_content(content)
-        content.is_a?(Hash) || content.is_a?(Array) ? content.to_json : content.to_s
-      end
-
       def append_tool_calls(msg, text)
         return text unless msg.role == :assistant && msg.respond_to?(:tool_calls) && msg.tool_calls&.any?
 
-        calls = msg.tool_calls.values.map { |tc| "#{tc.name}(#{tc.arguments.to_json})" }.join(", ")
+        calls = msg.tool_calls.values.map { |tc| "#{tc.name}(#{serialize_output(tc.arguments)})" }.join(", ")
         text.empty? ? "Tool calls: #{calls}" : "#{text}\nTool calls: #{calls}"
       end
 
       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
       end
 
@@ -334,6 +328,23 @@ module Agents
       def cleanup_tracing_state(context_wrapper)
         context_wrapper.context.delete(:__otel_tracing)
       end
+
+      def multimodal_content?(value)
+        value.respond_to?(:text) && value.respond_to?(:attachments)
+      end
+
+      def serialize_multimodal_content(content)
+        parts = []
+        text = content.text
+        parts << text if text && !text.empty?
+
+        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
+
+        parts.join("\n")
+      end
     end
   end
 end

data/lib/agents/runner.rb

@@ -81,9 +81,11 @@ module Agents
     # @param registry [Hash] Registry of agents for handoff resolution
     # @param max_turns [Integer] Maximum conversation turns before stopping
     # @param headers [Hash, nil] Custom HTTP headers passed to the underlying LLM provider
+    # @param params [Hash, nil] Provider-specific parameters passed to the underlying LLM (e.g., service_tier)
     # @param callbacks [Hash] Optional callbacks for real-time event notifications
     # @return [RunResult] The result containing output, messages, and usage
-    def run(starting_agent, input, context: {}, registry: {}, max_turns: DEFAULT_MAX_TURNS, headers: nil, callbacks: {})
+    def run(starting_agent, input, context: {}, registry: {}, max_turns: DEFAULT_MAX_TURNS, headers: nil, params: nil,
+            callbacks: {})
       # The starting_agent is already determined by AgentRunner based on conversation history
       current_agent = starting_agent
 
@@ -95,13 +97,17 @@ module Agents
       # Emit run start event
       context_wrapper.callback_manager.emit_run_start(current_agent.name, input, context_wrapper)
 
-      runtime_headers = Helpers::Headers.normalize(headers)
-      agent_headers = Helpers::Headers.normalize(current_agent.headers)
+      runtime_headers = Helpers::HashNormalizer.normalize(headers, label: "headers")
+      agent_headers = Helpers::HashNormalizer.normalize(current_agent.headers, label: "headers")
+      runtime_params = Helpers::HashNormalizer.normalize(params, label: "params")
+      agent_params = Helpers::HashNormalizer.normalize(current_agent.params, label: "params")
 
       # Create chat and restore conversation history
       chat = RubyLLM::Chat.new(model: current_agent.model)
-      current_headers = Helpers::Headers.merge(agent_headers, runtime_headers)
+      current_headers = Helpers::HashNormalizer.merge(agent_headers, runtime_headers)
+      current_params = Helpers::HashNormalizer.merge(agent_params, runtime_params)
       apply_headers(chat, current_headers)
+      apply_params(chat, current_params)
       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)
@@ -112,19 +118,18 @@ module Agents
         raise MaxTurnsExceeded, "Exceeded maximum turns: #{max_turns}" if current_turn > max_turns
 
         # Get response from LLM (RubyLLM handles tool execution with halting based handoff detection)
-        result = if current_turn == 1
-                   # Emit agent thinking event for initial message
-                   context_wrapper.callback_manager.emit_agent_thinking(current_agent.name, input, context_wrapper)
-                   # If conversation history already ends with this user message (e.g. passed
-                   # in via context from an external system), use complete to avoid duplicating it.
-                   input_already_in_history ? chat.complete : chat.ask(input)
-                 else
-                   # Emit agent thinking event for continuation
-                   context_wrapper.callback_manager.emit_agent_thinking(current_agent.name, "(continuing conversation)",
-                                                                        context_wrapper)
-                   chat.complete
-                 end
-        response = result
+        response = if current_turn == 1
+                     # Emit agent thinking event for initial message
+                     context_wrapper.callback_manager.emit_agent_thinking(current_agent.name, input, context_wrapper)
+                     # If conversation history already ends with this user message (e.g. passed
+                     # in via context from an external system), use complete to avoid duplicating it.
+                     input_already_in_history ? chat.complete : chat.ask(input)
+                   else
+                     # Emit agent thinking event for continuation
+                     context_wrapper.callback_manager.emit_agent_thinking(current_agent.name, "(continuing conversation)",
+                                                                          context_wrapper)
+                     chat.complete
+                   end
         track_usage(response, context_wrapper)
 
         # Emit LLM call complete event with model and response for instrumentation
@@ -140,22 +145,8 @@ module Agents
           # Validate that the target agent is in our registry
           # This prevents handoffs to agents that weren't explicitly provided
           unless registry[next_agent.name]
-            save_conversation_state(chat, context_wrapper, current_agent)
             error = AgentNotFoundError.new("Handoff failed: Agent '#{next_agent.name}' not found in registry")
-
-            result = RunResult.new(
-              output: nil,
-              messages: Helpers::MessageExtractor.extract_messages(chat, current_agent),
-              usage: context_wrapper.usage,
-              context: context_wrapper.context,
-              error: error
-            )
-
-            # Emit agent complete and run complete events with error
-            context_wrapper.callback_manager.emit_agent_complete(current_agent.name, result, error, context_wrapper)
-            context_wrapper.callback_manager.emit_run_complete(current_agent.name, result, context_wrapper)
-
-            return result
+            return finalize_run(chat, context_wrapper, current_agent, output: nil, error: error)
           end
 
           # Save current conversation state before switching
@@ -174,9 +165,12 @@ module Agents
 
           # Reconfigure existing chat for new agent - preserves conversation history automatically
           configure_chat_for_agent(chat, current_agent, context_wrapper, replace: true)
-          agent_headers = Helpers::Headers.normalize(current_agent.headers)
-          current_headers = Helpers::Headers.merge(agent_headers, runtime_headers)
+          agent_headers = Helpers::HashNormalizer.normalize(current_agent.headers, label: "headers")
+          current_headers = Helpers::HashNormalizer.merge(agent_headers, runtime_headers)
           apply_headers(chat, current_headers)
+          agent_params = Helpers::HashNormalizer.normalize(current_agent.params, label: "params")
+          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
           )
@@ -189,81 +183,50 @@ module Agents
 
         # Handle non-handoff halts - return the halt content as final response
         if response.is_a?(RubyLLM::Tool::Halt)
-          save_conversation_state(chat, context_wrapper, current_agent)
-
-          result = RunResult.new(
-            output: response.content,
-            messages: Helpers::MessageExtractor.extract_messages(chat, current_agent),
-            usage: context_wrapper.usage,
-            context: context_wrapper.context
-          )
-
-          # Emit agent complete and run complete events
-          context_wrapper.callback_manager.emit_agent_complete(current_agent.name, result, nil, context_wrapper)
-          context_wrapper.callback_manager.emit_run_complete(current_agent.name, result, context_wrapper)
-
-          return result
+          return finalize_run(chat, context_wrapper, current_agent, output: response.content)
         end
 
         # If tools were called, continue the loop to let them execute
         next if response.tool_call?
 
         # If no tools were called, we have our final response
-
-        # Save final state before returning
-        save_conversation_state(chat, context_wrapper, current_agent)
-
-        result = RunResult.new(
-          output: response.content,
-          messages: Helpers::MessageExtractor.extract_messages(chat, current_agent),
-          usage: context_wrapper.usage,
-          context: context_wrapper.context
-        )
-
-        # Emit agent complete and run complete events
-        context_wrapper.callback_manager.emit_agent_complete(current_agent.name, result, nil, context_wrapper)
-        context_wrapper.callback_manager.emit_run_complete(current_agent.name, result, context_wrapper)
-
-        return result
+        return finalize_run(chat, context_wrapper, current_agent, output: response.content)
       end
     rescue MaxTurnsExceeded => e
-      # Save state even on error
-      save_conversation_state(chat, context_wrapper, current_agent) if chat
-
-      result = RunResult.new(
-        output: "Conversation ended: #{e.message}",
-        messages: chat ? Helpers::MessageExtractor.extract_messages(chat, current_agent) : [],
-        usage: context_wrapper.usage,
-        error: e,
-        context: context_wrapper.context
-      )
+      finalize_run(chat, context_wrapper, current_agent,
+                   output: "Conversation ended: #{e.message}", error: e)
+    rescue StandardError => e
+      finalize_run(chat, context_wrapper, current_agent, output: nil, error: e)
+    end
 
-      # Emit agent complete and run complete events with error
-      context_wrapper.callback_manager.emit_agent_complete(current_agent.name, result, e, context_wrapper)
-      context_wrapper.callback_manager.emit_run_complete(current_agent.name, result, context_wrapper)
+    private
 
-      result
-    rescue StandardError => e
-      # Save state even on error
+    # Saves conversation state, builds a RunResult, emits completion callbacks, and returns it.
+    # Centralises the finalize-and-return pattern used by the normal path, halt path, and error rescues.
+    #
+    # @param chat [RubyLLM::Chat, nil] The chat instance (nil in early-failure rescues)
+    # @param context_wrapper [RunContext] Context wrapper for state and callbacks
+    # @param current_agent [Agents::Agent] The currently active agent
+    # @param output [String, nil] The output text for the result
+    # @param error [StandardError, nil] Optional error to attach to the result
+    # @return [RunResult]
+    def finalize_run(chat, context_wrapper, current_agent, output:, error: nil)
       save_conversation_state(chat, context_wrapper, current_agent) if chat
 
       result = RunResult.new(
-        output: nil,
+        output: output,
         messages: chat ? Helpers::MessageExtractor.extract_messages(chat, current_agent) : [],
         usage: context_wrapper.usage,
-        error: e,
+        error: error,
         context: context_wrapper.context
       )
 
-      # Emit agent complete and run complete events with error
-      context_wrapper.callback_manager.emit_agent_complete(current_agent.name, result, e, context_wrapper)
+      context_wrapper.callback_manager.emit_agent_complete(current_agent.name, result, error, context_wrapper)
       context_wrapper.callback_manager.emit_run_complete(current_agent.name, result, context_wrapper)
 
       result
     end
 
-    private
-
     # Creates a deep copy of context data for thread safety.
     # Preserves conversation history array structure while avoiding agent mutation.
     #
@@ -334,7 +297,7 @@ module Agents
 
       params = {
         role: role,
-        content: RubyLLM::Content.new(content_value)
+        content: build_content(content_value)
       }
 
       # Handle tool-specific parameters (Tool Results)
@@ -366,6 +329,24 @@ module Agents
       params
     end
 
+    # Build RubyLLM::Content from stored content, handling multimodal arrays with image attachments.
+    # Multimodal arrays follow the OpenAI content format: [{type: 'text', text: '...'}, {type: 'image_url', ...}]
+    def build_content(content_value)
+      return RubyLLM::Content.new(content_value) unless content_value.is_a?(Array)
+
+      text_parts = content_value.filter_map { |p| p[:text] || p["text"] if (p[:type] || p["type"]) == "text" }
+      image_urls = content_value.filter_map do |p|
+        next unless (p[:type] || p["type"]) == "image_url"
+
+        p.dig(:image_url, :url) || p.dig("image_url", "url")
+      end
+
+      return RubyLLM::Content.new(content_value.to_json) if text_parts.empty? && image_urls.empty?
+
+      text = text_parts.join(" ")
+      image_urls.any? ? RubyLLM::Content.new(text, image_urls) : RubyLLM::Content.new(text)
+    end
+
     # Validate tool message has required tool_call_id
     def valid_tool_message?(msg)
       if msg[:tool_call_id]
@@ -444,6 +425,12 @@ module Agents
       chat.with_headers(**headers)
     end
 
+    def apply_params(chat, params)
+      return if params.empty?
+
+      chat.with_params(**params)
+    end
+
     def track_usage(response, context_wrapper)
       return unless context_wrapper&.usage
 

data/lib/agents/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ai-agents
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Shivam Mishra
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.9.1
+        version: '1.14'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.9.1
+        version: '1.14'
 description: Ruby AI Agents SDK enables creating complex AI workflows with multi-agent
   orchestration, tool execution, safety guardrails, and provider-agnostic LLM integration.
 email:
@@ -61,6 +61,7 @@ files:
 - docs/guides/agent-as-tool-pattern.md
 - docs/guides/instrumentation.md
 - docs/guides/multi-agent-systems.md
+- docs/guides/provider-params.md
 - docs/guides/rails-integration.md
 - docs/guides/request-headers.md
 - docs/guides/state-persistence.md
@@ -106,8 +107,9 @@ files:
 - lib/agents/callback_manager.rb
 - lib/agents/handoff.rb
 - lib/agents/helpers.rb
-- lib/agents/helpers/headers.rb
+- lib/agents/helpers/hash_normalizer.rb
 - lib/agents/helpers/message_extractor.rb
+- lib/agents/helpers/name_normalizer.rb
 - lib/agents/instrumentation.rb
 - lib/agents/instrumentation/constants.rb
 - lib/agents/instrumentation/tracing_callbacks.rb

data/lib/agents/helpers/headers.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-module Agents
-  module Helpers
-    module Headers
-      module_function
-
-      def normalize(headers, freeze_result: false)
-        return freeze_result ? {}.freeze : {} if headers.nil? || (headers.respond_to?(:empty?) && headers.empty?)
-
-        hash = headers.respond_to?(:to_h) ? headers.to_h : headers
-        raise ArgumentError, "headers must be a Hash or respond to #to_h" unless hash.is_a?(Hash)
-
-        result = symbolize_keys(hash)
-        freeze_result ? result.freeze : result
-      end
-
-      def merge(agent_headers, runtime_headers)
-        return runtime_headers if agent_headers.empty?
-        return agent_headers if runtime_headers.empty?
-
-        agent_headers.merge(runtime_headers) { |_key, _agent_value, runtime_value| runtime_value }
-      end
-
-      def symbolize_keys(hash)
-        hash.transform_keys do |key|
-          key.is_a?(Symbol) ? key : key.to_sym
-        end
-      end
-      private_class_method :symbolize_keys
-    end
-  end
-end