activeagent 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 330c02d2e1ac16e72413f22401dbc6899f652b794d34090b0f499a37b901fbaf
-  data.tar.gz: a492f5c88db1f217fe47f9de1477f195c6b150b5dc5ce5791c66fe0f63b0b028
+  metadata.gz: 6ee3a092c5c836febf3c2e3045a1c1b2cd448edc18f3e76e4ee1ebc181f895b8
+  data.tar.gz: 9850ab912eedaac0a57f9a954648d096d6aa70ad470ff9aa7c84a18183ab76be
 SHA512:
-  metadata.gz: d8dac6789ba1f3685c24d711aace46ad5b681e9c795a975e61f07ee3c7d9a9bc44c2fd0568fabcabd739df5efd13b222c5fa6e954384bacb8bbcfdaaab0d7182
-  data.tar.gz: 8a0f61b2b5a9375c8f1b090bca29af077384079ba008622a1a510d8190acdff034c7f6b8065c1c752a2cee00dabd35d00f017db28954aacc17386fb06be63d50
+  metadata.gz: 199061594f115a823037504f84daf5ebc79b084c8a835b3e67f5427a19ffe33bbe208bb627dc26b1abf977c4d35a2977defcfb59e9128e60d94c6a3dc0ce5259
+  data.tar.gz: 661bf403014e2a0d1156614249b9fcdc352b8124e63457071ce75399ac69d089cf2d43d8b571e41614d811a5e6dc4ebc9072dfe38d912bc122672bf9823bb331

data/CHANGELOG.md

@@ -10,6 +10,77 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Major refactor with breaking changes. Complete provider rewrite. New modular architecture.
 
 **Requirements:** Ruby 3.1+, Rails 7.0+/8.0+/8.1+
+## What's Changed
+* Major Framework Refactor: ActiveAgent v1.0.0 by @sirwolfgang in https://github.com/activeagents/activeagent/pull/259
+* Add API gem version testing and fix Anthropic 1.14.0 compatibility by @sirwolfgang in https://github.com/activeagents/activeagent/pull/265
+* Fix version compatiblity issue for vitepress by @sirwolfgang in https://github.com/activeagents/activeagent/pull/266
+* Add missing API Keys by @sirwolfgang in https://github.com/activeagents/activeagent/pull/267
+* Fix website links by @sirwolfgang in https://github.com/activeagents/activeagent/pull/268
+* chore: remove `standard` from dev dependencies by @okuramasafumi in https://github.com/activeagents/activeagent/pull/272
+* Add thread safety tests by @sirwolfgang in https://github.com/activeagents/activeagent/pull/275
+* Refactor: Leverage Native Gem Types Across All Providers by @sirwolfgang in https://github.com/activeagents/activeagent/pull/271
+* Improved Usage Tracking by @sirwolfgang in https://github.com/activeagents/activeagent/pull/274
+
+## New Contributors
+* @okuramasafumi made their first contribution in https://github.com/activeagents/activeagent/pull/272
+
+**Full Changelog**: https://github.com/activeagents/activeagent/compare/v0.6.3...v1.0.0
+
+### Added
+
+**Universal Tools Format**
+```ruby
+# Single format works across all providers (Anthropic, OpenAI, OpenRouter, Ollama, Mock)
+tools: [{
+  name: "get_weather",
+  description: "Get current weather",
+  parameters: {
+    type: "object",
+    properties: {
+      location: { type: "string", description: "City and state" }
+    },
+    required: ["location"]
+  }
+}]
+
+# Tool choice normalization
+tool_choice: "auto"                   # Let model decide
+tool_choice: "required"               # Force tool use
+tool_choice: { name: "get_weather" }  # Force specific tool
+```
+
+Automatic conversion to provider-specific formats. Old formats still work (backward compatible).
+
+**Model Context Protocol (MCP) Support**
+```ruby
+# Universal MCP format works across providers (Anthropic, OpenAI)
+class MyAgent < ActiveAgent::Base
+  generate_with :anthropic, model: "claude-haiku-4-5"
+
+  def research
+    prompt(
+      message: "Research AI developments",
+      mcps: [{
+        name: "github",
+        url: "https://api.githubcopilot.com/mcp/",
+        authorization: ENV["GITHUB_MCP_TOKEN"]
+      }]
+    )
+  end
+end
+```
+
+- Common format: `{name: "server", url: "https://...", authorization: "token"}`
+- Auto-converts to provider native formats
+- Anthropic: Beta API support, up to 20 servers per request
+- OpenAI: Responses API with pre-built connectors (Dropbox, Google Drive, etc.)
+- Backwards compatible: accepts both `mcps` and `mcp_servers` parameters
+- Comprehensive documentation with tested examples
+- Full VCR test coverage with real MCP endpoints
+
+### Changed
+
+- Shared `ToolChoiceClearing` concern eliminates duplication across providers
 
 ### Breaking Changes
 

