diff --git a/mkdocs.yml b/mkdocs.yml
index bf804ed4d2..37163f183e 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -228,6 +228,10 @@ plugins:
             group_by_category: false
             # 3 because docs are in pages with an H2 just above them
             heading_level: 3
+            extensions:
+              - griffe_warnings_deprecated:
+                  kind: warning
+                  title: Deprecated
           import:
             - url: https://logfire.pydantic.dev/docs/objects.inv
             - url: https://docs.python.org/3/objects.inv
diff --git a/pyproject.toml b/pyproject.toml
index 24bca053ae..80c7ffb573 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -92,6 +92,7 @@ docs = [
     "mkdocs-llmstxt>=0.2.0",
     "mkdocs-material[imaging]>=9.5.45",
     "mkdocstrings-python>=1.12.2",
+    "griffe-warnings-deprecated>=1.1.0",
 ]
 docs-upload = ["algoliasearch>=4.12.0", "pydantic>=2.10.1"]
 
diff --git a/uv.lock b/uv.lock
index 8d2271fcb3..58007b31f2 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1423,6 +1423,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/76/67/b43330ed76f96be098c165338d47ccb952964ed77ba1d075247fbdf05c04/griffe-1.5.7-py3-none-any.whl", hash = "sha256:4af8ec834b64de954d447c7b6672426bb145e71605c74a4e22d510cc79fe7d8b", size = 128294, upload-time = "2025-02-11T13:38:09.319Z" },
 ]
 
+[[package]]
+name = "griffe-warnings-deprecated"
+version = "1.1.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "griffe" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/7e/0e/f034e1714eb2c694d6196c75f77a02f9c69d19f9961c4804a016397bf3e5/griffe_warnings_deprecated-1.1.0.tar.gz", hash = "sha256:7bf21de327d59c66c7ce08d0166aa4292ce0577ff113de5878f428d102b6f7c5", size = 33260, upload-time = "2024-12-10T21:02:18.395Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/43/4c/b7241f03ad1f22ec2eed33b0f90c4f8c949e3395c4b7488670b07225a20b/griffe_warnings_deprecated-1.1.0-py3-none-any.whl", hash = "sha256:e7b0e8bfd6e5add3945d4d9805b2a41c72409e456733965be276d55f01e8a7a2", size = 5854, upload-time = "2024-12-10T21:02:16.96Z" },
+]
+
 [[package]]
 name = "groq"
 version = "0.22.0"
@@ -3296,6 +3308,7 @@ logfire = [
 [package.dev-dependencies]
 docs = [
     { name = "black" },
+    { name = "griffe-warnings-deprecated" },
     { name = "mkdocs" },
     { name = "mkdocs-glightbox" },
     { name = "mkdocs-llmstxt" },
@@ -3325,6 +3338,7 @@ provides-extras = ["a2a", "examples", "logfire"]
 [package.metadata.requires-dev]
 docs = [
     { name = "black", specifier = ">=24.10.0" },
+    { name = "griffe-warnings-deprecated", specifier = ">=1.1.0" },
     { name = "mkdocs", specifier = ">=1.6.1" },
     { name = "mkdocs-glightbox", specifier = ">=0.4.0" },
     { name = "mkdocs-llmstxt", specifier = ">=0.2.0" },