@stamkavid/agent-cli

v0.3.1

Published

6 months ago

🤖 Scaffold AI agent projects instantly - zero configuration, just works!

0High
0Medium
0Low

stamkavid

ai agent cli development framework llm langchain langgraph scaffolding

🤖 AgentCLI - AI Agent Project Scaffolding Framework

Scaffold AI agent projects in minutes, not hours. The most focused and simplified project setup experience for AI agent development.

⚡ Now available for both Python and NPM ecosystems - choose your preferred installation method!

Demo GIF Placeholder

Quick Start • Project Structure • CLI Commands • Examples • Development • Contributing

Quick Start

Installation Options

Python Ecosystem (Recommended for Python developers)

# Global installation with pipx (recommended) - works everywhere
pipx install agent-cli

# Or use pip globally
pip install --user agent-cli

# Or in current environment
pip install agent-cli

NPM Ecosystem (For Node.js developers)

# Coming soon! NPM package is in development
# For now, use the Python version or install from source

# Alternative: Run from source (requires Python)
git clone https://github.com/StamKavid/agent-cli.git
cd agent-cli
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .
npm install
node bin/agent-cli.js my-awesome-project

Create Your First AI Agent Project

# Zero-config setup - just like Claude Code! 🎉
agent-cli my-ai-agent-project

# Or even shorter
agent my-project

# Interactive mode
agent-cli

That's it! Your AI agent project structure is ready for development. 🎯

Generated Project Structure

Every scaffolded project follows clean architecture principles with the exact structure you specified:

agent-project/
├── .github/
│   └── workflows/
│       └── ci.yml                  # CI/CD pipeline
├── .gitignore                      # Git ignore rules
├── .env.example                    # Environment template
├── .env                           # Local environment
├── README.md                      # Project documentation
├── Makefile                       # Build automation
├── Dockerfile                     # Container setup
├── docker-compose.yml             # Multi-container orchestration
├── pyproject.toml                 # Modern Python packaging
│
├── configs/
│   ├── agent_config.yaml         # Agent configuration
│   ├── llm_config.yaml           # LLM provider settings
│   └── deployment_config.yaml    # Deployment settings
│
├── data/
│   ├── knowledge_base/            # Knowledge storage
│   └── evaluation/                # Evaluation datasets
│
├── k8s/
│   ├── deployment.yaml           # Kubernetes deployment
│   └── service.yaml              # Kubernetes service
│
├── notebooks/
│   ├── 01_prompt_engineering.ipynb     # Prompt development
│   ├── 02_prompt_management.ipynb      # Prompt versioning
│   ├── 03_memory_system.ipynb          # Memory experiments
│   ├── 04_tool_integration.ipynb       # Tool development
│   ├── 05_langgraph_workflows.ipynb    # Workflow design
│   └── 06_evaluation.ipynb             # Performance evaluation
│
├── src/agent_project/
│   ├── __init__.py
│   ├── config.py                  # Configuration management
│   ├── main.py                    # Application entry point
│   │
│   ├── agent/
│   │   ├── __init__.py
│   │   ├── base_agent.py          # Abstract base agent
│   │   ├── langgraph_agent.py     # LangGraph implementation
│   │   └── state_manager.py       # State persistence
│   │
│   ├── memory/
│   │   ├── __init__.py
│   │   ├── langmem_integration.py # LangMem integration
│   │   ├── vector_store.py        # Vector storage
│   │   └── conversation_memory.py # Conversation context
│   │
│   ├── tools/
│   │   ├── __init__.py
│   │   ├── base_tool.py           # Tool interface
│   │   ├── web_search.py          # Web search capability
│   │   ├── file_operations.py     # File handling
│   │   └── custom_tools.py        # Custom tool templates
│   │
│   ├── workflows/
│   │   ├── __init__.py
│   │   ├── workflow_builder.py    # Workflow construction
│   │   └── common_workflows.py    # Pre-built workflows
│   │
│   ├── prompts/
│   │   ├── __init__.py
│   │   ├── prompt_manager.py      # Prompt lifecycle
│   │   ├── prompt_library.py      # Prompt collection
│   │   ├── templates/
│   │   │   ├── system_prompts.py  # System prompt templates
│   │   │   ├── user_prompts.py    # User prompt templates
│   │   │   ├── tool_prompts.py    # Tool prompt templates
│   │   │   └── workflow_prompts.py # Workflow prompts
│   │   └── versions/
│   │       ├── v1_prompts.py      # Version 1 prompts
│   │       └── v2_prompts.py      # Version 2 prompts
│   │
│   ├── llm/
│   │   ├── __init__.py
│   │   ├── client.py              # LLM client abstraction
│   │   └── prompt_executor.py     # Prompt execution
│   │
│   ├── api/
│   │   ├── __init__.py
│   │   ├── app.py                 # FastAPI application
│   │   ├── routes.py              # API endpoints
│   │   └── schemas.py             # Pydantic schemas
│   │
│   ├── observability/
│   │   ├── __init__.py
│   │   ├── opik_integration.py    # Opik monitoring
│   │   └── metrics.py             # Custom metrics
│   │
│   └── utils/
│       ├── __init__.py
│       ├── logging.py             # Logging configuration
│       └── helpers.py             # Utility functions
│
├── tools/
│   ├── run_agent.py               # Agent execution script
│   ├── evaluate_agent.py          # Performance evaluation
│   ├── populate_memory.py         # Memory initialization
│   ├── manage_prompts.py          # Prompt management
│   └── deploy.py                  # Deployment utilities
│
├── tests/
│   ├── test_agent.py              # Agent testing
│   ├── test_memory.py             # Memory testing
│   ├── test_tools.py              # Tool testing
│   └── test_workflows.py          # Workflow testing
│
└── docs/
    ├── getting_started.md         # Quick start guide
    ├── configuration.md           # Configuration guide
    └── deployment.md              # Deployment guide