data/lib/active_agent/providers/_base_provider.rb

@@ -4,6 +4,7 @@ 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 = {
@@ -45,6 +46,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
 
@@ -200,31 +231,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 ]

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
@@ -51,12 +51,6 @@ module ActiveAgent
                 when "assistant"
                   # Filter to only known attributes for Assistant
                   filtered_hash = hash.slice(:role, :content, :name)
-
-                  # Compress content array to string if needed (Anthropic format)
-                  if filtered_hash[:content].is_a?(Array)
-                    filtered_hash[:content] = compress_content_array(filtered_hash[:content])
-                  end
-
                   Common::Messages::Assistant.new(**filtered_hash)
                 when "tool"
                   # Filter to only known attributes for Tool
@@ -94,29 +88,6 @@ module ActiveAgent
                   raise ArgumentError, "Cannot serialize #{value.class}"
               end
             end
-
-            # Compresses Anthropic-style content array into a string.
-            #
-            # Anthropic messages can have content as an array of blocks like:
-            # [{type: "text", text: "..."}, {type: "tool_use", ...}]
-            # This extracts and joins text blocks into a single string.
-            #
-            # @param content_array [Array<Hash>]
-            # @return [String]
-            def compress_content_array(content_array)
-              content_array.map do |block|
-                case block[:type]&.to_s
-                when "text"
-                  block[:text]
-                when "tool_use"
-                  # Tool use blocks don't have readable text content
-                  nil
-                else
-                  # Unknown block type, try to extract text if present
-                  block[:text]
-                end
-              end.compact.join("\n")
-            end
           end
 
           # Type for Messages array
@@ -124,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
@@ -152,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

data/lib/active_agent/providers/concerns/previewable.rb

@@ -86,7 +86,13 @@ module ActiveAgent
         "### Message #{index} (#{role.capitalize})\n#{content}"
       end
 
-      # Renders available tools with descriptions and parameter schemas.
+      # Renders tools section for preview.
+      #
+      # Handles multiple tool formats:
+      # - Common format: {name: "...", description: "...", parameters: {...}}
+      # - Anthropic format: {name: "...", description: "...", input_schema: {...}}
+      # - Chat API format: {type: "function", function: {name: "...", description: "...", parameters: {...}}}
+      # - Responses API format: {type: "function", name: "...", description: "...", parameters: {...}}
       #
       # @param tools [Array<Hash>]
       # @return [String]
@@ -96,17 +102,45 @@ module ActiveAgent
         content = +"## Tools\n\n"
 
         tools.each_with_index do |tool, index|
-          content << "### #{tool[:name] || "Tool #{index + 1}"}\n"
-          content << "**Description:** #{tool[:description] || 'No description'}\n\n"
+          # Extract name and description from different formats
+          tool_name, tool_description, tool_params = extract_tool_details(tool)
+
+          content << "### #{tool_name || "Tool #{index + 1}"}\n"
+          content << "**Description:** #{tool_description || 'No description'}\n\n"
 
-          if tool[:parameters]
-            content << "**Parameters:**\n```json\n#{JSON.pretty_generate(tool[:parameters])}\n```\n\n"
+          if tool_params
+            content << "**Parameters:**\n```json\n#{JSON.pretty_generate(tool_params)}\n```\n\n"
           end
         end
 
         content.chomp
       end
 
