activeagent 1.0.0 → 1.0.2

data/lib/active_agent/providers/_base_provider.rb

@@ -4,11 +4,13 @@ require_relative "common/response"
 require_relative "concerns/exception_handler"
 require_relative "concerns/instrumentation"
 require_relative "concerns/previewable"
+require_relative "concerns/tool_choice_clearing"
 
 # @private
 GEM_LOADERS = {
   anthropic: [ "anthropic", "~> 1.12", "anthropic" ],
-  openai:    [ "openai",    "~> 0.34", "openai" ]
+  openai:    [ "openai",    "~> 0.34", "openai" ],
+  ruby_llm:  [ "ruby_llm",  ">= 1.0",  "ruby_llm" ]
 }
 
 # Requires a provider's gem dependency.
@@ -45,6 +47,7 @@ module ActiveAgent
       include ExceptionHandler
       include Instrumentation
       include Previewable
+      include ToolChoiceClearing
 
       class ProvidersError < StandardError; end
 

data/lib/active_agent/providers/anthropic/options.rb

@@ -28,15 +28,13 @@ module ActiveAgent
         end
 
         def serialize
-          super.except(:anthropic_beta).tap do |hash|
-            hash[:extra_headers] = extra_headers unless extra_headers.blank?
-          end
+          super.except(:anthropic_beta)
         end
 
+        # Anthropic gem handles beta headers differently via client.beta
+        # rather than via extra_headers in request_options
         def extra_headers
-          deep_compact(
-            "anthropic-beta" => anthropic_beta.presence,
-          )
+          {}
         end
 
         private

data/lib/active_agent/providers/anthropic/request.rb

@@ -67,11 +67,13 @@ module ActiveAgent
         # @option params [Array<Hash>] :messages required
         # @option params [Integer] :max_tokens (4096)
         # @option params [Hash] :response_format custom field for JSON mode simulation
+        # @option params [String] :anthropic_beta beta version for features like MCP
         # @raise [ArgumentError] when gem model validation fails
         def initialize(**params)
           # Step 1: Extract custom fields that gem doesn't support
           @response_format = params.delete(:response_format)
           @stream = params.delete(:stream)
+          anthropic_beta = params.delete(:anthropic_beta)
 
           # Step 2: Map common format 'instructions' to Anthropic's 'system'
           if params.key?(:instructions)
@@ -84,10 +86,24 @@ module ActiveAgent
           # Step 4: Transform params for gem compatibility
           transformed = Transforms.normalize_params(params)
 
-          # Step 5: Create gem model - this validates all parameters!
-          gem_model = ::Anthropic::Models::MessageCreateParams.new(**transformed)
+          # Step 5: Determine if we need beta params (for MCP or other beta features)
+          use_beta = anthropic_beta.present? || transformed[:mcp_servers]&.any?
 
-          # Step 6: Delegate all method calls to gem model
+          # Step 6: Add betas parameter if using beta API
+          if use_beta
+            # Default to MCP beta version if not specified
+            beta_version = anthropic_beta || "mcp-client-2025-04-04"
+            transformed[:betas] = [ beta_version ]
+          end
+
+          # Step 7: Create gem model - use Beta version if needed
+          gem_model = if use_beta
+            ::Anthropic::Models::Beta::MessageCreateParams.new(**transformed)
+          else
+            ::Anthropic::Models::MessageCreateParams.new(**transformed)
+          end
+
+          # Step 8: Delegate all method calls to gem model
           super(gem_model)
         rescue ArgumentError => e
           # Re-raise with more context
@@ -134,6 +150,15 @@ module ActiveAgent
           self.system = value
         end
 
+        # Accessor for MCP servers.
+        #
+        # Safely returns MCP servers array, defaulting to empty array if not set.
+        #
+        # @return [Array]
+        def mcp_servers
+          __getobj__.instance_variable_get(:@data)[:mcp_servers] || []
+        end
+
         # Removes the last message from the messages array.
         #
         # Used for JSON format simulation to remove the lead-in assistant message.

