activeagent 1.0.0.rc1 → 1.0.1

data/lib/active_agent/providers/anthropic_provider.rb

@@ -5,6 +5,7 @@ require_relative "_base_provider"
 require_gem!(:anthropic, __FILE__)
 
 require_relative "anthropic/_types"
+require_relative "anthropic/transforms"
 
 module ActiveAgent
   module Providers
@@ -16,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
@@ -24,10 +36,10 @@ module ActiveAgent
 
       protected
 
-      # Prepares the request and handles tool choice cleanup.
+      # Removes forced tool choice after first use to prevent endless looping.
       #
-      # Removes forced tool choice from subsequent requests to prevent endless looping
-      # when the tool has already been used in the conversation.
+      # Clears tool_choice when the specified tool has already been called in the
+      # conversation, preventing the model from being forced to call it repeatedly.
       #
       # @see BaseProvider#prepare_prompt_request
       # @return [Request]
@@ -38,74 +50,109 @@ module ActiveAgent
         super
       end
 
-      # @api private
-      def prepare_prompt_request_tools
-        return unless request.tool_choice
+      # 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)
 
-        if (request.tool_choice.type == "any" && functions_used.any?) ||
-          (request.tool_choice.type == "tool" && functions_used.include?(request.tool_choice.name))
+        request.tool_choice.type == :any
+      end
 
-          instrument("tool_choice_removed.provider.active_agent")
-          request.tool_choice = nil
-        end
+      # 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
+
+        tool_name = request.tool_choice.respond_to?(:name) ? request.tool_choice.name : nil
+        [ true, tool_name ]
       end
 
       # @api private
       def prepare_prompt_request_response_format
-        return unless request.response_format&.type == "json_object"
+        return unless request.response_format&.dig(:type) == "json_object"
 
         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, 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
 
-      # Processes streaming response chunks from Anthropic's API.
+      # @see BaseProvider#api_response_normalize
+      # @param api_response [Anthropic::Models::Message]
+      # @return [Hash]
+      def api_response_normalize(api_response)
+        return api_response unless api_response
+
+        Anthropic::Transforms.gem_to_hash(api_response)
+      end
+
+      # Processes streaming chunks and builds message incrementally in message_stack.
       #
       # Handles chunk types: message_start, content_block_start, content_block_delta,
       # content_block_stop, message_delta, message_stop. Manages text deltas,
       # tool use inputs, and Claude's thinking/signature blocks.
       #
-      # @param api_response_chunk [Object]
+      # @see BaseProvider#process_stream_chunk
+      # @param api_response_chunk [Anthropic::StreamEvent]
       # @return [void]
       def process_stream_chunk(api_response_chunk)
-        api_response_chunk = api_response_chunk.as_json.deep_symbolize_keys
-        chunk_type = api_response_chunk[:type].to_sym
+        chunk_type = api_response_chunk[:type]&.to_sym
 
-        instrument("stream_chunk_processing.provider.active_agent", chunk_type:)
+        instrument("stream_chunk.active_agent", chunk_type:)
 
         broadcast_stream_open
 
         case chunk_type
         # Message Created
         when :message_start
-          api_message = api_response_chunk.fetch(:message)
+          api_message = Anthropic::Transforms.gem_to_hash(api_response_chunk.message)
           self.message_stack.push(api_message)
           broadcast_stream_update(message_stack.last)
 
         # -> Content Block Create
         when :content_block_start
-          api_content = api_response_chunk.fetch(:content_block)
+          api_content = Anthropic::Transforms.gem_to_hash(api_response_chunk.content_block)
           self.message_stack.last[:content].push(api_content)
           broadcast_stream_update(message_stack.last, api_content[:text])
 
         # -> -> Content Block Append
         when :content_block_delta
-          index     = api_response_chunk.fetch(:index)
+          index     = api_response_chunk.index
           content   = self.message_stack.last[:content][index]
-          api_delta = api_response_chunk.fetch(:delta)
+          api_delta = api_response_chunk.delta
 
-          case (delta_type = api_delta[:type].to_sym)
+          case api_delta.type.to_sym
           # -> -> -> Content Text Append
           when :text_delta
-            content[:text] += api_delta[:text]
-            broadcast_stream_update(message_stack.last, api_delta[:text])
+            content[:text] += api_delta.text
+            broadcast_stream_update(message_stack.last, api_delta.text)
 
           # -> -> -> Content Function Call Append
           when :input_json_delta
@@ -113,21 +160,29 @@ module ActiveAgent
           when :thinking_delta, :signature_delta
             # TODO: Add with thinking rendering support
           else
-            fail "Unexpected Delta Type #{delta_type}"
+            raise "Unexpected delta type: #{api_delta.type}"
           end
         # -> Content Block Completed [Full Block]
         when :content_block_stop
-          index       = api_response_chunk.fetch(:index)
-          api_content = api_response_chunk.fetch(:content_block)
+          index       = api_response_chunk.index
+          api_content = Anthropic::Transforms.gem_to_hash(api_response_chunk.content_block)
           self.message_stack.last[:content][index] = api_content
 
         # Message Delta
         when :message_delta