+      # Extracts tool details from different formats.
+      #
+      # @param tool [Hash]
+      # @return [Array<String, String, Hash>] [name, description, parameters]
+      def extract_tool_details(tool)
+        tool_hash = tool.is_a?(Hash) ? tool : {}
+
+        # Chat API nested format: {type: "function", function: {...}}
+        if tool_hash[:type] == "function" && tool_hash[:function]
+          func = tool_hash[:function]
+          return [
+            func[:name],
+            func[:description],
+            func[:parameters] || func[:input_schema]
+          ]
+        end
+
+        # Flat formats (common, Anthropic, Responses)
+        [
+          tool_hash[:name],
+          tool_hash[:description],
+          tool_hash[:parameters] || tool_hash[:input_schema]
+        ]
+      end
+
       # Extracts text content from various message formats.
       #
       # Handles string messages, hash messages with :content key, and

data/lib/active_agent/providers/concerns/tool_choice_clearing.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    # Provides unified logic for clearing tool_choice after tool execution.
+    #
+    # When a tool_choice is set to "required" or to a specific tool name,
+    # it forces the model to use that tool. After the tool is executed,
+    # we need to clear the tool_choice to prevent infinite loops where
+    # the model keeps calling the same tool repeatedly.
+    #
+    # Each provider implements:
+    # - `extract_used_function_names`: Returns array of tool names that have been called
+    # - `tool_choice_forces_required?`: Returns true if tool_choice forces any tool use
+    # - `tool_choice_forces_specific?`: Returns [true, name] if tool_choice forces specific tool
+    module ToolChoiceClearing
+      extend ActiveSupport::Concern
+
+      # @api private
+      def prepare_prompt_request_tools
+        return unless request.tool_choice
+
+        functions_used = extract_used_function_names
+
+        # Clear if forcing required and any tool was used
+        if tool_choice_forces_required? && functions_used.any?
+          request.tool_choice = nil
+          return
+        end
+
+        # Clear if forcing specific tool and that tool was used
+        forces_specific, tool_name = tool_choice_forces_specific?
+        if forces_specific && tool_name && functions_used.include?(tool_name)
+          request.tool_choice = nil
+        end
+      end
+
+      private
+
+      # Extracts the list of function names that have been called.
+      #
+      # @return [Array<String>] function names
+      def extract_used_function_names
+        raise NotImplementedError, "#{self.class} must implement #extract_used_function_names"
+      end
+
+      # Returns true if tool_choice forces any tool to be used (e.g., "required", "any").
+      #
+      # @return [Boolean]
+      def tool_choice_forces_required?
+        raise NotImplementedError, "#{self.class} must implement #tool_choice_forces_required?"
+      end
+
+      # Returns [true, tool_name] if tool_choice forces a specific tool, [false, nil] otherwise.
+      #
+      # @return [Array<Boolean, String|nil>]
+      def tool_choice_forces_specific?
+        raise NotImplementedError, "#{self.class} must implement #tool_choice_forces_specific?"
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_ai/chat/transforms.rb

@@ -24,8 +24,8 @@ module ActiveAgent
             # Normalizes all request parameters for OpenAI Chat API
             #
             # Handles instructions mapping to developer messages, message normalization,
-            # and response_format conversion. This is the main entry point for parameter
-            # transformation.
+            # tools normalization, and response_format conversion. This is the main entry point
+            # for parameter transformation.
             #
             # @param params [Hash]
             # @return [Hash] normalized parameters
@@ -41,6 +41,12 @@ module ActiveAgent
               # Normalize messages for gem compatibility
               params[:messages] = normalize_messages(params[:messages]) if params[:messages]
 
+              # Normalize tools from common format to Chat API format
+              params[:tools] = normalize_tools(params[:tools]) if params[:tools]
+
+              # Normalize tool_choice from common format
+              params[:tool_choice] = normalize_tool_choice(params[:tool_choice]) if params[:tool_choice]
+
               # Normalize response_format if present
               params[:response_format] = normalize_response_format(params[:response_format]) if params[:response_format]
 
@@ -68,7 +74,8 @@ module ActiveAgent
                 messages.each do |msg|
                   normalized = normalize_message(msg)
 