data/lib/active_agent/providers/anthropic/transforms.rb

@@ -28,9 +28,137 @@ module ActiveAgent
             params = params.dup
             params[:messages] = normalize_messages(params[:messages]) if params[:messages]
             params[:system] = normalize_system(params[:system]) if params[:system]
+            params[:tools] = normalize_tools(params[:tools]) if params[:tools]
+            params[:tool_choice] = normalize_tool_choice(params[:tool_choice]) if params[:tool_choice]
+
+            # Handle mcps parameter (common format) -> transforms to mcp_servers (provider format)
+            if params[:mcps]
+              params[:mcp_servers] = normalize_mcp_servers(params.delete(:mcps))
+            elsif params[:mcp_servers]
+              params[:mcp_servers] = normalize_mcp_servers(params[:mcp_servers])
+            end
+
             params
           end
 
+          # Normalizes tools from common format to Anthropic format.
+          #
+          # Accepts both `parameters` and `input_schema` keys, converting to Anthropic's `input_schema`.
+          #
+          # @param tools [Array<Hash>]
+          # @return [Array<Hash>]
+          def normalize_tools(tools)
+            return tools unless tools.is_a?(Array)
+
+            tools.map do |tool|
+              tool_hash = tool.is_a?(Hash) ? tool.deep_symbolize_keys : tool
+
+              # If already in Anthropic format (has input_schema), return as-is
+              next tool_hash if tool_hash[:input_schema]
+
+              # Convert common format with 'parameters' to Anthropic format with 'input_schema'
+              if tool_hash[:parameters]
+                tool_hash = tool_hash.dup
+                tool_hash[:input_schema] = tool_hash.delete(:parameters)
+              end
+
+              tool_hash
+            end
+          end
+
+          # Normalizes MCP servers from common format to Anthropic format.
+          #
+          # Common format:
+          #   {name: "stripe", url: "https://...", authorization: "token"}
+          # Anthropic format:
+          #   {type: "url", name: "stripe", url: "https://...", authorization_token: "token"}
+          #
+          # @param mcp_servers [Array<Hash>]
+          # @return [Array<Hash>]
+          def normalize_mcp_servers(mcp_servers)
+            return mcp_servers unless mcp_servers.is_a?(Array)
+
+            mcp_servers.map do |server|
+              server_hash = server.is_a?(Hash) ? server.deep_symbolize_keys : server
+
+              # If already in Anthropic native format (has type: "url"), return as-is
+              # Check for absence of common format 'authorization' field OR presence of native 'authorization_token'
+              if server_hash[:type] == "url" && (server_hash[:authorization_token] || !server_hash[:authorization])
+                next server_hash
+              end
+
+              # Convert common format to Anthropic format
+              result = {
+                type: "url",
+                name: server_hash[:name],
+                url: server_hash[:url]
+              }
+
+              # Map 'authorization' to 'authorization_token'
+              if server_hash[:authorization]
+                result[:authorization_token] = server_hash[:authorization]
+              elsif server_hash[:authorization_token]
+                result[:authorization_token] = server_hash[:authorization_token]
+              end
+
+              result.compact
+            end
+          end
+
+          # Normalizes tool_choice from common format to Anthropic gem model objects.
+          #
+          # The Anthropic gem expects tool_choice to be a model object (ToolChoiceAuto,
+          # ToolChoiceAny, ToolChoiceTool, etc.), not a plain hash.
+          #
+          # Maps:
+          # - "required" → ToolChoiceAny (force tool use)
+          # - "auto" → ToolChoiceAuto (let model decide)
+          # - { name: "..." } → ToolChoiceTool with name
+          #
+          # @param tool_choice [String, Hash, Object]
+          # @return [Object] Anthropic gem model object
+          def normalize_tool_choice(tool_choice)
+            # If already a gem model object, return as-is
+            return tool_choice if tool_choice.is_a?(::Anthropic::Models::ToolChoiceAuto) ||
+                                   tool_choice.is_a?(::Anthropic::Models::ToolChoiceAny) ||
+                                   tool_choice.is_a?(::Anthropic::Models::ToolChoiceTool) ||
+                                   tool_choice.is_a?(::Anthropic::Models::ToolChoiceNone)
+
+            case tool_choice
+            when "required"
+              # Create ToolChoiceAny model for forcing tool use
+              ::Anthropic::Models::ToolChoiceAny.new(type: :any)
+            when "auto"
+              # Create ToolChoiceAuto model for letting model decide
+              ::Anthropic::Models::ToolChoiceAuto.new(type: :auto)
+            when Hash
+              choice_hash = tool_choice.deep_symbolize_keys
+
+              # If has type field, create appropriate model
+              if choice_hash[:type]
+                case choice_hash[:type].to_sym
+                when :any
+                  ::Anthropic::Models::ToolChoiceAny.new(**choice_hash)
+                when :auto
+                  ::Anthropic::Models::ToolChoiceAuto.new(**choice_hash)
+                when :tool
+                  ::Anthropic::Models::ToolChoiceTool.new(**choice_hash)
+                when :none
+                  ::Anthropic::Models::ToolChoiceNone.new(**choice_hash)
+                else
+                  choice_hash
+                end
+              # Convert { name: "..." } to ToolChoiceTool
+              elsif choice_hash[:name]
+                ::Anthropic::Models::ToolChoiceTool.new(type: :tool, name: choice_hash[:name])
+              else
+                choice_hash
+              end
+            else
+              tool_choice
+            end
+          end
+
           # Merges consecutive same-role messages into single messages with multiple content blocks.
           #
           # Required by Anthropic API - consecutive messages with the same role must be combined.