-          self.message_stack.last.merge!(api_response_chunk.fetch(:delta))
+          delta = Anthropic::Transforms.gem_to_hash(api_response_chunk.delta)
+          self.message_stack.last.merge!(delta)
 
         # Message Completed [Full Message]
         when :message_stop
-          self.message_stack[-1] = api_response_chunk.fetch(:message)
+          api_message = Anthropic::Transforms.gem_to_hash(api_response_chunk.message)
+
+          # Handle _json_buf (gem >= 1.14.0)
+          api_message[:content]&.each do |content_block|
+            content_block.delete(:_json_buf) if content_block[:type] == "tool_use"
+          end
+
+          self.message_stack[-1] = api_message
 
           # Once we are finished, close out and run tooling callbacks (Recursive)
           process_prompt_finished if message_stack.last[:stop_reason]
@@ -137,12 +192,12 @@ module ActiveAgent
           # TODO: https://docs.claude.com/en/docs/build-with-claude/streaming#error-events
         else
           # No-Op: Looks like internal tracking from gem wrapper
-          return if api_response_chunk.key?(:snapshot)
-          fail "Unexpected Chunk Type: #{api_response_chunk[:type]}"
+          return if api_response_chunk.respond_to?(:snapshot)
+          raise "Unexpected chunk type: #{api_response_chunk.type}"
         end
       end
 
-      # Executes tool calls and creates user message with results.
+      # Executes tool calls and appends user message with results to message_stack.
       #
       # @param api_function_calls [Array<Hash>] with :name, :input, and :id keys
       # @return [void]
@@ -151,58 +206,103 @@ module ActiveAgent
           process_tool_call_function(api_function_call)
         end
 
-        message = Anthropic::Requests::Messages::User.new(content:)
+        api_message = ::Anthropic::Models::MessageParam.new(role: "user", content:)
+        message     = Anthropic::Transforms.gem_to_hash(api_message)
 
-        message_stack.push(message.serialize)
+        message_stack.push(message)
       end
 
-      # Executes a single tool call and returns the result.
+      # Executes a single tool call via callback.
       #
       # @param api_function_call [Hash] with :name, :input, and :id keys
-      # @return [Anthropic::Requests::Content::ToolResult]
+      # @return [Anthropic::Models::ToolResultBlockParam]
       def process_tool_call_function(api_function_call)
-        instrument("tool_execution.provider.active_agent", tool_name: api_function_call[:name])
+        instrument("tool_call.active_agent", tool_name: api_function_call[:name]) do
+          results = tools_function.call(
+            api_function_call[:name], **api_function_call[:input]
+          )
+
+          ::Anthropic::Models::ToolResultBlockParam.new(
+            type:        "tool_result",
+            tool_use_id: api_function_call[:id],
+            content:     results.to_json,
+            is_error:    false
+          )
+        end
+      end
+
+      # 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
+
+        common_response = super(api_response_hash)
 
-        results = tools_function.call(
-          api_function_call[:name], **api_function_call[:input]
-        )
+        # 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
 
-        Anthropic::Requests::Content::ToolResult.new(
-          tool_use_id: api_function_call[:id],
-          content:     results.to_json,
-        )
+          resolve_prompt
+        else
+          common_response
+        end
       end
 
-      # Extracts messages from completed API response.
+      # Reconstructs JSON responses that were split due to Anthropic format constraints.
       #
-      # Handles JSON response format by merging the leading `{` prefix back into
-      # the message 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.
       #
-      # @param api_response [Object]
+      # @see BaseProvider#process_prompt_finished_extract_messages
+      # @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
 
-        message = api_response.as_json.deep_symbolize_keys
+        # 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
 
-        if request.response_format&.type == "json_object"
-          request.messages.pop # Remove the `Here is the JSON requested:\n{` lead in message
-          message[:content][0][:text] = "{#{message[:content][0][:text]}" # Merge in `{` prefix
+          # 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
 
-        [ message ]
+        [ api_response ]
       end
 
-      # Extracts function calls from message stack.
+      # Extracts tool_use blocks from message_stack and parses JSON inputs.
       #
-      # Processes tool_use content blocks and converts JSON buffers into proper
-      # input parameters for function execution.
+      # Handles JSON buffer parsing for gem versions and string inputs for gem >= 1.14.0.
       #
+      # @see BaseProvider#process_prompt_finished_extract_function_calls
       # @return [Array<Hash>] with :name, :input, and :id keys
       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
+
+          # Handle case where :input is still a JSON string (gem >= 1.14.0)
+          if api_function_call[:input].is_a?(String)
+            api_function_call[:input] = JSON.parse(api_function_call[:input], symbolize_names: true)
+          end
+
           api_function_call
         end
       end

data/lib/active_agent/providers/common/messages/_types.rb

@@ -37,7 +37,7 @@ module ActiveAgent
                 role = hash[:role]&.to_s
 
                 case role
-                when "system"
+                when "system", "developer"
                   nil # System messages are dropped in common format, replaced by Instructions
                 when "user", nil
                   # Handle both standard format and format with `text` key