-                  if grouped.empty? || grouped.last.role != normalized.role
+                  # Don't merge tool messages - each needs its own tool_call_id
+                  if grouped.empty? || grouped.last.role != normalized.role || normalized.role.to_s == "tool"
                     grouped << normalized
                   else
                     # Merge consecutive same-role messages
@@ -307,6 +314,79 @@ module ActiveAgent
               end
             end
 
+            # Normalizes tools from common format to OpenAI Chat API format.
+            #
+            # Accepts tools in multiple formats:
+            # - Common format: `{name: "...", description: "...", parameters: {...}}`
+            # - Common format alt: `{name: "...", description: "...", input_schema: {...}}`
+            # - Nested format: `{type: "function", function: {name: "...", parameters: {...}}}`
+            #
+            # Always outputs nested Chat API format: `{type: "function", function: {...}}`
+            #
+            # @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
+
+                # Already in nested format - return as is
+                if tool_hash[:type] == "function" && tool_hash[:function]
+                  tool_hash
+                # Common format - convert to nested format
+                elsif tool_hash[:name]
+                  {
+                    type: "function",
+                    function: {
+                      name: tool_hash[:name],
+                      description: tool_hash[:description],
+                      parameters: tool_hash[:parameters] || tool_hash[:input_schema]
+                    }.compact
+                  }
+                else
+                  tool_hash
+                end
+              end
+            end
+
+            # Normalizes tool_choice from common format to OpenAI Chat API format.
+            #
+            # Accepts:
+            # - "auto" (common) → "auto" (passthrough)
+            # - "required" (common) → "required" (passthrough)
+            # - `{name: "..."}` (common) → `{type: "function", function: {name: "..."}}`
+            # - Already nested format → passthrough
+            #
+            # @param tool_choice [String, Hash, Symbol]
+            # @return [String, Hash, Symbol]
+            def normalize_tool_choice(tool_choice)
+              case tool_choice
+              when "auto", :auto, "required", :required
+                # Passthrough - Chat API accepts these directly
+                tool_choice.to_s
+              when Hash
+                tool_choice_hash = tool_choice.deep_symbolize_keys
+
+                # Already in nested format with type and function keys
+                if tool_choice_hash[:type] == "function" && tool_choice_hash[:function]
+                  tool_choice_hash
+                # Common format with just name - convert to nested format
+                elsif tool_choice_hash[:name]
+                  {
+                    type: "function",
+                    function: {
+                      name: tool_choice_hash[:name]
+                    }
+                  }
+                else
+                  tool_choice_hash
+                end
+              else
+                tool_choice
+              end
+            end
+
             # Normalizes instructions to developer message format
             #
             # Converts instructions into developer messages with proper content structure.

data/lib/active_agent/providers/open_ai/chat_provider.rb

@@ -12,6 +12,8 @@ module ActiveAgent
       # @see Base
       # @see https://platform.openai.com/docs/api-reference/chat
       class ChatProvider < Base
+        include ToolChoiceClearing
+
         # @return [Class] the options class for this provider
         def self.options_klass
           Options
@@ -30,6 +32,42 @@ module ActiveAgent
           client.chat.completions
         end
 
+        # @see BaseProvider#prepare_prompt_request
+        # @return [Request]
+        def prepare_prompt_request
+          prepare_prompt_request_tools
+          super
+        end
+
+        # Extracts function names from Chat API tool_calls in assistant messages.
+        #
+        # @return [Array<String>]
+        def extract_used_function_names
+          message_stack
+            .select { |msg| msg[:role] == "assistant" && msg[:tool_calls] }
+            .flat_map { |msg| msg[:tool_calls] }
+            .map { |tc| tc.dig(:function, :name) }
+            .compact
+        end
+
+        # Returns true if tool_choice == "required".
+        #
+        # @return [Boolean]
+        def tool_choice_forces_required?
+          request.tool_choice == "required"
+        end
+
+        # Returns [true, name] if tool_choice is a hash with nested function name.
+        #
+        # @return [Array<Boolean, String|nil>]
+        def tool_choice_forces_specific?
+          if request.tool_choice.is_a?(Hash)
+            [ true, request.tool_choice.dig(:function, :name) ]
+          else
+            [ false, nil ]
+          end
+        end
+
         # @see BaseProvider#api_response_normalize
         # @param api_response [OpenAI::Models::ChatCompletion]
         # @return [Hash] normalized response hash

