Added short docs and a test for providing a custom agent.

docs/howto.rst

@@ -101,3 +101,17 @@ access as `requests cookies <http://requests.readthedocs.org/en/latest/user/quic
     :lines: 7-20
 
 Full example: :download:`using_cookies.py <examples/using_cookies.py>`
+
+Agent Customization
+-------------------
+
+`treq` creates its own `twisted.web.client.Agent` with reasonable defaults, but
+you may want to provide your own custom agent.  A custom agent can be passed
+to the various `treq` request methods using the ``agent`` keyword argument.
+
+.. code-block:: python
+
+    custom_agent = create_custom_agent(trusted_certs, timeout)
+    treq.get(url, agent=custom_agent)
+
+

treq/test/test_api.py

@@ -1,7 +1,6 @@
 import mock
 
 from treq.test.util import TestCase
-
 import treq
 from treq._utils import set_global_pool
 
@@ -44,3 +43,9 @@ def test_cached_pool(self):
         treq.get('http://test.com')
 
         self.Agent.assert_called_with(mock.ANY, pool=pool)
+
+    def test_custom_agent(self):
+        custom_agent = mock.Mock()
+        treq.get('https://www.example.org/', agent=custom_agent)
+        self.HTTPClient.assertCalledWith(custom_agent)
+