diff --git a/docs/agents/config.md b/docs/agents/config.md
index 31a34d8ad..69a206d62 100644
--- a/docs/agents/config.md
+++ b/docs/agents/config.md
@@ -79,6 +79,12 @@ To create an ADK project for use with Agent Config:
 
         adk create --type=config my_agent
 
+    !!! note "Agent naming constraints"
+        The agent name must be a valid Python identifier. It can only contain
+        letters, numbers, and underscores (e.g., `my_agent_1`). Names that
+        contain dashes or other special characters (like `my-agent`) will
+        result in a loading error.
+
     This command generates a `my_agent/` folder, containing a
     `root_agent.yaml` file and an `.env` file.
 
@@ -307,4 +313,4 @@ agent definitions in the ADK
 [adk-samples](https://github.com/search?q=repo:google/adk-python+path:/%5Econtributing%5C/samples%5C//+root_agent.yaml&type=code)
 repository. For detailed information on the syntax and settings supported by
 the Agent Config format, see the
-[Agent Config syntax reference](/adk-docs/api-reference/agentconfig/).
+[Agent Config syntax reference](/adk-docs/api-reference/agentconfig/).
\ No newline at end of file
diff --git a/docs/get-started/python.md b/docs/get-started/python.md
index f181160c5..692c2be86 100644
--- a/docs/get-started/python.md
+++ b/docs/get-started/python.md
@@ -50,6 +50,12 @@ Run the `adk create` command to start a new agent project.
 adk create my_agent
 ```
 
+!!! note "Agent naming constraints"
+    The agent name must be a valid Python identifier. It can only contain
+    letters, numbers, and underscores (e.g., `my_agent_1`). Names that
+    contain dashes or other special characters (like `my-agent`) will
+    result in a loading error.
+
 ### Explore the agent project
 
 The created agent project has the following structure, with the `agent.py`
@@ -151,4 +157,4 @@ upper left corner and type a request.
 Now that you have ADK installed and your first agent running, try building
 your own agent with our build guides:
 
-*  [Build your agent](/adk-docs/tutorials/)
+*  [Build your agent](/adk-docs/tutorials/)
\ No newline at end of file