ai-agents 0.9.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e4285e8a584df94b230a5e9e65e4d7991bab421c48b02726e7a69882068ca9d
-  data.tar.gz: 5ebaacb25ed21e880c6393b70ff1a661216b2f7f4f2e946db8d298bb1fe8acc2
+  metadata.gz: '071869beb00d53446a27f489c3817c58b0f8d163f334f0030c95b789a7c4895b'
+  data.tar.gz: 874227bd4dd05dd2947269bec7da2d593777a8600540ef9ec5a8fb50c346a884
 SHA512:
-  metadata.gz: 0c96c699fa544c44ca8200d70d8663adc2f82a39b9f58001d87b0a79f0c64ace068bbb5622d9708aaec7f5e48be0128c9e04dcbe918c899cc03c00ffaa710bd9
-  data.tar.gz: b103cd93cda31c7adfa874405587a6fdd5fc2c54049179e55651dd21585b4ea047d856596eceaf4108a631e30fc787f943d43247d3765c51950130f6e5126176
+  metadata.gz: 7e3814e0e76359be595534eb92ce11d655e19e3997f78aea006be89721aae771c6a1f97ad277ed80581957cdea5a0919506518dfd8e8de1911a03a3641668a8b
+  data.tar.gz: 351b99abda0942df5253e1735faca522b5eee988fc248ec16564dea700b2bcfcf31a8ec4ba8f9db73f3f57103e5f8b37a0997c6e71f4b1a1872ca796046cad2a