@@ -317,9 +445,10 @@ module ActiveAgent
             # Apply content compression for API efficiency
             compress_content(hash)
 
-            # Remove provider-internal fields that should not be in API request
-            hash.delete(:mcp_servers)   # Provider-level config, not API param
+            # Remove provider-internal fields and empty arrays
             hash.delete(:stop_sequences) if hash[:stop_sequences] == []
+            hash.delete(:mcp_servers) if hash[:mcp_servers] == []
+            hash.delete(:tool_choice) if hash[:tool_choice].nil?  # Don't send null tool_choice
 
             # Remove default values (except max_tokens which is required by API)
             defaults.each do |key, value|

data/lib/active_agent/providers/anthropic_provider.rb

@@ -17,6 +17,17 @@ module ActiveAgent
     #
     # @see BaseProvider
     class AnthropicProvider < BaseProvider
+      # Lead-in message for JSON response format emulation
+      JSON_RESPONSE_FORMAT_LEAD_IN = "Here is the JSON requested:\n{"
+
+      attr_internal :json_format_retry_count
+
+      def initialize(kwargs = {})
+        super
+
+        self.json_format_retry_count = kwargs[:max_retries] || ::Anthropic::Client::DEFAULT_MAX_RETRIES
+      end
+
       # @todo Add support for Anthropic::BedrockClient and Anthropic::VertexClient
       # @return [Anthropic::Client]
       def client
@@ -39,22 +50,31 @@ module ActiveAgent
         super
       end
 
-      # @api private
-      def prepare_prompt_request_tools
-        return unless request.tool_choice
-        return unless request.tool_choice.respond_to?(:type)
+      # Extracts function names from Anthropic's tool_use content blocks.
+      #
+      # @return [Array<String>]
+      def extract_used_function_names
+        message_stack.pluck(:content).flatten.select { _1[:type] == "tool_use" }.pluck(:name)
+      end
 
-        functions_used = message_stack.pluck(:content).flatten.select { _1[:type] == "tool_use" }.pluck(:name)
+      # Checks if tool_choice requires the model to call any tool.
+      #
+      # @return [Boolean] true if tool_choice type is :any
+      def tool_choice_forces_required?
+        return false unless request.tool_choice.respond_to?(:type)
 