@@ -63,6 +63,13 @@ module ActiveAgent
                 # Check if the value responds to to_common (provider-specific message)
                 if value.respond_to?(:to_common)
                   cast_message(value.to_common)
+                # Check if it's a gem model object that can be converted to hash
+                # Use JSON round-trip to ensure proper nested serialization
+                elsif value.respond_to?(:to_json)
+                  hash = JSON.parse(value.to_json, symbolize_names: true)
+                  cast_message(hash)
+                elsif value.respond_to?(:to_h)
+                  cast_message(value.to_h)
                 else
                   raise ArgumentError, "Cannot cast #{value.class} to Message"
                 end
@@ -78,7 +85,7 @@ module ActiveAgent
               when Hash
                 value
               else
-                raise ArgumentError, "Cannot serialize #{value.class}"
+                  raise ArgumentError, "Cannot serialize #{value.class}"
               end
             end
           end
@@ -88,7 +95,9 @@ module ActiveAgent
             def cast(value)
               case value
               when Array
-                value.map { |v| message_type.cast(v) }.compact
+                messages = value.map { |v| message_type.cast(v) }.compact
+                # Split messages with array content into separate messages
+                messages.flat_map { |msg| split_content_blocks(msg) }
               when nil
                 []
               else
@@ -116,6 +125,40 @@ module ActiveAgent
             def message_type
               @message_type ||= MessageType.new
             end
+
+            # Splits an assistant message with array content into separate messages
+            # for each content block.
+            #
+            # @param message [Common::Messages::Base]
+            # @return [Array<Common::Messages::Base>]
+            def split_content_blocks(message)
+              # Only split assistant messages with array content
+              return [ message ] unless message.is_a?(Common::Messages::Assistant) && message.content.is_a?(Array)
+
+              message.content.map do |block|
+                case block[:type]&.to_s
+                when "text"
+                  # Create a message for text blocks
+                  Common::Messages::Assistant.new(role: "assistant", content: block[:text], name: message.name)
+                when "tool_use"
+                  # Create a message with tool use info as string representation
+                  tool_info = "[Tool Use: #{block[:name]}]\nID: #{block[:id]}\nInput: #{JSON.pretty_generate(block[:input])}"
+                  Common::Messages::Assistant.new(role: "assistant", content: tool_info, name: message.name)
+                when "mcp_tool_use"
+                  # Create a message with MCP tool use info
+                  tool_info = "[MCP Tool Use: #{block[:name]}]\nID: #{block[:id]}\nServer: #{block[:server_name]}\nInput: #{JSON.pretty_generate(block[:input] || {})}"
+                  Common::Messages::Assistant.new(role: "assistant", content: tool_info, name: message.name)
+                when "mcp_tool_result"
+                  # Create a message with MCP tool result
+                  result_info = "[MCP Tool Result]\n#{block[:content]}"
+                  Common::Messages::Assistant.new(role: "assistant", content: result_info, name: message.name)
+                else
+                  # For unknown block types, try to extract text
+                  content = block[:text] || block.to_s
+                  Common::Messages::Assistant.new(role: "assistant", content:, name: message.name)
+                end
+              end.compact
+            end
           end
         end
       end

data/lib/active_agent/providers/common/messages/assistant.rb

@@ -9,7 +9,7 @@ module ActiveAgent
         # Represents messages sent by the AI assistant in a conversation.
         class Assistant < Base
           attribute :role, :string, as: "assistant"
-          attribute :content, :string
+          attribute :content # Accept both string and array (provider-native formats)
           attribute :name, :string
 
           validates :content, presence: true
@@ -24,9 +24,16 @@ module ActiveAgent
           # @param normalize_names [Symbol, nil] key normalization method (e.g., :underscore)
           # @return [Hash, Array, nil] parsed JSON structure or nil if parsing fails
           def parsed_json(symbolize_names: true, normalize_names: :underscore)
-            start_char       = [ content.index("{"),  content.index("[") ].compact.min
-            end_char         = [ content.rindex("}"), content.rindex("]") ].compact.max
-            content_stripped = content[start_char..end_char] if start_char && end_char
+            # Handle array content (from content blocks) by searching through each block
+            content_str = if content.is_a?(Array)
+              content.map { |block| block.is_a?(Hash) ? block[:text] : block.to_s }.join("\n")
+            else
+              content.to_s
+            end
+
+            start_char       = [ content_str.index("{"),  content_str.index("[") ].compact.min
+            end_char         = [ content_str.rindex("}"), content_str.rindex("]") ].compact.max
+            content_stripped = content_str[start_char..end_char] if start_char && end_char
             return unless content_stripped
 
             content_parsed = JSON.parse(content_stripped)
@@ -48,6 +55,15 @@ module ActiveAgent
             nil
           end
 
+          # Returns content as a string, handling both string and array formats
+          def text
+            if content.is_a?(Array)
+              content.map { |block| block.is_a?(Hash) ? block[:text] : block.to_s }.join("\n")
+            else
+              content.to_s
+            end
+          end
+
           alias_method :json_object, :parsed_json
           alias_method :parse_json,  :parsed_json
         end