diff --git a/akka-agent/src/main/scala/akka/agent/Agent.scala b/akka-agent/src/main/scala/akka/agent/Agent.scala
index 8b9337be1b..61bb5e73b3 100644
--- a/akka-agent/src/main/scala/akka/agent/Agent.scala
+++ b/akka-agent/src/main/scala/akka/agent/Agent.scala
@@ -15,14 +15,15 @@ object Agent {
   def apply[T](initialValue: T)(implicit context: ExecutionContext): Agent[T] = new SecretAgent(initialValue, context)
 
   /**
-   *  Factory method for Java Iterop.
+   * Java API
+   * Factory method for creating an Agent.
    */
   def create[T](initialValue: T, context: ExecutionContext): Agent[T] = Agent(initialValue)(context)
 
   /**
    * Default agent implementation.
    */
-  private class SecretAgent[T](initialValue: T, context: ExecutionContext) extends Agent[T] {
+  private final class SecretAgent[T](initialValue: T, context: ExecutionContext) extends Agent[T] {
     private val ref = Ref(initialValue)
     private val updater = SerializedSuspendableExecutionContext(10)(context)
 
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 e9b1a058bf..f414095a79 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
@@ -64,12 +64,14 @@ Brand new Agents
 ================
 
 Akka's ``Agent`` has been rewritten to improve the API and to remove the need to manually ``close`` an Agent.
+It's also now an abstract class with the potential for subtyping and has a new factory method
+allowing Java to correctly infer the type of the 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)``
+``new Agent<type>(value, actorSystem)``                   ``Agent.create(value, executionContext)``
 ``agent.update(newValue)``                                ``agent.send(newValue)``
 ``agent.future(Timeout)``                                 ``agent.future()``
 ``agent.await(Timeout)``                                  ``Await.result(agent.future(), Timeout)``