CLI Commands

| Command | Description | Example | |---------|-------------|---------| | create | Create new AI agent project scaffold | agent-cli create chatbot-project | | list-templates | Show available project templates | agent-cli list-templates | | validate-templates | Validate all project templates | agent-cli validate-templates | | validate | Validate a project name | agent-cli validate my-project | | info | Show CLI information | agent-cli info |

Quick Examples

Conversational Agent Project

# Create a customer service chatbot project
agent-cli create customer-service-bot

# Navigate to project
cd customer-service-bot

# Run the included quickstart
cd quickstart && python quickstart.py

# Start development
make dev-setup

Research Assistant Project

# Create a research agent project
agent-cli create research-assistant

# Navigate to project
cd research-assistant

# Explore the generated structure
ls -la

# Check the notebooks for experimentation
jupyter lab notebooks/

Task Automation Project

# Create an automation agent project
agent-cli create workflow-automation

# Navigate to project
cd workflow-automation

# Review the generated architecture
tree src/

# Start development
make install

Development Workflow

1. Scaffold & Setup

agent-cli my-agent-project
cd my-agent-project

2. Explore & Customize

# Review generated structure
tree src/

# Check configuration
cat configs/agent_config.yaml

# Explore notebooks
jupyter lab notebooks/

3. Develop & Test

# Install dependencies
pip install -e .

# Run tests
pytest

# Start development
make dev-setup

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=src/agent_cli --cov-report=html

🔧 Development

# Clone and setup
git clone https://github.com/StamKavid/agent-cli.git
cd agent-cli
pip install -e .[dev]

# Run tests
pytest

# Format code
black src/ && isort src/

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests and ensure they pass
Submit a pull request

Troubleshooting

Common Issues

Project name validation fails:

# Both formats work - CLI handles conversion automatically
agent-cli create my-agent-project  # ✅ Good (creates my-agent-project/ directory)
agent-cli create my_agent_project  # ✅ Good (creates my_agent_project/ directory)
agent-cli create "my agent!"       # ❌ Bad (invalid characters)

Template validation errors:

# Validate all templates
agent-cli validate-templates

Permission errors:

# Ensure write permissions
chmod +w /path/to/output/directory

NPM-Specific Issues

NPM package not found:

# The NPM package hasn't been published yet
# Use the Python version instead:
pipx install agent-cli

# Or install from source:
git clone https://github.com/StamKavid/agent-cli.git
cd agent-cli
python3 -m venv venv
source venv/bin/activate
pip install -e .

Python not found (NPM users):

# Install Python first
# Visit: https://python.org/downloads/

# Then create virtual environment and install
python3 -m venv venv
source venv/bin/activate
pip install -e .

Manual Python package installation:

# If auto-installation fails, create venv first
python3 -m venv venv
source venv/bin/activate
pip install agent-cli

# Or with pipx (recommended)
pipx install agent-cli

Debug Mode

# Enable verbose output
agent-cli create my-agent-project --verbose
agent-cli validate-templates --verbose

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Inspiration

This project structure was inspired by the amazing work of Miguel Otero Pedrido (@MichaelisTrofficus).

Check out his work:

🏢 The Neural Maze - Hub for ML projects with step-by-step explanations
📺 YouTube Channel - Tutorials and project showcases
📧 Newsletter - Latest articles and project updates
🔗 LinkedIn - Professional profile

Made with ❤️ by Stamatis Kavidopoulos

Ready to scaffold amazing AI agent projects? Start creating today! 🚀