diff --git a/akka-docs/rst/java/agents.rst b/akka-docs/rst/java/agents.rst
index d54b18e20f..98884bf37f 100644
--- a/akka-docs/rst/java/agents.rst
+++ b/akka-docs/rst/java/agents.rst
@@ -100,10 +100,7 @@ See :ref:`futures-java` for more information on ``Futures``.
 Transactional Agents
 ====================
 
-If an Agent is used within an enclosing transaction, then it will participate in
+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
 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/AgentDocTest.java#transfer-example
-   :language: java
\ No newline at end of file
+transaction is aborted.
\ No newline at end of file
diff --git a/akka-docs/rst/project/migration-guide-2.1.x-2.2.x.rst b/akka-docs/rst/project/migration-guide-2.1.x-2.2.x.rst
index 8baa78b249..0a7d3da4df 100644
--- a/akka-docs/rst/project/migration-guide-2.1.x-2.2.x.rst
+++ b/akka-docs/rst/project/migration-guide-2.1.x-2.2.x.rst
@@ -53,3 +53,42 @@ ZeroMQ ByteString
 ``akka.zeromq.Frame`` and the use of ``Seq[Byte]`` in the API has been removed and is replaced by ``akka.util.ByteString``.
 
 ``ZMQMessage.firstFrameAsString`` has been removed, please use ``ZMQMessage.frames`` or ``ZMQMessage.frame(int)`` to access the frames.
+
+Brand new Agents
+================
+
+Akka's ``Agent`` has been rewritten to improve the API and to remove the need to manually ``close`` an Agent.
+The Java API has also been harmonized so both Java and Scala call the same methods.
+
+======================================================= =======================================================
+Old Java API                                            New Java API
+======================================================= =======================================================
+``new Agent<type>(value, actorSystem)``                   ``new Agent<type>(value, executionContext)``
+``agent.update(newValue)``                                ``agent.send(newValue)``
+``agent.future(Timeout)``                                 ``agent.future()``
+``agent.await(Timeout)``                                  ``Await.result(agent.future(), Timeout)``
+``agent.send(Function)``                                  ``agent.send(Mapper)``
+``agent.sendOff(Function, ExecutionContext)``             ``agent.sendOff(Mapper, ExecutionContext)``
+``agent.alter(Function, Timeout)``                        ``agent.alter(Mapper)``
+``agent.alterOff(Function, Timeout, ExecutionContext)``   ``agent.alter(Mapper, ExecutionContext)``
+``agent.map(Function)``                                   ``agent.map(Mapper)``
+``agent.flatMap(Function)``                               ``agent.flatMap(Mapper)``
+``agent.foreach(Procedure)``                              ``agent.foreach(Foreach)``
+``agent.suspend()``                                       ``No replacement, pointless feature``
+``agent.resume()``                                        ``No replacement, pointless feature``
+``agent.close()``                                         ``No replacement, not needed in new implementation``
+======================================================= =======================================================
+
+
+======================================================== ========================================================
+Old Scala API                                            New Scala API
+======================================================== ========================================================
+``Agent[T](value)(implicit ActorSystem)``                  ``Agent[T](value)(implicit ExecutionContext)``
+``agent.update(newValue)``                                 ``agent.send(newValue)``
+``agent.alterOff(Function1)(Timeout, ExecutionContext)``   ``agent.alterOff(Function1)(ExecutionContext)``
+``agent.await(Timeout)``                                   ``Await.result(agent.future, Timeout)``
+``agent.future(Timeout)``                                  ``agent.future``
+``agent.suspend()``                                        ``No replacement, pointless feature``
+``agent.resume()``                                         ``No replacement, pointless feature``
+``agent.close()``                                          ``No replacement, not needed in new implementation``
+======================================================== ========================================================
\ No newline at end of file
diff --git a/akka-docs/rst/scala/agents.rst b/akka-docs/rst/scala/agents.rst
index e14b6e129c..29fe8f5e23 100644
--- a/akka-docs/rst/scala/agents.rst
+++ b/akka-docs/rst/scala/agents.rst
@@ -56,7 +56,7 @@ happens immediately. So while updates to an Agent are asynchronous, reading the
 state of an Agent is synchronous.
 
 Updating Agents (send & alter)
-======================
+==============================
 
 You update an Agent by sending a function that transforms the current value or
 by sending just a new value. The Agent will apply the new value or function