data/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-05-27
+
+### Added
+- Support RubyLLM provider overrides and custom model/deployment IDs on agents, including Azure configuration passthrough (#66)
+
+### Fixed
+- Preserve per-message assistant agent attribution when restoring and snapshotting multi-agent conversation history, preventing earlier assistant messages from being re-labeled as the final active agent after handoffs (#68)
+
+## [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

data/README.md

@@ -193,22 +193,40 @@ ruby examples/isp-support/interactive.rb
 Agents.configure do |config|
   # Provider API keys
   config.openai_api_key = ENV['OPENAI_API_KEY']
+  config.azure_api_base = ENV['AZURE_API_BASE']
+  config.azure_api_key = ENV['AZURE_API_KEY']
   config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
   config.gemini_api_key = ENV['GEMINI_API_KEY']
 
   # Defaults
-  config.default_provider = :openai
   config.default_model = 'gpt-4o'
 
   # Performance
   config.request_timeout = 120
-  config.max_turns = 10
 
   # Debugging
   config.debug = true
 end
 ```
 
+### Azure and Custom Deployments
+
+```ruby
+Agents.configure do |config|
+  config.azure_api_base = ENV["AZURE_API_BASE"]
+  config.azure_api_key = ENV["AZURE_API_KEY"]
+end
+
+agent = Agents::Agent.new(
+  name: "Support",
+  model: "my-azure-deployment",
+  provider: :azure,
+  assume_model_exists: true
+)
+```
+
+`provider` is optional for known, unambiguous registry models. Set it for custom deployment names and for model IDs that can exist under multiple providers, such as Azure and OpenAI deployments.
+
 ## 🔍 Observability
 
 Optional OpenTelemetry instrumentation for tracing agent execution, compatible with

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/rails-integration.md

@@ -24,12 +24,25 @@ Configure your LLM providers in an initializer:
 # config/initializers/ai_agents.rb
 Agents.configure do |config|
   config.openai_api_key = Rails.application.credentials.openai_api_key
+  config.azure_api_base = Rails.application.credentials.azure_api_base
+  config.azure_api_key = Rails.application.credentials.azure_api_key
   config.anthropic_api_key = Rails.application.credentials.anthropic_api_key
   config.default_model = 'gpt-4o-mini'
   config.debug = Rails.env.development?
 end
 ```
 
+For Azure custom deployment names, pass the provider at the agent level:
+
+```ruby
+support = Agents::Agent.new(
+  name: "Support",
+  model: "my-azure-deployment",
+  provider: :azure,
+  assume_model_exists: true
+)
+```
+
 ## ActiveRecord Integration
 
 ### Conversation Persistence

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/docs/index.md

@@ -61,6 +61,8 @@ require 'agents'
 # Configure your API keys
 Agents.configure do |config|
   config.openai_api_key = ENV['OPENAI_API_KEY']
+  # config.azure_api_base = ENV['AZURE_API_BASE']
+  # config.azure_api_key = ENV['AZURE_API_KEY']
   # config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
   # config.gemini_api_key = ENV['GEMINI_API_KEY']
   config.default_model = 'gpt-4o-mini'
@@ -87,6 +89,24 @@ result = runner.run("I need help with a technical issue")
 puts result.output
 ```
 
+### Azure and Custom Deployments
+
+```ruby
+Agents.configure do |config|
+  config.azure_api_base = ENV["AZURE_API_BASE"]
+  config.azure_api_key = ENV["AZURE_API_KEY"]
+end
+
+agent = Agents::Agent.new(
+  name: "Support",
+  model: "my-azure-deployment",
+  provider: :azure,
+  assume_model_exists: true
+)
+```
+
+`provider` is optional for known, unambiguous registry models. Set it for custom deployment names and duplicate model IDs, such as Azure and OpenAI deployments.
+
 ## Next Steps
 
 - [Learn about Agents](concepts/agents.html)

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,28 +50,35 @@ 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, :provider, :assume_model_exists, :tools, :handoff_agents, :temperature,
+                :response_schema, :headers, :params
 
     # Initialize a new Agent instance
     #
     # @param name [String] The name of the agent
     # @param instructions [String, Proc, nil] Static string or dynamic Proc that returns instructions
     # @param model [String] The LLM model to use (default: "gpt-4.1-mini")
+    # @param provider [Symbol, String, nil] Optional RubyLLM provider override
+    # @param assume_model_exists [Boolean] Whether RubyLLM should skip registry validation for custom model IDs
     # @param tools [Array<Agents::Tool>] Array of tool instances the agent can use
     # @param handoff_agents [Array<Agents::Agent>] Array of agents this agent can hand off to
     # @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
-    def initialize(name:, instructions: nil, model: "gpt-4.1-mini", tools: [], handoff_agents: [], temperature: 0.7,
-                   response_schema: nil, headers: nil)
+    # @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", provider: nil, assume_model_exists: false,
+                   tools: [], handoff_agents: [], temperature: 0.7, response_schema: nil, headers: nil, params: nil)
       @name = name
       @instructions = instructions
       @model = model
+      @provider = provider&.to_sym
+      @assume_model_exists = assume_model_exists
       @tools = tools.dup
       @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
@@ -153,6 +160,8 @@ module Agents
     # @option changes [String] :name New agent name
     # @option changes [String, Proc] :instructions New instructions
     # @option changes [String] :model New model identifier
+    # @option changes [Symbol, String, nil] :provider New provider override
+    # @option changes [Boolean] :assume_model_exists Whether to skip model registry validation
     # @option changes [Array<Agents::Tool>] :tools New tools array (replaces all tools)
     # @option changes [Array<Agents::Agent>] :handoff_agents New handoff agents
     # @option changes [Float] :temperature Temperature for LLM responses (0.0-1.0)
@@ -163,11 +172,14 @@ module Agents
         name: changes.fetch(:name, @name),
         instructions: changes.fetch(:instructions, @instructions),
         model: changes.fetch(:model, @model),
+        provider: changes.fetch(:provider, @provider),
+        assume_model_exists: changes.fetch(:assume_model_exists, @assume_model_exists),
         tools: changes.fetch(:tools, @tools.dup),
         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/message_extractor.rb

@@ -18,8 +18,30 @@
 module Agents
   module Helpers
     module MessageExtractor
+      # RubyLLM::Message has no metadata/extension API, so agent ownership is stored
+      # as an SDK-namespaced ivar on the message object until it is extracted.
+      #
+      # Caveat: RubyLLM::Message#instance_variables is overridden to hide :@raw but does
+      # not hide this ivar, so it will appear in instance_variables listings. This is
+      # harmless for our own code path (we read it via instance_variable_get and
+      # serialize through extract_messages, not Marshal), but external introspection
+      # of a message's ivars will see :@agents_authoring_agent.
+      AUTHORING_AGENT_IVAR = :@agents_authoring_agent
+
       module_function
 
+      def assign_agent_name(message, agent_name)
+        return unless message && agent_name
+
+        message.instance_variable_set(AUTHORING_AGENT_IVAR, agent_name)
+      end
+
+      def attributed_agent_name_for(message)
+        return unless message&.instance_variable_defined?(AUTHORING_AGENT_IVAR)
+
+        message.instance_variable_get(AUTHORING_AGENT_IVAR)
+      end
+
       # Check if content is considered empty (handles both String and Hash content)
       #
       # @param content [String, Hash, nil] The content to check
@@ -65,7 +87,8 @@ module Agents
 
         return message unless msg.role == :assistant
 
-        message[:agent_name] = current_agent.name if current_agent
+        attributed_agent_name = attributed_agent_name_for(msg) || current_agent&.name
+        message[:agent_name] = attributed_agent_name if attributed_agent_name
 
         if tool_calls_present
           # RubyLLM stores tool_calls as Hash with call_id => ToolCall object

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

@@ -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 = serialize_content(content)
-        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,21 +219,15 @@ 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)
-        return serialize_multimodal_content(content) if multimodal_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
 

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,21 @@ 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)
+      chat = RubyLLM::Chat.new(
+        model: current_agent.model,
+        provider: current_agent.provider,
+        assume_model_exists: current_agent.assume_model_exists
+      )
+      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 +122,20 @@ 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
+        message_count_before_response = chat_message_count(chat)
+        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
+        assign_agent_name_to_new_assistant_messages(chat, current_agent, message_count_before_response)
         track_usage(response, context_wrapper)
 
         # Emit LLM call complete event with model and response for instrumentation
@@ -140,22 +151,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 +171,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 +189,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.
     #
@@ -303,6 +272,7 @@ module Agents
         next unless message_params # Skip invalid messages
 
         message = RubyLLM::Message.new(**message_params)
+        assign_restored_agent_name(message, msg)
         chat.add_message(message)
 
         if message.role == :assistant && message_params[:tool_calls]
@@ -414,6 +384,33 @@ module Agents
       context_wrapper.context.delete(:pending_handoff)
     end
 
+    def assign_agent_name_to_new_assistant_messages(chat, current_agent, start_index)
+      # Runtime chats are RubyLLM::Chat instances and expose messages. Keep this
+      # no-op guard for chat-like doubles/adapters that do not expose history.
+      return unless chat.respond_to?(:messages)
+
+      chat.messages[start_index..]&.each do |message|
+        next unless message.role == :assistant
+
+        Helpers::MessageExtractor.assign_agent_name(message, current_agent.name)
+      end
+    end
+
+    def chat_message_count(chat)
+      # Runtime chats are RubyLLM::Chat instances and expose messages. Keep this
+      # fallback for chat-like doubles/adapters where attribution is irrelevant.
+      return 0 unless chat.respond_to?(:messages)
+
+      chat.messages.length
+    end
+
+    def assign_restored_agent_name(message, msg)
+      return unless message.role == :assistant
+
+      restored_agent_name = msg[:agent_name] || msg["agent_name"]
+      Helpers::MessageExtractor.assign_agent_name(message, restored_agent_name)
+    end
+
     # Configures a RubyLLM chat instance with agent-specific settings.
     # Uses RubyLLM's replace option to swap agent context while preserving conversation history during handoffs.
     #
@@ -430,7 +427,13 @@ module Agents
       all_tools = build_agent_tools(agent, context_wrapper)
 
       # Switch model if different (important for handoffs between agents using different models)
-      chat.with_model(agent.model) if replace
+      if replace
+        chat.with_model(
+          agent.model,
+          provider: agent.provider,
+          assume_exists: agent.assume_model_exists
+        )
+      end
 
       # Configure chat with instructions, temperature, tools, and schema
       chat.with_instructions(system_prompt, replace: replace) if system_prompt
@@ -462,6 +465,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.1"
+  VERSION = "0.11.0"
 end

data/lib/agents.rb

@@ -56,6 +56,9 @@ module Agents
 
       # Other providers
       apply_if_present(config, :anthropic_api_key)
+      apply_if_present(config, :azure_api_base)
+      apply_if_present(config, :azure_api_key)
+      apply_if_present(config, :azure_ai_auth_token)
       apply_if_present(config, :gemini_api_key)
       apply_if_present(config, :deepseek_api_key)
       apply_if_present(config, :openrouter_api_key)
@@ -83,8 +86,9 @@ module Agents
   class Configuration
     # Provider API keys and configuration
     attr_accessor :openai_api_key, :openai_api_base, :openai_organization_id, :openai_project_id
-    attr_accessor :anthropic_api_key, :gemini_api_key, :deepseek_api_key, :openrouter_api_key, :ollama_api_base,
-                  :bedrock_api_key, :bedrock_secret_key, :bedrock_region, :bedrock_session_token
+    attr_accessor :anthropic_api_key, :azure_api_base, :azure_api_key, :azure_ai_auth_token, :gemini_api_key,
+                  :deepseek_api_key, :openrouter_api_key, :ollama_api_base, :bedrock_api_key, :bedrock_secret_key,
+                  :bedrock_region, :bedrock_session_token
 
     # General configuration
     attr_accessor :request_timeout, :default_model, :debug
@@ -100,7 +104,7 @@ module Agents
     def configured?
       @openai_api_key || @anthropic_api_key || @gemini_api_key ||
         @deepseek_api_key || @openrouter_api_key || @ollama_api_base ||
-        @bedrock_api_key
+        @bedrock_api_key || (@azure_api_base && (@azure_api_key || @azure_ai_auth_token))
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ai-agents
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.11.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