diff --git a/ironic/drivers/modules/agent.py b/ironic/drivers/modules/agent.py
index bf93c4902f..16a7fdcfcb 100644
--- a/ironic/drivers/modules/agent.py
+++ b/ironic/drivers/modules/agent.py
@@ -565,6 +565,9 @@ class AgentVendorInterface(agent_base_vendor.BaseAgentVendor,
     """Implementation of agent vendor interface.
 
     Contains old lookup and heartbeat endpoints currently pending deprecation.
+
+    WARNING: This class is deprecated and will be removed in the Ocata release.
+    Drivers should stop relying on it.
     """
 
 
diff --git a/ironic/drivers/modules/agent_base_vendor.py b/ironic/drivers/modules/agent_base_vendor.py
index d7929596cf..20da382998 100644
--- a/ironic/drivers/modules/agent_base_vendor.py
+++ b/ironic/drivers/modules/agent_base_vendor.py
@@ -655,6 +655,8 @@ class AgentDeployMixin(object):
                  node.uuid)
 
 
+# TODO(dtantsur): deprecate and remove it as soon as we stop using it ourselves
+# in the Ocata release.
 class BaseAgentVendor(AgentDeployMixin, base.VendorInterface):
 
     def __init__(self):
@@ -766,6 +768,10 @@ class BaseAgentVendor(AgentDeployMixin, base.VendorInterface):
         :raises: NotFound if no matching node is found.
         :raises: InvalidParameterValue with unknown payload version
         """
+        LOG.warning(
+            _LW('Agent lookup vendor passthru is deprecated and will be '
+                'removed in the Ocata release; please update your '
+                'ironic-python-agent image to the Newton version'))
         LOG.debug('Agent lookup using data %s', kwargs)
         uuid = kwargs.get('node_uuid')
         if uuid:
diff --git a/ironic/drivers/modules/iscsi_deploy.py b/ironic/drivers/modules/iscsi_deploy.py
index e43afad816..5e35a24ab0 100644
--- a/ironic/drivers/modules/iscsi_deploy.py
+++ b/ironic/drivers/modules/iscsi_deploy.py
@@ -581,4 +581,10 @@ class ISCSIDeploy(AgentDeployMixin, base.DeployInterface):
 
 
 class VendorPassthru(AgentDeployMixin, agent_base_vendor.BaseAgentVendor):
-    """Interface to mix IPMI and PXE vendor-specific interfaces."""
+    """Interface to mix IPMI and PXE vendor-specific interfaces.
+
+    Contains old lookup and heartbeat endpoints currently pending deprecation.
+
+    WARNING: This class is deprecated and will be removed in the Ocata release.
+    Drivers should stop relying on it.
+    """
diff --git a/releasenotes/notes/deprecate-agent-passthru-67d1e2cf25b30a30.yaml b/releasenotes/notes/deprecate-agent-passthru-67d1e2cf25b30a30.yaml
new file mode 100644
index 0000000000..7576964082
--- /dev/null
+++ b/releasenotes/notes/deprecate-agent-passthru-67d1e2cf25b30a30.yaml
@@ -0,0 +1,6 @@
+---
+deprecations:
+  - Agent vendor passthru is deprecated and will be removed in Ocata release.
+    Operators should update their IPA image to the Newton version to use
+    the new replacement API. Driver developers should stop using the agent
+    vendor passthru.