diff --git a/akka-agent/src/main/scala/akka/agent/Agent.scala b/akka-agent/src/main/scala/akka/agent/Agent.scala
index 988356259d..9ec343421f 100644
--- a/akka-agent/src/main/scala/akka/agent/Agent.scala
+++ b/akka-agent/src/main/scala/akka/agent/Agent.scala
@@ -107,12 +107,6 @@ object Agent {
  * potentially interleaved with actions dispatched to the same agent from
  * other sources.
  *
- * If an Agent is used within an enclosing transaction, then it will
- * participate in that transaction. Agents are integrated with the STM -
- * any dispatches made in a transaction are held until that transaction
- * commits, and are discarded if it is retried or aborted.
- * <br/><br/>
- *
  * Example of usage:
  * {{{
  * val agent = Agent(5)
@@ -150,6 +144,15 @@ object Agent {
  * } yield value1 + value2
  *
  * }}}
+ *
+ * ==DEPRECATED STM SUPPORT==
+ *
+ * Agents participating in enclosing STM transaction is a deprecated feature in 2.3.
+ *
+ * If an Agent is used within an enclosing transaction, then it will
+ * participate in that transaction. Agents are integrated with the STM -
+ * any dispatches made in a transaction are held until that transaction
+ * commits, and are discarded if it is retried or aborted.
  */
 abstract class Agent[T] {
 
diff --git a/akka-docs/rst/java/agents.rst b/akka-docs/rst/java/agents.rst
index 785ff92051..fcb9bc24f7 100644
--- a/akka-docs/rst/java/agents.rst
+++ b/akka-docs/rst/java/agents.rst
@@ -23,10 +23,6 @@ each Agent is being executed. Actions dispatched to an agent from another thread
 will occur in the order they were sent, potentially interleaved with actions
 dispatched to the same agent from other threads.
 
-If an Agent is used within an enclosing transaction, then it will participate in
-that transaction. Agents are integrated with Scala STM - any dispatches made in
-a transaction are held until that transaction commits, and are discarded if it
-is retried or aborted.
 
 
 Creating Agents
@@ -97,8 +93,10 @@ See :ref:`futures-java` for more information on ``Futures``.
    :include: import-future,import-function,alter-off
    :language: java
 
-Transactional Agents
-====================
+Deprecated Transactional Agents
+===============================
+
+Agents participating in enclosing STM transaction is a deprecated feature in 2.3.
 
 If an Agent is used within an enclosing ``Scala STM transaction``, then it will participate in
 that transaction. If you send to an Agent within a transaction then the dispatch
diff --git a/akka-docs/rst/project/migration-guide-2.2.x-2.3.x.rst b/akka-docs/rst/project/migration-guide-2.2.x-2.3.x.rst
index b07dec0311..c449360c2e 100644
--- a/akka-docs/rst/project/migration-guide-2.2.x-2.3.x.rst
+++ b/akka-docs/rst/project/migration-guide-2.2.x-2.3.x.rst
@@ -113,6 +113,11 @@ tools to support reliable messaging.
 Read more about ``akka-persistence`` in the :ref:`documentation for Scala <persistence-scala>` and 
 :ref:`documentation for Java <persistence-java>`.
 
+Deprecated STM Support for Agents
+=================================
+
+Agents participating in enclosing STM transaction is a deprecated feature.
+
 Removed Deprecated Features
 ===========================
 
@@ -122,4 +127,3 @@ The following, previously deprecated, features have been removed:
  * `API changes to FSM and TestFSMRef <http://doc.akka.io/docs/akka/2.2.3/project/migration-guide-2.1.x-2.2.x.html#API_changes_to_FSM_and_TestFSMRef>`_
  * DefaultScheduler superseded by LightArrayRevolverScheduler
  
-
diff --git a/akka-docs/rst/scala/agents.rst b/akka-docs/rst/scala/agents.rst
index 107d04f2de..58f527b5e1 100644
--- a/akka-docs/rst/scala/agents.rst
+++ b/akka-docs/rst/scala/agents.rst
@@ -24,11 +24,6 @@ each Agent is being executed. Actions dispatched to an agent from another thread
 will occur in the order they were sent, potentially interleaved with actions
 dispatched to the same agent from other threads.
 
-If an Agent is used within an enclosing transaction, then it will participate in
-that transaction. Agents are integrated with Scala STM - any dispatches made in
-a transaction are held until that transaction commits, and are discarded if it
-is retried or aborted.
-
 .. note::
 
   Agents are local to the node on which they are created. This implies that you
@@ -99,17 +94,6 @@ currently queued updates have completed:
 
 See :ref:`futures-scala` for more information on ``Futures``.
 
-Transactional Agents
-====================
-
-If an Agent is used within an enclosing transaction, then it will participate in
-that transaction. If you send to an Agent within a transaction then the dispatch
-to the Agent will be held until that transaction commits, and discarded if the
-transaction is aborted. Here's an example:
-
-.. includecode:: code/docs/agent/AgentDocSpec.scala#transfer-example
-
-
 Monadic usage
 =============
 
@@ -121,3 +105,15 @@ as-is. They are so-called 'persistent'.
 Example of monadic usage:
 
 .. includecode:: code/docs/agent/AgentDocSpec.scala#monadic-example
+
+Deprecated Transactional Agents
+===============================
+
+Agents participating in enclosing STM transaction is a deprecated feature in 2.3.
+
+If an Agent is used within an enclosing transaction, then it will participate in
+that transaction. If you send to an Agent within a transaction then the dispatch
+to the Agent will be held until that transaction commits, and discarded if the
+transaction is aborted. Here's an example:
+
+.. includecode:: code/docs/agent/AgentDocSpec.scala#transfer-example
\ No newline at end of file