diff --git a/agent_builder/builder.py b/agent_builder/builder.py
index ec0248a..15194ec 100644
--- a/agent_builder/builder.py
+++ b/agent_builder/builder.py
@@ -65,6 +65,19 @@ expose:
   public: true
 ```
 
+If the agent needs system binaries the Python-only base image doesn't
+ship (ffmpeg, imagemagick, poppler-utils, sqlite3, etc.), declare
+them under ``runtime.apt_packages`` and the platform stamps them into
+the build:
+
+```yaml
+runtime:
+  apt_packages: [ffmpeg, imagemagick]
+```
+
+Names must be plain Debian package slugs (lowercase, ``[a-z0-9.+-]``).
+Don't reach for this for Python deps — those go in ``requirements.txt``.
+
 And a ``requirements.txt`` listing any extra deps beyond a2a-pack
 itself (pandas, httpx, etc. — the base image ships a2a-pack already
 when you deploy through the control plane).