data/lib/active_agent/providers/open_ai/responses/request.rb

@@ -73,10 +73,25 @@ module ActiveAgent
             # Step 6: Normalize input content for gem compatibility
             params[:input] = Responses::Transforms.normalize_input(params[:input]) if params[:input]
 
-            # Step 7: Create gem model - delegates to OpenAI gem
+            # Step 7: Normalize tools and tool_choice from common format
+            params[:tools] = Responses::Transforms.normalize_tools(params[:tools]) if params[:tools]
+            params[:tool_choice] = Responses::Transforms.normalize_tool_choice(params[:tool_choice]) if params[:tool_choice]
+
+            # Step 8: Normalize MCP servers from common format (mcps parameter)
+            # OpenAI treats MCP servers as a special type of tool in the tools array
+            mcp_param = params[:mcps] || params[:mcp_servers]
+            if mcp_param&.any?
+              normalized_mcp_tools = Responses::Transforms.normalize_mcp_servers(mcp_param)
+              params.delete(:mcps)
+              params.delete(:mcp_servers)
+              # Merge MCP servers into tools array
+              params[:tools] = (params[:tools] || []) + normalized_mcp_tools
+            end
+
+            # Step 9: Create gem model - delegates to OpenAI gem
             gem_model = ::OpenAI::Models::Responses::ResponseCreateParams.new(**params)
 
-            # Step 8: Delegate all method calls to gem model
+            # Step 10: Delegate all method calls to gem model
             super(gem_model)
           rescue ArgumentError => e
             # Re-raise with more context

data/lib/active_agent/providers/open_ai/responses/transforms.rb

@@ -21,6 +21,141 @@ module ActiveAgent
               JSON.parse(gem_object.to_json, symbolize_names: true)
             end
 
