Skip to content

"adk create" allows hyphens in agent names, causing agent discovery to fail #4054

@sofaquitegud

Description

@sofaquitegud

Describe the bug
The adk create command allows hyphens in agent folder names (e.g., sample-agent), but hyphens create invalid Python module names. Since ADK needs to import the agent as a Python package, agents created with hyphens cannot be discovered by adk web.

To Reproduce

# 1. Set up environment
export $(cat .env | xargs)

# 2. Create agent with hyphen (fails)
adk create sample-agent --model gemini-2.5-flash-lite --api_key $GOOGLE_API_KEY
adk web sample-agent   # Server starts but web UI shows "No agents found"
adk web                # Same issue - no agents found

# 3. Delete and recreate with underscore (works)
rm -rf sample-agent
adk create sample_agent --model gemini-2.5-flash-lite --api_key $GOOGLE_API_KEY
adk web                # ✅ Works! Agent appears in web UI

Expected behavior
Either:

  1. adk create should reject agent names with hyphens and suggest using underscores, OR
  2. adk create should automatically convert hyphens to underscores in the folder name

Desktop

  • OS: Linux
  • Python version: 3.10.19
  • ADK version: 1.21.0

Model Information:

  • Are you using LiteLLM: No
  • Which model is being used: gemini-2.5-flash-lite

Additional context
I was following the official Kaggle tutorial "Day 1a: From Prompt to Action" to learn how to create an agent with ADK.

The tutorial includes this command:

!adk create sample-agent --model gemini-2.5-flash-lite --api_key $GOOGLE_API_KEY

This creates an agent folder with a hyphen, which fails to load in the web UI. Learners following this tutorial will encounter this confusing error.

Workaround:
Use underscores instead of hyphens when creating agents:

!adk create sample_agent --model gemini-2.5-flash-lite --api_key $GOOGLE_API_KEY

Metadata

Metadata

Assignees

No one assigned

    Labels

    core[Component] This issue is related to the core interface and implementation

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions