Installation

There are several ways to install the Agent Starter Pack. Choose the method that works best for your workflow.

Want zero setup? 👉 Try in Firebase Studio or in Cloud Shell

uvx for Quick Project Creation

If you have uv installed, you can create projects without a permanent installation:

uvx agent-starter-pack create my-awesome-agent

Virtual Environment Installation

Installs into an isolated Python environment.

# Create and activate venv
python -m venv .venv && source .venv/bin/activate # source .venv/Scripts/activate for Windows Git Bash

# Install using pip or uv
pip install agent-starter-pack

Persistent CLI Installation

Installs the agent-starter-pack command globally.

With pipx (Isolated Global Tool)

# Install pipx (if needed)
python3 -m pip install --user pipx && python3 -m pipx ensurepath

# Install Agent Starter Pack
pipx install agent-starter-pack

With uv tool install (Fast, Isolated Global Tool)

Requires uv (see uvx section for install).

uv tool install agent-starter-pack

Create Project (After Persistent/Venv Install)

If you installed via pipx, uv tool install, or in a virtual environment:

agent-starter-pack create my-awesome-agent

Managing Installation

Upgrading

• uvx: Not needed (always uses latest).
• pipx: pipx upgrade agent-starter-pack
• uv tool: uv tool install agent-starter-pack (this upgrades)
• pip/uv pip (in .venv): (uv) pip install --upgrade agent-starter-pack

Uninstalling

• uvx: Not applicable.
• pipx: pipx uninstall agent-starter-pack
• uv tool: uv tool uninstall agent-starter-pack
• pip/uv pip (in .venv): (uv) pip uninstall agent-starter-pack

Troubleshooting Common Installation Issues

Command Not Found After Installation

If you encounter "command not found" errors after installation:

1. Check your PATH: Ensure that the Python scripts directory is in your PATH:

   echo $PATH

2. Verify installation location: Check where the package was installed:

   pip show agent-starter-pack

3. Manual path addition: If needed, add the scripts directory to your PATH:

   export PATH="$HOME/.local/bin:$PATH"
   # For user installations

   Add this line to your ~/.bashrc or ~/.zshrc for persistence.

Permission Errors During Installation

If you encounter permission errors:

1. Use user installation mode:

   pip install --user agent-starter-pack

2. Check directory permissions:

   ls -la ~/.local/bin

3. Fix permissions if needed:

   chmod +x ~/.local/bin/agent-starter-pack

Python Version Compatibility Issues

If you encounter Python version errors:

1. Check your Python version:

   python --version

2. Install a compatible Python version if needed (3.10 or newer is required).
3. Create a virtual environment with the correct Python version:

   python3.10 -m venv .venv
   source .venv/bin/activate

Package Dependency Conflicts

If you encounter dependency conflicts:

1. Use a clean virtual environment:

   python -m venv .venv
   source .venv/bin/activate
   pip install agent-starter-pack

2. Update pip and setuptools:

   pip install --upgrade pip setuptools

3. Install with verbose output to identify conflicts:

   pip install -v agent-starter-pack

Installation Verification

To verify your installation is working correctly:

1. Check the installed version:

   agent-starter-pack --version

2. Run the help command:

   agent-starter-pack --help

If you continue to experience issues, please file an issue with details about your environment and the specific error messages you're encountering.