+            # Normalizes tools from common format to OpenAI Responses API format.
+            #
+            # Accepts tools in multiple formats:
+            # - Common format: `{name: "...", description: "...", parameters: {...}}`
+            # - Nested format: `{type: "function", function: {name: "...", ...}}`
+            # - Responses format: `{type: "function", name: "...", parameters: {...}}`
+            #
+            # Always outputs flat Responses API format.
+            #
+            # @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 Responses format (flat with type, name, parameters), return as-is
+                if tool_hash[:type] == "function" && tool_hash[:name]
+                  next tool_hash
+                end
+
+                # If in nested Chat API format, flatten it
+                if tool_hash[:type] == "function" && tool_hash[:function]
+                  func = tool_hash[:function]
+                  next {
+                    type: "function",
+                    name: func[:name],
+                    description: func[:description],
+                    parameters: func[:parameters] || func[:input_schema]
+                  }.compact
+                end
+
+                # If in common format (no type field), convert to Responses format
+                if tool_hash[:name] && !tool_hash[:type]
+                  next {
+                    type: "function",
+                    name: tool_hash[:name],
+                    description: tool_hash[:description],
+                    parameters: tool_hash[:parameters] || tool_hash[:input_schema]
+                  }.compact
+                end
+
+                # Pass through other formats
+                tool_hash
+              end
+            end
+
+            # Normalizes MCP servers from common format to OpenAI Responses API format.
+            #
+            # Common format:
+            #   {name: "stripe", url: "https://...", authorization: "token"}
+            # OpenAI format:
+            #   {type: "mcp", server_label: "stripe", server_url: "https://...", authorization: "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 OpenAI format (has type: "mcp" and server_label), return as-is
+                if server_hash[:type] == "mcp" && server_hash[:server_label]
+                  next server_hash
+                end
+
+                # Convert common format to OpenAI format
+                result = {
+                  type: "mcp",
+                  server_label: server_hash[:name] || server_hash[:server_label],
+                  server_url: server_hash[:url] || server_hash[:server_url]
+                }
+
+                # Keep authorization field (OpenAI uses 'authorization', not 'authorization_token')
+                if server_hash[:authorization]
+                  result[:authorization] = server_hash[:authorization]
+                end
+
+                result.compact
+              end
+            end
+
+            # Normalizes tool_choice from common format to OpenAI Responses API format.
+            #
+            # Responses API uses flat format for specific tool choice, unlike Chat API's nested format.
+            # Must return gem model objects for proper serialization.
+            #
+            # Maps:
+            # - "required" → :required symbol (force tool use)
+            # - "auto" → :auto symbol (let model decide)
+            # - { name: "..." } → ToolChoiceFunction model object
+            #
+            # @param tool_choice [String, Hash, Object]
+            # @return [Symbol, Object] Symbol or 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?(::OpenAI::Models::Responses::ToolChoiceFunction) ||
+                                     tool_choice.is_a?(::OpenAI::Models::Responses::ToolChoiceAllowed) ||
+                                     tool_choice.is_a?(::OpenAI::Models::Responses::ToolChoiceTypes) ||
+                                     tool_choice.is_a?(::OpenAI::Models::Responses::ToolChoiceMcp) ||
+                                     tool_choice.is_a?(::OpenAI::Models::Responses::ToolChoiceCustom)
+
+              case tool_choice
+              when "required"
+                :required  # Return as symbol
+              when "auto"
+                :auto  # Return as symbol
+              when "none"
+                :none  # Return as symbol
+              when Hash
+                choice_hash = tool_choice.deep_symbolize_keys
+
+                # If already in proper format with type, try to create gem model
+                if choice_hash[:type] == "function" && choice_hash[:name]
+                  # Create ToolChoiceFunction gem model object
+                  ::OpenAI::Models::Responses::ToolChoiceFunction.new(
+                    type: :function,
+                    name: choice_hash[:name]
+                  )
+                # Convert { name: "..." } to ToolChoiceFunction model
+                elsif choice_hash[:name] && !choice_hash[:type]
+                  ::OpenAI::Models::Responses::ToolChoiceFunction.new(
+                    type: :function,
+                    name: choice_hash[:name]
+                  )
+                else
+                  choice_hash
+                end
+              else
+                tool_choice
+              end
+            end
+
             # Simplifies input for cleaner API requests
             #
             # Unwraps single-element arrays:

data/lib/active_agent/providers/open_ai/responses_provider.rb

@@ -13,6 +13,8 @@ module ActiveAgent
       # @see Base
       # @see https://platform.openai.com/docs/api-reference/responses
       class ResponsesProvider < Base
+        include ToolChoiceClearing
+
         # @return [Class]
         def self.options_klass
           Options
@@ -25,6 +27,42 @@ module ActiveAgent
 
         protected
 
+        # @see BaseProvider#prepare_prompt_request
+        # @return [Request]
+        def prepare_prompt_request
+          prepare_prompt_request_tools
+
+          super
+        end
+
+        # Extracts function names from Responses API function_call items.
+        #
+        # @return [Array<String>]
+        def extract_used_function_names
+          message_stack
+            .select { |item| item[:type] == "function_call" }
+            .map { |item| item[:name] }
+            .compact
+        end
+
+        # Returns true if tool_choice == :required.
+        #
+        # @return [Boolean]
+        def tool_choice_forces_required?
+          request.tool_choice == :required
+        end
+
+        # Returns [true, name] if tool_choice is a ToolChoiceFunction model object.
+        #
+        # @return [Array<Boolean, String|nil>]
+        def tool_choice_forces_specific?
+          if request.tool_choice.is_a?(::OpenAI::Models::Responses::ToolChoiceFunction)
+            [ true, request.tool_choice.name ]
+          else
+            [ false, nil ]
+          end
+        end
+
         # @return [Object] OpenAI client's responses endpoint
         def api_prompt_executer
           client.responses

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

@@ -148,6 +148,26 @@ module ActiveAgent
           self.messages = instructions_messages + current_messages
         end
 