-        # tool_choice is always a gem model object (ToolChoiceAny, ToolChoiceTool, ToolChoiceAuto)
-        tool_choice_type = request.tool_choice.type
-        tool_choice_name = request.tool_choice.respond_to?(:name) ? request.tool_choice.name : nil
+        request.tool_choice.type == :any
+      end
 
-        if (tool_choice_type == :any && functions_used.any?) ||
-          (tool_choice_type == :tool && tool_choice_name && functions_used.include?(tool_choice_name))
+      # Checks if tool_choice requires a specific tool to be called.
+      #
+      # @return [Array<Boolean, String|nil>] [true, tool_name] if forcing a specific tool, [false, nil] otherwise
+      def tool_choice_forces_specific?
+        return [ false, nil ] unless request.tool_choice.respond_to?(:type)
+        return [ false, nil ] unless request.tool_choice.type == :tool
 
-          request.tool_choice = nil
-        end
+        tool_name = request.tool_choice.respond_to?(:name) ? request.tool_choice.name : nil
+        [ true, tool_name ]
       end
 
       # @api private
@@ -63,19 +83,30 @@ module ActiveAgent
 
         self.message_stack.push({
           role:    "assistant",
-          content: "Here is the JSON requested:\n{"
+          content: JSON_RESPONSE_FORMAT_LEAD_IN
         })
       end
 
+      # Selects between Anthropic's stable and beta message APIs.
+      #
+      # Uses beta API when explicitly requested via anthropic_beta option or when
+      # using MCP servers, which require beta features. Falls back to stable API
+      # for standard message creation.
+      #
       # @see BaseProvider#api_prompt_executer
-      # @return [Anthropic::Messages]
+      # @return [Anthropic::Messages, Anthropic::Resources::Beta::Messages]
       def api_prompt_executer
-        client.messages
+        # Use beta API when anthropic_beta option is set or when using MCP servers
+        if options.anthropic_beta.present? || request.mcp_servers&.any?
+          client.beta.messages
+        else
+          client.messages
+        end
       end
 
       # @see BaseProvider#api_response_normalize
       # @param api_response [Anthropic::Models::Message]
-      # @return [Hash] normalized response hash
+      # @return [Hash]
       def api_response_normalize(api_response)
         return api_response unless api_response
 
@@ -158,9 +189,14 @@ module ActiveAgent
         when :ping
           # No-Op Keep Awake
         when :overloaded_error
-          # TODO: https://docs.claude.com/en/docs/build-with-claude/streaming#error-events
+        # TODO: https://docs.claude.com/en/docs/build-with-claude/streaming#error-events
+
+        # Higher-level convenience events from anthropic gem's MessageStream
+        when :text, :input_json, :citation, :thinking, :signature
+          # No-Op; Already handled via :content_block_delta
+
         else
-          # No-Op: Looks like internal tracking from gem wrapper
+          # No-Op; Internal tracking from gem wrapper
           return if api_response_chunk.respond_to?(:snapshot)
           raise "Unexpected chunk type: #{api_response_chunk.type}"
         end
@@ -200,31 +236,57 @@ module ActiveAgent
         end
       end
 
-      # Converts API response message to hash for message_stack.
-      # Converts Anthropic gem response object to hash for storage.
+      # Processes completed API response and handles JSON format retries.
+      #
+      # When response_format is json_object and the response fails JSON validation,
+      # recursively retries the request to obtain well-formed JSON.
       #
+      # @see BaseProvider#process_prompt_finished
       # @param api_response [Anthropic::Models::Message]
       # @return [Common::PromptResponse, nil]
       def process_prompt_finished(api_response = nil)
         # Convert gem object to hash so that raw_response[:usage] works
         api_response_hash = api_response ? Anthropic::Transforms.gem_to_hash(api_response) : nil
