feat(ee): Captain custom http tools (#12584)

To test this out, use the following PR:
https://github.com/chatwoot/chatwoot/pull/12585

---------

Co-authored-by: Pranav <pranavrajs@gmail.com>

enterprise/app/controllers/api/v1/accounts/captain/assistants_controller.rb

@@ -33,7 +33,8 @@ class Api::V1::Accounts::Captain::AssistantsController < Api::V1::Accounts::Base
   end
 
   def tools
-    @tools = Captain::Assistant.available_agent_tools
+    assistant = Captain::Assistant.new(account: Current.account)
+    @tools = assistant.available_agent_tools
   end
 
   private

enterprise/app/models/captain/assistant.rb

@@ -50,6 +50,19 @@ class Captain::Assistant < ApplicationRecord
     name
   end
 
+  def available_agent_tools
+    tools = self.class.built_in_agent_tools.dup
+
+    custom_tools = account.captain_custom_tools.enabled.map(&:to_tool_metadata)
+    tools.concat(custom_tools)
+
+    tools
+  end
+
+  def available_tool_ids
+    available_agent_tools.pluck(:id)
+  end
+
   def push_event_data
     {
       id: id,

enterprise/app/models/captain/custom_tool.rb

@@ -0,0 +1,91 @@
+# == Schema Information
+#
+# Table name: captain_custom_tools
+#
+#  id                :bigint           not null, primary key
+#  auth_config       :jsonb
+#  auth_type         :string           default("none")
+#  description       :text
+#  enabled           :boolean          default(TRUE), not null
+#  endpoint_url      :text             not null
+#  http_method       :string           default("GET"), not null
+#  param_schema      :jsonb
+#  request_template  :text
+#  response_template :text
+#  slug              :string           not null
+#  title             :string           not null
+#  created_at        :datetime         not null
+#  updated_at        :datetime         not null
+#  account_id        :bigint           not null
+#
+# Indexes
+#
+#  index_captain_custom_tools_on_account_id           (account_id)
+#  index_captain_custom_tools_on_account_id_and_slug  (account_id,slug) UNIQUE
+#
+class Captain::CustomTool < ApplicationRecord
+  include Concerns::Toolable
+  include Concerns::SafeEndpointValidatable
+
+  self.table_name = 'captain_custom_tools'
+
+  PARAM_SCHEMA_VALIDATION = {
+    'type': 'array',
+    'items': {
+      'type': 'object',
+      'properties': {
+        'name': { 'type': 'string' },
+        'type': { 'type': 'string' },
+        'description': { 'type': 'string' },
+        'required': { 'type': 'boolean' }
+      },
+      'required': %w[name type description],
+      'additionalProperties': false
+    }
+  }.to_json.freeze
+
+  belongs_to :account
+
+  enum :http_method, %w[GET POST].index_by(&:itself), validate: true
+  enum :auth_type, %w[none bearer basic api_key].index_by(&:itself), default: :none, validate: true, prefix: :auth
+
+  before_validation :generate_slug
+
+  validates :slug, presence: true, uniqueness: { scope: :account_id }
+  validates :title, presence: true
+  validates :endpoint_url, presence: true
+  validates_with JsonSchemaValidator,
+                 schema: PARAM_SCHEMA_VALIDATION,
+                 attribute_resolver: ->(record) { record.param_schema }
+
+  scope :enabled, -> { where(enabled: true) }
+
+  def to_tool_metadata
+    {
+      id: slug,
+      title: title,
+      description: description,
+      custom: true
+    }
+  end
+
+  private
+
+  def generate_slug
+    return if slug.present?
+
+    base_slug = title.present? ? "custom_#{title.parameterize}" : "custom_#{SecureRandom.uuid}"
+    self.slug = find_unique_slug(base_slug)
+  end
+
+  def find_unique_slug(base_slug, counter = 0)
+    slug_candidate = counter.zero? ? base_slug : "#{base_slug}-#{counter}"
+    return find_unique_slug(base_slug, counter + 1) if slug_exists?(slug_candidate)
+
+    slug_candidate
+  end
+
+  def slug_exists?(candidate)
+    self.class.exists?(account_id: account_id, slug: candidate)
+  end
+end

enterprise/app/models/captain/scenario.rb

@@ -57,7 +57,7 @@ class Captain::Scenario < ApplicationRecord
   end
 
   def agent_tools
-    resolved_tools.map { |tool| self.class.resolve_tool_class(tool[:id]) }.map { |tool| tool.new(assistant) }
+    resolved_tools.map { |tool| resolve_tool_instance(tool) }
   end
 
   def resolved_instructions
@@ -69,12 +69,24 @@ class Captain::Scenario < ApplicationRecord
   def resolved_tools
     return [] if tools.blank?
 
-    available_tools = self.class.available_agent_tools
+    available_tools = assistant.available_agent_tools
     tools.filter_map do |tool_id|
       available_tools.find { |tool| tool[:id] == tool_id }
     end
   end
 
+  def resolve_tool_instance(tool_metadata)
+    tool_id = tool_metadata[:id]
+
+    if tool_metadata[:custom]
+      custom_tool = Captain::CustomTool.find_by(slug: tool_id, account_id: account_id, enabled: true)
+      custom_tool&.tool(assistant)
+    else
+      tool_class = self.class.resolve_tool_class(tool_id)
+      tool_class&.new(assistant)
+    end
+  end
+
   # Validates that all tool references in the instruction are valid.
   # Parses the instruction for tool references and checks if they exist
   # in the available tools configuration.
@@ -95,8 +107,8 @@ class Captain::Scenario < ApplicationRecord
     tool_ids = extract_tool_ids_from_text(instruction)
     return if tool_ids.empty?
 
-    available_tool_ids = self.class.available_tool_ids
-    invalid_tools = tool_ids - available_tool_ids
+    all_available_tool_ids = assistant.available_tool_ids
+    invalid_tools = tool_ids - all_available_tool_ids
 
     return unless invalid_tools.any?
 

enterprise/app/models/concerns/captain_tools_helpers.rb

@@ -8,12 +8,12 @@ module Concerns::CaptainToolsHelpers
   TOOL_REFERENCE_REGEX = %r{\[[^\]]+\]\(tool://([^/)]+)\)}
 
   class_methods do
-    # Returns all available agent tools with their metadata.
+    # Returns all built-in agent tools with their metadata.
     # Only includes tools that have corresponding class files and can be resolved.
     #
     # @return [Array<Hash>] Array of tool hashes with :id, :title, :description, :icon
-    def available_agent_tools
-      @available_agent_tools ||= load_agent_tools
+    def built_in_agent_tools
+      @built_in_agent_tools ||= load_agent_tools
     end
 
     # Resolves a tool class from a tool ID.
@@ -26,12 +26,12 @@ module Concerns::CaptainToolsHelpers
       class_name.safe_constantize
     end
 
-    # Returns an array of all available tool IDs.
-    # Convenience method that extracts just the IDs from available_agent_tools.
+    # Returns an array of all built-in tool IDs.
+    # Convenience method that extracts just the IDs from built_in_agent_tools.
     #
-    # @return [Array<String>] Array of available tool IDs
-    def available_tool_ids
-      @available_tool_ids ||= available_agent_tools.map { |tool| tool[:id] }
+    # @return [Array<String>] Array of built-in tool IDs
+    def built_in_tool_ids
+      @built_in_tool_ids ||= built_in_agent_tools.map { |tool| tool[:id] }
     end
 
     private

enterprise/app/models/concerns/safe_endpoint_validatable.rb

@@ -0,0 +1,84 @@
+module Concerns::SafeEndpointValidatable
+  extend ActiveSupport::Concern
+
+  FRONTEND_HOST = URI.parse(ENV.fetch('FRONTEND_URL', 'http://localhost:3000')).host.freeze
+  DISALLOWED_HOSTS = ['localhost', /\.local\z/i].freeze
+
+  included do
+    validate :validate_safe_endpoint_url
+  end
+
+  private
+
+  def validate_safe_endpoint_url
+    return if endpoint_url.blank?
+
+    uri = parse_endpoint_uri
+    return errors.add(:endpoint_url, 'must be a valid URL') unless uri
+
+    validate_endpoint_scheme(uri)
+    validate_endpoint_host(uri)
+    validate_not_ip_address(uri)
+    validate_no_unicode_chars(uri)
+  end
+
+  def parse_endpoint_uri
+    # Strip Liquid template syntax for validation
+    # Replace {{ variable }} with a placeholder value
+    sanitized_url = endpoint_url.gsub(/\{\{[^}]+\}\}/, 'placeholder')
+    URI.parse(sanitized_url)
+  rescue URI::InvalidURIError
+    nil
+  end
+
+  def validate_endpoint_scheme(uri)
+    return if uri.scheme == 'https'
+
+    errors.add(:endpoint_url, 'must use HTTPS protocol')
+  end
+
+  def validate_endpoint_host(uri)
+    if uri.host.blank?
+      errors.add(:endpoint_url, 'must have a valid hostname')
+      return
+    end
+
+    if uri.host == FRONTEND_HOST
+      errors.add(:endpoint_url, 'cannot point to the application itself')
+      return
+    end
+
+    DISALLOWED_HOSTS.each do |pattern|
+      matched = if pattern.is_a?(Regexp)
+                  uri.host =~ pattern
+                else
+                  uri.host.downcase == pattern
+                end
+
+      next unless matched
+
+      errors.add(:endpoint_url, 'cannot use disallowed hostname')
+      break
+    end
+  end
+
+  def validate_not_ip_address(uri)
+    # Check for IPv4
+    if /\A\d+\.\d+\.\d+\.\d+\z/.match?(uri.host)
+      errors.add(:endpoint_url, 'cannot be an IP address, must be a hostname')
+      return
+    end
+
+    # Check for IPv6
+    return unless uri.host.include?(':')
+
+    errors.add(:endpoint_url, 'cannot be an IP address, must be a hostname')
+  end
+
+  def validate_no_unicode_chars(uri)
+    return unless uri.host
+    return if /\A[\x00-\x7F]+\z/.match?(uri.host)
+
+    errors.add(:endpoint_url, 'hostname cannot contain non-ASCII characters')
+  end
+end

enterprise/app/models/concerns/toolable.rb

@@ -0,0 +1,78 @@
+module Concerns::Toolable
+  extend ActiveSupport::Concern
+
+  def tool(assistant)
+    custom_tool_record = self
+
+    tool_class = Class.new(Captain::Tools::HttpTool) do
+      description custom_tool_record.description
+
+      custom_tool_record.param_schema.each do |param_def|
+        param param_def['name'].to_sym,
+              type: param_def['type'],
+              desc: param_def['description'],
+              required: param_def.fetch('required', true)
+      end
+    end
+
+    tool_class.new(assistant, self)
+  end
+
+  def build_request_url(params)
+    return endpoint_url if endpoint_url.blank? || endpoint_url.exclude?('{{')
+
+    render_template(endpoint_url, params)
+  end
+
+  def build_request_body(params)
+    return nil if request_template.blank?
+
+    render_template(request_template, params)
+  end
+
+  def build_auth_headers
+    return {} if auth_none?
+
+    case auth_type
+    when 'bearer'
+      { 'Authorization' => "Bearer #{auth_config['token']}" }
+    when 'api_key'
+      if auth_config['location'] == 'header'
+        { auth_config['name'] => auth_config['key'] }
+      else
+        {}
+      end
+    else
+      {}
+    end
+  end
+
+  def build_basic_auth_credentials
+    return nil unless auth_type == 'basic'
+
+    [auth_config['username'], auth_config['password']]
+  end
+
+  def format_response(raw_response_body)
+    return raw_response_body if response_template.blank?
+
+    response_data = parse_response_body(raw_response_body)
+    render_template(response_template, { 'response' => response_data })
+  end
+
+  private
+
+  def render_template(template, context)
+    liquid_template = Liquid::Template.parse(template, error_mode: :strict)
+    liquid_template.render(context.deep_stringify_keys, registers: {}, strict_variables: true, strict_filters: true)
+  rescue Liquid::SyntaxError, Liquid::UndefinedVariable, Liquid::UndefinedFilter => e
+    Rails.logger.error("Liquid template error: #{e.message}")
+    raise "Template rendering failed: #{e.message}"
+  end
+
+  def parse_response_body(body)
+    JSON.parse(body)
+  rescue JSON::ParserError
+    body
+  end
+end

enterprise/app/models/enterprise/concerns/account.rb

@@ -10,6 +10,7 @@ module Enterprise::Concerns::Account
     has_many :captain_assistants, dependent: :destroy_async, class_name: 'Captain::Assistant'
     has_many :captain_assistant_responses, dependent: :destroy_async, class_name: 'Captain::AssistantResponse'
     has_many :captain_documents, dependent: :destroy_async, class_name: 'Captain::Document'
+    has_many :captain_custom_tools, dependent: :destroy_async, class_name: 'Captain::CustomTool'
 
     has_many :copilot_threads, dependent: :destroy_async
     has_many :voice_channels, dependent: :destroy_async, class_name: '::Channel::Voice'

enterprise/lib/captain/tools/http_tool.rb

@@ -0,0 +1,105 @@
+require 'agents'
+
+class Captain::Tools::HttpTool < Agents::Tool
+  def initialize(assistant, custom_tool)
+    @assistant = assistant
+    @custom_tool = custom_tool
+    super()
+  end
+
+  def active?
+    @custom_tool.enabled?
+  end
+
+  def perform(_tool_context, **params)
+    url = @custom_tool.build_request_url(params)
+    body = @custom_tool.build_request_body(params)
+
+    response = execute_http_request(url, body)
+    @custom_tool.format_response(response.body)
+  rescue StandardError => e
+    Rails.logger.error("HttpTool execution error for #{@custom_tool.slug}: #{e.class} - #{e.message}")
+    'An error occurred while executing the request'
+  end
+
+  private
+
+  PRIVATE_IP_RANGES = [
+    IPAddr.new('127.0.0.0/8'),    # IPv4 Loopback
+    IPAddr.new('10.0.0.0/8'),     # IPv4 Private network
+    IPAddr.new('172.16.0.0/12'),  # IPv4 Private network
+    IPAddr.new('192.168.0.0/16'), # IPv4 Private network
+    IPAddr.new('169.254.0.0/16'), # IPv4 Link-local
+    IPAddr.new('::1'),            # IPv6 Loopback
+    IPAddr.new('fc00::/7'),       # IPv6 Unique local addresses
+    IPAddr.new('fe80::/10')       # IPv6 Link-local
+  ].freeze
+
+  # Limit response size to prevent memory exhaustion and match LLM token limits
+  # 1MB of text ≈ 250K tokens, which exceeds most LLM context windows
+  MAX_RESPONSE_SIZE = 1.megabyte
+
+  def execute_http_request(url, body)
+    uri = URI.parse(url)
+
+    # Check if resolved IP is private
+    check_private_ip!(uri.host)
+
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = uri.scheme == 'https'
+    http.read_timeout = 30
+    http.open_timeout = 10
+    http.max_retries = 0 # Disable redirects
+
+    request = build_http_request(uri, body)
+    apply_authentication(request)
+
+    response = http.request(request)
+
+    raise "HTTP request failed with status #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+    validate_response!(response)
+
+    response
+  end
+
+  def check_private_ip!(hostname)
+    ip_address = IPAddr.new(Resolv.getaddress(hostname))
+
+    raise 'Request blocked: hostname resolves to private IP address' if PRIVATE_IP_RANGES.any? { |range| range.include?(ip_address) }
+  rescue Resolv::ResolvError, SocketError => e
+    raise "DNS resolution failed: #{e.message}"
+  end
+
+  def validate_response!(response)
+    content_length = response['content-length']&.to_i
+    if content_length && content_length > MAX_RESPONSE_SIZE
+      raise "Response size #{content_length} bytes exceeds maximum allowed #{MAX_RESPONSE_SIZE} bytes"
+    end
+
+    return unless response.body && response.body.bytesize > MAX_RESPONSE_SIZE
+
+    raise "Response body size #{response.body.bytesize} bytes exceeds maximum allowed #{MAX_RESPONSE_SIZE} bytes"
+  end
+
+  def build_http_request(uri, body)
+    if @custom_tool.http_method == 'POST'
+      request = Net::HTTP::Post.new(uri.request_uri)
+      if body
+        request.body = body
+        request['Content-Type'] = 'application/json'
+      end
+    else
+      request = Net::HTTP::Get.new(uri.request_uri)
+    end
+    request
+  end
+
+  def apply_authentication(request)
+    headers = @custom_tool.build_auth_headers
+    headers.each { |key, value| request[key] = value }
+
+    credentials = @custom_tool.build_basic_auth_credentials
+    request.basic_auth(*credentials) if credentials
+  end
+end