+        # Gets tool_choice bypassing gem validation
+        #
+        # OpenRouter supports "any" which isn't valid in OpenAI gem types.
+        #
+        # @return [String, Hash, nil]
+        def tool_choice
+          __getobj__.instance_variable_get(:@data)[:tool_choice]
+        end
+
+        # Sets tool_choice bypassing gem validation
+        #
+        # OpenRouter supports "any" which isn't valid in OpenAI gem types,
+        # so we bypass the gem's type validation by setting @data directly.
+        #
+        # @param value [String, Hash, nil]
+        # @return [void]
+        def tool_choice=(value)
+          __getobj__.instance_variable_get(:@data)[:tool_choice] = value
+        end
+
         # Accessor for OpenRouter-specific provider preferences
         #
         # @return [Hash, nil]

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

@@ -62,9 +62,39 @@ module ActiveAgent
             # Use OpenAI transforms for the base parameters
             openai_params = OpenAI::Chat::Transforms.normalize_params(params)
 
+            # Override tool_choice normalization for OpenRouter's "any" vs "required" difference
+            if openai_params[:tool_choice]
+              openai_params[:tool_choice] = normalize_tool_choice(openai_params[:tool_choice])
+            end
+
             [ openai_params, openrouter_params ]
           end
 
+          # Normalizes tools using OpenAI transforms
+          #
+          # @param tools [Array<Hash>]
+          # @return [Array<Hash>]
+          def normalize_tools(tools)
+            OpenAI::Chat::Transforms.normalize_tools(tools)
+          end
+
+          # Normalizes tool_choice for OpenRouter API differences
+          #
+          # OpenRouter uses "any" instead of OpenAI's "required" for forcing tool use.
+          # Converts common format to OpenRouter-specific format:
+          # - "required" (common) → "any" (OpenRouter)
+          # - Everything else delegates to OpenAI transforms
+          #
+          # @param tool_choice [String, Hash, Symbol]
+          # @return [String, Hash, Symbol]
+          def normalize_tool_choice(tool_choice)
+            # Convert "required" to OpenRouter's "any"
+            return "any" if tool_choice.to_s == "required"
+
+            # For everything else, use OpenAI transforms
+            OpenAI::Chat::Transforms.normalize_tool_choice(tool_choice)
+          end
+
           # Normalizes messages using OpenAI transforms
           #
           # @param messages [Array, String, Hash, nil]

data/lib/active_agent/providers/open_router_provider.rb

@@ -33,6 +33,20 @@ module ActiveAgent
 
       protected
 
+      # @see BaseProvider#prepare_prompt_request
+      # @return [Request]
+      def prepare_prompt_request
+        prepare_prompt_request_tools
+        super
+      end
+
+      # Returns true if tool_choice == "any" (OpenRouter's equivalent of "required").
+      #
+      # @return [Boolean]
+      def tool_choice_forces_required?
+        request.tool_choice == "any"
+      end
+
       # Merges streaming delta into the message with role cleanup.
       #
       # Overrides parent to handle OpenRouter's role copying behavior which duplicates

data/lib/active_agent/version.rb

@@ -1,3 +1,3 @@
 module ActiveAgent
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activeagent
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Justin Bowen
@@ -129,14 +129,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 8.0.0
+        version: 8.1.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 8.0.0
+        version: 8.1.1
 - !ruby/object:Gem::Dependency
   name: anthropic
   requirement: !ruby/object:Gem::Requirement
@@ -386,6 +386,7 @@ files:
 - lib/active_agent/providers/concerns/exception_handler.rb
 - lib/active_agent/providers/concerns/instrumentation.rb
 - lib/active_agent/providers/concerns/previewable.rb
+- lib/active_agent/providers/concerns/tool_choice_clearing.rb
 - lib/active_agent/providers/log_subscriber.rb
 - lib/active_agent/providers/mock/_types.rb
 - lib/active_agent/providers/mock/embedding_request.rb
@@ -472,7 +473,7 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/activeagents/activeagent/issues
-  documentation_uri: https://github.com/activeagents/activeagent
+  documentation_uri: https://docs.activeagents.ai
   source_code_uri: https://github.com/activeagents/activeagent
   rubygems_mfa_required: 'true'
 rdoc_options: []