-        super(api_response_hash)
+
+        common_response = super(api_response_hash)
+
+        # If we failed to get the expected well formed JSON Object Response, recursively try again
+        if request.response_format&.dig(:type) == "json_object" && common_response.message.parsed_json.nil? && json_format_retry_count > 0
+          self.json_format_retry_count -= 1
+
+          resolve_prompt
+        else
+          common_response
+        end
       end
 
+      # Reconstructs JSON responses that were split due to Anthropic format constraints.
       #
-      # Handles JSON response format simulation by prepending `{` to the response
-      # content after removing the assistant lead-in message.
+      # Anthropic's API doesn't natively support json_object response format, so we
+      # simulate it by having the assistant echo a JSON lead-in ("Here is the JSON requested:\n{"),
+      # then send the response back for completion. This method detects and reverses
+      # that workaround by stripping the lead-in message and prepending "{" to the response.
       #
       # @see BaseProvider#process_prompt_finished_extract_messages
-      # @param api_response [Hash] converted response hash
+      # @param api_response [Hash] API response with content blocks
       # @return [Array<Hash>, nil]
       def process_prompt_finished_extract_messages(api_response)
         return unless api_response
 
-        # Handle JSON response format simulation
-        if request.response_format&.dig(:type) == "json_object"
-          request.pop_message!
-          api_response[:content][0][:text] = "{#{api_response[:content][0][:text]}"
+        # Get the last message (may be either Hash or gem object)
+        last_message = request.messages.last
+        last_role    = last_message.is_a?(Hash) ? last_message[:role]    : last_message&.role
+        last_content = last_message.is_a?(Hash) ? last_message[:content] : last_message&.content
+
+        # Check if the last message in request is the JSON lead-in prompt
+        if last_role.to_sym == :assistant && last_content == JSON_RESPONSE_FORMAT_LEAD_IN
+          # Remove the lead-in message from the request
+          request.messages.pop
+
+          # Prepend "{" to the response's first content text
+          if api_response[:content]&.first&.dig(:text)
+            api_response[:content][0][:text] = "{#{api_response[:content][0][:text]}"
+          end
         end
 
         [ api_response ]
@@ -239,11 +301,16 @@ module ActiveAgent
       def process_prompt_finished_extract_function_calls
         message_stack.pluck(:content).flatten.select { _1 in { type: "tool_use" } }.map do |api_function_call|
           json_buf = api_function_call.delete(:json_buf)
-          api_function_call[:input] = JSON.parse(json_buf, symbolize_names: true) if json_buf
+          api_function_call[:input] = JSON.parse(json_buf, symbolize_names: true) if json_buf.present?
 
           # Handle case where :input is still a JSON string (gem >= 1.14.0)
+          # For tools with no parameters, input may be an empty string
           if api_function_call[:input].is_a?(String)
-            api_function_call[:input] = JSON.parse(api_function_call[:input], symbolize_names: true)
+            if api_function_call[:input].present?
+              api_function_call[:input] = JSON.parse(api_function_call[:input], symbolize_names: true)
+            else
+              api_function_call[:input] = {}
+            end
           end
 
           api_function_call

data/lib/active_agent/providers/azure/_types.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "options"
+require_relative "../open_ai/chat/_types"
+require_relative "../open_ai/embedding/_types"

data/lib/active_agent/providers/azure/options.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative "../open_ai/options"
+
+module ActiveAgent
+  module Providers
+    module Azure
+      # Configuration options for Azure OpenAI Service.
+      #
+      # Azure OpenAI uses a different authentication and endpoint structure than standard OpenAI:
+      # - Endpoint: https://{resource}.openai.azure.com/openai/deployments/{deployment}/
+      # - Authentication: api-key header instead of Authorization: Bearer
+      # - API Version: Required query parameter
+      #
+      # You can configure Azure OpenAI in two ways:
+      #
+      # 1. Using azure_resource and deployment_id (standard Azure OpenAI):
+      #    @example
+      #      options = Azure::Options.new(
+      #        api_key: ENV["AZURE_OPENAI_API_KEY"],
+      #        azure_resource: "mycompany",
+      #        deployment_id: "gpt-4-deployment",
+      #        api_version: "2024-10-21"
+      #      )
+      #
+      # 2. Using a direct host/base_url (for custom domains or Azure AI Foundry):
+      #    @example
+      #      options = Azure::Options.new(
+      #        api_key: ENV["AZURE_OPENAI_API_KEY"],
+      #        host: "https://mycompany.cognitiveservices.azure.com/openai/deployments/gpt-4",
+      #        api_version: "2024-10-21"
+      #      )
+      class Options < ActiveAgent::Providers::OpenAI::Options
+        DEFAULT_API_VERSION = "2024-10-21"
+
+        attribute :azure_resource, :string
+        attribute :deployment_id,  :string
+        attribute :api_version,    :string, fallback: DEFAULT_API_VERSION
+
+        validates :azure_resource, presence: true, unless: :explicit_host_provided?
+        validates :deployment_id, presence: true, unless: :explicit_host_provided?
+
+        def initialize(kwargs = {})
+          kwargs = kwargs.deep_symbolize_keys if kwargs.respond_to?(:deep_symbolize_keys)
+          kwargs[:api_version] ||= resolve_api_version(kwargs)
+          # Store explicit host before super processes kwargs
+          # host is aliased to base_url in parent, so check both
+          @explicit_host = kwargs[:host] || kwargs[:base_url]
+          super(kwargs)
+        end
+
+        # Returns Azure-specific headers for authentication.
+        #
+        # Azure uses api-key header instead of Authorization: Bearer.
+        #
+        # @return [Hash] headers including api-key
+        def extra_headers
+          { "api-key" => api_key }
+        end
+
+        # Returns Azure-specific query parameters.
+        #
+        # Azure requires api-version as a query parameter.
+        #
+        # @return [Hash] query parameters including api-version
+        def extra_query
+          { "api-version" => api_version }
+        end
+
+        # Builds the base URL for Azure OpenAI API requests.
+        #
+        # If a direct host/base_url is provided, uses that directly.
+        # Otherwise, constructs the URL from azure_resource and deployment_id.
+        #
+        # @return [String] the Azure OpenAI endpoint URL
+        def base_url
+          if @explicit_host.present?
+            @explicit_host
+          elsif azure_resource.present? && deployment_id.present?
+            "https://#{azure_resource}.openai.azure.com/openai/deployments/#{deployment_id}"
+          else
+            raise ArgumentError, "Either host or azure_resource + deployment_id must be provided"
+          end
+        end
+
+        private
+
+        def explicit_host_provided?
+          @explicit_host.present?
+        end
+
+        def resolve_api_key(kwargs)
+          kwargs[:api_key] ||
+            kwargs[:access_token] ||
+            ENV["AZURE_OPENAI_API_KEY"] ||
+            ENV["AZURE_OPENAI_ACCESS_TOKEN"]
+        end
+
+        def resolve_api_version(kwargs)
+          kwargs[:api_version] ||
+            ENV["AZURE_OPENAI_API_VERSION"] ||
+            DEFAULT_API_VERSION
+        end
+
+        # Not used as part of Azure OpenAI
+        def resolve_organization_id(_settings) = nil
+        def resolve_project_id(_settings)      = nil
+      end
+    end
+  end
+end

data/lib/active_agent/providers/azure_open_ai_provider.rb

@@ -0,0 +1,2 @@
+# Azure OpenAI, alias for AzureOpenAI service name resolution
+require_relative "azure_provider"

data/lib/active_agent/providers/azure_openai_provider.rb

@@ -0,0 +1,2 @@
+# Azure OpenAI, alias for :azure_openai provider reference
+require_relative "azure_provider"